《铁与旗 Iron & Banner》创意工坊开发约定（WORKSHOP）

本文件是作者与 Mod 创作者之间的开发契约，不是安全沙箱。平台不会扫描或限制 Mod 代码， Mod 作者必须自律遵守这里的边界；若引用本契约之外的游戏内部对象，作者不承诺兼容。

1. 玩家可以制作哪些 Mod

• 自定义武器：新武器基准（伤害类型/距离/攻速），进入玩家装备与战利品池
• 自定义装备：武器/身甲/头盔/坐骑四槽位物品，进市场、军械商、战利品掉落
• 自定义兵种：新兵种（属性/武器/远程/骑行/持盾），可被招募、驻防、参与坐镇与守城
• 扩展升级链：把新兵种接在已有兵种之后
• 玩家外观：覆盖玩家部队披挂配色（布料色/饰边色，十六进制）
• 事件驱动内容：订阅战斗/世界事件做数据展示、统计、提示（不控制战斗）
• 只读查询：读取玩家等级/金币/天数/兵力/领地数量

2. 公共对象

对象	位置	说明
window.IronAndBannerModApi	启动前已挂载	唯一官方 Mod 接口（见下节）
window.VibeHubWorkshop	官方 Loader 提供	beforeStart / markGameReady() / afterStart / getEnabledMods()；不要修改其任何内部属性

游戏不对外暴露 G（游戏状态单例）、DOM 节点、渲染对象或内部函数；访问它们不算接口，随时可能破坏。

3. 注册函数（必须在游戏启动前调用，即 beforeStart 之前）

所有注册返回 { ok: true } 或 { ok: false, reason }；reason 取值示例：invalid id / invalid def / duplicate / unknown weapon ref / invalid slot。

id 规则：仅小写字母/数字/点/横线/下划线，1-48 字符，以字母数字开头。同 id 重复注册返回 duplicate 且不覆盖已有内容。

const api = window.IronAndBannerModApi

// 1. 声明自己（元信息，用于冲突诊断；可省略）
api.registerMod('my_mod', { name: '我的旗帜', version: '1.0.0' })

// 2. 新武器基准（weapon ref）
api.registerWeapon('my_mod', 'war_scythe', {
  name: '战镰', type: 'cut', damage: 30, reach: 3.1, speed: 0.9
})

// 3. 新装备（weapon 槽引用上面注册的 ref；armor/速度按槽位）
api.registerItem('my_mod', 'w_war_scythe', {
  name: '战镰', slot: 'weapon', ref: 'war_scythe', price: 260
})
api.registerItem('my_mod', 'a_scale', { name: '鳞甲', slot: 'body', armor: 26, price: 420 })

// 4. 新兵种（weapon 引用已存在武器；upgrades 指向已存在或本 Mod 内后续注册的兵种 id）
api.registerTroop('my_mod', 'black_guard', {
  name: '黑曜卫兵', branch: 'inf', tier: 5, hp: 118, speed: 4.4, armor: 48,
  weapon: 'greatblade', shield: true, cost: 360, wage: 16
})

// 5. 玩家外观（只影响本地表现；传十六进制整数）
api.registerAppearance('my_mod', { playerClothHex: 0x14141a, playerTrimHex: 0xd8b45a })

// 6. 事件订阅（可随时调用；返回 { ok, off }）
api.on('battle_finished', e => console.log('战斗结算', e.outcome, e.killedEnemies))

// 7. 只读查询（启动后可用）
if (api.getPlayerInfo()) console.log(api.getPlayerInfo().day)

参数表

注册函数	参数	说明
registerMod(modId, {name, version})	modId 唯一	声明元信息
registerWeapon(modId, refId, {name, type, damage, reach, speed, projectile?})	type ∈ cut/pierce/blunt	新武器基准
registerItem(modId, itemId, {name, slot, ref?, armor?, speed?, price})	slot ∈ weapon/body/helmet/horse	新装备；weapon 槽必填 ref
registerTroop(modId, troopId, {name, branch, tier, hp, speed, armor, weapon, ranged?, mounted?, mountSpeed?, shield?, upgrades[], cost, wage})	branch ∈ inf/arc/cav；tier 1-5	新兵种
registerAppearance(modId, {playerClothHex?, playerTrimHex?})	—	玩家配色
on(event, handler) / off(event, handler)	见事件表	事件订阅
getPlayerInfo()	—	{level, gold, day, partySize, morale, towns} 只读快照（启动前为 null）

4. 事件及参数

事件	时机	payload（只读快照）
battle_started	战斗场景就绪	{ siege, defend, tournament, allyCount, enemyTotal }
battle_finished	战斗分出胜负	{ outcome, killedEnemies, lostAllies, siege, defend, tournament }
unit_killed	任意单位阵亡	{ faction, troop, isPlayer, isGarrison, x, z }
day_passed	每日结算	{ day, weather, gold, taxes, wages }
town_captured	玩家占领据点	{ townId, name }
player_level_up	玩家升级	{ level, attrPoints }

处理器异常会被捕获并打印，不影响游戏。事件 payload 是快照——修改 payload 不会影响游戏。

5. 最小可运行 Mod（完整示例）

// my-first-mod.js —— 在创意工坊中作为已启用 Mod 加载
const api = window.IronAndBannerModApi
if (!api) { console.warn('Mod API 未就绪'); return }

api.registerMod('demo_black_armor', { name: '黑甲军团', version: '1.0.0' })
api.registerItem('demo_black_armor', 'a_black_plate', {
  name: '黑曜板甲', slot: 'body', armor: 46, price: 1200
})
api.registerTroop('demo_black_armor', 'black_guard', {
  name: '黑曜卫兵', branch: 'inf', tier: 5, hp: 118, speed: 4.4, armor: 48,
  weapon: 'greatblade', shield: true, cost: 360, wage: 16
})
api.registerAppearance('demo_black_armor', { playerClothHex: 0x14141a })
api.on('battle_finished', e => {
  console.log('[黑甲军团] 战斗结束:', e.outcome)   // 只记录，不控制
})

6. 加载时机

• 启动前（beforeStart 之前）：所有 registerMod / registerWeapon / registerItem / registerTroop / registerAppearance
• 启动后：on 事件订阅、getPlayerInfo 只读查询
• 启动前注册的内容会进入存档校验白名单（详见第 9 节）

7. 前置依赖与加载顺序

• 允许：一个 Mod 内部先注册武器基准再注册引用它的物品/兵种（同一脚本内顺序执行）
• 禁止跨 Mod 依赖：加载顺序不保证；联动请运行时检查 getRegistrySnapshot() 中对方 id，缺失时优雅降级
• beforeStart 是唯一的「全部 Mod 就绪」信号；不要依赖脚本在页面中的排列顺序

8. 多 Mod 命名、去重与冲突规则

• 命名空间：所有资源 id 全局唯一；使用 mod前缀_ 前缀降低撞车概率
• 去重：同 id 重复注册 -> 后到者收到 { ok:false, reason:'duplicate' }，先注册者保留，游戏内容不变
• 冲突展示：getModsSnapshot()（Mod 元信息）与 getRegistrySnapshot()（资源到属主映射）用于发现冲突；作者不提供自动合并
• Mod 之间不要约定互相改写；一切影响通过注册与事件完成

9. 存档、加载顺序与游戏版本兼容

• 存档：localStorage 键 iron_banner_* 由游戏读写；Mod 不得直接读写（防止坏档与作弊）
• 卸载 Mod：存档中来自已卸载 Mod 的物品/兵种会在下一次读档时被校验丢弃（不会崩档），装备回退默认值
• 游戏版本：API_VERSION = '1'；package.json version 0.1.0。API 变更会提升 API_VERSION 并在更新说明注明；破坏性变更前提供至少一个版本双轨支持
• 读取已注册内容：getRegistrySnapshot() 返回资源到属主映射；不提供修改

10. 联机策略

本游戏为纯单机；工坊联机策略为 mods-disabled（联机前拒绝任何已启用 Mod）。能力声明仅用于展示，不是安全沙箱。

11. 明确禁止的能力

• 访问或修改游戏内部状态单例（G）、私有 DOM、渲染/骨架对象、内部函数与原型链覆盖
• 读写 localStorage 存档、账号凭据、Token、管理接口、VibeHubWorkshop 内部字段
• 覆盖、替换已注册内容或事件处理器链（只能新增，不能删除他人）；不保证 handler 顺序
• 无限循环、持续高帧率工作或常驻 requestAnimationFrame（Mod 渲染需自行封装并节流）
• 引入外部网络请求读取隐私数据、广告或跟踪脚本