mirror of https://github.com/motajs/template.git synced 2026-10-18 12:40:18 +08:00

unanmed 0d14d32a48 docs(10-03): write hero-equipment, hero-location, map-structure

- 勇士装备：装备槽与实例仓库、装备加成即修饰器、compareEquip
- 勇士位置：坐标、朝向与楼层的获取
- 地图结构：楼层集合、楼层激活、楼层与图层（含事件层）

2026-10-17 18:01:19 +08:00

3.1 KiB

Raw Blame History

勇士装备

勇士的装备系统分两部分：state.hero.equip 管理装备槽（哪件装备穿在哪一栏），state.hero.items.equipment 是装备实例仓库（管理所有已获得的装备实例）。本篇介绍如何用这两组接口。

装备槽（IHeroEquipment）

state.hero.equip 提供：

slots：装备槽位数组，每一项是这一栏的名称；
setSlots(slots)：设置装备槽；
canEquipTo(uid, slot)：判断某件装备能否装备到指定槽，返回 EquipStatus；
equip(uid, slot, autoUnload?)：把装备穿上；
unequip(slot)：卸下指定槽的装备；
equipped(uid)：查询某装备是否处于装备状态；
getEquipped(slot)：取指定槽的装备 uid；
getEquips()：按槽位顺序取所有已装备实例。

slot 可以传装备槽索引（数字）或槽位名称（字符串）。EquipStatus 有三个取值：CanEquip（可以直接装备）、CannotEquip（不能装备）、NeedReplace（需要替换槽位上的装备）。

equip 的 autoUnload 参数默认为 true：当要装备的装备当前穿在别的槽上时，自动把它从原槽卸下。equip 与 unequip 都会返回被卸下的装备 uid（没有则为 undefined）。

const uid = state.hero.items.equipment.add('sword');

state.hero.equip.equip(uid, 0);
const off = state.hero.equip.unequip(0);

装备实例仓库（IHeroEquipsStore）

state.hero.items.equipment 提供：

add(item)：获得一件装备道具、创建实例，返回新实例的 uid；
delete(uid)：移除指定装备实例；
get(uid)：取指定装备实例的状态，与是否装备无关；
instancesOf(equip)：取某件装备的所有实例；
instances()：取当前所有装备实例；
count(item)：取某件装备的实例总数。

const instances = state.hero.items.equipment.instancesOf('sword');
const total = state.hero.items.equipment.count('sword');

装备的加成

每件装备实例（IEquipmentState）对勇士属性提供数值加成与百分比加成，分别通过 getValue / getPercentage 读取，setValue / setPercentage 修改。这两类加成本质上就是勇士属性中的修饰器：装备时把对应的 ValueModifier / PercentageModifier 挂到勇士属性上，卸下时移除，因此不必手动维护加成数值。

const equipState = state.hero.items.equipment.get(uid);
equipState?.setValue('atk', 12);
const atkBonus = equipState?.getValue('atk') ?? 0;

比较装备

compareEquip(equipA, equipB, slot) 用于比较两件装备在指定装备槽上的表现，返回「装备 A 时属性 − 装备 B 时属性」的差值。传入 -1 表示该侧无装备，可用来比较「某件装备相对空槽」的提升。

const diff = state.hero.equip.compareEquip(uid, -1, 0);
// diff.atk 即装备这件装备相对空槽的攻击提升

3.1 KiB Raw Blame History Unescape Escape