AncTe/template
1
0
Fork 0
mirror of https://github.com/motajs/template.git synced 2026-10-20 05:40:18 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(10-10): 引导式重写 hero-items、hero-equipment

Browse Source
This commit is contained in:
unanmed 2026-10-17 21:22:33 +08:00
parent ef8cd06c07
commit b4d1202a74
2 changed files with 22 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/intermediate/hero-equipment.md
View File

@ -1,10 +1,10 @@
# 勇士装备
勇士的装备系统分两部分：`state.hero.equip` 管理**装备槽**（哪件装备穿在哪一栏），`state.hero.items.equipment` 是**装备实例仓库**（管理所有已获得的装备实例）。本篇介绍如何用这两组接口。
装备是一种特殊的道具：它要穿到某个槽位上，并给属性加成。为了把「穿在哪」和「拥有哪些」分开管，装备系统分成了两部分——`state.hero.equip` 管理**装备槽**（哪件装备穿在哪一栏），`state.hero.items.equipment` 是**装备实例仓库**（管理所有已获得的装备实例）。本篇介绍如何用这两组接口。
## 装备槽（IHeroEquipment）
`state.hero.equip` 提供：
`state.hero.equip` 管的是「穿在身上的装备」，它提供：
- `slots`：装备槽位数组，每一项是这一栏的名称；
- `setSlots(slots)`：设置装备槽；
@ -28,7 +28,7 @@ const off = state.hero.equip.unequip(0);
## 装备实例仓库（IHeroEquipsStore）
`state.hero.items.equipment` 提供：
`state.hero.items.equipment` 管的是「背包里所有的装备实例」——同一件装备可以有多件，各自独立，所以这里存的是**实例**而非装备本身。它提供：
- `add(item)`：获得一件装备道具、创建实例，返回新实例的 uid；
- `delete(uid)`：移除指定装备实例；

34
docs/intermediate/hero-items.md
View File

@ -1,26 +1,28 @@
# 勇士道具
勇士道具（`state.hero.items`）负责管理勇士拥有的除装备外的所有道具，并提供增加、查询、使用等接口。装备虽然也是道具，但归独立的装备系统，见[勇士装备](./hero-equipment.md)。
勇士的背包里能放哪些东西？捡起一把黄钥匙、使用一瓶药水、捡到就立刻生效的宝石——这些行为背后其实是同一套道具系统在管。勇士道具（`state.hero.items`）负责管理勇士拥有的除装备外的所有道具，并提供增加、查询、使用等接口。装备虽然也是道具，但归独立的装备系统，见[勇士装备](./hero-equipment.md)。
## 四种类别
## 先分清四类道具
道具的类别由 `ItemCategory` 定义，决定它被拾取或使用时的行为：
一件道具被捡起或使用时会发生什么，取决于它属于哪一类。类别由 `ItemCategory` 定义：
| 类别 | 含义 |
| --- | --- |
| `Constant` | 永久道具，使用后不消耗 |
| `Consumable` | 一次性道具，使用后消耗一个 |
| `Pick` | 即捡即用道具，拾取时立刻生效 |
| `Equipment` | 装备类道具，走装备系统 |
| 类别 | 含义 | 典型行为 |
| --- | --- | --- |
| `Constant` | 永久道具 | 使用后不消耗，可以反复使用 |
| `Consumable` | 一次性道具 | 使用后消耗一个，用完即消失 |
| `Pick` | 即捡即用道具 | 拾取时立刻生效，不进入背包 |
| `Equipment` | 装备类道具 | 走装备系统，见[勇士装备](./hero-equipment.md) |
`Unknown` 表示尚未归类。`Pick` 道具不会进入背包：`addItem` 到 `Pick` 道具时会直接触发它的效果。
`Unknown` 表示尚未归类。理解了这四类的差别，就能预判一件道具「什么时候、发生什么」：`Pick` 道具不会进入背包——`addItem` 到 `Pick` 道具时会直接触发它的效果。
## 常用接口
- `addItem(item, count?)`：增加道具数量，`count` 可以填负数以扣除道具，默认为 1；对 `Pick` 道具会立刻执行其效果。
- `getItemState(item)`：获取指定道具的状态，不存在返回 `null`。
- `iterateItems()`：迭代勇士拥有的所有道具。
- `useItem(item)`：使用道具，**仅对 `Constant` 与 `Consumable` 生效**，`Consumable` 使用后数量减一。
日常打交道的主要是下面几个：
- `addItem(item, count?)`：增加道具数量，`count` 可以填负数以扣除道具，默认为 1；对 `Pick` 道具会立刻执行其效果；
- `getItemState(item)`：获取指定道具的状态，不存在返回 `null`；
- `iterateItems()`：迭代勇士拥有的所有道具；
- `useItem(item)`：使用道具，**仅对 `Constant` 与 `Consumable` 生效**，`Consumable` 使用后数量减一；
- `itemCount(item)`：获取指定道具的持有数量。
`item` 参数可以传道具的图块数字或字符串 id。
@ -41,6 +43,8 @@ const count = state.hero.items.itemCount('yellow-key');
## 迭代背包
想一次看遍勇士拥有的全部道具，用 `iterateItems()`。它每一项的键是道具图块数字，值是道具状态：
```ts
for (const [num, item] of state.hero.items.iterateItems()) {
// num 为道具图块数字，item 为道具状态
@ -50,7 +54,7 @@ for (const [num, item] of state.hero.items.iterateItems()) {
## 道具效果属内容层
道具的**使用效果本身**写在内容层的 `src/content/item.ts`，通过 `IItemEffect` 描述：`useEffect` 在 `Pick` 拾取或 `Constant`/`Consumable` 使用时触发，`canUse` 决定能否使用，`useEvent` 关联使用事件。道具效果可以调用 `state`（数据端主对象）与道具数据，因而能修改勇士属性、设置 Flag、发送提示等。
道具「被捡起或使用时具体做什么」，写在内容层的 `src/content/item.ts`，用 `IItemEffect` 描述：`useEffect` 在 `Pick` 拾取或 `Constant` / `Consumable` 使用时触发，`canUse` 决定能否使用，`useEvent` 关联使用事件。道具效果可以调用 `state`（数据端主对象）与道具数据，因而能修改勇士属性、设置 Flag、发送提示等。
```ts
// src/content/item.ts（内容层）