daoqi/erqiwang_youle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

二七王：精灵常量改为以 UI View 为组织单位

Browse Source 
Layer/Group 扁平声明在 View 定义下，精灵只写 id、所属关系写在注释里；
一个 View 对应一个 UI 组件，拿到 View 即拿到它的全部精灵与图层群组。

SpriteIndex 的展平逻辑随之调整：保留键 Layer*/Group* 跳过，其余键即精灵；
新增「值非数字即报错」——两者结构上同级、只靠键名区分，写错前缀会静默变成假精灵。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
joywayer
2026-08-26 20:44:17 +08:00
co-authored by Claude Opus 5
parent 6546f75965
commit 5ac445d08d
2 changed files with 101 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-08-26-二七王前端A-地基与逻辑层.md
+92 -57
View File
@@ -1529,15 +1529,20 @@ EOF
- Create: `client/js/01_SubGame/codes/config/Sprites_CreateRoom.js`（清单 §5.8） - Create: `client/js/01_SubGame/codes/config/Sprites_CreateRoom.js`（清单 §5.8）
**Interfaces:** **Interfaces:**
- Produces: 全局 `EQW_Sprites`，五个文件用保护性声明合并为一份。结构照 `GameView_Sprites.template.js`： - Produces: 全局 `EQW_Sprites`，五个文件用保护性声明合并为一份。**以 UI View 为组织单位**——一个 View 将来对应一个 `BaseComponent` 组件（前端红线：每个界面的数据与渲染只由其对应 UI 组件负责）：
```js ```js
EQW_Sprites.<界面名> = { EQW_Sprites.<ViewName> = {
LAYER: <图层ID>, Layer: <图层常量>, // 该 View 用到的图层；用到多个时写 Layer1 / Layer2 …
<群组名>: { GROUP_ID: <群组ID>, SPRITES: { <键名>: <精灵ID>, ... } } Group: <群组常量>, // 该 View 用到的群组；用到多个时写 Group1 / Group2 …
<精灵键名>: <精灵ID>, // 精灵只写 id；所属 Layer/Group 写在注释里
...
}; };
``` ```
- **保留键约定**（`SpriteIndex` 与守卫测试据此机械区分）：View 内键名为 `Layer` / `Group`，或以二者为前缀（`Layer1`、`Group2`…）的，是 **View 级声明**；**其余键一律是精灵 id**。
- 精灵条目**不重复写 Layer/Group**——它们扁平放在 View 定义下，精灵的所属关系在**注释**里说明。
- 键名与 ID 一律照抄清单 §5 各表，**不改名、不改号**（Task 11 的 `SpriteIndex` 与 Task 12 的布局配置都按键名引用） - 键名与 ID 一律照抄清单 §5 各表，**不改名、不改号**（Task 11 的 `SpriteIndex` 与 Task 12 的布局配置都按键名引用）
- [ ] **Step 1: 写 `Sprites_Table.js`** - [ ] **Step 1: 写 `Sprites_Table.js`**
@@ -1549,31 +1554,42 @@ EQW_Sprites.<界面名> = {
////////// EQW_Sprites: 精灵结构（清单 §5.1 牌桌常驻）///////// ////////// EQW_Sprites: 精灵结构（清单 §5.1 牌桌常驻）/////////
/////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////
// 子游戏精灵段 1001–2999（段内仅 3000 被平台占用）。 // 子游戏精灵段 1001–2999（段内仅 3000 被平台占用）。
// 每个精灵注明：类型（图片/文字）+ 用途 + 资源键 + 帧说明—— // 以 UI View 为组织单位：Layer / Group 扁平声明在 View 下，
// 精灵只写 id，其所属 Layer/Group 在注释里说明。
// 每个精灵注明：类型（图片/文字）+ 用途 + 资源键 + 帧说明 + 所属群组——
// 后期即照这些注释在编辑器里逐个创建。 // 后期即照这些注释在编辑器里逐个创建。
var EQW_Sprites = EQW_Sprites || {}; var EQW_Sprites = EQW_Sprites || {};
EQW_Sprites.TABLE = { //顶部信息条：主 / 叫分 / 抓分 三列
LAYER: EQW_Layers.TABLE_STATIC, EQW_Sprites.TopInfoView = {
Layer: EQW_Layers.TABLE_STATIC, //101
Group: EQW_Groups.TOP_INFO, //201
//顶部信息条：主 / 叫分 / 抓分 三列 TOP_INFO_BG: 1001, //图片：三列表格底，资源 PANEL_TOP_INFO
TOP_INFO: { TOP_SUIT_ICON: 1002, //图片：「主」列花色，资源 SUIT_ICON_S，帧 = flower(1方块 2梅花 3红心 4黑桃)
GROUP_ID: EQW_Groups.TOP_INFO, TOP_CALL_TEXT: 1003, //文字：叫分数值
SPRITES: { TOP_CALL_BADGE_BG: 1004, //图片：叫分角标底，资源 BADGE_MULTIPLE 帧1
TOP_INFO_BG: 1001, //图片：三列表格底，资源 PANEL_TOP_INFO TOP_CALL_BADGE_TEXT: 1005, //文字：「N子」
TOP_SUIT_ICON: 1002, //图片：「主」列花色，资源 SUIT_ICON_S，帧 = flower(1方块 2梅花 3红心 4黑桃) TOP_GRADE_TEXT: 1006, //文字：抓分数值
TOP_CALL_TEXT: 1003, //文字：叫分数值 TOP_GRADE_BADGE_BG: 1007, //图片：抓分角标底，资源 BADGE_MULTIPLE 帧2
TOP_CALL_BADGE_BG: 1004, //图片：叫分角标底，资源 BADGE_MULTIPLE 帧1 TOP_GRADE_BADGE_TEXT: 1008 //文字：「N倍」，取 Math.abs(curmultiple)（T-16/S-8）
TOP_CALL_BADGE_TEXT: 1005, //文字：「N子」
TOP_GRADE_TEXT: 1006, //文字：抓分数值
TOP_GRADE_BADGE_BG: 1007, //图片：抓分角标底，资源 BADGE_MULTIPLE 帧2
TOP_GRADE_BADGE_TEXT: 1008 //文字：「N倍」，取 Math.abs(curmultiple)（T-16/S-8）
}
},
// ... 其余按清单 §5.1 续：群组 206 亮牌条（1030–1031）、
// 群组 205 底栏（1040–1055）、群组 202/203/204 三家附加标记（1100–1121）
}; };
//三家玩家位附加标记：跨三个群组，故写 Group1/2/3
EQW_Sprites.PlayerMarkView = {
Layer: EQW_Layers.TABLE_STATIC, //101
Group1: EQW_Groups.P_LEFT_MARK, //202 左上家
Group2: EQW_Groups.P_RIGHT_MARK, //203 右上家
Group3: EQW_Groups.P_SELF_MARK, //204 自己
//—— Group1 左上家（群组 202）——
P_LEFT_BANKER: 1100, //图片：「庄」印章，资源 MARK_BANKER
P_LEFT_ZHU_BG: 1101, //图片：「主N」角标底，资源 BADGE_ZHU_PAIR 帧1
// ... 其余按清单 §5.1 续
};
// ... 其余 View 按清单 §5.1 续：亮牌条（群组 206，1030–1031）、
// 底栏（群组 205，1040–1055）
``` ```
清单 §5.1 里 `1110–1115 P_RIGHT_*`「结构同 202」是省略写法，**必须展开写全**：`P_RIGHT_BANKER:1110`、`P_RIGHT_ZHU_BG:1111`、`P_RIGHT_ZHU_TEXT:1112`、`P_RIGHT_PAIR_BG:1113`、`P_RIGHT_PAIR_TEXT:1114`、`P_RIGHT_STATUS_TEXT:1115`。 清单 §5.1 里 `1110–1115 P_RIGHT_*`「结构同 202」是省略写法，**必须展开写全**：`P_RIGHT_BANKER:1110`、`P_RIGHT_ZHU_BG:1111`、`P_RIGHT_ZHU_TEXT:1112`、`P_RIGHT_PAIR_BG:1113`、`P_RIGHT_PAIR_TEXT:1114`、`P_RIGHT_STATUS_TEXT:1115`。
@@ -1627,44 +1643,57 @@ EOF
- Consumes: `EQW_Sprites`（Task 10） - Consumes: `EQW_Sprites`（Task 10）
- Produces: 全局 `EQW_SpriteIndex`，含 `build(spriteTree)` → `{ 键名: 精灵ID }`、`idOf(key)` → `number`（查不到抛错）、`init()`（用 `EQW_Sprites` 建好内部索引） - Produces: 全局 `EQW_SpriteIndex`，含 `build(spriteTree)` → `{ 键名: 精灵ID }`、`idOf(key)` → `number`（查不到抛错）、`init()`（用 `EQW_Sprites` 建好内部索引）
> 布局配置里 `attach.target` 写的是**键名**而非数字 ID（清单 §6.1：「`target` 一律写键名，ID 回填时只改一处映射表」），而精灵常量是按图层/群组嵌套的，故需要这张扁平索引。 > 布局配置里 `attach.target` 写的是**键名**而非数字 ID（清单 §6.1：「`target` 一律写键名，ID 回填时只改一处映射表」），而精灵常量是按 View 组织的，故需要这张扁平索引。
> **重复键必须报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。 > **重复键必须报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。
> **保留键约定**：View 内键名为 `Layer` / `Group` 或带数字后缀（`Layer1`、`Group2`…）的是 View 级声明，跳过不进索引；其余键一律是精灵 id。
> **值必须是数字**：View 级声明与精灵条目在结构上同级、只靠键名区分，所以把「值不是数字」当作错误抓出来——否则写错前缀（如 `Grup: 201`）会静默变成一个假精灵。
- [ ] **Step 1: 写失败的测试 `client/tests/test_spriteindex.js`** - [ ] **Step 1: 写失败的测试 `client/tests/test_spriteindex.js`**
```js ```js
// 嵌套精灵常量 → 扁平键名索引 // View 组织的精灵常量 → 扁平键名索引
const { load, throws } = require('./_load'); const { load, throws } = require('./_load');
const t = require('./_assert')(); const t = require('./_assert')();
load('client/js/01_SubGame/codes/core/SpriteIndex.js'); load('client/js/01_SubGame/codes/core/SpriteIndex.js');
// ---- 展平嵌套结构 ---- // ---- 展平：Layer/Group 声明跳过，精灵进索引 ----
const tree = { const tree = {
VIEW_A: { TopInfoView: {
LAYER: 101, Layer: 101,
GROUP_X: { GROUP_ID: 201, SPRITES: { BTN_A: 1001, BTN_B: 1002 } }, Group: 201,
GROUP_Y: { GROUP_ID: 202, SPRITES: { LABEL_C: 1003 } } BTN_A: 1001,
BTN_B: 1002
}, },
VIEW_B: { PlayerMarkView: {
LAYER: 102, Layer: 101,
GROUP_Z: { GROUP_ID: 210, SPRITES: { CARD_1: 1200 } } Group1: 202,
Group2: 203,
P_LEFT_BANKER: 1100,
P_RIGHT_BANKER: 1110
} }
}; };
t.eq('展平结果', EQW_SpriteIndex.build(tree), { BTN_A: 1001, BTN_B: 1002, LABEL_C: 1003, CARD_1: 1200 }); t.eq('展平结果', EQW_SpriteIndex.build(tree),
{ BTN_A: 1001, BTN_B: 1002, P_LEFT_BANKER: 1100, P_RIGHT_BANKER: 1110 });
// ---- LAYER / GROUP_ID 不进索引 ---- // ---- View 级声明不进索引（含带数字后缀的）----
const flat = EQW_SpriteIndex.build(tree); const flat = EQW_SpriteIndex.build(tree);
t.eq('LAYER 不进索引', flat.LAYER, undefined); t.eq('Layer 不进索引', flat.Layer, undefined);
t.eq('GROUP_ID 不进索引', flat.GROUP_ID, undefined); t.eq('Group 不进索引', flat.Group, undefined);
t.eq('Group1 不进索引', flat.Group1, undefined);
t.eq('Group2 不进索引', flat.Group2, undefined);
// ---- 反面：重复键报错，不静默覆盖 ---- // ---- 反面：重复键报错，不静默覆盖 ----
const dupTree = { const dupTree = {
VIEW_A: { LAYER: 101, G1: { GROUP_ID: 201, SPRITES: { SAME: 1001 } } }, ViewA: { Layer: 101, Group: 201, SAME: 1001 },
VIEW_B: { LAYER: 102, G2: { GROUP_ID: 202, SPRITES: { SAME: 1002 } } } ViewB: { Layer: 102, Group: 202, SAME: 1002 }
}; };
t.eq('重复键报错', throws(() => EQW_SpriteIndex.build(dupTree)), true); t.eq('重复键报错', throws(() => EQW_SpriteIndex.build(dupTree)), true);
// ---- 反面：精灵值不是数字要报错（防写错保留键前缀变成假精灵）----
const badTree = { ViewA: { Layer: 101, Group: 201, NESTED: { id: 1001 } } };
t.eq('值非数字报错', throws(() => EQW_SpriteIndex.build(badTree)), true);
// ---- idOf：查得到 / 查不到抛错 ---- // ---- idOf：查得到 / 查不到抛错 ----
EQW_SpriteIndex.init(tree); EQW_SpriteIndex.init(tree);
t.eq('idOf 查到', EQW_SpriteIndex.idOf('BTN_A'), 1001); t.eq('idOf 查到', EQW_SpriteIndex.idOf('BTN_A'), 1001);
@@ -1702,33 +1731,39 @@ Expected: `EQW_SpriteIndex is not defined`。
/////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////
////////// EQW_SpriteIndex: 精灵键名 → ID 扁平索引 ///////////// ////////// EQW_SpriteIndex: 精灵键名 → ID 扁平索引 /////////////
/////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////
// 精灵常量按「界面 → 群组 → 精灵」嵌套（照 GameView_Sprites 模板）， // 精灵常量以 UI View 为组织单位：Layer / Group 扁平声明在 View 下，
// 而布局配置里 attach.target 写的是【键名】（清单 §6.1：ID 回填时只改一处映射表）。 // 精灵只写 id（所属关系在注释里）。而布局配置里 attach.target 写的是
// 本模块把嵌套结构展平成 { 键名: 精灵ID } 供求解器查用。 // 【键名】（清单 §6.1：ID 回填时只改一处映射表），故需把 View 结构
// 【显式失败】重复键、查不到的键一律抛错——静默覆盖会让某个界面 // 展平成 { 键名: 精灵ID } 供求解器查用。
// 指向另一个界面的精灵，且极难排查（工程总则 §7）。 // 【显式失败】重复键、值非数字、查不到的键一律抛错——静默覆盖会让某个
// 界面指向另一个界面的精灵，且极难排查（工程总则 §7）。
var EQW_SpriteIndex = EQW_SpriteIndex || { var EQW_SpriteIndex = EQW_SpriteIndex || {
_index: null, _index: null,
//展平：遍历 树 → 界面 → 群组 → SPRITES //View 级保留键：Layer / Group，可带数字后缀（Layer1、Group2…）
_isReserved: function (key) {
return (/^Layer\d*$/).test(key) || (/^Group\d*$/).test(key);
},
//展平：遍历 树 → View → 键
build: function (spriteTree) { build: function (spriteTree) {
var index = {}; var index = {};
for (var viewName in spriteTree) { for (var viewName in spriteTree) {
if (!spriteTree.hasOwnProperty(viewName)) { continue; } if (!spriteTree.hasOwnProperty(viewName)) { continue; }
var view = spriteTree[viewName]; var view = spriteTree[viewName];
for (var groupName in view) { for (var key in view) {
if (!view.hasOwnProperty(groupName)) { continue; } if (!view.hasOwnProperty(key)) { continue; }
var group = view[groupName]; if (this._isReserved(key)) { continue; } //View 级 Layer/Group 声明
if (!group || !group.SPRITES) { continue; } //跳过 LAYER 等标量字段 if (typeof view[key] !== 'number') {
for (var key in group.SPRITES) { throw new Error('[EQW_SpriteIndex] 精灵 ' + key + ' 的值不是数字（View ' +
if (!group.SPRITES.hasOwnProperty(key)) { continue; } viewName + '）——Layer/Group 声明请用保留键名 Layer* / Group*');
if (index.hasOwnProperty(key)) {
throw new Error('[EQW_SpriteIndex] 精灵键名重复: ' + key +
'（' + viewName + '.' + groupName + ' 与更早的定义冲突）');
}
index[key] = group.SPRITES[key];
} }
if (index.hasOwnProperty(key)) {
throw new Error('[EQW_SpriteIndex] 精灵键名重复: ' + key +
'（View ' + viewName + ' 与更早的定义冲突）');
}
index[key] = view[key];
} }
} }
return index; return index;
docs/superpowers/specs/2026-08-26-二七王前端A-地基与逻辑层-design.md
+9 -5
View File
@@ -104,7 +104,7 @@ client/tests/
| `Groups.js` | `EQW_Groups` | 清单 §0.3 群组表 201–250 | | `Groups.js` | `EQW_Groups` | 清单 §0.3 群组表 201–250 |
| `ImageResources.js` | `EQW_Images` | 清单 §3 图片资源总表，**每条按 ImageResources.template 的要求注明用途 / 帧数 / 每帧含义 / 尺寸** | | `ImageResources.js` | `EQW_Images` | 清单 §3 图片资源总表，**每条按 ImageResources.template 的要求注明用途 / 帧数 / 每帧含义 / 尺寸** |
| `SoundResources.js` | `EQW_Sounds` | 清单 §4——**整节 T-20 未定**，本阶段只建文件骨架与说明注释，不臆造条目（见 §11） | | `SoundResources.js` | `EQW_Sounds` | 清单 §4——**整节 T-20 未定**，本阶段只建文件骨架与说明注释，不臆造条目（见 §11） |
| `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8，嵌套结构 `{ LAYER, 群组: { GROUP_ID, SPRITES: { 键名: ID } } }`（照 `GameView_Sprites.template.js`），每个精灵注明类型 / 用途 / 资源键 / 帧说明 | | `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8。**以 UI View 为组织单位**（一个 View 将来对应一个 `BaseComponent`）：`Layer` / `Group` 扁平声明在 View 下（用到多个时写 `Layer1`/`Group2`…），精灵只写 id、所属关系在注释里。每个精灵注明类型 / 用途 / 资源键 / 帧说明 / 所属群组 |
| `LayoutConstants.js` | `EQW_Layout` | 清单 §6.3 `textStyle` 预设、§6.4 `CARD_SIZE` 三档、座位键常量 `SELF/LEFT/RIGHT` | | `LayoutConstants.js` | `EQW_Layout` | 清单 §6.3 `textStyle` 预设、§6.4 `CARD_SIZE` 三档、座位键常量 `SELF/LEFT/RIGHT` |
| `Layout_Table.js` | `EQW_Layout` | 清单 §6.5 常驻区 + §6.6 玩家位（含气泡朝向 `arrowRight`） | | `Layout_Table.js` | `EQW_Layout` | 清单 §6.5 常驻区 + §6.6 玩家位（含气泡朝向 `arrowRight`） |
| `Layout_Cards.js` | `EQW_Layout` | 清单 §6.7 牌区（手牌单排/双排、底牌、埋牌底牌、已出牌 `bySeat`、冲关牌） | | `Layout_Cards.js` | `EQW_Layout` | 清单 §6.7 牌区（手牌单排/双排、底牌、埋牌底牌、已出牌 `bySeat`、冲关牌） |
@@ -189,16 +189,20 @@ EQW_SeatMap.toSeat(displayKey, mySeat) // → 服务端座位号
### 5.5 `SpriteIndex` ### 5.5 `SpriteIndex`
精灵常量是按图层/群组嵌套的（照模板），而布局配置里 `attach.target` 写的是**键名**（清单 §6.1：「`target` 一律写键名而非数字 ID」）。故需一张扁平索引： 精灵常量以 UI View 为组织单位（`Layer`/`Group` 扁平声明在 View 下，精灵只写 id），而布局配置里 `attach.target` 写的是**键名**（清单 §6.1：「`target` 一律写键名而非数字 ID」）。故需一张扁平索引：
```js ```js
EQW_SpriteIndex.build(spriteTrees) // 遍历嵌套结构 → { 键名: 精灵ID } EQW_SpriteIndex.build(spriteTree) // 遍历 树 → View → 键 → { 键名: 精灵ID }
EQW_SpriteIndex.idOf(key) // 查 ID；查不到显式抛错，不返回 undefined EQW_SpriteIndex.idOf(key) // 查 ID；查不到显式抛错，不返回 undefined
``` ```
**显式失败**：键名拼错时立即报错（工程总则 §7），而不是把 `undefined` 传给 `SpriteManager` 静默无效。 **保留键约定**：View 内键名为 `Layer` / `Group` 或带数字后缀（`Layer1`、`Group2`…）的是 View 级声明，跳过不进索引；其余键一律是精灵 id。
同名键在不同群组下重复（如三家结构相同的 `PLAY_*`）由清单 §5 的键名设计避免（`PLAY_SELF_*` / `PLAY_LEFT_*` / `PLAY_RIGHT_*`）；`build` 遇到重复键**报错**而非后者覆盖前者。 **显式失败**三处（工程总则 §7）：
- 键名拼错时 `idOf` 立即报错，而不是把 `undefined` 传给 `SpriteManager` 静默无效；
- **重复键报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。同名键在不同 View 下重复由清单 §5 的键名设计避免（`PLAY_SELF_*` / `PLAY_LEFT_*` / `PLAY_RIGHT_*`）；
- **值非数字报错**——View 级声明与精灵条目在结构上同级、只靠键名区分，写错前缀（如 `Grup: 201`）会静默变成一个假精灵，故把「值不是数字」当作错误抓出来。
--- ---