月咏大陆

用 Rust (macroquad) 重写的 2D 探索 RPG。

目录

• 技术栈
• 当前状态
• 待办清单

---

技术栈

• 引擎: macroquad 0.4
• 数据格式: JSON + serde 反序列化
• UI: 自研布局引擎 (src/ui/engine/) + 全局覆盖层 (src/ui/global/) + 面板 (src/ui/panels/)
• 资源路径: 所有数据文件位于 assets/ 目录

---

当前状态

已完成功能

• 基本移动、攻击、对话、交易
• 装备系统（化合等级 + 隐藏属性）
• 属性加点（力量/体力/敏捷）
• 任务系统（主线 初试锋芒 + 支线 每日猎猪/宠物伙伴）
• 宠物系统（火狐跟随 + 帧动画）
• 全局 UI（HUD、快捷栏、小地图、聊天框、任务列表、采集条）
• 多轮对话系统（steps 逐句推进）
• 地图传送（portal 系统）
• 怪物刷新、掉落、变异
• 存档/读档

---

待办清单

第一阶段：战斗系统完善

• CombatConfig 的命中/闪避/暴击/攻速公式接入实际战斗计算
• element 元素系统接入伤害计算（element_fluctuation() 目前未调用）
• 等级差惩罚 (level_penalty) 接入
• 怪物 strength_offset/stamina_offset/agility_offset 用于属性计算（已有字段但公式只用了等级）

第二阶段：任务系统修复

• ReachLevel 类型任务目标 — add_exp() 升级时 emit QuestEvent::LeveledUp
• ExploreMap 类型任务目标 — 地图切换时 emit QuestEvent::MapExplored
• 任务 JSON 的 in_progress 节点统一使用 steps 格式（chief_first_hunt.json 仍有 text 字段）

第三阶段：数据驱动化

• 锻造配方从 JSON 读取（目前硬编码在 crafting_ui.rs:32-57）
• NPC 商店从 JSON 读取（目前硬编码在 npc_interaction.rs:158-177）
• 猪/熊装备 JSON 文件创建（pig_shield.json 等不存在，导致 Equipment::from_id() 不能用于它们）
• 装备构造器 new_pig_shield() / new_pig_gloves() / new_bear_chest() 等改为 JSON 驱动

第四阶段：性能与架构

• 通用 JSON 加载器提取（6 个 data 模块重复的 read_dir → filter → parse → insert 模式）
• render/resource.rs 拆分（动画 → render/anim.rs，伤害数字 → render/damage.rs）
• 双 draw_rounded_rect 合并（ui/engine/core.rs 和 ui/global/fixed.rs 各有一份）
• 敌人 is_chasing 状态对外可见（目前写了但无人读取）

第五阶段：目标血条（预留 feature）

• GlobalUiState.set_target() / clear_target() 已定义，待战斗系统稳定后接入
• 点击怪物时调用 set_target()，怪物死亡或脱离时调用 clear_target()
• UiSkin.panel_deco 已定义，待花边贴图就绪后接入

第六阶段：新内容

• 更多怪物、装备、地图
• 宠物成长系统（Pet::add_exp() 已定义但未被调用）
• 技能系统扩展（skill_effect_range_dmg(), skill_effect_heal() 已实现）
• 物品 pet_egg 的孵化功能（effects.use = "hatch_pet" 从未被处理）

已知技术债务

• Player::target_tile 字段被写入但从未被读取

• Player::skill2_timer / skill8_timer 递减但从未被检查

• MonsterTemplate.spawn 的 min_per_map / max_per_map / dist_from_spawn 字段从未使用

• CraftingDef / CraftingMat / ItemDef.crafting 整块死代码（JSON 读到但不用）

• 寻路 find_path 使用 8 方向但启发了 4 方向 — 已修复为切比雪夫距离

• 装备 panel_deco 始终为 None（UiSkin 预留字段，待花边贴图就绪）

• 疲劳值 draw_fatigue 始终显示 0/100（桩代码，待功能实现）

• GlobalUiState::add_global_message() 便捷包装器未直接调用（内部通过 add_global_message_duration 间接使用）

• GlobalUiState::set_target() / clear_target() 未接入（目标血条 feature 预留）

• Registry<T> 泛型注册表已提取但现有 6 个 data 模块尚未迁移

• 语言: Rust (edition 2024)

• 引擎: Macroquad 0.4

• 寻路: 自实现 A*

• 配置: JSON 驱动所有游戏数据

架构

src/
├── main.rs                 # 游戏主循环
├── game_state.rs           # GameState 状态聚合
├── utility/                # 输入处理、常量、存档
├── entity/                 # Player / Enemy / NPC / Item / Inventory / Quickbar / Equipment
├── render/                 # map 加载/绘制、resource 绘图原语
├── behavior/               # A* 寻路
├── interaction/            # 战斗系统
├── data/                   # JSON 注册表加载
│   ├── items.rs            # 物品注册表（药水/技能/装备/材料）
│   ├── monsters.rs         # 怪物注册表（含掉落表内嵌材料定义）
│   ├── npcs.rs             # NPC 注册表
│   ├── player.rs           # 玩家初始属性 + 快捷栏配置
│   ├── maps.rs             # 地图注册表
│   └── keymap.rs           # 按键映射
├── mapgen/                 # 地图程序化生成算法（离线用）
└── ui/                     # HUD / 背包 / 锻造 / 对话框 / 快捷栏 / 小地图

数据驱动设计

所有游戏数据由 JSON 驱动，注册表在启动时加载到 OnceLock 全局缓存：

assets/data/
├── player.json                     # 初始属性 / 升级公式 / 快捷栏布局
├── keymap.json                     # 按键映射
├── map_registry.json               # 地图注册表（ID、名称、PNG 路径、传送门编号配对）
├── registered_item/                # 物品注册表
│   ├── small_potion.json
│   ├── large_potion.json
│   ├── gold.json
│   ├── skill_basic_attack.json
│   ├── skill_aoe.json
│   ├── skill_heal.json
│   └── monkey_bow.json            # 装备 + 锻造配方
├── registered_monster/
│   ├── pig.json                   # 淘气猪
│   └── monkey.json                # 顽皮猴（材料掉落定义内嵌）
└── registered_npc/
    └── chief.json                  # 野柳村村长

地图系统

地图通过注册表管理，所有地图统一走 Map::load(id) 从 PNG 加载：

assets/maps/
├── map_registry.json    # 统一注册
└── png/                 # 地图 PNG 文件
    ├── willow_village.png   # 128×128 野柳村（全浅色，新手区）
    └── wild_forest.png      # 128×128 绿野森林

传送门编号配对：每张图的传送门按 target_index 编号。进入编号 N 的传送门 → 传送到目标地图的编号 N 传送门，不硬编码坐标。

离线地图生成（src/mapgen/）：蛇形障碍物从边缘深入 + 椭圆深色区 + 元胞自动机平滑。examples/gen_map.rs 可批量生成 PNG。

地图生成算法

128×128 格，gen_map(seed, portals, entry_y) 一次调用完成：

1. 蛇形障碍物 — 从右边缘指定 Y 坐标进入，75% 动量保持方向，遇边（<30 格）渐进惩罚强制转向，赢者通吃倾斜生长，目标 ~1/9。
2. 零星障碍簇 — 距主体 ≥12 格处 4 个小簇（4-12 格）。
3. 填充 — 3/4 邻居填充 + ≤9 格孤立岛填充。
4. 深色区 — 3 个 seed 按 Y 轴分段分配，最小堆椭圆代价展开，保证间距 ≥5 格。每 seed 配额 2000 格，不足则回退补量。
5. 平滑 — 元胞自动机（8 邻域，<3 腐蚀 / ≥5 膨胀，2 轮）消除锯齿。
6. 传送门 — 支持手动指定或自动放置（距障碍物 ≥4 格，不被围）。

当前功能

功能	说明
移动	WASD / 方向键 + 鼠标点击寻路
快捷栏	0-9 键，物品/技能混排，冷却管理读 JSON
战斗	左键点怪 / 技能 1 自动锁定最近敌人 / 技能 2 范围攻击 / 技能 8 治疗
怪物	淘气猪、顽皮猴，JSON 配置属性 + 渲染 + 掉落 + 重生间隔
NPC 对话	走近高亮 → E 触发，对话树 JSON 配置
背包	B 键，↑↓←→ 选择，Enter 装备/卸下，S 出售
锻造	C 键，材料 + 金币读 monkey_bow.json 配方
装备	7 槽位，武器属性读 JSON
传送	编号配对，不硬编码坐标
重生	每怪种独立追踪 refresh_interval
小地图	Tab 键，右上角

快速开始

cargo run