evomeme 0.1.9 → 0.1.10

package/dist/skills/en-US/godot-3d-game/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: godot-3d-game
+description: Build and maintain 3D games with Godot 4, and consume EvoMeme canonical asset packages. Use when the work involves Godot scene structure, GLB import, alignment wrappers, skeleton animation, colliders, builds, or 3D runtime QA; when assets are not ready, you must return to game-asset-align.
+---
+
+# Godot 3D Game
+
+## Responsibility boundary
+
+Godot is the shipping runtime, not an asset-orientation guesser. The source of truth for asset alignment belongs to `game-asset-align`; this skill is responsible for import gates, the single wrapper, game-scene integration, and real-device Godot validation.
+
+## Required workflow
+
+1. Confirm that the project root contains `project.godot`, and read the reference files relevant to the task.
+2. **After Blender modeling, you must open the Stage board first, and only import into Godot after confirmation.** Read the canonical `asset.json` and run format checks, call `evomeme_stage_open({workspace_dir, asset_id, target:"godot"})`, and compare space, structure, materials, and lighting between Blender and the native Godot view in Stage. The user clicks "Confirm current version, allow import". You must not click for the user, write confirmation files, or skip this using a technical ready status.
+3. Call `evomeme_asset_sync_to_godot`; do not manually copy some files.
+4. Use `CanonicalAssetLoader.load_scene(parent, package_dir)` for complete scenes, while also connecting the Stage-confirmed PBR material calibration, lights, environment, exposure, and camera. Use `load_package` when a prop enters an existing level to avoid stacking scene environments. A model may only be under one `A3AlignmentRoot` with `canonical_alignment_key`.
+5. Layer gameplay nodes, animation, collision, and the visible model separately; do not compensate the canonical Transform in the character controller or animation tree.
+6. Check composition, grounding, orientation, scale, materials, and interactive collision in the real Godot runtime view.
+
+## Routing references
+
+- Project directory and scene layering: read [project-structure.md](references/project-structure.md).
+- Materials, lighting, exposure, camera, and Stage native preview: read [appearance-alignment.md](references/appearance-alignment.md).
+- v2 loader, revision, and single-wrapper rules: read [canonical-asset-runtime.md](references/canonical-asset-runtime.md).
+- Pre-import/runtime/delivery gates: read [alignment-gates.md](references/alignment-gates.md).
+- GLB import, inherited scenes, and wrapper maintenance: read [import-and-wrapper-scenes.md](references/import-and-wrapper-scenes.md).
+- Character skeletons and animation: read [skeleton-animation.md](references/skeleton-animation.md).
+- Physics bodies and collision layers: read [physics-colliders.md](references/physics-colliders.md).
+- Build, runtime, and screenshot QA: read [build-and-qa.md](references/build-and-qa.md).
+
+## Completion gates
+
+- The sync result has `alignment_status=aligned` and a non-empty `alignment_key`.
+- Stage confirmation comes from the current native Godot view; after changing the model or display configuration, view and confirm again, then sync.
+- The same asset has only one canonical alignment root in the Godot scene.
+- Model nodes preserve the original imported Transform, and game logic does not apply repair recipes repeatedly.
+- Skeleton, animation, collision, and visual nodes have separated responsibilities.
+- Accept using actual Godot runtime screenshots; when deviations are found, update the canonical package and do not patch locally in Godot.

package/dist/skills/en-US/godot-3d-game/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Godot 3D Game"
+  short_description: "Build Godot 4 3D games and safely consume continuously aligned canonical assets"
+  default_prompt: "Please use $godot-3d-game to integrate the accepted canonical assets into this Godot 4 project, and complete scene, runtime, and build validation."
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/en-US/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/en-US/godot-3d-game/references/appearance-alignment.md

@@ -0,0 +1,52 @@
+# Godot Basic Material and Lighting Alignment
+
+## Required Order
+
+**Model/modify and save with Blender MCP -> evomeme_scene_export_blender -> select Godot in Stage -> user reviews and confirms -> sync_to_godot -> Godot project integration and revalidation.** For the source contract, optional procedural material baking, and parameters, see [scene export workflow](../../game-asset-align/references/blender-scene-pipeline.md).
+
+`evomeme_stage_open({workspace_dir,asset_id,target:"godot"})` opens the target-engine viewport. The host provides `godot` through `EVOMEME_GODOT` / `GODOT_PATH` (absolute executable path) or PATH. The PNG on the right comes from an independent native Godot process, and the model snapshot is written to `.evomeme/godot-previews/`; it is not written into the final game project early. The left side uses the Blender baseline that matches the contract camera or a native render from the current camera position. You cannot confirm an old frame when Godot is not installed, native rendering fails, or the camera position changes.
+
+## Data and Adjustable Parameters
+
+By default, preserve standard GLB PBR materials and textures, normals, and transparency; enable linear vertex colors for meshes with COLOR_0. By default, rebuild SUN/POINT/SPOT from `scene.contract.json.blender_lights`, converting positions and Blender Euler XYZ light directions as `[x,y,z]->[x,z,-y]`. AREA is approximated with a spotlight, and the interface shows this clearly; power is a basic conversion and must be visually calibrated.
+
+When calibration is needed, write `runtime/godot.profile.json` inside the package, add the file byte count and SHA-256 to `scene.contract.json.files`, and set `display_profiles.godot.profile_file` to that path. For example:
+
+```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}]
+}
+```
+
+Materials are overridden by exact name. Missing names cause native preview failure to avoid silent no-ops. You can also specify `albedo_srgb` RGBA, `emission_srgb` RGB, `emission_energy`, and `double_sided`; unspecified fields preserve GLB values and textures.
+
+You can explicitly provide a `lights` array to replace derived lights. Each item's `type` is `directional/omni/spot`, using Godot Y-up metric `position`, `quaternion_xyzw`, `color_linear` RGB, `energy`, `range`, `spot_angle_degrees` (half-angle, 0.1-89), and `shadow_enabled`. `lights:[]` explicitly disables extra lights. Explicit configuration uses Godot energy values and no longer performs Blender power conversion.
+
+## Comparison and Modification Loop
+
+Color ambient light is fixed at `ambient_light_sky_contribution=0`, preventing the default sky contribution value from making the profile's color ambient light ineffective. Compatibility vertex colors participate in shading as sRGB and cannot rely only on the `vertex_color_is_srgb` switch: the shared adapter encodes glTF linear COLOR_0 into a private mesh copy, updates only RGB bytes, and preserves Alpha, UVs, indices, skeletons, LOD, and source resources; Forward+/Mobile keep linear data. Native Stage hides `-colonly` / `-convcolonly` helper meshes (including copy suffixes) to prevent GLTFDocument runtime loading from drawing colliders as physical objects.
+
+1. Fix the camera quaternion, vertical FOV, and frame, and check front/back faces, normals, transparency, textures, and vertex colors.
+2. Check key light direction, light/dark relationships, shadows, roughness, metallic highlights, emission, ambient color, and exposure.
+3. Fix geometry/node materials back in Blender; make basic engine calibration changes in the Godot profile, and update the manifest summary.
+4. Reload Stage and click confirm in the current native Godot view. `ready=true`, passing spec checks, or Three.js confirmation cannot replace this step.
+5. After sync, use `CanonicalAssetLoader.load_scene(parent, package_dir)` for complete scenes. It applies the same `canonical_appearance.gd`, `godot.appearance.json`, and camera as the preview; `load_package` only handles prop models and spatial transforms.
+
+## Runtime and Scope
+
+profile.renderer supports gl_compatibility (default), mobile, and forward_plus. During export, the actual renderer of an existing project can be read; Stage uses the same mode for native preview and does not silently fall back to OpenGL; during sync, it verifies that the target project mode is consistent. Choosing a more advanced renderer does not automatically implement volumetric or GI resource conversion, and the board still clearly shows missing items. Camera3D keeps vertical FOV; callers use SubViewport or margins to preserve the confirmed frame. The scene environment is connected only once to avoid stacking with the level's existing WorldEnvironment/lights. The gameplay camera can take over after integration, and after changes, composition and materials must be revalidated.
+
+Godot export settings must include `*.json` non-resource files to ensure asset.json/godot.appearance.json are packaged into the game. Three.js shaders, Cycles full-scene baked display modules, and LUTs in the spec are not executed by Godot. Basic PBR and real-time lights/fog do not promise pixel-by-pixel equivalence for Blender procedural nodes, volumetric light, or indirect light.
+
+API basis: [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/en-US/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/en-US/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/en-US/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/en-US/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/en-US/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/en-US/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/en-US/phaser-2d-game/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: phaser-2d-game
+description: Implement 2D browser games with Phaser, TypeScript, and Vite. Use when scenes, gameplay systems, cameras, sprite animation, Arcade physics, tilemaps, DOM-overlay HUDs, or portrait touch controls are needed.
+---
+
+# Phaser 2D Game Implementation
+
+## Overview
+
+This skill is used for the concrete implementation phase of 2D browser games.
+
+Tech stack: **Phaser 3 + TypeScript + Vite + pnpm**. Production HUDs/menus use a **DOM overlay** (usually React) layered over the Canvas.
+
+## Architecture Principles
+
+1. **Separate Systems and Scenes**
+   - Systems own game rules, turn order, movement, combat, inventory, objectives, and progress logic. (Aligned with `game/simulation` in the 3D skill: the rules source-of-truth layer)
+   - Phaser Scene only maps system state to sprite positions, camera movement, animation playback, and effects; it does not hold game truth.
+
+2. **Keep Scenes Lightweight**
+   - Boot Scene: configuration initialization and asset preloading
+   - Menu Scene: main menu or shell layer (complex menus can still use DOM)
+   - Gameplay Scene: main game-loop view
+   - Optional: parallel debug Scene (does not replace the production HUD)
+
+3. **Renderable Objects Are Disposable**
+   - Sprite containers, particles, Tweens, and camera rigs are view state, not data sources.
+
+4. **Asset Keys Are Stable**
+   - Reference assets through a manifest / `public/config.json`; business code must not hardcode scattered URLs.
+
+## Implementation Guidance
+
+- Scene reads System through a single boundary and sends input intents back to System.
+- Prefer deterministic system updates; avoid piling complete rules into `update`.
+- Use DOM, not dense Canvas text, for text-heavy HUDs/menus with complex state.
+- Derive animation state from game state.
+- **Use only Phaser Scale Manager for viewport scaling**; CSS/`transform` hand-rolled scaling is forbidden (see `references/engine-runtime.md`).
+- **Measure the image before writing a spritesheet loader** (see `references/engine-spritesheets.md`).
+
+## Engine References (Load As Needed)
+
+When writing/modifying Phaser runtime code, load references by task in addition to `file-structure.md`; do not preread all of them at once:
+
+| Task | Load |
+| --- | --- |
+| Scene lifecycle, Scale, delta, scene switching | `references/engine-runtime.md` |
+| Arcade/Matter selection, collisions, object pools | `references/engine-physics.md` |
+| Any spritesheet / atlas / nine-slice | `references/engine-spritesheets.md` (before loading the sheet) |
+| Tiled maps, collision layers, spawning objects | `references/engine-tilemaps.md` |
+| Stutter, pooling, culling, update allocations | `references/engine-performance.md` |
+
+## Covered 2D Game Types
+
+- Turn-based grids and tactical chess-like games
+- Top-down exploration maps
+- Side-scrolling action platformers
+- Character action combat (sprite animation frames)
+- Lightweight management or card/command-battle scenes
+
+## Camera and Presentation
+
+- Decide the camera model early: locked, follow, room switching, tactical panning.
+- Keep camera logic completely separate from game rules.
+- Shake, hit-stop, and parallax must improve readability and must not obscure key information.
+- Large maps: align `cameras.setBounds` with `physics.world.setBounds`.
+
+## UI Integration
+
+- Use DOM overlays for HUDs, command menus, settings, and narrative.
+- Canvas is responsible for the game world, combat readability, and motion presentation.
+- Unless the project explicitly requires it, do not render dense text or complex settings UI inside Phaser.
+
+## Asset Directory Convention
+
+```
+assets/
+  characters/   sprites, frame animations
+  environment/  backgrounds, tiles, scene props
+  ui/           HUD images, icons, buttons
+  fx/           particles, effects
+  audio/        BGM, SFX
+  data/         level config, dialogue data, Tiled JSON
+```
+
+## Scaffolding and Configuration
+
+New project entry points: `index.html`, `src/main.ts`, `public/config.json`. The package manager is **pnpm**. Build output includes `dist/index.html` and `dist/config.json`. The directory and config schema use `references/file-structure.md` as the only normative source.
+
+## Common Anti-Patterns
+
+When React and Phaser coexist, calling `createGame()` immediately after `root.render()` creates a startup race: React has not yet committed `#game-container`, so Phaser may mount the Canvas at the wrong layer and cover the menu, while the game still remains in the `menu` or `inputLocked` state; the result is a visible screen that cannot be operated. Use `flushSync`, `useLayoutEffect`, a callback ref, or an explicit container-ready signal, start in the order "React container commit complete -> container exists and has valid dimensions -> create Phaser", and check the container and Canvas mount relationship before initialization; when clicks are ineffective, first confirm UI state, input locks, and DOM structure, then adjust the event path.
+
+React development mode performs one extra mount cleanup and restart. If an old Phaser Scene is destroyed without unregistering its event listeners, a button may receive the click, but the event may first hit the already-destroyed old Scene, then throw and interrupt the new Scene's click handling. It is forbidden to destroy only the Phaser instance while leaving Scene listeners registered on the input system, DOM, `window`, a shared EventEmitter, or the React bridge layer; every `on`, `addEventListener`, or subscription must have a corresponding `off`, `removeEventListener`, or unsubscribe, and cleanup must be completed in the Scene's `SHUTDOWN`/`DESTROY` and React effect cleanup. In development mode, you must verify that after repeated "create -> cleanup -> create", only the current Scene responds to a click once.
+
+- Game rules are written in Scene `update` with no system boundary
+- Scenes pass state through mutable `window` globals
+- CSS scaling is used for Canvas instead of Scale Manager
+- spritesheet frameWidth/Height are guessed without measurement
+- Matter is used for simple AABB
+- Bullets/enemies are constantly created and destroyed without pooling
+- Production HUD is drawn on Canvas just for convenience
+- Asset paths are hardcoded in many places
+- A generic React dashboard pattern is applied to game UI
+- CRA / Next.js / npm-only scaffolding replaces this specification (unless the user explicitly requests it)
+
+## References
+
+**Engine (This Skill)**
+- File structure and layering: `references/file-structure.md`
+- Runtime / scaling: `references/engine-runtime.md`
+- Physics and object pools: `references/engine-physics.md`
+- Spritesheet / atlas: `references/engine-spritesheets.md`
+- Tilemap: `references/engine-tilemaps.md`
+- Performance: `references/engine-performance.md`
+
+**Cross-Skill**
+- Art style: `../game-art/references/art-styles.md`
+- Spatial composition patterns: `../game-art/references/scene-profiles.md`
+- 2D visual quality improvement: `../phaser-2d-graphics-builder/SKILL.md`
+- Animation specs: `../game-art/references/animation-specs.md`
+- UI style: `../game-ui/references/ui-styles.md`
+- Game feel: `../game-designer/references/game-feel.md`
+- Level design: `../game-designer/references/game-design-level-design.md`
+- New game DoD: `../game-designer/references/checklists/new-game-definition-of-done.md`
+- Game feel checklist: `../game-designer/references/checklists/game-feel.md`
+- Level checklist: `../game-designer/references/checklists/game-design-level-design.md`

package/dist/skills/en-US/phaser-2d-game/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Phaser 2D Game"
+  short_description: "Build clearly structured 2D browser games, handling scenes, gameplay, input, and UI integration"
+  default_prompt: "Please use $phaser-2d-game to implement this 2D browser game according to my requirements, and keep the scene, gameplay system, and UI boundaries clear."
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/en-US/phaser-2d-game/references/engine-performance.md

@@ -0,0 +1,64 @@
+# Engine: Performance
+
+Load this when there is stutter, frame drops, or spawn spikes.
+
+## Priority Items
+
+1. **Object pools**: bullets, enemies, floating text, short-lived particle carriers — see `engine-physics.md`  
+2. **Atlases**: keep on-screen assets in the same atlas where possible to reduce texture switching  
+3. **Fewer collision pairs**: attach only needed collider/overlap pairs; disable offscreen bodies  
+4. **No allocations in update**: do not create `{}` / `new Vector2` every frame; reuse temporary vectors  
+5. **Use delta for time**: `delta/1000`; AI/pathfinding can run at a lower frequency  
+
+## Physics
+
+```ts
+// Offscreen bodies can be disabled
+enemy.body.enable = cam.worldView.contains(enemy.x, enemy.y);
+
+// Circular collision is often cheaper than a large rectangle
+sprite.body.setCircle(16);
+```
+
+With many dynamic bodies, evaluate `arcade.useTree` / `maxEntries`; consider disabling the tree only after >5000 bodies (based on measurement).
+
+## Rendering
+
+- Use `tileSprite` or a static image for backgrounds; do not redraw large images every frame  
+- Use ADD/MULTIPLY and similar blending cautiously (they can easily split batches)  
+- Set particle `maxParticles` / `frequency`  
+- Sprites outside the camera are culled by default; fixed UI with `scrollFactor 0` on Canvas must be intentional (production HUD still uses DOM)
+
+## Memory and Scene Switching
+
+```ts
+shutdown() {
+  this.enemies?.clear(true, true);
+  // this.textures.remove('only-this-level') as needed;
+}
+```
+
+When changing levels, unload only this level's large images/tilemap; shared atlases can stay.
+
+## Reduce Frequency of Expensive Logic
+
+```ts
+if (time - this.lastAiAt > 100) {
+  this.lastAiAt = time;
+  this.updateEnemyAi(); // Can also be on the System side
+}
+```
+
+Movement/camera runs every frame; AI, pathfinding, and cleanup scans can run at 5-10Hz.
+
+## Quick Check Table
+
+| Symptom | Common Cause | Handling |
+| --- | --- | --- |
+| Slower over time | Leak not destroyed | Check pools and shutdown |
+| Periodic stutter | GC | Pool, reduce update allocations |
+| Constant low FPS | Too many objects/draws | Cull, atlas, reduce particles |
+| Spawn spike | Create on the spot | Pre-pool |
+| Collision stutter | Check pair-count explosion | Reduce pairs, simplify shape |
+
+During development, you can inspect `this.game.loop.actualFps`; for release, turn off physics debug and dense FPS text (or keep only a DOM debug toggle).

package/dist/skills/en-US/phaser-2d-game/references/engine-physics.md

@@ -0,0 +1,139 @@
+# Engine: Arcade Physics and Object Pools
+
+Gameplay values still belong to System / `config.json`; this file only covers Phaser physics APIs and common pitfalls.
+
+Load this when modifying collisions, platforms, bullet pools, knockback, or one-way platforms.
+
+## World Config (Excerpt)
+
+```ts
+physics: {
+  default: 'arcade',
+  arcade: {
+    gravity: { x: 0, y: 300 }, // Can be multiplied by config gravity_scale
+    debug: false,              // Turn off for release
+    fps: 60,
+    overlapBias: 4,
+    tileBias: 16,
+    useTree: true,             // Re-evaluate false only with extremely many dynamic bodies
+  },
+}
+```
+
+## Body Types
+
+- **Dynamic**: velocity, gravity, collision response (player, enemies, bullets).
+- **Static**: unmoving platforms; call `refreshBody()` / group `refresh()` after changing scale/position.
+
+```ts
+const player = this.physics.add.sprite(100, 100, 'player');
+player.body.setCollideWorldBounds(true);
+player.body.setSize(24, 40, true);
+player.body.setOffset(4, 8);
+player.body.setMaxVelocity(300, 400);
+player.body.setDrag(100, 0);
+```
+
+Circle body: `setCircle(radius, offsetX, offsetY)`. The visual mesh can be larger than the body; **do not** use an entire large image as the collision box.
+
+## Collider vs Overlap
+
+```ts
+// Physical separation
+this.physics.add.collider(player, platforms);
+this.physics.add.collider(player, enemies, onHit, processCb, this);
+
+// Detect overlap only (pickup, trigger)
+this.physics.add.overlap(player, coins, onCollect, undefined, this);
+```
+
+A `process` callback can return `false` to skip this collision (invulnerability frames, one-way platforms).
+
+### Grounded / Wall Contact
+
+```ts
+if (player.body.blocked.down) { /* grounded */ }
+if (player.body.touching.down) { /* standing on a body */ }
+if (player.body.wasTouching.down && !player.body.touching.down) { /* just left the ground */ }
+```
+
+### World Bounds
+
+```ts
+this.physics.world.setBounds(0, 0, mapWidth, mapHeight);
+this.cameras.main.setBounds(0, 0, mapWidth, mapHeight);
+this.cameras.main.startFollow(player, true, 0.08, 0.08);
+```
+
+## Object Pools (Required for High-Frequency Spawning)
+
+```ts
+this.bullets = this.physics.add.group({
+  defaultKey: 'bullet',
+  maxSize: 100,
+});
+
+function fire(x: number, y: number, vx: number, vy: number) {
+  const b = this.bullets.get(x, y);
+  if (!b) return;
+  b.setActive(true).setVisible(true);
+  b.body.enable = true;
+  b.body.reset(x, y);
+  b.setVelocity(vx, vy);
+}
+
+function kill(b: Phaser.Physics.Arcade.Sprite) {
+  b.setActive(false).setVisible(false);
+  b.body.enable = false;
+  b.body.stop();
+}
+```
+
+It is forbidden to `new` / `destroy` bullets and particle carriers every frame on hot paths.
+
+## Common Patterns
+
+### Platform Jump
+
+```ts
+if (jumpPressed && player.body.blocked.down) {
+  player.setVelocityY(-330); // Height uses config
+}
+```
+
+### Acceleration Movement
+
+```ts
+player.body.setMaxVelocity(maxSpeed);
+player.body.setDrag(drag, 0);
+player.body.setAccelerationX(left ? -accel : right ? accel : 0);
+```
+
+### One-Way Platform
+
+```ts
+function oneWay(
+  player: Phaser.Physics.Arcade.Sprite,
+  platform: Phaser.Physics.Arcade.Sprite,
+) {
+  return (
+    player.body.velocity.y > 0 &&
+    player.body.bottom <= platform.body.top + 10
+  );
+}
+this.physics.add.collider(player, platforms, undefined, oneWay, this);
+```
+
+### Knockback
+
+After changing velocity, System records invulnerability; Scene only plays feedback. The `setVelocity` direction is determined by relative position.
+
+## Layering with System
+
+- In collision callbacks: hand the event to System **first** (damage, pickup), then modify the view (white flash, disable sprite).
+- Do not scatter duplicate win/loss rules inside callbacks.
+- `debug: true` is development-only; turn it off before release and screenshots.
+
+## Matter?
+
+Only when Arcade AABB is insufficient (complex polygons, joints, ragdolls). Do not enable physics for menus/cards. For detailed requirements, consult the Phaser Matter docs; keep Arcade as the default path.