gplan-2/design/art/asset-path-map.md

素材路径分工约定（asset-path-map）

• 定立：2026-09-26（用户立约指令「把哪些路径、哪些位置是干什么的确定好」——台账 161）
• 效力：全仓素材批的路径判据单点；新素材批开工前对照，违例=实施缺陷

1. 目录分工总表

路径	角色	入 git	游戏运行时引用
design/art/candidates/**	设计侧源档（母版 PNG/.pxo/GIF/对比图/验收留底）——素材的原产地与档案库，游戏禁直接引用	否（.gitignore 三行规则；*.md 指引例外）	禁（res:// 路径禁指 candidates）
game/assets/art/**	游戏运行时素材唯一落地处（res://assets/art/...）——定稿素材从 candidates 拷贝入此，改名按圣经 §8.3	否（untracked，勿 git add；worktree 间需脚本拷贝同步）	唯一合法引用源
game/assets/ui/icons/**	UI 图标（状态图标批特例——唯一已提交入 git 的素材目录）	是（2026-09-24 批特例）	是
production/mockups/**	混合样张/版式对比图（设计评审产物，非游戏素材）	否	禁

2. 素材流（新素材批标准路径）

1. 产出/候选：candidates 对应子目录（如 hero-idle/）
2. 验收定稿：用户拍板（候选目录留档不动）
3. 入包：拷贝 → game/assets/art/<语义子目录>/，改名 §8.3 域键式（如 character_hero_portrait.png）
4. 接线：代码 res://assets/art/... 引用（路径常量单点归 UiKit.TEX_*）；装载一律 UiKit.load_tex（exists 守卫——素材不入 git，缺位树回退），禁 preload
5. 提交：只提交代码/文档；PNG 与 .import（全局忽略）均不入 git

3. game/assets/art 语义子目录

子目录	内容	现役
character/	角色棋盘帧 + B 区立绘	character_hero_idle/walk（棋盘 32×32 朝左基准）、character_hero_portrait（B 区立绘 48×48）
fx/	特效帧	shovel_swing_f0/f1/f2（挥铲三帧，握把锚 (18,12)）
board/	砖面/墙/地板（beast-cave 复用包，地砖复用批）	board_floor/wall/pillar_dungeon_*

4. 坐标/朝向等工程侧约定备查

• 素材基准朝向：角色/铲帧一律朝左入库，右向=运行时 flip_h（镜像帧不入包，right 变体留 candidates）
• 挥铲握把锚：画布 (18,12)（三帧同位——以手为圆心旋转的预烤相位）
• 缩放纪律：圣经 §8.2 整数缩放为一般规则；棋盘小人 1.5× 系 2026-09-26 用户明示裁决（豁免注记归 art-bible 批另落）