可单独安装的 客户端信息卡与后台窗口模组 已提供 Fabric／NeoForge 1.21.1 两套构建；不依赖 Agent 框架、游戏核心或服务器插件，也可与导播组合使用。
静态摄影的 viewerPhotoPage 支持显式第一／第三人称模式。 就绪判断要求实际地形网格、皮肤、头部材质和 YSM 加载任务完成；隐藏的第一人称本人及视野外人物不会被误算成模型加载失败。 宿主应先选择当前连接已完整接收的区块范围，并处理传输背压错误；不能用放行缺失区块或延长超时来假装成片成功。
原生 Fabric 1.21.1 观战可选用 Native Director： 只控制一个已认证、显式配置的现有观察者，接受有时限的选人／视角请求，以实际 相机 UUID 确认切换，手动脱离即暂停。目标数据仍由原生 observer HUD 提供， 模型使用匹配版本的 YSM；不将已发送镜头命令当成显示成功或完整插件兼容。
另有独立的 NeoForge 1.21.1 观战候选， 使用官方 NeoForge/TLM/YSM 和原生显示接口；不加载 Fabric Loader 或 Connector。 该可选原生观战成品采用 GPL-3.0-only 并保留共享代码的 MIT 声明， 参见其 来源与许可证。核心 SDK 与网页渲染器的许可证保持各自声明。 源码构建、离线启动与正式服画面分别验收；各版本的实际验收范围见原生观战说明，其他消费端仍需独立加载与验证。
2026-10-26 公网观战候选：地形重叠增量、多人材质请求合并、缓存限额与可测计数，另修正YSM转向倾斜及怪物持械方向。消费者须同时更新匹配页面和观战源；改动、实测及未支持范围。
2026-10-25 Paper 观战动作候选：连续服务器位置驱动原模型行走，保留原受力速度；重复 tick 去重并补齐高频姿态/使用物品字段。原可米模型回放已验，正式消费端须独立更新，见动作来源与验收边界。
Mineflayer 驱动的 Minecraft 网页可视化。现代画面渲染器的源码在
packages/modern-viewer/renderer-src；
按版本提交的模型、贴图、物品图标和可选音频位于 asset-packs，浏览器 bundle 从当前源码构建。
1.21.1 模组服另有使用实际模组包资源与注册表的原生接入路径，复用同一套完整页面和界面布局；
两个版本的数据与构建入口分别维护，不能混用方块编号或代理模型。
| 层 | 从哪里取得数据 | 归属 |
|---|---|---|
| 通用画面 | Mineflayer 已收到的区块、实体、装备、背包、窗口、交易、天气、生命/饱食度、状态效果、粒子、音效和动作 | 本仓库的现代渲染器、页面和构建工具；宿主项目负责按 Socket.IO 合约发送数据 |
| 千灯纪 World | /mycli、保护预检、技能和试炼规则、服务端事件的行动语义 |
cortico-world-qiandengji |
| 千灯纪画面预设 | 精确身份匹配的命名 NPC、肖像、美术档案、技能视觉类型 | renderer-src/src/modern-viewer/presets/qiandengji/ 和 renderer-src/tools/presets/；构建时可选择 |
| 服务端状态 | 可选的 mcagent:state、mcagent:event 插件消息 |
千灯纪服务端提供；普通服务器无需这些消息，通用画面照常运行 |
现代网页画面不在千灯纪 World 扩展里。千灯纪 World 在独立 Minecraft 核心上维护连接和执行器，宿主提供 viewer 桥接，本仓库提供浏览器渲染源码。通用画面只显示客户端收到的信息；服务端独有的魔力、技能冷却等需服务端另发结构化状态。
游戏协议由宿主的 Mineflayer 自动协商或显式指定，不使用可视化的维护版本限制登录。画面按实际协商版本选择经过校验的原版资源和注册表；缺失时明确报告画面不可用，游戏连接独立保持，不借用其他版本的资源。
新增 java-1.21.11：从 Mojang 对应客户端导出模型、纹理、物品定义、图集与字库，校验全部 29671 个方块状态。构建方式：node tools/prepare-viewer-assets.mjs java-1.21.11 <output-dir> --no-sounds。该包暂不包含音频、地图/粒子扩展与新实体模型；不宣称完整 Java 画面等价。1.21.1 仍是主要维护版本，1.20.6 保留回归。
宿主可以通过核心连接台的 nativeClients:false 关闭观察者/玩家原生启动入口。共享页面保留 Agent 连接、微软授权和同连接网页画面；画面失败与游戏断线分别显示。
页面、HUD、动作、装备、钓鱼、特效、音效处理和原始素材均随仓库提供。在仓库根目录安装渲染器依赖，再校验素材并构建；无需 Cortico 或其他项目的本机素材目录。
npm ci --prefix packages/modern-viewer/renderer-src
node tools/prepare-viewer-assets.mjs java-1.20.6 "<output-dir>"命令先检查逐文件哈希，再复制对应版本的素材和完整声音包并编译当前浏览器代码；viewer-assets.json 记录素材版本和清单哈希。音乐与音效默认包含，只有明确需要静音资源部署时才加 --no-sounds；旧的 --sounds 参数仍兼容。八首公共原创 BGM 位于独立的 original-bgm 素材包，两个 Minecraft 版本均完整复制；已有个人音乐目录会保留。直接构建浏览器代码也会补齐匹配的声音包，不会因只更新画面而遗漏音频。自定义导出仍可按渲染器说明使用自己的客户端 JAR。
构建默认使用通用模式，适合 Neko 等其他宿主。千灯纪的技能视觉映射和公会看板显示用 --preset=qiandengji 显式开启；此选项不启用参考包内的命名 NPC 身份或本地剧情。服务端机制和 Agent 决策仍在独立 World 中。
1.20.6 的第三人称和 3D观战画面只在检测到视线或顶层遮挡时开启透视／切面；无遮挡时恢复完整地形，不再常驻人物周围的透视圈。离开遮挡沿用连续采样确认，避免边缘来回闪烁。
2026-10-10：玩家与 NPC 头顶气泡已接入同连接原版 TextDisplay，包含匹配 1.20.6 的中文原字库、跟随、更新和清理。远端电脑需更新 content 桥并重建实际网页资源；更新步骤与支持范围。无需重启 Minecraft 服务器。
2026-10-12：OBS 可编辑 Agent 公开行动说明、按键/鼠标、寻路与候选轨迹、攻击/采集/交互标记和图文动画。新增点线面 Marker API、垂直 FOV 与画幅校准、实时 FOV 上报；接入、配置与验证边界。宿主 bridge 和实际网页资源需同时更新。
2026-10-13 的 1.20.6 源码新增六种高级运镜、模型构图与避障、可选遮挡剔除和 YSM 平滑采样。键鼠／触摸／手柄操控通过宿主授权和 Agent 暂停回调显式启用；接入与验证范围。消费端需重建资源并接控制桥，原生 SSE 场景与远端部署尚未自动更新。
My Agent World 的实验接入复用原 page-template.html、viewer.css、背包人物预览和自适应画质组件，
由 native-scene.js 绘制实际 1.21.1 模组资源；native-console.js 与 native-ui-adapter.js 接上本人界面。
静态模型与纹理可从仓库中的 native-1.21.1 素材包准备；它绑定原模组包锁定哈希。注册表与资源覆盖变体来自匹配服务器的实际导出，缺失能力明确显示未支持。
宿主先调用 prepareNativeWorldPreviewHost，再向 attach 提供已有动作 bot、该连接的原生包流、
getAgentStatus 和可选 getPresentationState。宿主拥有 bot 的生命周期，网页不登录另一位观察者，
不提供游戏动作或管理员 HTTP 接口。资源导出、具体接口与回归命令见
渲染器说明，原生 SSE 合约见
协议第 8 节。
| 路径 | 当前作用 |
|---|---|
/、/third/ |
原完整页面的第一人称、第三人称跟随 |
/3dview/ |
同一原完整页面的3D观战 跟随相机；遮挡、切面与点击操控尚未接入 |
/diagnostics |
独立原生模型、身份、注册表与缺口检查页 |
/events、/status.json、/healthz |
同账号 SSE、只读状态、连接与原生流健康 |
当前可展示实际生命/饥饿/经验、原生物品名称与数量、本人原生窗口和已收到的技能状态。 部分无组件敏感规则的原版物品可显示经原始 JSON 与 PNG 校验的静态图标；模组及动态物品图标、装备模型、 声音、小地图、全部实体与动画、完整光照仍需适配和实机验收。 资源哈希与测试通过分别证明来源和程序行为；完整画面一致性门槛保持关闭。 这一入口使用 SSE 和专用原生包桥，不能把模组 state ID 发给下面的 1.20.6 Socket.IO 渲染器。
2026-10-04 已在隔离的新 My Agent World 常驻服实际发布：浏览器验证同账号 Makena 皮肤、46 格背包与本人预览、 第一／第三人称和地下城相机，原版小麦种子与腐肉显示经过原始资源校验的静态图标，浏览器无 warn/error。 这是一次实际部署和短时游玩验证，旧服未改；完整模组画面、长期稳定和基岩接入尚未验收。
仓库根目录的 pnpm test 运行全部可独立使用的核心与 renderer 回归，不要求 Cortico。
pnpm test:cortico 单独验证真实可选 Cortico API；未安装 SDK 时用 CORTICO_SOURCE_DIR 指向实际源码 checkout，
缺失 SDK 会明确失败，不跳过或用 mock 替代。入口与所需源文件见 测试说明。
本轮根回归 230 项、renderer 专项 213 项、真实 Cortico 0.1.4 集成 6 项及 typecheck 通过，测试集合有重叠，不相加。
共享可视化改动与素材统一维护在 main；后端实验 worker 的分支单独维护。
从 renderer-src/README.md 开始：宿主提供静态文件和 Socket.IO 数据桥接，前端通过 SOCKET_PROTOCOL.md 接收 Mineflayer 状态。第一人称、第三人称和3D观战 共用同一套资源。
Neko 接入与更新检查见 Neko 复用说明。
生命、饱食度、装备和背包等来自 Mineflayer。魔力、技能和冷却使用可选的规范化 skillsState 数据，其他服务器可以提供自己的适配器，无需安装千灯纪插件。
在现有 Cortico 部署中，将 worlds.minecraft.viewerAssetsDir 或 worlds.mymc.viewerAssetsDir 指向 <output-dir>，沿用其 viewer 桥接即可。
共享源码以本仓库的 main 分支为准。各项目更新源码后，需要按自己的 Minecraft 版本、原资源目录和预设重新构建；更新宿主代码不会更新已经复制的浏览器文件。
- 在可视化源码目录运行
git pull --ff-only origin main，并记录git rev-parse HEAD。 - 使用上面的离线构建步骤生成新产物。保留原资源版本；千灯纪继续使用
--preset=qiandengji，原生模组宿主按其原生构建说明更新。 - 将产物同步到宿主实际提供的静态资源目录，核对
viewer-client.json的browserBundleSha256与页面/index.js的内容哈希，然后刷新页面。
原资源未变时无需重新导出 Minecraft JAR。不同版本或预设的产物分别构建，不互相覆盖。发布源码、更新本地部署和其他机器完成更新是三个独立结果。
旧版独立控制台、webplay 的实验记录在 docs/early-roadmap.md。它们与这套 1.20.6 直播画面的构建和兼容承诺不同。
./performance-relay 导出 createRelay({endpoint, sourceId})。endpoint 必须是完整 HTTP(S) origin，sourceId 必须匹配该 bot 的演出身份。构造时不联网；收到 overlay/stream 请求才核对指定端点的 /identity。没有端口发现或回退扫描。宿主未配置时不创建 relay，关闭 viewer 时调用 close()。此桥只传递演出内容，不拥有游戏 bot、人格、模型或 TTS。