@codyswann/lisa 2.161.0 → 2.162.0

package/plugins/lisa-phaser-cursor/skills/phaser-scenes/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: phaser-scenes
+description: This skill should be used when creating or editing Phaser 4 scenes — the init/preload/create/update lifecycle, starting/stopping/sleeping scenes, running scenes in parallel (HUD/pause overlays), passing data between scenes, the registry, and event-based communication. Use it when adding a scene, wiring scene transitions, or debugging lifecycle/ordering issues. Pairs with phaser-project-structure, phaser-assets, and phaser-gameobjects.
+---
+
+# Phaser 4 Scenes
+
+## Overview
+
+Scenes are Phaser's unit of game-flow composition. The lifecycle is unchanged
+from Phaser 3 — `init(data)` → `preload()` → `create(data)` → `update(time, delta)`
+— and each scene owns its display list, input, camera, time events, and (if
+enabled) physics world.
+
+One scene class per file under `src/scenes/`, exported as a class whose key
+matches the file name:
+
+```ts
+export class Game extends Phaser.Scene {
+  constructor() {
+    super("Game"); // the scene key — also a constant in src/assets.ts
+  }
+  init(data: GameStartData) { /* receive data, reset state */ }
+  preload() { /* per-scene late loads only — bulk loading is the Preloader's job */ }
+  create() { /* build GameObjects, wire input + events */ }
+  update(_time: number, delta: number) { /* per-frame; delta in ms */ }
+}
+```
+
+## Lifecycle rules
+
+- `init` receives the data passed by `scene.start(key, data)` — type that payload
+  (an interface per scene) instead of `any`.
+- `preload` in gameplay scenes should be rare; the Preloader scene loads the game
+  pack up front ([[phaser-assets]]). Use per-scene `preload` only for genuinely
+  scene-local or late-bound assets.
+- `create` is where GameObjects are built. Everything constructed here must be
+  cleaned up on shutdown if it lives outside the scene's display list (timers on
+  other scenes, global event listeners, DOM elements).
+- `update(time, delta)` runs per render frame. Frame-rate-independent movement
+  multiplies by `delta`; physics movement belongs in Arcade bodies, not manual
+  position math ([[phaser-physics]]).
+
+## Scene control
+
+Via `this.scene` (the ScenePlugin):
+
+- `start(key, data)` — stop the current scene, start another.
+- `launch(key, data)` — start another scene **in parallel** (HUD, pause overlay).
+- `pause` / `resume`, `sleep` / `wake` — suspend update/render without rebuild.
+- `stop(key)` — shuts a scene down (fires `Phaser.Scenes.Events.SHUTDOWN`).
+- `bringToTop` / `sendToBack` — z-order between parallel scenes.
+
+Overlay pattern: `Game` launches `HUD`; `HUD` renders score/health and listens to
+events from `Game`. Pause: launch `Pause`, `this.scene.pause("Game")`.
+
+## Communicating between scenes
+
+In preference order:
+
+1. **Events** — emit on the scene's own emitter and have the other scene listen:
+   `gameScene.events.emit("score-changed", score)`. Always remove listeners on
+   `SHUTDOWN`: `this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => …)`.
+2. **`scene.start`/`launch` data** — for handoff at transition time.
+3. **The registry** (`this.registry`) — game-wide key/value store with change
+   events; for cross-cutting state like settings or the run seed.
+
+Never reach into another scene's GameObjects directly
+(`this.scene.get("Game").player.x = …`) — that couples scenes to each other's
+display-list internals and breaks when the other scene rebuilds.
+
+## Project conventions
+
+- Scene keys are constants in `src/assets.ts` (e.g. `SceneKeys.Game`) — `super(SceneKeys.Game)`.
+- A scene is an orchestrator: input wiring, GameObject lifecycles, and event
+  plumbing. Game rules live in `src/logic/**` and are called from the scene.
+- Per-scene state is reset in `init`, not in field initializers — scene classes
+  are instantiated once but started many times; stale fields from a previous run
+  are a classic restart bug.
+
+## Verification
+
+A scene change is verified by booting the game (`bun run dev`) and exercising the
+actual transition: start → play → (pause/resume or restart) → confirm no
+duplicated listeners (events firing twice after a restart is the canonical
+symptom of a missed `SHUTDOWN` cleanup).

package/plugins/lisa-phaser-cursor/skills/phaser-testing/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: phaser-testing
+description: This skill should be used when writing or designing tests for a Phaser 4 game — unit-testing pure game logic with Vitest, keeping logic Phaser-free so it tests without a browser, the Phaser.HEADLESS renderer for logic-only boots, asset-manifest coverage tests, and Playwright smoke tests that prove the game actually boots and renders. Use it when adding tests, setting up CI verification, or deciding what is testable at which level. Pairs with phaser-project-structure, phaser-assets, and phaser-physics.
+---
+
+# Phaser 4 Testing
+
+## Overview
+
+Games are testable when the game is not welded to the engine. The stack's test
+pyramid, bottom-up:
+
+1. **Vitest unit tests** over `src/logic/**` — the bulk of coverage.
+2. **Manifest/contract tests** — cheap structural checks (asset packs, scene
+   keys, anim definitions).
+3. **Playwright smoke test** — the game boots in a real browser, renders past
+   the Preloader, no console errors.
+
+There is no official Phaser testing harness — this layering IS the strategy.
+
+## Layer 1: pure logic under Vitest (the rule that makes it possible)
+
+`src/logic/**` contains game rules as plain TypeScript with **no `phaser`
+imports**: damage calculation, wave spawning schedules, inventory, scoring,
+state machines, procedural generation. Scenes call logic; logic never touches
+GameObjects.
+
+```ts
+// src/logic/score.ts
+export function comboMultiplier(streak: number): number { … }
+
+// tests/logic/score.test.ts — plain vitest, node environment, no browser
+import { comboMultiplier } from "../../src/logic/score";
+it("caps the combo multiplier at 8x", () => {
+  expect(comboMultiplier(999)).toBe(8);
+});
+```
+
+Determinism makes this work for anything random: logic takes a
+`Phaser.Math.RandomDataGenerator`-compatible interface (or just a `() => number`)
+as a parameter, production passes the seeded RND, tests pass a fixed sequence.
+
+If a piece of "logic" can't be tested without constructing a Scene, that is a
+design smell — extract the rule from the scene first, then test it.
+
+## Layer 2: contract tests
+
+Cheap tests that catch the silent runtime failures Phaser is famous for:
+
+- **Asset coverage**: every key constant in `src/assets.ts` appears in
+  `public/assets/pack.json` (and optionally vice versa). A missing pack entry
+  otherwise ships as a green-square texture ([[phaser-assets]]).
+- **Scene registry**: every `SceneKeys` constant has a scene class registered in
+  the game config's `scene` array.
+- These are plain Vitest tests reading JSON/TS — no Phaser instance needed.
+
+## Layer 3: booting Phaser in tests (use sparingly)
+
+`Phaser.HEADLESS` (renderer type 3) boots a Game without creating a canvas or
+WebGL context — but Phaser still expects DOM-ish globals, so it needs a
+browser-like environment (jsdom/happy-dom) and careful teardown
+(`game.destroy(true)`). Reserve headless boots for integration tests of things
+that genuinely need the engine loop (scene transitions, timer events). Most of
+what people reach for headless to test belongs in Layer 1 instead.
+
+## Layer 4: Playwright smoke
+
+The non-negotiable end of the pyramid — proof the game runs:
+
+```ts
+test("game boots and renders", async ({ page }) => {
+  const errors: string[] = [];
+  page.on("pageerror", e => errors.push(e.message));
+  await page.goto("/");
+  const canvas = page.locator("canvas");
+  await expect(canvas).toBeVisible();
+  // Past the Preloader: poll a window hook the game sets, e.g. in MainMenu.create()
+  await page.waitForFunction(() => (window as never as { __sceneReady?: string }).__sceneReady === "MainMenu");
+  expect(errors).toEqual([]);
+  await expect(page).toHaveScreenshot("boot.png", { maxDiffPixelRatio: 0.02 });
+});
+```
+
+Convention: scenes set `window.__sceneReady = key` in `create()` (dev/test
+builds) so tests await real readiness instead of sleeping. Run against
+`bun run dev` (or `vite preview` in CI).
+
+## Project conventions
+
+- `bun run test` = Vitest (layers 1–2, coverage-gated). Playwright smoke runs as
+  its own script/CI job against a built preview.
+- Tests never assert on private scene fields; they assert on logic outputs
+  (layer 1) or observable behavior (layer 4).
+
+## Verification
+
+The testing setup itself is verified when `bun run test` passes with coverage
+over `src/logic/**`, and the Playwright smoke fails when you deliberately break
+boot (rename a pack file) — a smoke test that can't fail is decoration.

package/plugins/lisa-phaser-cursor/skills/phaser-v3-migration/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: phaser-v3-migration
+description: This skill should be used when migrating a Phaser 3 game to Phaser 4, reviewing code that contains Phaser 3 idioms, or answering "does this v3 API still exist" questions — pipelines→render nodes, preFX/postFX/BitmapMask→Filters, tintFill→TintModes, removed namespaces (Geom.Point, Struct, Mesh/Plane, Camera3D, bundled Spine), config default changes, and texture-orientation changes. Pairs with phaser-rendering and phaser-project-structure.
+---
+
+# Phaser 3 → Phaser 4 Migration
+
+## Overview
+
+Phaser 4.0.0 "Caladan" (April 2026; current line v4.1 "Salusa") keeps the core
+game-facing API stable — scenes, input, Arcade/Matter physics, tweens,
+animations, audio, and the scale manager are **unchanged** — and replaces the
+rendering internals. The official estimate for a standard-API game is hours,
+not weeks. The npm package is still `phaser`; v4 ships its own
+`types/phaser.d.ts`.
+
+Upstream references for deeper detail: the official migration guide in the
+phaser repo (`changelog/v4/4.0/MIGRATION-GUIDE.md`) and the shader-specific
+guide. This skill is original Lisa content written against those primary
+sources — it is not a port of any upstream plugin or skill package.
+
+## What did NOT change (don't "migrate" these)
+
+Scene lifecycle (`init/preload/create/update`), `this.scene` control, Loader
+API (plus new `atlasPCT`), Input, Arcade & Matter physics, Tweens/Timelines,
+`anims`, Scale Manager, Sound managers, Groups, Containers, particle emitter
+API (v3.60 style).
+
+## The breaking changes, by frequency of impact
+
+| Phaser 3 | Phaser 4 |
+| --- | --- |
+| `setPipeline(...)` / `setPostPipeline(...)` / `resetPipeline()` | RenderNodes (`render.renderNodes` config) — rewrite required |
+| `preFX` / `postFX` controllers | Unified **Filter** system (internal/external lists) |
+| `BitmapMask` / `GeometryMask` | `Mask` filter; `Phaser.Actions.AddMaskShape()` |
+| Bloom/Shine/Circle FX | `Actions.AddEffectBloom()` / `AddEffectShine()` |
+| Gradient FX | `Gradient` GameObject |
+| `setTintFill(c)` / `tintFill` | `setTint(c)` + `setTintMode(Phaser.TintModes.FILL)` |
+| `setPipeline('Light2D')` | `gameObject.setLighting(true)`; lights gained `z` |
+| `Phaser.Geom.Point` | Removed — `Phaser.Math.Vector2` (geometry returns Vector2) |
+| `Phaser.Struct.Set` / `Struct.Map` | Native `Set` / `Map` |
+| Shadertoy-style `Shader` uniforms | Rewritten Shader: `ShaderQuadConfig`, `setUniform()`, `#pragma` |
+| RenderTexture/DynamicTexture draw-executes-immediately | **Buffered** — call `render()`; `preserve()`, `renderMode` |
+| Bundled Spine 3/4 plugins | Removed — Esoteric's official Phaser Spine runtime |
+| `Mesh`, `Plane`, OBJ loader, `Camera3D`, `Layer3D` | Removed, no replacement |
+| `Math.TAU` = π/2 (wrong) | `Math.TAU` = 2π (correct); `PI_OVER_2` added; `PI2` removed |
+| `Create.GenerateTexture`, polyfills, IE9 entry | Removed |
+
+## Behavior/default changes that silently alter a port
+
+- `roundPixels` default flipped **true → false**. If a pixel-art game looks
+  blurry after porting, set `pixelArt: true` (or `render.smoothPixelArt`) —
+  don't blanket-restore roundPixels.
+- **Texture Y-flip**: UVs are GL-oriented (Y=0 bottom). Standard usage is
+  translated automatically, but custom shaders and **compressed textures** must
+  be updated/re-encoded.
+- `Camera#matrix` no longer includes position (`matrixExternal` does;
+  `matrixCombined` removed) — affects code doing manual camera-space math.
+- `Grid` "outline" properties renamed to "stroke". TileSprite was rebuilt
+  (atlas frames, `tileRotation`; cropping removed). `DOMElement` without a
+  container parent now throws.
+
+## Migration procedure
+
+1. Bump `phaser` to `^4.1.0`; remove any `@types/phaser`.
+2. Typecheck — removed APIs surface as compile errors; fix using the table.
+3. Grep for the silent ones types won't catch: `Light2D`, `tintFill`,
+   `Math.TAU`, custom shader GLSL, compressed-texture loads.
+4. Rewrite pipelines/FX as RenderNodes/Filters ([[phaser-rendering]]); re-add
+   `render()` calls after DynamicTexture drawing.
+5. Swap Spine to the Esoteric runtime; check third-party plugins (`rex` users:
+   the v4 line is the separate `phaser4-rex-plugins` package, which also ships
+   `p3-fx` ports of the dropped v3 FX).
+6. Verify visually per [[phaser-rendering]] — renderer migrations produce
+   wrong-pixels bugs, not exceptions.
+
+## Project conventions
+
+This stack's lint config hard-bans the left column of the table in `src/**` —
+a migration is not complete until lint passes with those rules on, with zero
+disables.

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.161.0",
+  "version": "2.162.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/phaser/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "lisa-phaser",
+  "version": "1.0.0",
+  "description": "Phaser 4 game-development rules for TypeScript projects",
+  "author": { "name": "Cody Swann" },
+  "dependencies": ["lisa-typescript"],
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ],
+    "SubagentStart": [
+      { "matcher": "", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh" }] }
+    ]
+  }
+}

package/plugins/src/phaser/hooks/inject-rules.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into Claude context at session/subagent start.
+set -euo pipefail
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+RULES_DIR="$ROOT/rules"
+
+[ -d "$RULES_DIR" ] || exit 0
+
+for rule in "$RULES_DIR"/*.md; do
+  [ -f "$rule" ] || continue
+  printf '\n<lisa-phaser-rule path="%s">\n' "$rule"
+  cat "$rule"
+  printf '\n</lisa-phaser-rule>\n'
+done

package/plugins/src/phaser/rules/phaser.md

@@ -0,0 +1,59 @@
+# Phaser 4 Project Rules
+
+This is a **Phaser 4** (v4.1+ "Salusa") TypeScript game project. Phaser 4 is the
+only supported target — never introduce Phaser 3 idioms. The lint config enforces
+the bans below; do not disable those rules, fix the code.
+
+## Phaser 4 Only — Banned v3 Idioms
+
+- **No pipelines.** `setPipeline` / `setPostPipeline` / `resetPipeline` are gone.
+  Custom rendering is a **RenderNode** (registered via `render.renderNodes` in the
+  game config); post-processing is a **Filter** (`gameObject.filters` /
+  `camera.filters`). See the `phaser-rendering` skill.
+- **No preFX/postFX.** The v3 FX controllers were replaced by the unified Filter
+  system. `BitmapMask` → `Mask` filter.
+- **No `setTintFill`/`tintFill`.** Use `setTint()` + `setTintMode(Phaser.TintModes.FILL)`.
+- **No `Phaser.Geom.Point`** (removed — use `Phaser.Math.Vector2`) and **no
+  `Phaser.Struct.Set/Map`** (removed — use native `Set`/`Map`).
+- **No raw WebGL calls.** External GL work goes through the `Extern` game object.
+- **No `setPipeline('Light2D')`.** Lighting is `gameObject.setLighting(true)`.
+
+## Architecture
+
+- **One scene class per file** under `src/scenes/`, named after the scene key.
+  The scene flow is `Boot → Preloader → MainMenu → Game` (plus overlays). Boot
+  loads only what the Preloader needs; the Preloader loads everything else.
+- **Pure game logic lives outside scenes** in `src/logic/` (or `src/core/`) with
+  **no `phaser` imports** — plain TypeScript functions and classes that take and
+  return data. Scenes are thin orchestrators that wire logic to GameObjects.
+  This is what makes the game unit-testable; see the `phaser-testing` skill.
+- **Asset keys are typed constants** in `src/assets.ts` — never inline magic
+  strings for texture/audio/animation keys. Load via asset-pack manifests
+  (`this.load.pack`), not ad-hoc `load.image` lists scattered across scenes.
+
+## Determinism
+
+- **No `Math.random()` in game code.** Use the scene-seeded
+  `Phaser.Math.RandomDataGenerator` (`Phaser.Math.RND` or a local instance with
+  an explicit seed) so replays and tests are reproducible.
+- Arcade physics keeps its v4 default `fixedStep: true`. Do not switch physics to
+  variable step to "fix" a tunneling bug — fix the body/velocity configuration.
+
+## Performance
+
+- **No allocations in `update()`.** No `new`, array literals, closures, or
+  `.filter/.map` chains in per-frame paths — hoist scratch objects, reuse vectors.
+- **Pool, don't churn.** Bullets, enemies, particles, and pickups come from
+  `Group` pools (`get`/`killAndHide`), never `new`/`destroy` per spawn.
+- **Mass rendering uses the GPU layers.** Large static/animated sprite fields →
+  `SpriteGPULayer`; large tile maps → `TilemapGPULayer`. Texture atlases (PCT
+  where possible) over loose images — see the `phaser-assets` skill.
+- Target WebGL; the Canvas renderer is deprecated in v4 and only acceptable as an
+  explicit, documented fallback decision.
+
+## Verification
+
+Before reporting any change complete: run `bun run typecheck`, `bun run test`,
+and `bun run build`. For changes that affect rendering or input, verify in the
+real browser — `bun run dev` plus a Playwright check (the game boots, the canvas
+renders, no console errors). A green typecheck alone is not proof a game works.

package/plugins/src/phaser/skills/phaser-assets/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: phaser-assets
+description: This skill should be used when loading or organizing assets in a Phaser 4 game — the Loader (images, texture atlases, spritesheets, audio, fonts), asset-pack manifests via this.load.pack, the new PCT compact atlas format (load.atlasPCT), typed asset keys, and where files live in the Vite project. Use it when adding any asset, restructuring loading, fixing a missing-texture/green-square bug, or optimizing load size. Pairs with phaser-project-structure, phaser-scenes, and phaser-gameobjects.
+---
+
+# Phaser 4 Assets and Loading
+
+## Overview
+
+All runtime assets live under `public/assets/` (served verbatim by Vite — never
+`import` game assets through the bundler) and are loaded by Phaser's Loader in a
+scene's `preload()`. The opinionated pattern: **one asset-pack manifest, loaded
+by the Preloader, with every key defined as a typed constant.**
+
+## Asset packs (the default loading strategy)
+
+A pack is a JSON manifest the Loader consumes wholesale:
+
+```json
+{
+  "main": {
+    "files": [
+      { "type": "atlasPCT", "key": "game-atlas", "url": "atlases/game.pct" },
+      { "type": "image", "key": "background", "url": "images/background.png" },
+      { "type": "audio", "key": "sfx-jump", "url": ["audio/jump.ogg", "audio/jump.m4a"] },
+      { "type": "spritesheet", "key": "explosion", "url": "sheets/explosion.png",
+        "frameConfig": { "frameWidth": 64, "frameHeight": 64 } }
+    ]
+  }
+}
+```
+
+```ts
+// Preloader.preload()
+this.load.pack("game-pack", "assets/pack.json");
+```
+
+Why packs: loading is declared in one reviewable file instead of scattered
+`load.*` calls; adding an asset never touches scene code beyond using the key.
+
+## Texture atlases — the rule, not the suggestion
+
+Individual images break sprite batching. Everything that renders together ships
+in an atlas:
+
+- **PCT (Phaser Compact Texture)** is the preferred v4 atlas format —
+  `this.load.atlasPCT(key, url)` — its manifests are 90–95% smaller than the
+  JSON-hash equivalent. JSON/XML/Unity/multi-atlas loaders still exist for
+  third-party toolchains.
+- Spritesheets (`load.spritesheet`) are acceptable only for uniform-grid
+  animation strips; anything else is an atlas.
+
+## Audio
+
+- Provide at least two encodings (`.ogg` + `.m4a`) in the url array; Phaser
+  picks the first the browser can play.
+- Web Audio is the default manager; it unlocks on first user gesture — never
+  autoplay sound before input (it will silently fail and "work on my machine").
+- Use audio sprites (`load.audioSprite`) for large sets of short SFX.
+
+## Typed keys
+
+Every key lives in `src/assets.ts`:
+
+```ts
+export const Tex = { GameAtlas: "game-atlas", Background: "background" } as const;
+export const Sfx = { Jump: "sfx-jump" } as const;
+export const SceneKeys = { Boot: "Boot", Preloader: "Preloader", Game: "Game" } as const;
+```
+
+Scenes use `Tex.GameAtlas`, never `"game-atlas"` inline. A bad inline key fails
+at runtime as a green square or silent missing audio; a bad constant fails in
+review and in tests that assert the pack manifest covers every constant.
+
+## Loading UX and failure handling
+
+- The Preloader binds `this.load.on("progress", …)` to a progress bar built from
+  Boot-loaded art ([[phaser-project-structure]]).
+- Handle `loaderror`: `this.load.on(Phaser.Loader.Events.FILE_LOAD_ERROR, …)` —
+  log the key and URL; a missing asset must fail loudly in dev, not render as a
+  placeholder in production.
+
+## Project conventions
+
+- `public/assets/` subdirs: `atlases/`, `images/`, `audio/`, `sheets/`, `fonts/`,
+  plus `pack.json` at the root of `assets/`.
+- Generated atlas files (PCT/JSON + PNG pages) are build inputs, committed to the
+  repo; their source art lives wherever the art pipeline keeps it.
+- A test should assert that every key constant in `src/assets.ts` appears in
+  `pack.json` (cheap manifest-coverage check; see [[phaser-testing]]).
+
+## Verification
+
+Asset changes are verified by booting the game and watching the network panel /
+console: every file 200s, no `FILE_LOAD_ERROR`, and the new asset visibly renders
+or audibly plays in the scene that uses it.