戏仿式的

Pandorical

面向 Fabric 的客户端启用桥接，用于服务器驱动的 UI、内容和渲染。

服务器模组声明界面、HUD 覆盖层、自定义方块/物品和相机提示。Pandorical 负责处理协议、资源同步和客户端渲染；原版客户端加入时不受影响。

功能

功能	作用
screens	为每个玩家打开、更新和关闭声明式 UI 界面
hud	显示、更新和隐藏持久化 HUD 覆盖层，包括动画组件（可变几何体、缩放/旋转以及更新之间的客户端插值），以及用于轻量级本地粒子效果的 particle_burst 组件
hud_elements	按玩家隐藏原版 HUD 元素（例如饥饿值条），使 HUD 覆盖层可以替代原版元素，而不是与其并列显示
content	在加入时同步自定义方块、物品和资源到客户端，并且仅对 Pandorical 客户端覆盖原版物品的外观
camera	控制相机距离和视角
playerInventory	注册额外的物品栏槽位，这些槽位显示在原版物品栏界面中并跨会话持久保存
blockTints	为自定义方块注册生物群系颜色和恒定色调映射
structures	将移动、旋转的方块组（例如可骑乘的船只）作为一个批量渲染的对象展示给 Pandorical 客户端
entity_overlays	在特定生物实体的模型上覆盖一层额外的纹理层（按实体的装饰），自动推送给跟踪该实体的每个玩家
keybinds	服务器声明的可重新绑定按键绑定：模组从固定的客户端池中认领槽位（类别为 "Pandorical"，槽位 1 默认为 G），通过同步的 lang 文件命名，并在服务器端接收按键事件；声明模组不需要任何客户端代码
实体渲染	为自定义实体类型注册简单的内置渲染器（thrown_item、invisible），无需完整的客户端模型

安装

Pandorical 需要安装在服务器 和 每个应看到服务器声明内容的客户端上。它是这套模组中唯一需要同时安装在两端的模组。版本目标位于 gradle.properties（Minecraft、加载器、Fabric API）和 fabric.mod.json（Java）中。

用法

将 Pandorical 作为依赖添加，并通过 PandoricalApi 进行交互。

// 在任何 API 调用前检查；保护原版客户端上的玩家
if (!PandoricalApi.isAvailable(player)) return;

// 按能力检查
if (!PandoricalApi.hasCapability(player, "screens")) return;

时机： isAvailable(player) 和 hasCapability(...) 在客户端能力握手完成之前返回 false，而握手发生在玩家 JOIN 事件 之后 不久，而非之前。不要直接在 JOIN 处理器中推送界面或 HUD；请延迟推送（加入后一两刻，或触发玩家自己的第一个动作），否则推送会静默失效。

界面

ScreenApi screens = PandoricalApi.screens();

// 打开界面
screens.open(player, new OpenScreenS2C(...));

// 打开由服务器端容器支持的界面
screens.openContainer(player, screenDef, serverContainer, readOnlySlots);

// 向已打开的界面推送实时更新
screens.update(player, screenId, List.of(new ComponentUpdate(...)));

// 关闭界面
screens.close(player, screenId);

// 处理来自客户端的操作
screens.onAction("my-screen", "confirm-button", (player, data) -> { ... });
screens.onActionFallback("my-screen", (player, data) -> {
    String componentId = data.get("_componentId");
    // ...
});
screens.onClose("my-screen", player -> { ... });
screens.onSlotChange("my-screen", (player, slotIndex, stack) -> { ... });
screens.onContainerRemoved("my-screen", player -> { /* 归还物品 */ });

HUD

HudApi hud = PandoricalApi.hud();

hud.show(player, new ShowHudS2C(...));
hud.update(player, overlayId, updates);
hud.hide(player, overlayId);

// 替代原版元素而不是与它并列绘制
hud.hideVanillaElements(player, "my-mod", List.of(VanillaHudElement.FOOD_BAR));
hud.restoreVanillaElements(player, "my-mod");

抑制是按请求模组为键的，因此两个隐藏不同元素的模组不会互相影响，并且只要其中任何一个模组仍然想要隐藏某个元素，该元素就保持隐藏状态。聊天、玩家列表、睡眠覆盖层和演示计时器故意设置为不可抑制。没有 hud_elements 能力的客户端会继续绘制原版版本，因此旨在替代原版元素的覆盖层需要一个仍然可以与原版元素并存的布局（或者根本不应该推送给那些客户端）。

内容

在 onInitialize 期间注册方块、物品和资源。它们在配置阶段同步到客户端，早于 Fabric 的注册表同步。

ContentApi content = PandoricalApi.content();

content.registerBlock("my-mod:my-block", new BlockRegistration(...));
content.registerItem("my-mod:my-item", new ItemRegistration(...));
content.registerAsset("my-mod/models/block/my-block.json", jsonBytes);
content.registerModAssets("my-mod"); // 自动扫描 classpath assets/

// 仅对 Pandorical 客户端覆盖原版物品的外观
content.overrideVanillaItem("minecraft:rabbit_hide", new VanillaItemOverride(...));

内容就绪状态按玩家跟踪；在打开依赖于同步资源的界面之前，请等待 isContentReady：

if (PandoricalApi.isContentReady(player)) {
    screens.open(player, ...);
}

相机

CameraApi camera = PandoricalApi.camera();

camera.setDistance(player, 6.0f);
camera.setPerspective(player, "third_person_back");
camera.reset(player);

实体覆盖层

// 为特定实体附加额外的纹理层。纹理必须遵循
// 实体模型自身的纹理布局；透明像素不会被绘制。
// 广播给该实体的所有当前和未来跟踪者；无需玩家参数。
PandoricalApi.entityOverlays().set(entity,
    Identifier.fromNamespaceAndPath("mymod", "textures/entity/my_overlay.png"));

PandoricalApi.entityOverlays().clear(entity);

覆盖层状态仅存在于内存中，并在实体卸载时丢弃：在实体加载时重新调用 set（例如从读取你自己持久化标志的 tick 钩子中）。将纹理打包在你的模组 jar 中，并使用 content().registerModAssets(...) 注册，以便 Pandorical 将其同步到客户端。

按键绑定

// 在模组初始化时认领一个池化按键绑定，需在玩家连接之前。键码使用
// 游戏自身的 InputConstants 表，而非 GLFW（在这个快照版本中 10 是 KEY_G）；
// 只有在空闲池槽位有该默认值时，首选键才会生效（槽位 1 是 G，其余初始未绑定）。
// 显示名称会出现在该服务器的客户端控制界面中。按键事件在服务器线程上
// 到达，经过 Pandorical 验证和速率限制。
PandoricalApi.keybinds().register("mymod:action", 10, "Do The Thing",
    player -> doTheThing(player));

池固定为 8 个槽位，因为选项系统只接受客户端启动期间的按键绑定注册；槽位的重新绑定会像任何其他按键一样持久保存在 options.txt 中。未认领的槽位是惰性的，不发送任何内容。

其他功能

structures、playerInventory、blockTints 和自定义实体渲染通过 PandoricalApi 以相同方式驱动。它们的约定（包括陷阱：服务器全局唯一的结构 ID、为避免状态泄漏而进行的销毁、色调注册时机）位于 StructureApi、PlayerInventoryApi、BlockTintApi 和 PandoricalApi#registerEntityRenderer 的 javadoc 中：在接入它们之前请先阅读这些文档。

组件

界面和 HUD 覆盖层由以下组件类型组成：

panel · scroll_panel · text · button · text_input · sprite · item_slot · item_icon · inventory_grid · map · particle_burst