evomeme 0.1.9 → 0.1.10

package/dist/skills/zh-CN/game-ui/references/ui-patterns.md

@@ -0,0 +1,140 @@
+# Game UI Patterns
+
+Use this when designing HUDs, menus, overlays, pause/fail/win states, touch controls, typography, responsive layout, and UI/world cohesion.
+
+## UI Principles
+
+- Build the game interface, not a web dashboard.
+- Prioritize gameplay hierarchy: survival/status, objective/progress, immediate feedback, then flavor.
+- Use meters, icons, reticles, badges, alert strips, cooldown rings, inventory slots, minimaps, diegetic labels, and compact clusters before generic stat cards.
+- Keep UI outside the play path and away from threats, pickups, the player, and the next decision.
+- UI should reinforce the world art direction through material cues, color roles, icon shapes, and motion language.
+- Do not use visible text to explain obvious controls when an icon, affordance, or direct interaction can do the job.
+
+## Required States
+
+Inventory states before designing:
+
+- Gameplay HUD.
+- Pause/resume.
+- Settings or audio/accessibility controls when useful.
+- Fail/retry.
+- Win/milestone/level complete when relevant.
+- Loading/empty/error when async assets exist.
+- Mobile/touch controls when target includes mobile.
+- Debug/tuning UI gated separately from player UI.
+
+Premium games should not have only one HUD state.
+
+## HUD Composition
+
+Use intentional zones:
+
+- Top or top-left: objective, wave, distance, timer, route/progress.
+- Top or top-right: score, currency, combo, inventory, pause.
+- Bottom left/right: touch movement/action controls when needed.
+- Center top or near player: short event banners, combo, warnings.
+- Near-world labels: diegetic prompts, target markers, offscreen indicators.
+
+Rules:
+
+- Use fixed-width numeric containers for score, timer, ammo, speed, health, and best values.
+- Use icons plus short labels for unfamiliar resources.
+- Use meter fills for quantities the player must read quickly.
+- Use alert colors consistently: danger, reward, shield, boost, objective, disabled.
+- Animate state changes briefly: count-up, meter fill, pulse, slide/fade, snap, ring cooldown.
+- Do not stack multiple large banners over the play path.
+
+## Menus And Overlays
+
+Pause/fail/win overlays should support quick action:
+
+- Primary action first: resume, retry, continue, next.
+- Secondary actions: settings, quit, restart, level select.
+- Avoid marketing-page hero layouts inside a game.
+- Keep menu panels stable and readable across desktop/mobile.
+- Use icon buttons for pause, sound, restart, fullscreen, settings when familiar.
+- Provide focus/hover/pressed/disabled states.
+- Gate debug panels behind a dev flag or query param.
+
+## Touch Controls
+
+When mobile is in scope:
+
+- Use pointer events where possible.
+- Ensure controls emit the same game intents as keyboard/mouse.
+- Handle `pointerup`, `pointercancel`, `lostpointercapture`, blur, and visibility change.
+- Use safe-area insets.
+- Avoid controls overlapping HUD warnings or the play path.
+- Keep touch targets at least roughly 44 CSS pixels where practical.
+- Separate adjacent controls enough to prevent accidental presses.
+- Use `touch-action` to prevent unwanted page scrolling only in control regions or the game surface.
+
+## Responsive Constraints
+
+- Define stable dimensions with CSS variables, `clamp`, grid tracks, fixed icon slots, and fixed-width numbers.
+- Present a fixed-aspect game stage as the sole visual subject and maximize it within the viewport; keep extra desktop space as passive page background.
+- Do not scale text purely with viewport width.
+- Avoid negative letter spacing.
+- Check desktop, laptop, tablet/narrow, and phone viewports.
+- Test longest likely values: high score, long labels, multi-digit timers, localized-ish text if relevant.
+- No clipped text, overlapping controls, unreadably small labels, or layout shift from changing values.
+- Menus must remain reachable without offscreen controls.
+
+## Visual Style
+
+- Match the genre: arcade racers need speed/status readability; fighters need health/round/impact hierarchy; exploration games need inventory/objective clarity.
+- Prefer restrained panels with meaningful geometry, borders, ticks, glow accents, and material cues over nested cards.
+- Use a limited status palette plus neutral surfaces.
+- Avoid one-note purple/blue gradient UI unless it is strongly justified by the game world.
+- Connect UI motifs to world decals, faction marks, vehicle panels, pickups, or hazards.
+
+## 2D Asset Sourcing
+
+Prefer procedural/CSS/canvas UI art from this skill when hand-coded techniques are enough. When external 2D is needed:
+
+- User-supplied PNG/JPG/WebP wired via config or `<img>`/canvas textures.
+- Remote MCP `evomeme_generate_game_image` when available.
+- Procedural canvas exports saved under `assets/ui/` or `assets/textures/`.
+
+Use cases:
+
+- Faction logos, team crests, title marks.
+- Pickup, ability, weapon, inventory, achievement, and objective icons.
+- Hazard signs, decals, lane glyphs, cockpit labels, item badges.
+- Menu/loading/background plates, illustrated map panels, world-style UI textures.
+- GUI material references: glass panels, metal frames, holographic strips, paper/parchment, tactical screens.
+
+Use procedural geometry or a user-provided GLB only when the UI needs a 3D object: rotating character preview, vehicle garage, weapon inspect model, trophy, diorama, or diegetic 3D menu prop.
+
+## State Wiring
+
+- UI reads game state from a single source of truth.
+- UI events dispatch game intents; they should not mutate unrelated simulation internals directly.
+- UI should update on pause, restart, resize, mobile orientation, mute, fail/win, score, health, boost, combo, inventory, and accessibility settings.
+- Avoid stale values after restart.
+
+## Verification
+
+Capture evidence:
+
+- Gameplay HUD desktop screenshot.
+- Gameplay HUD mobile screenshot when in scope.
+- Pause/fail/retry state screenshot if changed.
+- Text-fit and overlap check with high values.
+- Touch target and safe-area check when mobile is in scope.
+- Interaction test for UI buttons and touch controls.
+- Console/page error check after UI events.
+- Sourced 2D asset path and source (procedural / user-provided / remote MCP) when external 2D was used.
+- Imported 3D preview model path and renderer diagnostics when a 3D UI prop/model was used.
+
+## Common Failures
+
+- Generic dashboard/stat-card HUD.
+- Nested cards and oversized decorative panels.
+- UI covers threats, pickups, player, or next decision.
+- Text explains obvious controls instead of designing affordances.
+- Mobile safe areas ignored.
+- Touch controls look correct but do not emit intents.
+- Values change width and shift layout during play.
+- Debug UI ships as player UI.

package/dist/skills/zh-CN/game-ui/references/ui-prompt-templates.md

@@ -0,0 +1,63 @@
+# Game UI Prompt Templates
+
+Reusable prompt templates packaged with this skill. Use only templates relevant to the current request, and adapt placeholders to the game/project context.
+
+---
+
+# Premium HUD/UI Pass Prompt
+
+Use `game-ui` to make this browser game's HUD and in-game UI feel premium, readable, and genre-specific.
+
+Context to gather:
+- Current screenshots at desktop and mobile sizes.
+- Game genre, core verb, target mood, and player decisions the HUD must support.
+- Current HUD/menu files, game state sources, input model, and touch controls.
+
+Design goals:
+- Keep the playable game as the first screen.
+- Make survival/status/objective information readable during motion.
+- Use stable dimensions for counters, buttons, meters, and labels.
+- Use icons where they reduce clutter, with labels where meaning is ambiguous.
+- Match the game's world materials, color, typography, and feedback language.
+
+Constraints:
+- Do not add marketing-page hero sections or explanatory feature copy.
+- Do not nest cards inside cards.
+- Do not let UI cover critical gameplay at desktop or mobile sizes.
+- Avoid text overflow, clipped controls, layout shift, and generic dashboard styling.
+
+Verification:
+- Build and run locally.
+- Capture desktop and mobile screenshots.
+- Check console/page errors.
+- Verify text fit, no overlap, no clipped controls, and at least one UI state change from real input.
+
+---
+
+# Responsive Game Menu Pass Prompt
+
+Use `game-ui` to design or improve this browser game's pause, start, settings, win, lose, or restart menus.
+
+Menu states needed:
+- 
+
+Target devices/orientations:
+- 
+
+Requirements:
+- Menus must feel like part of the game, not a website overlay.
+- Modal menus may pause or dim gameplay, but should not look like marketing cards.
+- Buttons need clear hover, pressed, focus, disabled, and touch states.
+- Settings must use appropriate controls: toggles, sliders, segmented controls, icon buttons, and select menus.
+- Layout must respect safe-area insets and remain usable on mobile.
+
+Implementation notes:
+- Prefer semantic HTML/CSS over canvas-rendered UI unless 3D placement is required.
+- Keep UI state driven by the game state model.
+- Keep dimensions stable so labels and counters do not shift layout.
+
+Verification:
+- Test every menu state.
+- Capture desktop and mobile screenshots.
+- Check keyboard/mouse and touch paths when both are supported.
+- Confirm no text overflow, overlap, clipping, or unreachable controls.

package/dist/skills/zh-CN/godot-3d-game/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: godot-3d-game
+description: 用 Godot 4 构建和维护 3D 游戏，并消费 EvoMeme canonical 资产包。涉及 Godot 场景结构、GLB 导入、对齐 wrapper、骨骼动画、碰撞体、构建或 3D 运行时 QA 时使用；资产未就绪时必须转回 game-asset-align。
+---
+
+# Godot 3D Game
+
+## Responsibility boundary
+
+Godot 是出货运行时，不是资产朝向猜测器。资产对齐事实源属于 `game-asset-align`；本技能负责导入门禁、唯一 wrapper、游戏场景集成和 Godot 实机验证。
+
+## Required workflow
+
+1. 确认工程根含 `project.godot`，并阅读与任务相关的参考文件。
+2. **Blender 建模后必须先打开 Stage 展板，确认后才能导入 Godot。** 读取 canonical `asset.json` 并执行格式检查，调用 `evomeme_stage_open({workspace_dir, asset_id, target:"godot"})`，在 Stage 对比 Blender 与 Godot 原生画面的空间、结构、材质和灯光。由用户点击“确认当前版本，允许导入”。不得替用户点击、写确认文件或用技术 ready 状态跳过。
+3. 调用 `evomeme_asset_sync_to_godot`，不要手工复制部分文件。
+4. 完整场景使用 `CanonicalAssetLoader.load_scene(parent, package_dir)`，同时接入 Stage 已确认的 PBR 材质校准、灯光、环境、曝光和相机。道具进入已有关卡时使用 `load_package`，避免叠加场景环境。模型只能位于一个带 `canonical_alignment_key` 的 `A3AlignmentRoot` 下。
+5. 将玩法节点、动画、碰撞与可视模型分层；不要在角色控制器或动画树里补 canonical Transform。
+6. 在真实 Godot 运行画面中检查构图、接地、朝向、比例、材质和交互碰撞。
+
+## Routing references
+
+- 工程目录与场景分层：读 [project-structure.md](references/project-structure.md)。
+- 材质、灯光、曝光、相机和 Stage 原生预览：读 [appearance-alignment.md](references/appearance-alignment.md)。
+- v2 loader、revision 与单 wrapper 规则：读 [canonical-asset-runtime.md](references/canonical-asset-runtime.md)。
+- 导入前/运行时/交付门禁：读 [alignment-gates.md](references/alignment-gates.md)。
+- GLB 导入、继承场景与 wrapper 维护：读 [import-and-wrapper-scenes.md](references/import-and-wrapper-scenes.md)。
+- 角色骨骼与动画：读 [skeleton-animation.md](references/skeleton-animation.md)。
+- 物理体与碰撞层：读 [physics-colliders.md](references/physics-colliders.md)。
+- 构建、运行与截图 QA：读 [build-and-qa.md](references/build-and-qa.md)。
+
+## Completion gates
+
+- 同步结果带 `alignment_status=aligned` 和非空 `alignment_key`。
+- Stage 确认来自当前 Godot 原生画面；修改模型或显示配置后重新查看并确认，再同步。
+- Godot 场景中同一资产只有一个 canonical alignment root。
+- 模型节点保留原始导入 Transform，游戏逻辑不重复应用修复配方。
+- 骨骼、动画、碰撞和视觉节点职责分离。
+- 使用 Godot 实际运行截图验收；发现偏差时更新 canonical 包，不在 Godot 局部打补丁。

package/dist/skills/zh-CN/godot-3d-game/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Godot 3D Game"
+  short_description: "构建 Godot 4 三维游戏并安全消费持续对齐的 canonical 资产"
+  default_prompt: "请使用 $godot-3d-game 把已验收的 canonical 资产集成到这个 Godot 4 工程，并完成场景、运行时与构建验证。"
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/zh-CN/godot-3d-game/references/alignment-gates.md

@@ -0,0 +1,26 @@
+# Alignment gates
+
+## Before sync
+
+- Godot root contains `project.godot`.
+- Blender modeling/changes MUST be followed by opening Stage with target=godot and explicit user confirmation of the current native Godot view. Opening the page or setting ready/spec metadata is insufficient; no manual-copy bypass.
+- Package is v2 and all required conditions are aligned or explicitly waived.
+- Current `model.glb` bytes match the recorded SHA-256 and byte count.
+- Recipe binds current source and intent revisions.
+- Scene supplement, when present, passes coordinate, camera, manifest and path validation.
+- Current confirmation binds the Godot profile, native screenshot, shared adapter, camera and source revision. A Three.js confirmation cannot authorize a Godot sync.
+
+`evomeme_asset_sync_to_godot` performs these checks before creating or overwriting destination files.
+
+## At runtime
+
+The loader repeats lightweight schema/revision assertions before loading the PackedScene. It does not recompute SHA-256 inside Godot; host-side sync owns byte validation. A package edited after sync is unsupported—resync it.
+
+## Before delivery
+
+- inspect the remote scene tree for one `A3AlignmentRoot` per asset instance;
+- verify intended forward motion, ground contact, scale and camera framing;
+- exercise animation and physics so they do not reapply the wrapper transform;
+- record a Godot run capture for render acceptance.
+
+If any gate fails, use `game-asset-align`. Do not turn off assertions or hard-code fallback rotations.

package/dist/skills/zh-CN/godot-3d-game/references/appearance-alignment.md

@@ -0,0 +1,52 @@
+# Godot 基础材质与灯光对齐
+
+## 必须遵守的顺序
+
+**Blender MCP 建模/修改并保存 → evomeme_scene_export_blender → Stage 选择 Godot → 用户查看并确认 → sync_to_godot → Godot 工程集成与复验。** 源契约、可选程序材质烘焙与参数见 [场景导出流程](../../game-asset-align/references/blender-scene-pipeline.md)。
+
+`evomeme_stage_open({workspace_dir,asset_id,target:"godot"})` 打开目标引擎视窗。宿主通过 `EVOMEME_GODOT` / `GODOT_PATH`（绝对可执行文件路径）或 PATH 提供 `godot`。右侧 PNG 来自独立 Godot 原生进程，模型快照写入 `.evomeme/godot-previews/`；不会提前写入最终游戏工程。左侧使用与契约相机匹配的 Blender 基准或当前机位原生渲染。未安装 Godot、原生渲染失败或机位变化时不能确认旧帧。
+
+## 数据与可调参数
+
+默认保留 GLB 标准 PBR 材质与纹理、法线、透明度；有 COLOR_0 的网格启用线性顶点颜色。默认从 `scene.contract.json.blender_lights` 重建 SUN/POINT/SPOT，按 `[x,y,z]→[x,z,-y]` 转换位置及 Blender Euler XYZ 灯光方向。AREA 使用聚光灯近似，界面明确提示；功率是基础换算，须目视校准。
+
+需要校准时，写入包内 `runtime/godot.profile.json`，并把文件字节数和 SHA-256 加到 `scene.contract.json.files`，设置 `display_profiles.godot.profile_file` 为该路径。例如：
+
+```json
+{
+  "schema": "evomeme.godot_scene_profile.v1",
+  "asset_id": "my_scene",
+  "renderer": "gl_compatibility",
+  "environment": {
+    "background_srgb": [0.10, 0.14, 0.16],
+    "ambient_srgb": [0.75, 0.82, 0.85],
+    "ambient_energy": 0.5,
+    "exposure": 1.0,
+    "tonemapper": "filmic",
+    "fog": {"enabled": false, "color_srgb": [0.6, 0.7, 0.8], "density": 0.01}
+  },
+  "materials": [{"material_name": "Stone", "roughness": 0.8, "metallic": 0.0}]
+}
+```
+
+材质按精确名称覆盖，名称缺失会使原生预览失败，避免静默无效。还可指定 `albedo_srgb` RGBA、`emission_srgb` RGB、`emission_energy`、`double_sided`；未指定字段保留 GLB 值和贴图。
+
+可显式提供 `lights` 数组替换派生灯光。每项 `type` 为 `directional/omni/spot`，使用 Godot Y-up 米制 `position`、`quaternion_xyzw`、`color_linear` RGB、`energy`、`range`、`spot_angle_degrees`（半角，0.1–89）及 `shadow_enabled`。`lights:[]` 明确禁用额外灯光。显式配置使用 Godot 能量值，不再进行 Blender 功率换算。
+
+## 对比与修改循环
+
+颜色环境光固定 `ambient_light_sky_contribution=0`，避免默认天空贡献值使 profile 的颜色环境光无效。Compatibility 的顶点颜色按 sRGB 参与着色，不能仅依赖 `vertex_color_is_srgb` 开关：共享适配器将 glTF 线性 COLOR_0 编码到私有网格副本，只更新 RGB 字节并保留 Alpha、UV、索引、骨骼、LOD 和源资源；Forward+/Mobile 保持线性数据。原生 Stage 隐藏 `-colonly` / `-convcolonly` 辅助网格（含复制后缀），防止 GLTFDocument 的运行时加载把碰撞体画成实物。
+
+1. 固定相机 quaternion、垂直 FOV、画幅，核对正反面、法线、透明度、贴图和顶点色。
+2. 核对主光方向、亮暗关系、阴影、粗糙度、金属高光、自发光、环境色和曝光。
+3. 修几何/节点材质回 Blender；基础引擎校准改 Godot profile，更新清单摘要。
+4. 重新载入 Stage，在当前 Godot 原生画面点击确认。`ready=true`、规范检查通过或 Three.js 确认不能替代此步骤。
+5. 同步后完整场景用 `CanonicalAssetLoader.load_scene(parent, package_dir)`。它应用与预览相同的 `canonical_appearance.gd`、`godot.appearance.json` 和相机；`load_package` 只处理道具模型与空间变换。
+
+## 运行时与范围
+
+profile.renderer 支持 gl_compatibility（默认）、mobile、forward_plus。导出时可读取已有工程的实际 renderer；Stage 用相同模式原生预览，不静默退回 OpenGL；同步时校验目标工程模式一致。选择更高级渲染器不会自动实现体积或 GI 资源转换，展板仍明确显示缺失项。Camera3D 保持垂直 FOV，调用方用 SubViewport 或留边保持确认画幅；场景环境只接入一次，避免与关卡已有 WorldEnvironment/灯光叠加。玩法相机可在集成后接管，变化后要复验构图和材质。
+
+Godot 导出设置需包含 `*.json` 非资源文件，保证 asset.json/godot.appearance.json 打入游戏。规范里的 Three.js 着色器、Cycles 全场景烘焙显示模块和 LUT 不会被 Godot 执行。基础 PBR、实时灯光/雾不承诺 Blender 程序节点、体积光、间接光或逐像素等价。
+
+API 依据：[GLTFDocument](https://docs.godotengine.org/en/stable/classes/class_gltfdocument.html)、[Environment](https://docs.godotengine.org/en/stable/classes/class_environment.html)、[SpotLight3D](https://docs.godotengine.org/en/stable/classes/class_spotlight3d.html)。

package/dist/skills/zh-CN/godot-3d-game/references/build-and-qa.md

@@ -0,0 +1,22 @@
+# Build and QA
+
+## Minimum verification
+
+1. Let Godot finish GLB import with no resource errors.
+2. Run the scene that instances the asset through `CanonicalAssetLoader`.
+3. Confirm one alignment root and the expected alignment key in the remote scene tree.
+4. Exercise movement, animation, collision, camera and material visibility.
+5. Restart the scene or load the asset twice to confirm idempotency.
+6. Capture the actual Godot viewport/build for visual acceptance.
+
+## Failure routing
+
+- schema/readiness/revision assertion: resync or return to `game-asset-align`;
+- missing PackedScene/import failure: inspect GLB export and Godot import log, then repair/re-export the canonical source;
+- wrong pose or missing parts: structural review/Blender path;
+- wrong identity/detail: semantic review/source regeneration;
+- material/culling/texture mismatch: render review, with Godot capture as evidence;
+- collision or gameplay transform issue: fix the authored Godot scene above/beside the visual root without modifying canonical TRS.
+
+Do not claim completion from a successful file copy alone. A successful run and target-engine visual check are required.
+

package/dist/skills/zh-CN/godot-3d-game/references/canonical-asset-runtime.md

@@ -0,0 +1,27 @@
+# Canonical asset runtime
+
+Before any engine sync, open Stage with `target=godot` after Blender modeling and obtain the user's explicit confirmation of the current native frame. Technical alignment metadata alone cannot authorize import.
+
+For a complete scene, call `CanonicalAssetLoader.load_scene(parent, package_dir)`. It applies the same material overrides, native lights, environment/exposure and reference camera reviewed in Stage. Use `load_package` below for props in a level with its own lighting. See [appearance-alignment.md](appearance-alignment.md).
+
+Call:
+
+```gdscript
+var visual := CanonicalAssetLoader.load_package(
+    visual_parent,
+    "res://assets/canonical/hero"
+)
+```
+
+The generated loader verifies:
+
+- canonical asset and alignment schema versions;
+- `alignment.ready=true` and `overall_status=aligned`;
+- source fingerprint revision equality;
+- recipe source and intent revision equality;
+- a non-empty `alignment_key`;
+- complete translation, quaternion and positive scale values.
+
+It creates `<asset_id>_A3AlignmentRoot`, tags it with the asset ID and alignment key, and places the raw imported model below it. A second call with the same key returns the existing root. A newer key replaces that one root; calling it below another canonical root is rejected.
+
+Do not copy recipe values into a `.tscn`, animation track or controller. The generated loader remains the only application point. Gameplay transform belongs above the canonical root; model-local animation remains below it.

package/dist/skills/zh-CN/godot-3d-game/references/import-and-wrapper-scenes.md

@@ -0,0 +1,20 @@
+# Import and wrapper scenes
+
+Godot imports GLB as a `PackedScene`. Keep that import generated and reproducible. Put scripts, collision, navigation, interaction markers and gameplay signals in a separate authored scene.
+
+Recommended hierarchy:
+
+```text
+EntityRoot (gameplay/world transform)
+  CollisionRoot
+  VisualParent
+    <asset_id>_A3AlignmentRoot (canonical recipe)
+      ImportedGLBRoot (unchanged)
+```
+
+Do not edit the imported GLB child transform to fix orientation. Do not put the canonical recipe on `EntityRoot`, because its transform changes during gameplay. Do not wrap an inherited scene and then call the loader again inside it.
+
+When the canonical asset changes, resync and let the alignment key replace the visual root. Preserve authored gameplay nodes outside that root.
+
+For full scenes/maps with `pivot=origin`, instance under a world parent with identity transform. A level streaming offset is gameplay/world placement and belongs above the canonical root; it must not be written back as asset repair.
+

package/dist/skills/zh-CN/godot-3d-game/references/physics-colliders.md

@@ -0,0 +1,13 @@
+# Physics and colliders
+
+Collision belongs to the gameplay scene, not inside the generated canonical package unless the source contract explicitly carries collider data.
+
+- Use simple authored primitives for dynamic actors where possible.
+- Use trimesh collision only for appropriate static environment geometry.
+- Keep collision and visual roots as siblings under the entity so visual alignment does not silently scale physics twice.
+- Validate collision layers, masks, ground clearance and center of mass after every source/recipe revision.
+
+If the canonical wrapper scale is not `[1,1,1]`, size authored colliders against the accepted world dimensions. Do not copy the wrapper scale onto both the collision root and its shapes.
+
+Physics mismatch can reveal a spatial or semantic defect. If the visual object cannot align with a reasonable collider without local hacks, mark the relevant canonical condition non-ready and repair the source or recipe.
+

package/dist/skills/zh-CN/godot-3d-game/references/project-structure.md

@@ -0,0 +1,22 @@
+# Godot project structure
+
+Use a stable separation between imported assets, authored wrapper scenes and gameplay systems.
+
+```text
+res://
+  assets/canonical/<asset_id>/
+    model.glb
+    asset.json
+    canonical_loader.gd
+  scenes/assets/
+  scenes/levels/
+  scripts/gameplay/
+  scripts/presentation/
+```
+
+The synchronized package is generated input. Do not hand-edit it in the Godot project; update the workspace canonical package and sync again.
+
+Keep gameplay state on a stable parent such as `CharacterBody3D` or an entity root. Add the canonical visual root as a child. This lets control, networking and save state remain stable when the visual package revision changes.
+
+Use authored `.tscn` scenes for gameplay composition, signals and engine-specific components. Keep the imported GLB scene read-only or inherited. Never save canonical compensation transforms into multiple scene layers.
+

package/dist/skills/zh-CN/godot-3d-game/references/skeleton-animation.md

@@ -0,0 +1,16 @@
+# Skeleton and animation
+
+Keep the canonical wrapper above the imported skeleton. Never apply alignment rotation to individual bones or bake it into animation clips.
+
+After sync, verify:
+
+- Skeleton3D and skinned meshes share the expected imported hierarchy;
+- animations bind to existing node/bone paths;
+- root motion is handled by one gameplay policy, not both AnimationTree and entity movement;
+- frame zero does not snap because an animation track overwrites the wrapper;
+- sockets for weapons or effects attach to bones/markers below the imported root as intended.
+
+Retargeting, missing bones, broken weights and unusable clip naming are structural problems. Mark structural review non-ready and return to the canonical/Blender repair flow. A Godot AnimationTree state machine is not a geometry repair mechanism.
+
+When replacing a character source, repeat structural and semantic review even if the silhouette appears unchanged; bone names and clip bindings are part of the maintained state.
+

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/compose-quality.md

@@ -0,0 +1,10 @@
+# Compose Quality Checklist
+
+- [ ] Camera model matches `scene_profile_id`
+- [ ] Depth layer table documented and applied
+- [ ] Parallax ratios sensible; Far slower than Play
+- [ ] Tint/vignette does not gray-out state colors
+- [ ] Shake/punch does not hide next decision
+- [ ] No CSS/transform scaling of the game canvas
+- [ ] Near occluders do not block critical telegraphs
+- [ ] Readability tests passed on mobile screenshot

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/performance-safe-visual-detail.md

@@ -0,0 +1,9 @@
+# Performance-Safe Visual Detail Checklist
+
+- [ ] Particle/emitter caps set and respected
+- [ ] Bullets/FX/enemies pooled where spammy
+- [ ] Large biome textures unload or reuse across scenes when possible
+- [ ] Parallax layer count justified (≤ strong layers, not many weak)
+- [ ] First-cut order documented (what drops on low FPS)
+- [ ] No per-frame texture generation
+- [ ] Lights Manager avoided unless budgeted

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/premium-game-quality-gate.md

@@ -0,0 +1,15 @@
+# Premium Game Quality Gate (2D)
+
+Before claiming premium / showcase / release-ready visuals:
+
+- [ ] `scene_profile_id` recorded from `scene-profiles.md`
+- [ ] Active-play screenshot compared to `assets/scorecard-anchors/` before scoring
+- [ ] Reference ledger complete (no skipped required refs without reason)
+- [ ] Asset sourcing ledger complete for hero + main background (+ primary hazards)
+- [ ] Visual scorecard filled; premium or showcase thresholds met
+- [ ] Automatic Failures = none
+- [ ] Fresh-eyes review done
+- [ ] Mobile active-play screenshot captured
+- [ ] Technical art brief + budgets noted
+- [ ] Formal HUD still DOM (unless project explicitly requires Canvas HUD)
+- [ ] Playability not regressed (controls, hitboxes fair)

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/sprite-quality.md

@@ -0,0 +1,10 @@
+# Sprite Quality Checklist
+
+- [ ] Hero facing matches movement/art brief
+- [ ] Hero readable at mobile play size without glow crutch
+- [ ] Hazards: enough silhouette variants for the genre (or documented single-threat)
+- [ ] Rewards distinct from hazards in shape and color
+- [ ] Backgrounds free of characters/UI baked into plates
+- [ ] Spritesheet frame sizes measured before loader config
+- [ ] `config.json` keys bound for all premium surfaces claimed
+- [ ] Collision proxies fair vs art overhang

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/technical-art-quality.md

@@ -0,0 +1,9 @@
+# Technical Art Quality Checklist
+
+- [ ] Technical art brief written before broad visual changes
+- [ ] Hero vs support surfaces listed
+- [ ] Texture/atlas plan noted
+- [ ] VFX language + caps noted
+- [ ] Asset strategy per high-value surface recorded
+- [ ] Mobile constraints acknowledged
+- [ ] Post-pass diagnostics reported (even if qualitative + caps)

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/visual-scorecard.md

@@ -0,0 +1,9 @@
+# Visual Scorecard Checklist (2D)
+
+- [ ] Compared active-play screenshot to `assets/scorecard-anchors/` (scene-1 / scene-2 / scene-3)
+- [ ] Scored from active-play screenshot (not title-only)
+- [ ] All 10 categories scored 0–3 with one-line evidence
+- [ ] Average computed
+- [ ] Automatic Failures checked explicitly
+- [ ] Fresh-eyes weakest-two named
+- [ ] Measured evidence cited for textures/config/screenshots where claiming ≥2 on fidelity/performance

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/compose-recipes.md

@@ -0,0 +1,71 @@
+# Compose Recipes (Phaser 2D)
+
+Use before changing camera, parallax, global tint, vignette, depth sorting, or screen-space overlays. Compose supports readability; it is not a replacement for authored sprites.
+
+## Camera
+
+| Model | When | Notes |
+| --- | --- | --- |
+| Lock | `portrait_stage`, `board_table`, `fixed_arena` | Punch zoom on big events only |
+| Follow + deadzone | `side_scroll_lane`, `topdown_map`, `runner_lane` | Deadzone avoids jitter |
+| Room snap | Metroidvania-like | Bounds = room; no lerp fight |
+
+Rules:
+
+- Camera logic stays out of gameplay Systems when possible.
+- Shake intensity scales with event severity; never obscure the next hazard.
+- Prefer Phaser camera effects over CSS transforms on the canvas.
+- World bounds and physics bounds stay aligned (`phaser-2d-game`).
+
+## Parallax
+
+1. Place Far → Mid → Play → Near per `DepthLayers`.
+2. Set `scrollFactorX/Y` (or parent container motion) so Far moves slowest.
+3. Near may move slightly faster than Play for depth, but must not cover telegraphs.
+4. Disable strong parallax on `topdown_map` / `board_table` unless subtle.
+
+Reject: background scrolling faster than player decision reading; mismatched tile seams while scrolling.
+
+## Tint / Overlay / Vignette
+
+Use a single full-screen Image/Graphics or Camera fade for:
+
+- Biome mood (cool night, warm dusk).
+- Pressure (arena wave)—keep center Play clearer than edges.
+- Damage flash (≤100–150ms).
+
+Do **not**:
+
+- Stack multiple multiply overlays until art is gray mush.
+- Use permanent heavy vignette to hide empty Far layers.
+- Recolor every sprite differently so the palette collapses.
+
+Signal colors (hazard / reward / safe) stay consistent with HUD tokens.
+
+## Depth Sorting
+
+- Static world: fixed depths from the layer table.
+- Mobile actors: Y-sort within Play band, or explicit depth = `base + y`.
+- VFX above the actor that owns them, below Near occluders unless the FX is screen-space.
+
+## Screen FX vs World FX
+
+| Kind | Placement | Examples |
+| --- | --- | --- |
+| World FX | At entity position, Play/Motion depth | Impact burst, dash dust |
+| Screen FX | Camera-fixed container | Hit flash, edge warning |
+
+Prefer world FX for spatial clarity; screen FX for global state only.
+
+## Readability Tests
+
+After compose changes, verify on mobile:
+
+1. Hero silhouette still finds the eye in <1s.
+2. Next hazard/reward in the decision window is unobscured.
+3. Parallax does not cause mis-taps on touch targets (DOM HUD separate).
+4. No CSS scaling of the game canvas.
+
+## Checklist Hook
+
+Run `checklists/compose-quality.md` before scoring the Compose category.

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/graphics-prompt-templates.md

@@ -0,0 +1,33 @@
+# Graphics Pass Prompt Templates (Phaser 2D)
+
+Use only when the user asks for reusable prompts or a templated graphics pass.
+
+## Full premium pass
+
+```text
+Load phaser-2d-graphics-builder. Select or confirm scene_profile_id from game-art/references/scene-profiles.md (2D Compose rail only).
+Fill reference ledger (visual-scorecard, implementation-blueprint, sprite-recipes, compose-recipes, technical-art).
+Score current mobile active-play screenshot. Build asset sourcing ledger; generate missing hero/bg/parallax via game-asset-image-generator.
+Upgrade all weak surfaces; then compose; then event VFX. Re-score to premium thresholds or list blockers.
+```
+
+## Hero + background only
+
+```text
+Graphics pass scoped to hero silhouette and Far/Mid backgrounds for profile <id>.
+MCP-generate and bind config keys; do not redesign HUD. Report scorecard categories 2, 5, 6 only plus blockers.
+```
+
+## Compose-only
+
+```text
+Do not regenerate art. Fix camera/parallax/depth/tint per compose-recipes for profile <id>.
+Verify readability tests; update technical-art notes if layer count changed.
+```
+
+## VFX-only
+
+```text
+Sprites/world already premium. Add event-driven FX from vfx-recipes for: <events>.
+Pool emitters; respect technical-art caps; no ambient filler.
+```