livingitem

Imported from 777hi/livingitem (AGENTS.md). Install upstream with npx skills add 777hi/livingitem. Copyright stays with the author.

Living Item (活物品)

Minecraft 1.21.1 + NeoForge 21.1.x 最后更新: 2026-09-20 状态: Alpha 测试阶段 - 活信标 Phase 4 完成（tooltip 重设计 + 9 柱面板）；v8.1 接口化重构 / 红电 v19.1 等更早变更见 changelog

项目概述

将世界中的方块功能（熔炉、漏斗等）活化到物品层面。活物品在容器（箱子、背包等）内自动运行，状态通过 DataComponent 持久化，跟随物品跨容器迁移。

核心特性

• 活按钮 UI：在容器界面点击按钮，将手持物品转化为活物品
• 容器内自动执行：含活物品的被加载容器会自动 tick
• DataComponent 直接管理：每个功能类直接管理其类型化的 DataComponent，替代旧的 ComponentState + LivingFunctionData 中转层
• 功能内聚：每个功能类自行实现 tick 逻辑和数据管理，不再依赖编排器调度
• 不可变数据模型：使用 Java Record 实现不可变数据结构，通过 withXxx() 方法创建新实例
• 增量同步：功能数据拆分为独立的 DataComponent，只在数据变化时更新并同步到客户端
• 活物品隔离：活物品不会被其他活物品当作普通物品处理（不传输、不熔炼、不作为燃料）
• GUI交互系统：声明式规则 + 统一拦截 + 服务端处理
• 活物品图标系统：组件化声明式配置，新增活物品图标无需编写 Java 类
• 活箱子：堆叠数 × 27 槽虚拟箱子，UUID 映射 + LRU 缓存 + 磁盘持久化
• 活末影箱：无线传输路由器，路由模式（共享黑板）+ 直连模式（绑定玩家末影箱）
• 活水车：应力产生类活物品，软依赖 Create，3D 旋转渲染
• 活地图传送：活末影珍珠 + 活地图，三种场景 + UV 精确传送 + 跨维度 + 载具 + Sable 飞艇兼容
• 活耕地：GUI 交互获取/种植/骨粉催熟 + 世界轴节拍生长 + round-robin 逐项产出 + 双槽渲染
• 接口化扩展：HasDirection（WASD 朝向配置）+ HasContainerData（容器级数据计算），新增活物品无需修改核心文件
• 活红石系统：活红石粉（信号传播）+ 活红石火把（反相器）+ 活按钮/活拉杆/活红石灯 + 活中继器/活比较器/活红石块，支持与世界红石双向互通
• 活工具 / 活武器：记忆玩家的操作（挖掘 / 交互 / 攻击）→ 借 FakePlayer 回放；无记忆的在背后环上辅助玩家（挖掘 / 攻击），有记忆的自主沿记忆射线干活；两类状态联机可见（主动模式的记忆射线需 F3+B）

架构概览

服务端 tick (LivingItem.onServerTick)
    ↓
ContainerChunkCache (容器位置缓存，拉取模型)
    ↓
ContainerLivingItemHandler (扫描容器、按功能分组)
    ↓
LivingItemFunction.tick() (各功能类自行实现 tick 逻辑)
    ↓
功能类直接管理 DataComponent，无中间层
    ├── LivingTntFunction        → LivingTntData
    ├── LivingFurnaceFunction    → LivingFurnaceData
    ├── LivingHopperFunction     → TransferPipeline (统一传输入口)
    ├── LivingEnderChestFunction → LivingEnderChestData
    ├── LivingWaterWheelFunction → LivingWaterWheelData
    ├── LivingChestFunction      → InternalStorageComponent (旧架构)
    ├── LivingEnderPearlFunction → (纯工具类，无 DataComponent)
    ├── LivingRedstoneFunction   → LivingRedstoneData
    ├── LivingRedstoneTorchFunction → LivingRedstoneTorchData
    ├── LivingButtonFunction / LivingLeverFunction / LivingRedstoneLampFunction
    │   LivingRepeaterFunction / LivingComparatorFunction / LivingRedstoneBlockFunction
    └── LivingToolFunction      → LivingToolMemory / LivingToolProgress
                                  LivingToolAction / LivingToolOwner / LivingToolDigTicks
                                  （活工具 + 活武器：记忆玩家操作 → FakePlayer 回放；
                                   渲染见 client/render/LivingToolModelRenderer + RayRenderer）
    ↓
容器级数据计算（HasContainerData 接口，按优先级排序；**全库仅 4 个实现者**）
    ├── LivingFluidFunction        (prio 0) — 容器级流体 BFS（**自维持**，与桶解耦）
    ├── LivingWaterWheelFunction   (prio 1) — 应力计算 + postTickSync
    ├── LivingRedstoneFunction     (prio 2) — 红石信号传播（**自维持，唯一驱动点**）
    └── LivingWaxedCopperFunction  (prio 3) — 电力记账（依赖红石已算完）
    ↓
ContainerContext (组合接口) → TickContext (tick 级临时状态 + 脏槽位批量同步)
    ↓
SlotAccessor (模拟优先传输 + FilteredSlotAccessor 过滤)

容器级流体/红石数据由 ContainerLivingItemHandler 以「维度+containerKey」为键跨 tick 持久化， 并维护「位置 → 缓存键」反向索引供 mixin 热路径 O(1) 查询。

📄 基础设施详见 living-item-infrastructure.md 📄 数据模型与设计决策详见 data-model.md 📄 框架重构总结详见 framework-refactoring.md

子系统索引

下方全部子系统均已实现（没有列在这里的就是没做）。按族列出，族内每个子系统直链其文档； 每个子系统「做什么」的完整概述见 subsystem-index.md， 逐项能力清单见各 tech 文档 §0（能力口径与不变量以各子系统文档为准，本文只作路由）。

⭐ 读子系统先读它 tech 文档最前面的「§0 玩法定义」（是什么 / 怎么玩 / 规则 / 能力清单） —— 它是功能需求的来源与行为对错的判据（规约见 docs/README.md）。

模块地图

只列目录级职责（根级文件与关键子目录随附）。完整文件树用 find src/main -name "*.java" （人工文件树快照已于 2026-10-10 删除 —— 清单型内容必然漂移，不再维护）。

src/main/java/com/qiqi/li/
├── LivingItem.java                          # Mod 主类：tick 入口、网络包注册
├── LivingItemClient.java                    # 客户端入口
├── living/
│   ├── api/                                 # 公开接口 + 管理器
│   ├── container/                           # 容器抽象层（跨活物品共享基础设施）
│   ├── domain/                              # 领域模块（每个活物品内聚到此）
│   │   ├── hopper/                           #   活漏斗领域
│   │   ├── chest/                            #   活箱子领域
│   │   ├── ender/                            #   活末影箱领域
│   │   ├── furnace/                          #   活熔炉领域
│   │   ├── water/                            #   活水领域
│   │   ├── tnt/                              #   活TNT领域
│   │   ├── farmland/                         #   活耕地领域
│   │   ├── tools/                            #   活工具 / 活武器领域（记忆 + 回放 + 环渲染）
│   │   └── map/                              #   活地图传送领域
│   ├── domain/redstone/                     #   活红石领域
│   ├── domain/power/                        #   红电发电领域（活涂蜡铜块）
│   ├── function/                             # 简单活物品功能（无需领域模块）
│   ├── compat/                              # 第三方模组兼容层
│   │   ├── create/                          #   Create 兼容（软依赖）
│   │   └── sable/                           #   Sable 飞艇兼容（软依赖）
│   ├── components/                          # 无状态工具组件
│   ├── transfer/                            # 传输基础设施
│   ├── interaction/                         # GUI交互
│   ├── model/                               # 配置/方向模型
│   ├── mixin/                               # 服务端 Mixin
│   │   └── create/                          #   Create Mixin（条件加载）
│   ├── debug/                               # 调试工具（默认关闭，命令启用）
│   └── perf/                                # 性能监控
├── client/
│   ├── gui/LivingButton.java                # 活按钮
│   ├── icon/                                # 图标系统（声明式配置）
│   ├── input/                               # 输入处理
│   ├── render/                              # 渲染
│   ├── util/                                # 客户端工具
│   └── mixin/                               # 客户端 Mixin
└── network/                                 # 网络包

合计测试用例 746 个（含参数化展开与 SimpleContainerContextTest 的 @Nested 内部类）； 全绿 = doc_check 第 2 项机械核验（XML 实测 failures/errors 恒 0）—— 取代手维护的 passed 快照数（它随每次加测试必漂：2026-10-10 写下 554 passed，两天后实测已 588）。 已知 @Disabled 为环境性（FML 单测不加载 item tags，已游戏内验证兜住）， 说明与回归入口住 test-map.md。 逐次新增明细见 changelog.md。

📄 测试环境配置与编写约定见 unit-testing.md； 测试文件树（每个测试类守什么）见 test-map.md。

开发进展

📄 完整变更正文：changelog.md（按日期倒序，含全部历史细节）

条目体例（2026-09-22 修订）：本表只放最近 10 条「一行结论 + 指针」—— 完整正文直接写 changelog，不在此铺细节。超出 10 条时删掉最底部一行 （正文早已在 changelog ⇒ 无需迁移、不存在归档操作）。 能沉淀成约束的写进对应的 docs/tech/*.md / docs/system-design/*.md （changelog 是流水，不是约束）。详见 docs/README.md §4。 判据可复算：python tools/doc_check.py 第 4 项（条数 ≤ 10，且最新日期与 changelog 顶部一致）。

当前版本: 以 gradle.properties 的 mod_version 为准（不放快照数字 —— 快照必漂，2026-10-11 实证漏同步一次；alpha 阶段不做旧存档兼容）

排查铁律：原版机制挡路时

遇到「原版 / NeoForge 的某个机制限制了我们」时，按顺序做，别跳步：

1. 先找官方配置入口。 该机制通常留了口子 —— 看到 getter / container / 事件名，就顺着追它的 setter 与调用方。

   🔴 反面案例（2026-09-24）：需要"无视实体无敌帧打出多段伤害"时， 我 grep 到 LivingEntity#hurt 里的 getPostAttackInvulnerabilityTicks()， 却没深追，直接去改 public int invulnerableTime 字段。 而正解是 NeoForge 官方接口： LivingIncomingDamageEvent#getContainer().setPostAttackInvulnerabilityTicks(0) （铁魔法 DamageSources#preHitEffects 正是这么做的）。

2. 确认没有，才考虑改字段 / 反射 / Access Transformer —— 并在代码注释里写明代价（如"生产环境会因混淆失效"）。

⚠️ 跳步的代价：野路子会在 MC / NeoForge 改内部实现时静默失效， 且往往比官方接口影响面更大（波及本不该波及的场景）。 📌 教训：看到 getter 就该想到有 setter，看到 container 就该想到有事件入口。

Mixin 铁律：@Accessor / @Invoker 方法名必须带 living_item$ 前缀

Mixin 的 @Accessor / @Invoker 会在目标类上生成合成方法，名字直接取自接口里的方法名。 如果名字是从原版字段推导的通用名（如 getTarget、getSkipNextRelease），任何其它模组 只要也访问同一个原版字段、起了同名方法，就会在加载该目标类时触发 Incompatible @Accessor ... previously written by ... ⇒ MixinApplyError ⇒ 客户端崩溃 （本模组是「打开创造模式物品栏并点标签页、加载 Slot 时」触发）。

📌 硬性规则：所有 @Accessor / @Invoker 方法名一律加 living_item$ 前缀， 且必须同时显式指定目标成员 —— @Accessor("字段名") / @Invoker("方法名")。 接口名可带 LivingItem 前缀，但方法名前缀才是关键 —— 冲突判定以「在目标类上生成的 方法名」为键，与接口名 / 包名无关。新增访问器 / 调用器前先确认方法名全局唯一。

🔴 前缀的代价（2026-10-11 实测踩坑，启动即 FATAL）：Mixin 靠方法名的 get / is / set（Invoker：call）前缀推断目标成员名，裸 @Accessor + 带前缀方法名 ⇒ 推断失效 ⇒ InvalidAccessorException: Failed to inflect target name ... supported prefixes: [get, is]。「加前缀」与「显式指定成员名」必须成对出现，缺一即崩。

🔴 反面案例（2026-10-11）：

1. SlotWrapperAccessor.getTarget() 与 inventoryessentials（背包必备）的同名 @Accessor 命中同一 CreativeModeInventoryScreen$SlotWrapper ⇒ 崩溃。已改名 LivingItemSlotWrapperAccessor + 方法 living_item$getWrappedTarget()。
2. AbstractContainerScreenAccessor.getSkipNextRelease / setSkipNextRelease 是原版私有字段 skipNextRelease 推导出的通用名，与 getTarget 同一类隐患（只是暂未撞上其它模组）。 已全部加 living_item$ 前缀。

⚠️ @Inject / @Mixin 注入器的 handler 方法名任意（惯例 living_item$xxx），不在目标类生成 同名合成方法 ⇒ 无此碰撞。@Shadow 恰恰相反：它是「别名目标已有成员」，必须与目标成员 同名、不能加前缀（加了 = 解析不到目标而失效）；且 shadow 成员被剥离、不生成新成员 ⇒ 无碰撞风险。（「建议 @Shadow 也加前缀」是 2026-10-11 更正掉的错误说法。）

「以小见大」原则：通用名（原版字段派生 / 短方法名）一律默认有全局碰撞风险， 先加前缀再写，别等撞了才改。

判据可复算：python tools/check_mixins.py —— R1 前缀 / R2 显式成员 / R3 mixins.json 条目·插件 ↔ 源文件 / R4 @Mixin 源文件 ↔ 配置双向一致； 违例即退出码 1（先例同 check_layers.py，可挂 CI / 提交前检查）。

文档导航

文档按层组织（契约 / 实现 / 指南 / 参考 / 归档）—— 分层定义、体量约束与维护规约见 docs/README.md（改文档前先读）。

该读哪一篇：见上方「子系统索引」（每个子系统一行，直链到对应文档）。其余常用入口：