# npmc **Repository Path**: w-8/npmc ## Basic Information - **Project Name**: npmc - **Description**: mc server rewrite by ai - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-22 - **Last Updated**: 2026-09-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # npmc Rust 编写的模块化 Minecraft 服务器。 **架构核心：协议层 = 内核，玩法功能 = 模块（Linux 内核/驱动模型）** * 仅支持最新版 Minecraft **Java Edition 26.2** * 协议层（连接状态机、加密、压缩、认证、包编解码）是服务器核心，不包含任何玩法逻辑 * 所有玩法功能（玩家生命周期、聊天、命令、世界时间/天气、战斗、饥饿、经验……）都是可插拔模块 * 当前阶段**不追求性能**，只要求可维护性与快速功能验证/迭代 ## 快速开始 ```bash # 需要 Rust 1.95+（stable） cargo build -p npmc-server --release # 运行（首次启动会生成 npmc.toml 配置文件与 world/ 世界目录） cargo run -p npmc-server ``` 启动后控制台可用命令：`help`、`modules`、`stop` 等；游戏内可用 `/help`、`/gamemode`、`/tp`、`/time`、`/weather`、`/list` 等。 > 默认配置 `online_mode = true`（需要正版账号）。测试时可改 `npmc.toml` 中 > `[networking.java] online_mode = false`。 ### 动态模块（玩法热插拔） ```bash # 编译动态插件（示例：事件调试器） cargo build -p npmc-mod-example-dynamic # 把产物复制到 modules/ 目录（服务器启动时自动加载） cp target/debug/npmc_mod_example_dynamic.dll modules/ # 配置 npmc.toml # [modules] # enabled = true # dynamic_dir = "modules" # exclude = [] ``` 改插件代码只需 `cargo build -p that-plugin`，无需重编服务器。 ## 工作区结构 ``` npmc/ ├── crates/ │ ├── npmc-util / npmc-nbt / npmc-codecs / npmc-config # 内核基础设施 │ ├── npmc-data # 注册表数据（方块/物品/实体/生物群系，生成代码） │ ├── npm-world-core # 世界存储核心（Level/区块接口，由原 npmc-world 拆出） │ ├── npmc-protocol # 协议包定义（26.2，生成代码） │ ├── npmc-inventory # 物品栏核心 │ ├── npmc-kernel # ★ 服务器内核：协议核心 + 模块管理器 + 动态插件加载器 │ ├── npmc-module-api # 模块公共接口（KAPI）+ 动态模块宏 + MobService 等跨模块 trait │ └── modules/ # ★ 玩法模块（31 个 cdylib 动态插件）+ 世界/AI 纵切库 crate │ ├── npm-world-gen / world-engine / world-chunk / world-info / world-inventory │ │ # 世界生成/引擎/区块/信息/物品栏世界侧库（自旧 npmc-world 纵切） │ ├── npm-block-core / npm-block-red / npm-block-container │ │ # 方块实体+随机刻 / 红石·活塞 / 容器窗口库（自 mod-block 纵切） │ ├── npm-entity-core / npm-entity-motion │ │ # 实体注册与 AI 核心 / 移动几何+A* 寻路（自 mod-entities 纵切） │ ├── npmc-mod-player / chat / commands / world / block / item / inventory │ ├── npmc-mod-vehicles（船/矿车/盔甲架/画/展示框 + 坐骑挂载窗口） │ ├── npmc-mod-boss（凋灵/末影龙）/ npmc-mod-villager（交易窗口 + 袭击/raid） │ ├── npmc-mod-combat / hunger / experience / scoreboard / bossbar / effects │ ├── npmc-mod-advancements / entities / datapack / waypoints / systems26 │ ├── npmc-mod-gamerules / home / lighting / sleep / worldborder / rcon / query / lan │ └── npmc-mod-example-dynamic（示例） ├── modules/ # ★ 动态插件部署目录（编译后自动复制到这里，服务器启动时加载） ├── npmc-server/ # 可执行程序（只含内核，不链接任何玩法模块） ├── build_common.rs # 动态模块构建辅助（产物自动复制模板） ├── docs/ │ ├── ARCHITECTURE.md # 架构设计（内核/模块模型详解） │ ├── MODULE_GUIDE.md # 模块开发指南 │ └── porting.md # 功能模块映射与实现状态 └── scripts/ # 构建与冒烟测试脚本 ``` ## 玩法模块全动态化 **所有玩法模块均为 cdylib 动态插件**（`modules/` 目录，服务器启动时扫描加载）： ```bash # 编译单个模块：产物自动复制到 modules/ 目录（build.rs watcher） cargo build -p npmc-mod-player # 或全量构建 cargo build -p npmc-server -p npmc-mod-advancements ... # 启动服务器（自动加载 modules/ 下全部 .dll/.so/.dylib） cargo run -p npmc-server ``` 动态化约束：插件与服务器同 rustc 版本编译；插件内不直接 `tokio::spawn`（用 `ctx.spawn` / 事件处理器内直接 await / commands 的 spawner 桥）；跨模块数据经内核对象字段（如 World 时间/天气）。 ## 验证状态 | 项目 | 状态 | | ------------ | ------------------------ | | 真实 MC 客户端端到端 | ⏳ 需本机 MC 客户端实测（建议先用离线模式） | 自动化测试：`cargo run -p npmc-simclient`（tools/npmc-simclient，无头协议测试客户端， 跑通 login→config→play→聊天→命令全链路）。 ## 26.2 完成度对照（未完成清单） > 2026-08-28 对照 26.2 反编译服务端逐条复核，2026-08-29/30 复核对齐并落地当日审计修复（摔落伤害、 > 投射物命中生物、silk touch 掉落、触发器路由 35→44 等）；2026-08-31 按 08-30 全量差距审计 > [262-gap-audit-20260830.md](docs/262-gap-audit-20260830.md) 同步本文：已完成条目全部移除（历史经 git 可查）， > 并收编审计新发现桩点。逐轮判定证据见[核对台账](docs/262-verification-20260828.md)。 > 基准：Minecraft **Java Edition 26.2** 反编译服务端（protocol 776 / world 4903 / data 107）。 ### 领域状态总览 | 领域 | 条目 | 剩余待办 | | -------- | ------------------------------ | --------------------------------------- | | 命令 | 95 条原版 | 4 处桩点（回切/推送/纹饰/可视化，见下） | | 实体 | 90 mob | 客户端渲染边界 4 项；击退抗性/驯服随从行为缺口；数值近似 | | Boss | 凋灵/末影龙 | 凋灵冲撞+BossBar 分格；龙呼吸线扇形+跨维度 | | 投射物 | 20 种 | 效果粒度（生物药水面/蓄力曲线/浮标/烟花） | | 方块 | 468 类 | 客户端边界 1 项（唱片机循环音）+ 4 项近似 | | 物品 | 438 类 | 客户端边界 4 项；成书 JSON/附魔台经验/附魔消费面缺口 | | 容器 | 25 MenuType | 铁砧点击 MVP；熔炉窗口 offhand 槽 | | 进度 | 26.2 canonical ~52 触发类型，已路由 44 | 未路由 10 名（机制依赖）；高级条件/事件源边界一批 | | 统计 | 9 类别 | 1 项（time_since_death/rest） | | 战利品表 | 49 函数 + 25 条件 | 受限函数 + canonical 缺口；采样不足 | | 数据包 | 71 目录类 | damage_type/enchantment 进求值器；play 动态推送 | | 26.2 新系统 | 6 类 | 3 项剩余边界 | > 核心循环（挖掘/放置/合成/烧炼/战斗/生存，摔落伤害已并入）与世界系统（时间/天气/边界/睡眠/生成）无剩余待办，故不在本清单。 ### 未完成条目清单 **命令（95/95 条原版命令有 handler；剩余 4 处桩点）** * 剩余 4 处桩点（返回明确错误回包，代码留 `STUB:` 标记）：`debug-config` play→config 回切（连接状态机未支持）；`serverpack` play 阶段 push/pop 包未生成（回退发 config 阶段 `CConfigAddResourcePack`；与数据包 play 动态推送同源）；`spawn-armor-trims` 纹饰注册表查询面缺失（smithing trim 合成已可用）；`debug-path` 方块级可视化（debug 类包未接；A* 求路 + 路径长度/可达性回包已可用） **实体** * 客户端渲染边界（服务端无法覆盖，已用近似替代）：Sonic Boom beam、木灵背部眼位节点、流浪商人隐形货物渲染、哞菇炖菜 tooltip 效果列表未验证 * 行为缺口：击退抗性属性未入击退结算（combat lib.rs:299）；驯服动物随从行为（忠诚跟随/坐下/受击反击）未实现（taming.rs:15，驯服成功判定为原版逐次尝试语义的近似）；注：繁殖求爱状态机（in_love 粒子/心跳，600 tick 求爱窗口 + 配对范围 4 格）已于 v0.14.0 实现（mob.rs:1258-1331；breeding.rs 文档未同步） * 数值近似：骷髅马陷阱、僵尸增援 25%（原版 Normal 50%）、猪灵以物易物 loot 子集、铁傀儡补货固定周期 **Boss** * 凋灵紧贴冲撞、BossBar 分格归属。_计划：护盾期结算按原版每目标朝向判定后施加 WitherDistCapped 冲撞速度，BossBar 分格随护盾量下发 setHealth 分段阈值_ * 末影龙呼吸线缺扇形扩散与跨维度坐标缩放。_计划：呼吸时对扇形角度内 3-5 条射线各跑一次 breath\_line；跨维度在多世界落地后接坐标缩放表_ **投射物（效果粒度）** * 药水效果边界：生物侧仅即时伤害/治疗（其余状态效果未对生物建模）；滞留药水仅对玩家施效；`custom_effects`（命令药水）不随投射物携带（仅按 potion\_id 解析）；喷溅返还玻璃瓶为「投掷即返还」（未等落地）。_计划：MobService 加通用 `apply_effect_to_mob` 状态面（MobState 挂 effects 表），投射物把完整 EffectInstance 列表传下去；custom\_effects 随 ItemStack data component 序列化携带；玻璃瓶改为命中落地点后生成 ItemEntity_ * 弓/弩蓄力伤害随弦距曲线未接入；浮标沉浮/诱鱼动画未接；烟花无爆炸/多段星形（projectile.rs:86）。_计划：弓蓄力伤害在 SInteract/SUseItem 的拉弓 tick 差值算系数乘基础伤害；烟花爆炸复用 broadcast\_explosion + 星形粒子多段循环_ **方块** * 客户端渲染 / 原版即无（服务端无法覆盖）：唱片机循环音（客户端音频） * 近似实现：红石信号源布尔近似（强 15）、容器比较器读填充近似 1、作物生长光照门限以天空光近似（原版 `getRawBrightness ≥ 9`）、目标方块命中强度无面命中 voxel 精度 **物品（客户端权威边界 + 消费面缺口）** * 客户端权威边界（服务端不处理）：地图 exploration 装饰渲染、浮标沉浮动画、鞘翅「滑翔抵消落地伤害」判定、栅栏结可见实体渲染 * 成书页内容按 `§` 纯文本处理（原版为 JSON 富文本 component，未解析）；页数（100）/单页字数（1024）上限已读包截断（clamp_pages，books.rs:68-87） * 附魔台经验消耗按等级直扣（原版按经验点数公式，enchanting.rs:8） * 附魔效果消费端缺口：`sweeping`/`depth_strider`/`respiration`/`aqua_affinity`/`breach`/`lunge`（26.2 新）仅注册无运行时效果；生物受击侧无护甲/附魔减伤结算（protection 已接玩家受击、Feather Falling 已随摔落伤害接入；已接入面见 gap 审计 §三） **容器/窗口** * 铁砧点击 MVP 简化：slot=0 button 0-2 附魔选项直换（click.rs:63） * 熔炉窗口 offhand/装备槽不携带（furnace.rs:39、open.rs:94） **进度 advancements（事件面 43 触发器；26.2 canonical ~52 触发类型已路由 44）** * 未路由触发器 10 名（数据包 criterion 不授予，均机制依赖）：`fall_after_explosion`（需爆炸击退速度）、`slide_down_block`（蜂蜜块滑动）、`cured_zombie_villager`、`kill_mob_near_sculk_catalyst`、`allay_drop_item_on_block`、`avoid_vibration`、`hero_of_the_village`（袭击胜利判定未建模）、`player_sheared_equipment`、`ride_entity_in_lava`、`crafter_recipe_crafted`（合成器无配方 id 记录） * 计划推进（2026-09）：③ `target_hit` 红石数值化写回已实现——投射物命中后按强度写方块 `power`（0-15）并广播 CBlockUpdate（projectile.rs `target_power_write_back`）；① 配方 id 链路已打通——`PlayerCraftItem` 新增 `recipe_id` 字段（数据包覆盖配方携带 id），`recipe_crafted` 按 `conditions.recipe` 精确匹配（生成静态配方未采集 id，待重跑数据生成）；`entity_hurt_player` 按伤害源细分（`conditions.damage` 的 is_projectile/is_explosion/is_lightning，对照 source 字符串）；② `tame_animal`/`bred_animals` 已在驯服/繁殖成功时派发既有事件（mob.rs tame_animal/finalize_breeding）。剩余：鞘翅滑翔距离等内核事件字段、伤害源实体（attacker entity）结构化字段、磁石 3×3×3 认块、voluntary_exile 进村触发（voluntary_exile.rs:16）、生成静态配方 id 采集。逐项验收 criterion 全字段命中为真 **统计（scoreboard）** * `time_since_death`/`time_since_rest` 事件源占位未激活（需死亡/床事件配合） **战利品表** * 受限函数（缺数据/建模，见 `npmc-data/src/loot.rs` unsupported 分支）：SetAttributes（缺 attribute 名解析）、SetLore（`LoreImpl` 单元结构）、CopyComponents/CopyCustomData（上下文源建模）、ExplorationMap/SetBookshelfContent/SetItemAttachments/SetContents（组件与数据缺失） * 按 26.2 canonical 口径函数覆盖 34/42：另缺解析侧类型 `copy_name`/`set_banner_pattern`/`set_book_cover`/`set_components`/`set_firework_explosion`/`set_fireworks`/`set_random_dyes`/`set_random_potion`/`set_stew_effect`/`toggle_tooltips`/`filtered`/`sequence`/`modify_contents`/`set_loot_table`（未知 id 走回退路径）；反向 `SetTNTCount`/`SetItemModel` 为 npmc 侧类型、26.2 canonical 表未见（疑 26.2 移除/改名，待核）。条件侧 `environment_attribute_check` 已落地（loot.rs 求值保守不通过、mob_kind MVP 按通过，环境属性未建模） * 内置数据采样不足：生成内置数据仍只采部分函数样本；数据包覆盖路径支持条目级 functions/conditions 的简化子集。_计划：扩数据采样或靠数据包覆盖补常用表_ **数据包** * damage\_type/enchantment 注册表覆盖面未进求值器（damage\_source/附魔条件现用 ctx 字段近似）；进度侧 predicate（criterion 内联谓词）归高级条件范畴 * play 阶段动态资源包推送：`/serverpack` 命令已落地（26.2 字面量；push 对在线玩家回退发 config 阶段 `CConfigAddResourcePack`、pop 为桩），但 play 阶段 `ClientboundResourcePackPush`/`Pop` 包未生成（协议 id 在表，crate 未生成结构体）——剩余：play 阶段 push/pop 包生成与接线（login 配置化下发仍在，kernel login.rs:385） **26.2 新系统（剩余边界）** * Chase mob 泛化（需实体注册服务）；Dialog 按钮 NBT 字段以客户端实测为准；JSON-RPC 插件通道消费端示例 ### 验证方式 1. `cargo build --workspace` 编译通过；2. 服务器冒烟无 panic；3. 代码级对照原版数值；4. simclient 全链路。 ### 代码规模（2026-08-28 实测） 手写 Rust 886 文件 / 182,595 行（排除 generated/target）；生成数据层（`npmc-data::generated`，注册表/进度/翻译）≈1.44M 行。大量实现依赖生成的全量 26.2 注册表作为数据底座，手写逻辑在此基础上做机制与玩法实现。 ## 性能优化候选（未实施） > 仅记录候选，不承诺时间表；已实施项不再列出（历史见 git）。 | 项 | 现状 | 建议 | | ---------- | ----------------------------------------------- | --------------------------------------------------- | | WorldTick 频率 | `kernel.tick()` 仅 `tick % 10 == 0` 派发 → 玩法模拟实际 2Hz | 改每 tick 派发，慢系统（自然生成/袭击）自行降频 | | 区块加载 | ticket 等级传播半径随客户端视距、加载下沉发视距 | 加载 radius 维持=下发视距（勿放大到服务端视距，避免为不可见范围过度生成） | | 广播序列化 | `broadcast_java_packet`/`send_chunks` 每玩家各序列化一次 | 序列化一次 → 分发 `Bytes`（O(1) 克隆） | | Player 位置 | `position()/yaw()/pitch()` 三次独立 RwLock 读锁 | 提供一次快照 / 换 `AtomicCell` | | 内核门面 | `Kernel` 全部字段 `pub`，模块直摸内部 | 抽窄 `KernelApi` facade，重字段 `pub(crate)` | ## 现状问题与技术债（2026-08-28 源码核读） > 只收「必要」横切项：玩法缺口见上方未完成清单，性能候选见上节。 | # | 问题 | 现状（2026-08-28 实测） | 影响 / 决策方向 | | - | -------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | 1 | 玩法 tick 实际 2Hz | `WorldTick` 仍嵌在 `kernel.tick()` 的 `tick % 10` 分支内派发 | 熔炉烧炼、掉落物物理、挖掘进度等玩法模拟与原版 20Hz 游戏刻语义不齐（慢 10 倍）；待决策改每 tick 派发（与上节优化候选同项） | | 2 | 动态插件 Rust ABI 硬约束 | 插件必须与服务器同 rustc 版本；Windows 下 DLL 加载后被锁定无法热卸载；插件内禁直接 `tokio::spawn`、`tracing` 日志不可见 | 动态加载定位为**调试期快速迭代**手段；生产稳定版应将模块静态链接合并（与 ARCHITECTURE.md 口径一致） | | 3 | 事件总线无同步取消语义 | v2 总线 channel 异步投递：每订阅者独立 FIFO 保序、跨模块之间无序 | 「取消/拦截」靠模块自主决策（如聊天模块不广播），无裁决点；需要顺序或裁决保证的逻辑必须收敛进同一模块或改走服务表，新增模块时注意 | | 4 | 内核遗留已知行为未收敛 | P0-P6 解耦后 4 项留档（详见 ARCHITECTURE §9.2）：`/difficulty` 修改不回写 level.dat（重启回退，仅启动时读取）、背包同步后移至 PlayerJoin（进服瞬间可能短暂空背包）、idle 超时默认 0 休眠、portal 生成期规则为 MVP 恒等实现 | 均为已知行为非回归；按需逐项决策：难度落盘、spawn 序列内联背包、配置启用 idle、真接 portal 规则 | | 5 | 数据底座与执行端深度不对称 | 注册表/类型层全量先行（生成代码 ≈1.44M 行），运行时机制深度不均 | 各域缺口已台账于上方未完成清单（如战利品受限函数、进度高级条件），不在此重复 | | 6 | 世界引擎继承上游 TODO | 世界引擎继承 Pumpkin 的 116 处 TODO（heightmap 追踪、chunk saver 归属等内部实现债） | 内部实现债，按需逐项收敛 | | 7 | 存量单测失败 | `npmc-util` noise::perlin `tests::no_y_chunk` 为存量失败（上游 Pumpkin 测试债，HEAD 复现） | 修复或上游跟进；与玩法功能无关 | ## 文档 * [架构设计](docs/ARCHITECTURE.md) * [模块开发指南](docs/MODULE_GUIDE.md) * [功能模块映射与实现状态](docs/porting.md) * [26.2 实现程度核对台账](docs/262-verification-20260828.md) * [26.2 全量差距审计（2026-08-30）](docs/262-gap-audit-20260830.md) ## 许可 GPL-3.0