@codyswann/lisa 2.161.0 → 2.163.0

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

@@ -0,0 +1,35 @@
+{
+  "name": "lisa-phaser",
+  "version": "2.163.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/lisa-phaser/.codex-plugin/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,30 @@
+{
+  "name": "lisa-phaser",
+  "version": "2.163.0",
+  "description": "Phaser 4 game-development rules for TypeScript projects",
+  "author": {
+    "name": "Cody Swann"
+  },
+  "keywords": [
+    "lisa"
+  ],
+  "dependencies": [
+    "lisa-typescript"
+  ],
+  "skills": "./skills/",
+  "hooks": "./.codex-plugin/hooks.json",
+  "interface": {
+    "displayName": "lisa-phaser",
+    "shortDescription": "Phaser 4 game-development rules for TypeScript projects",
+    "longDescription": "Phaser 4 game-development rules for TypeScript projects",
+    "developerName": "Cody Swann",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Use lisa-phaser"
+    ]
+  }
+}

package/plugins/lisa-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/lisa-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/lisa-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.

package/plugins/lisa-phaser/skills/phaser-assets/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Assets"
+short_description: "loading or organizing assets in a Phaser 4 game — the Loader (images, texture atlases, spritesheets, audio, fonts), asset-pack manifests…"
+default_prompt:
+  - "Use $phaser-assets: loading or organizing assets in a Phaser 4 game — the Loader (images, texture atlases, spritesheets, audio, fonts), asset-pack manifests…."

package/plugins/lisa-phaser/skills/phaser-gameobjects/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: phaser-gameobjects
+description: This skill should be used when creating or managing Phaser 4 GameObjects — sprites, images, text, containers, groups and object pooling, animations (anims), tweens, particles, and the v4 GPU layers (SpriteGPULayer, TilemapGPULayer) for massive object counts. Use it when adding entities, fixing per-frame allocation/GC issues, pooling projectiles, or choosing between a Container and a Group. Pairs with phaser-scenes, phaser-physics, phaser-rendering, and phaser-assets.
+---
+
+# Phaser 4 GameObjects
+
+## Overview
+
+GameObjects carry over from Phaser 3 largely unchanged: `Sprite`, `Image`,
+`Text`, `BitmapText`, `Container`, `Group`, `Graphics`, the Shape objects, and
+the particle system. v4 adds `Gradient`, `Stamp`, `CaptureFrame`, the Noise
+objects, NineSlice tiling (`tileX`/`tileY`), and — the headline — the GPU
+layers. Removed: `Mesh`, `Plane`, the OBJ loader, `Camera3D`/`Layer3D`
+([[phaser-v3-migration]]).
+
+## Choosing the right object
+
+- **Image** for static visuals (cheaper than Sprite — no animation component).
+- **Sprite** only when it animates.
+- **Container** for transform-grouping a small, fixed set of children (a unit +
+  its health bar). Containers are not free — don't nest deeply or use them as
+  ad-hoc layers. In v4.1+, `Layer` is a true GameObject and is the right tool
+  for z-grouping with filters.
+- **Group** for managing many homogeneous objects — and for pooling (below).
+- **Text** uses Canvas rasterization per change; for score counters and other
+  hot text use `BitmapText`.
+
+## Object pooling (mandatory for spawn-heavy entities)
+
+Bullets, enemies, particles, pickups: never `new`/`destroy` per spawn — pool
+through a Group:
+
+```ts
+this.bullets = this.add.group({ classType: Bullet, maxSize: 64, runChildUpdate: true });
+// spawn
+const b = this.bullets.get(x, y, Tex.GameAtlas, "bullet") as Bullet | null;
+if (b) { b.setActive(true).setVisible(true); b.fire(dir); }
+// despawn (inside Bullet when off-screen/expired)
+this.bullets.killAndHide(this); this.body.enable = false;
+```
+
+`maxSize` caps the pool; `get()` returns `null` when exhausted — handle it
+(drop the spawn) rather than growing unbounded.
+
+## Per-frame discipline
+
+In `update()` paths: no object literals, no array spreads, no `.map/.filter`
+chains, no closures. Hoist scratch `Vector2`s and reuse them. The GC pause from
+per-frame garbage is the most common cause of stutter that profilers get blamed
+for.
+
+## Animations and tweens
+
+- Define animations once (Preloader `create` or a dedicated module) on the
+  global `this.anims`; play by key constant: `sprite.play(Anim.Run)`.
+- Tweens (`this.tweens.add`) and Timelines carry over from v3 unchanged. Kill
+  tweens that target objects you pool/despawn — a tween holding a pooled object
+  alive is a classic leak.
+
+## Massive counts: the GPU layers
+
+New in v4 — reach for these instead of "thousands of sprites":
+
+- **SpriteGPULayer** — on the order of a million static-ish sprites in a single
+  draw call, with per-member GPU-driven animation, easing, and parallax. Use for
+  starfields, crowds, debris, background fauna.
+- **TilemapGPULayer** — renders a whole tile layer as one quad with per-pixel
+  cost, up to 4096×4096 tiles. Use for large maps, especially on mobile.
+
+Regular Sprites + Groups remain correct for interactive entities (things with
+bodies, input, per-entity logic).
+
+## Particles
+
+The particle API is the v3.60-style `this.add.particles(x, y, texture, config)`
+emitter manager. v4 additions: particles respect the lighting system. Pool
+explosion-style one-shot emitters or use `emitter.explode()` rather than
+creating emitters per event.
+
+## Project conventions
+
+- Entity classes (`Bullet extends Phaser.Physics.Arcade.Sprite`) live in
+  `src/entities/`, take their tunables from `src/logic/` config objects, and use
+  asset-key constants ([[phaser-assets]]).
+- Depth management: named depth constants (`Depth.World`, `Depth.FX`,
+  `Depth.UI`), not scattered magic numbers.
+
+## Verification
+
+Object-lifecycle changes are verified in the running game: spawn/despawn the
+entity repeatedly and watch the object count (`this.children.length`,
+`group.getLength()`) stay bounded, and the FPS meter stay flat — an unbounded
+count or sawtooth memory profile means the pool or tween cleanup is wrong.

package/plugins/lisa-phaser/skills/phaser-gameobjects/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Gameobjects"
+short_description: "creating or managing Phaser 4 GameObjects — sprites, images, text, containers, groups and object pooling, animations (anims), tweens…"
+default_prompt:
+  - "Use $phaser-gameobjects: creating or managing Phaser 4 GameObjects — sprites, images, text, containers, groups and object pooling, animations (anims), tweens…."

package/plugins/lisa-phaser/skills/phaser-physics/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: phaser-physics
+description: This skill should be used when working with physics in a Phaser 4 game — Arcade physics bodies, velocity/acceleration, colliders and overlaps, the fixed timestep, groups and static groups, and when (rarely) to reach for Matter.js instead. Use it when adding movement, collision, platforming behavior, or debugging tunneling/jitter. Pairs with phaser-gameobjects and phaser-scenes.
+---
+
+# Phaser 4 Physics
+
+## Overview
+
+Phaser 4 bundles the same two engines as v3: **Arcade** (AABB, fast, the
+default) and **Matter.js** (full rigid-body). The opinionated default is
+Arcade; Matter is opt-in for genuinely physical mechanics (stacking, joints,
+torque). Bundled Spine left v4, Matter did not.
+
+Key v4 fact: Arcade's **`fixedStep` defaults to `true`** — the world steps at a
+fixed rate decoupled from render FPS. Keep it. Fixed-step physics is what makes
+movement deterministic across 60 Hz/144 Hz displays and what makes
+logic-level tests reproducible. Do not switch to variable step to mask a bug.
+
+## Setup
+
+```ts
+// game config
+physics: { default: "arcade", arcade: { gravity: { x: 0, y: 0 }, debug: false } }
+
+// scene
+const player = this.physics.add.sprite(x, y, Tex.GameAtlas, "player");
+player.setCollideWorldBounds(true);
+const platforms = this.physics.add.staticGroup();
+this.physics.add.collider(player, platforms);
+this.physics.add.overlap(player, pickups, (p, item) => this.collect(item), undefined, this);
+```
+
+## Movement rules
+
+- Move bodies with **velocity/acceleration** (`setVelocity`, `setAccelerationX`),
+  never by writing `x`/`y` per frame — direct position writes teleport the body
+  past colliders and create tunneling.
+- For teleports (respawn, screen wrap) set position once and reset the body
+  (`body.reset(x, y)`).
+- Drag, bounce, and max velocity are body config, not per-frame math:
+  `setDrag`, `setBounce`, `setMaxVelocity`.
+- Platformer jump checks use `body.blocked.down` (world/static contact) rather
+  than `touching.down` alone.
+
+## Colliders, overlaps, groups
+
+- `collider` separates bodies; `overlap` only reports. Pickups/triggers are
+  overlaps; walls/floors are colliders.
+- Register colliders **once in `create`** between groups — never inside
+  `update` (a per-frame `add.collider` leaks collider objects and tanks the
+  frame rate).
+- Pooled entities ([[phaser-gameobjects]]) must disable their body on despawn
+  (`body.enable = false`) or dead objects keep colliding invisibly.
+
+## Tunneling and jitter checklist
+
+1. Fast small bodies passing through thin walls → keep `fixedStep: true`, give
+   walls thickness, cap speed with `setMaxVelocity`.
+2. Jitter against walls → bodies overlap due to direct position writes; use
+   velocities.
+3. "Collider stopped working" after pooling → the body wasn't re-enabled on
+   `get()` or wasn't disabled on despawn.
+4. Different behavior on different monitors → someone turned off fixed step or
+   moved physics math into `update` scaled by render delta.
+
+## When Matter is justified
+
+Choose Matter for: realistic stacking/toppling, constraints/joints, compound
+bodies, polygon collision shapes. Run it in a dedicated scene; don't mix Arcade
+and Matter for the same entities. If the mechanic is "platformer/top-down/
+shmup", the answer is Arcade.
+
+## Determinism
+
+Physics-adjacent randomness (spawn jitter, knockback variance) uses the seeded
+`Phaser.Math.RND` — never `Math.random()` — so a recorded seed reproduces a run
+exactly. Combined with fixed-step Arcade, gameplay bugs become replayable; see
+[[phaser-testing]].
+
+## Verification
+
+Physics changes are verified by playing the affected interaction in the running
+game with `arcade.debug: true` toggled on (body outlines visible), confirming
+contacts/velocities behave as specified, then toggling debug back off before
+committing.

package/plugins/lisa-phaser/skills/phaser-physics/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Physics"
+short_description: "working with physics in a Phaser 4 game — Arcade physics bodies, velocity/acceleration, colliders and overlaps, the fixed timestep, groups…"
+default_prompt:
+  - "Use $phaser-physics: working with physics in a Phaser 4 game — Arcade physics bodies, velocity/acceleration, colliders and overlaps, the fixed timestep, groups…."

package/plugins/lisa-phaser/skills/phaser-project-structure/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: phaser-project-structure
+description: This skill should be used when creating, restructuring, or reasoning about a Phaser 4 game project — the game config, the Vite + TypeScript layout, the Boot → Preloader → MainMenu → Game scene flow, scale/resolution setup for desktop and mobile, and where code and assets belong. Use it before scaffolding a project, adding a major subsystem, or deciding where a file should live. Pairs with phaser-scenes, phaser-assets, phaser-rendering, and phaser-testing.
+---
+
+# Phaser 4 Project Structure
+
+## Overview
+
+This stack targets **Phaser 4** (v4.1+ "Salusa", npm package `phaser`), built
+with **Vite + TypeScript** — the layout the official `phaserjs/template-vite-ts`
+template and `npm create @phaserjs/game@latest` scaffold. Phaser 4 ships its own
+type definitions (`types/phaser.d.ts`); do not add `@types/phaser`.
+
+## Canonical layout
+
+| Path | Role |
+| --- | --- |
+| `index.html` | Single page that loads `src/main.ts`; owns the game container div |
+| `src/main.ts` | Game config + `new Phaser.Game(config)` — the only bootstrap file |
+| `src/scenes/` | One scene class per file (`Boot.ts`, `Preloader.ts`, `MainMenu.ts`, `Game.ts`, …) |
+| `src/logic/` | Pure TypeScript game logic — **no `phaser` imports** (testable) |
+| `src/assets.ts` | Typed asset-key constants (texture, audio, anim, scene keys) |
+| `public/assets/` | Static assets served by Vite (atlases, audio, packs) — never imported |
+| `tests/` | Vitest unit tests for `src/logic/**` and pure helpers |
+| `dist/` | Vite build output — generated, never edited or committed |
+
+## The game config
+
+One config object in `src/main.ts`. The opinionated baseline:
+
+```ts
+const config: Phaser.Types.Core.GameConfig = {
+  type: Phaser.AUTO,            // WebGL; Canvas renderer is deprecated in v4
+  width: 1280,
+  height: 720,
+  parent: "game-container",
+  backgroundColor: "#028af8",
+  scale: {
+    mode: Phaser.Scale.FIT,
+    autoCenter: Phaser.Scale.CENTER_BOTH,
+  },
+  physics: {
+    default: "arcade",
+    arcade: { gravity: { x: 0, y: 0 }, debug: false }, // fixedStep defaults to true in v4 — keep it
+  },
+  scene: [Boot, Preloader, MainMenu, Game],
+};
+```
+
+v4-specific config facts:
+
+- `roundPixels` now defaults to **`false`** (v3 defaulted true). Leave it — the
+  new default prevents flicker on rotated/scaled objects.
+- Pixel-art games: `pixelArt: true` (nearest-neighbor + roundPixels), or the new
+  **`render.smoothPixelArt: true`** (WebGL-only) for pixel art that rotates or
+  scales smoothly. Pick one per project and record the choice.
+- Custom render nodes register under `render.renderNodes` — see [[phaser-rendering]].
+- `Phaser.HEADLESS` exists for logic-only boots (tests) — see [[phaser-testing]].
+
+## Scene flow
+
+Four-stage boot, in order (see [[phaser-scenes]] for lifecycle detail):
+
+1. **Boot** — loads only the handful of assets the Preloader's loading screen
+   needs (logo, progress-bar art). No game assets here.
+2. **Preloader** — renders the loading UI and loads everything else, preferably
+   via a single asset-pack manifest (see [[phaser-assets]]), then starts MainMenu.
+3. **MainMenu** — entry UI; starts Game.
+4. **Game** (+ overlay scenes like `HUD`, `Pause` run in parallel) — gameplay.
+
+## Project conventions
+
+- All game code is TypeScript under `src/`; `bun run dev` (vite), `bun run build`
+  (vite build), `bun run preview` serve and package it.
+- Scenes orchestrate; they do not contain algorithmic game logic. Rules
+  evaluation, procedural generation, scoring, pathfinding, and state machines
+  live in `src/logic/` as pure functions/classes so Vitest can run them without
+  a browser.
+- Asset keys come from `src/assets.ts` constants — a typo in an inline string
+  key fails at runtime only; a typo in a constant fails at compile time.
+- Determinism: seed `Phaser.Math.RND` (or a local `RandomDataGenerator`) from a
+  single place; never `Math.random()` in game code.
+
+## Verification
+
+A structural change is verified when `bun run typecheck`, `bun run test`, and
+`bun run build` pass AND the game boots: `bun run dev`, open the page, confirm
+the canvas renders past the Preloader with no console errors.

package/plugins/lisa-phaser/skills/phaser-project-structure/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Project Structure"
+short_description: "creating, restructuring, or reasoning about a Phaser 4 game project — the game config, the Vite + TypeScript layout, the Boot → Preloader →…"
+default_prompt:
+  - "Use $phaser-project-structure: creating, restructuring, or reasoning about a Phaser 4 game project — the game config, the Vite + TypeScript layout, the Boot → Preloader →…."

package/plugins/lisa-phaser/skills/phaser-rendering/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: phaser-rendering
+description: This skill should be used when working on rendering in Phaser 4 — the render node architecture that replaced v3 pipelines, the unified Filter system that replaced FX and masks, tint modes, pixel-rounding options (roundPixels, smoothPixelArt, vertexRoundMode), DynamicTexture's buffered drawing, the Extern object for external WebGL, and lighting. Use it for any visual-effect, shader, mask, or custom-rendering task, and whenever v3 rendering idioms (setPipeline, preFX/postFX, BitmapMask, tintFill) appear. Pairs with phaser-gameobjects and phaser-v3-migration.
+---
+
+# Phaser 4 Rendering
+
+## Overview
+
+Phaser 4 replaced the entire v3 WebGL pipeline system with a **render node
+architecture**: small single-purpose nodes (each with a `run` method, batchable
+where it matters) that the renderer composes per object. WebGL state is fully
+managed, context loss restores automatically, and rendering is just-in-time —
+GPU work is deferred until actually needed. WebGL2 is fully supported; WebGL1
+still works; **there is no WebGPU backend**; the Canvas renderer is deprecated.
+
+Practical consequences, in order of how often they bite:
+
+## Filters replaced FX and masks
+
+The v3 `preFX`/`postFX` controllers and `BitmapMask` are gone. Phaser 4 has one
+unified **Filter** system that works on any GameObject **and on cameras**:
+
+- Geometry/bitmap masks → the `Mask` filter.
+- Bloom / Shine / Circle FX → `Phaser.Actions.AddEffectBloom()`,
+  `AddEffectShine()`, `AddMaskShape()` helpers.
+- Gradient FX → the new `Gradient` GameObject.
+- Filters split into **internal** and **external** lists (replacing the
+  pre/post distinction); filter setters are chainable.
+- A filtered or masked `Container` can itself be used as a mask source — new
+  capability, not possible in v3.
+
+## Tinting
+
+`tintFill` and `setTintFill()` were removed. Use `setTint(color)` plus
+`setTintMode(mode)` with `Phaser.TintModes`: `MULTIPLY` (default), `FILL`,
+`ADD`, `SCREEN`, `OVERLAY`, `HARD_LIGHT`.
+
+## Custom shaders and pipelines
+
+- A v3 custom pipeline must be rewritten as a **RenderNode**, registered at boot
+  via the game config's `render.renderNodes` map.
+- The `Shader` GameObject was rewritten: config-based constructor
+  (`ShaderQuadConfig`), explicit `setUniform()`, `renderImmediate`, GLSL
+  `#pragma` directives. Shadertoy-style automatic uniforms are gone.
+- **Never make raw WebGL calls** — wrap external GL renderers in the `Extern`
+  GameObject, which fences GL state around your code.
+- Texture coordinates now follow GL orientation (**Y=0 at bottom**). Phaser
+  translates standard usage automatically, but custom shaders and pre-compressed
+  textures must account for the flip (re-encode compressed textures).
+
+## Pixel rounding and pixel art
+
+- `roundPixels` defaults to **`false`** in v4 (v3: true). The old default caused
+  flicker on rotated/scaled objects; leave the new default alone.
+- Pixel-art projects choose ONE strategy: `pixelArt: true` (crisp,
+  nearest-neighbor) or `render.smoothPixelArt: true` (WebGL-only, anti-aliased
+  scaling/rotation of pixel art).
+- Per-object fine-tuning: `gameObject.vertexRoundMode` —
+  `"off" | "safe" | "safeAuto" | "full" | "fullAuto"`.
+
+## DynamicTexture / RenderTexture are buffered
+
+Draw commands no longer execute immediately — they queue until you call
+**`render()`**. Forgetting `render()` is the #1 "my RenderTexture is blank" bug
+in v4. Related: `preserve()` keeps a command buffer for reuse, `callback()`
+injects custom steps, and `RenderTexture#renderMode` selects
+`"render" | "redraw" | "all"`.
+
+## Lighting
+
+`setPipeline('Light2D')` is gone. Enable per object with
+`gameObject.setLighting(true)`; lights have an explicit `z`; self-shadowing is
+supported; lighting now works on many more object types (including particles).
+
+## Performance notes specific to the v4 renderer
+
+- Quads render from index buffers (4 vertices, not 6) and batching survives
+  multi-texture switches better, especially on mobile — but atlases are still
+  the foundation of batching ([[phaser-assets]]).
+- For massive draw counts use `SpriteGPULayer` / `TilemapGPULayer`
+  ([[phaser-gameobjects]]) instead of thousands of individual sprites.
+
+## Verification
+
+Rendering changes are verified visually in a real browser: `bun run dev`, then a
+Playwright screenshot assertion or manual confirmation that the effect renders
+and the console shows no WebGL errors. For filter/shader work, verify on both a
+WebGL2 and (if supported) WebGL1 context before calling it done.

package/plugins/lisa-phaser/skills/phaser-rendering/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Rendering"
+short_description: "working on rendering in Phaser 4 — the render node architecture that replaced v3 pipelines, the unified Filter system that replaced FX and…"
+default_prompt:
+  - "Use $phaser-rendering: working on rendering in Phaser 4 — the render node architecture that replaced v3 pipelines, the unified Filter system that replaced FX and…."