Phaser 4 guard for Phaser 3 pipelines, FX and masks

# AGENTS.md: Phaser 4 game (Phaser 3 API guard)

This game runs **Phaser 4** (`phaser` 4.2.x), with TypeScript. `npm i phaser` has installed Phaser 4 since
April 2026, and 3.90.0 was the last Phaser 3 release. Nearly every Phaser tutorial and answer you learnt from is
Phaser 3, and Phaser 4 replaced the renderer: pipelines, preFX/postFX and BitmapMask are gone.

## Check the version first
- Read `package.json`. If `phaser` is `3.x`, this file doesn't apply: write Phaser 3 code and don't use any
  Phaser 4 API. If it's `4.x`, follow the rules below. If you're not sure, stop and ask.
- Phaser 4 ships its own agent skills in the package: `node_modules/phaser/skills/`. Read
  `node_modules/phaser/skills/v3-to-v4-migration/SKILL.md` before porting Phaser 3 code, and the topic skill
  (for example `filters-and-postfx`, `render-textures`) before using an API you're unsure of.
- The types are the truth: `node_modules/phaser/types/phaser.d.ts`. If `tsc` says a property doesn't exist, it's
  gone. Don't cast to `any` to get round it.

## Rules
- Write Phaser 4 code only. The `phaser-4-guard` skill has the table. The common ones are:
  - `setPipeline('Light2D')` → `setLighting(true)` (and `this.lights.enable()`)
  - `preFX` / `postFX` → `obj.enableFilters()`, then `obj.filters.internal` / `obj.filters.external`, or `camera.filters`
  - `BitmapMask` → `obj.filters.internal.addMask(maskObject)`
  - `setTintFill(c)` → `setTint(c).setTintMode(Phaser.TintModes.FILL)`
  - `Geom.Point` → `Phaser.Math.Vector2`. `Structs.Set` / `Map` → native `Set` / `Map`
  - `Math.PI2` → `Math.TAU`. **`Math.TAU` is now `PI * 2`**; in Phaser 3 it was `PI / 2`. Use `Math.PI_OVER_2` for a quarter turn.
  - `colorMatrix.sepia()` → `colorMatrix.colorMatrix.sepia()`
- `RenderTexture` / `DynamicTexture` drawing is buffered: call `.render()` after `draw()`, `stamp()` and so on.
- `roundPixels` now defaults to `false`. For pixel art set `pixelArt: true` or choose a `vertexRoundMode`.
- Don't make raw WebGL calls. Use an `Extern` game object if you need to.
- Don't upgrade or downgrade Phaser without asking.

## Before you say "done"
1. Run the `phaser-4-guard` scanner on `src` and `package.json`. It must report `0 error(s)`. Any warning you leave needs a reason.
2. Run `npx tsc --noEmit`. It must pass, with no new `any` or `@ts-ignore` around Phaser calls.
3. If you changed rendering, filters or lighting, run the game and look at it.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `phaser-4-guard`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "Phaser 4 guard for Phaser 3 pipelines, FX and masks" v1.0.0 — https://setupbay.com/loadouts/phaser-4-api-guard/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `phaser-4-guard`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "Phaser 4 guard for Phaser 3 pipelines, FX and masks" v1.0.0 — https://setupbay.com/loadouts/phaser-4-api-guard/ -->

---
description: Phaser 4 only; never Phaser 3 pipelines, FX or masks
globs: "src/**/*.ts,src/**/*.js,package.json"
alwaysApply: false
---

This game uses Phaser 4 (check `package.json`; if it says 3.x, ignore this rule and stay on Phaser 3).

| Never (Phaser 3) | Always (Phaser 4) |
|---|---|
| `sprite.setPipeline("Light2D")` | `sprite.setLighting(true)` and `this.lights.enable()` |
| `sprite.preFX.addGlow()`, `postFX` | `sprite.enableFilters()` then `sprite.filters.internal.addGlow()` |
| `new Display.Masks.BitmapMask(...)`, `setMask` | `sprite.filters.internal.addMask(maskObject)` |
| `setTintFill(0xff0000)` | `setTint(0xff0000).setTintMode(Phaser.TintModes.FILL)` |
| `new Geom.Point(x, y)` | `new Phaser.Math.Vector2(x, y)` |
| `Math.PI2`; `Math.TAU` meaning a quarter turn | `Math.TAU` (= PI * 2); `Math.PI_OVER_2` |
| `new Structs.Set()` / `Structs.Map` | native `Set` / `Map` |
| `cm.sepia()` | `cm.colorMatrix.sepia()` |
| `rt.draw(obj)` and nothing else | `rt.draw(obj).render()` |
| `this.add.mesh()`, `textures.generate()` | removed; ask |

- Official guide: `node_modules/phaser/skills/v3-to-v4-migration/SKILL.md`.
- After editing, run the `phaser-4-guard` skill's scanner and `npx tsc --noEmit`.

---
name: phaser-4-guard
description: Check a Phaser 4 game for Phaser 3 APIs (pipelines, preFX/postFX, BitmapMask, setTintFill, Geom.Point, Math.PI2) and silent changes such as Math.TAU and buffered RenderTexture drawing, then type-check against Phaser 4's own types. Use after writing or editing Phaser scenes, when tsc says a Phaser property doesn't exist, or when porting a Phaser 3 tutorial.
---

# Phaser 4 guard

`npm i phaser` gives you Phaser 4, but most Phaser examples online are Phaser 3. Phaser 4 replaced the renderer,
so the commonest Phaser 3 calls (`setPipeline`, `preFX`, `postFX`, `BitmapMask`) no longer exist. Some changes don't
fail at all: `Math.TAU` changed value, and RenderTexture drawing does nothing until `render()`.

## 1. Confirm the version
- `node -p "require('phaser/package.json').version"` should print `4.x`. If it's `3.x`, stop: this skill is for Phaser 4.

## 2. Scan
```bash
python3 .agents/skills/phaser-4-guard/scripts/phaser4_guard.py src package.json
```
(Use the path the skill was installed to: `.claude/skills/...` for Claude Code, `.agents/skills/...` for the others.)

- Each `error` line is a Phaser 3 API that Phaser 4 removed. Fix it with the replacement on the line, or look it up
  in `references/v3-to-v4.md`.
- Each `warn` line is a change that compiles but may behave differently: `Math.TAU`, a texture `draw()` that may need
  `.render()`, `roundPixels`, `GeometryMask` (Canvas only), Grid `outline*` names, raw WebGL. Check each one. When it's
  right, add `// guard: ok <reason>` to the line.

## 3. Type-check against Phaser 4
```bash
npx tsc --noEmit
```
- Phaser 4's types are generated from its source, so `Property 'postFX' does not exist` means the API is gone, not
  that the types are wrong. Never cast to `any` or add `@ts-ignore` to keep a Phaser 3 call.
- For JavaScript projects, add `// @ts-check` to the file or `"checkJs": true` to get the same errors.

## 4. Read the official guide when porting
Phaser ships agent skills in the package. For anything not in the table, read
`node_modules/phaser/skills/v3-to-v4-migration/SKILL.md`, then the topic skill such as
`node_modules/phaser/skills/filters-and-postfx/SKILL.md`.

## 5. Report
Say which Phaser 3 calls you replaced, which warnings you kept and why, and that the scanner and `tsc` were clean.
If you changed rendering, filters or lighting, say whether you ran the game and looked at it.

#!/usr/bin/env python3
"""Find Phaser 3 APIs that Phaser 4 removed or changed, in a Phaser 4 game's .ts/.js files.

Usage: python3 phaser4_guard.py [PATH ...]        (default: the current folder)
       python3 phaser4_guard.py --list            (print every rule)

A "guard: ok" comment on a line silences its warnings (never its errors).
Prints one line per finding:  path:line: level [rule] what is wrong -> what to use
Exit 0 when nothing at "error" level is found, 1 when something is, 2 on bad usage.
Standard library only. Read-only: it never edits a file and makes no network calls.
"""
import fnmatch
import os
import re
import sys

# (rule id, level, regex, message, file patterns). Patterns run against each line with comments removed.
RULES = [
    ('set-pipeline', 'error', '\\.setPipeline\\(|\\.setPostPipeline\\(|\\.resetPipeline\\(|pipelines\\.(add|get)\\(',
     'pipelines were removed in Phaser 4 -> render nodes (RenderConfig#renderNodes); for lights use setLighting(true)', []),
    ('prefx-postfx', 'error', '\\.(preFX|postFX)\\b',
     'preFX/postFX were replaced by filters -> obj.filters.internal / obj.filters.external (enable with obj.enableFilters())', []),
    ('bitmap-mask', 'error', '\\bBitmapMask\\b|\\.createBitmapMask\\(',
     'BitmapMask was removed -> obj.filters.internal.addMask(maskObject)', []),
    ('geometry-mask-webgl', 'warn', '\\bcreateGeometryMask\\(|\\bGeometryMask\\b',
     'GeometryMask only works in the Canvas renderer in Phaser 4 -> the Mask filter for WebGL', []),
    ('set-tint-fill', 'error', '\\.setTintFill\\(|\\.tintFill\\b',
     'setTintFill()/tintFill were removed -> setTint(c).setTintMode(Phaser.TintModes.FILL)', []),
    ('geom-point', 'error', '\\bGeom\\.Point\\b',
     'Geom.Point was removed -> Phaser.Math.Vector2', []),
    ('math-pi2', 'error', '\\bMath\\.PI2\\b',
     'Phaser.Math.PI2 was removed -> Phaser.Math.TAU (now PI * 2)', []),
    ('struct-set-map', 'error', '\\bStructs\\.(Set|Map)\\b',
     'Phaser.Structs.Set/Map were removed -> native Set / Map', []),
    ('mesh-plane', 'error', '\\.add\\.(mesh|plane)\\(|\\bGameObjects\\.(Mesh|Plane)\\b',
     'Mesh and Plane were removed in Phaser 4', []),
    ('textures-generate', 'error', '\\btextures\\.generate\\(|\\bCreate\\.GenerateTexture\\b',
     'TextureManager.generate / Create.GenerateTexture were removed -> draw to a Graphics and generateTexture(), or load an image', []),
    ('bloom-shine-fx', 'error', '\\.add(Bloom|Shine|Circle|Gradient)\\(',
     'the Bloom/Shine/Circle/Gradient FX were removed -> Phaser.Actions.AddEffectBloom/AddEffectShine/AddMaskShape, or the Gradient game object', []),
    ('color-matrix-direct', 'error', '(?<![.\\w])(cm|colorMatrix|matrixFX|cmFX|grade|fx)\\.(sepia|grayscale|blackWhite|brown|vintagePinhole|kodachrome|technicolor|polaroid|shiftToBGR|desaturate|saturate|hue|brightness|contrast|night|lsd|negative)\\(',
     'ColorMatrix methods moved onto .colorMatrix -> filter.colorMatrix.sepia()', []),
    ('spine-bundled', 'error', 'SpinePlugin|phaser/plugins/spine',
     'the bundled Spine plugins are no longer updated -> the official Spine plugin from Esoteric Software', []),
    ('camera3d', 'error', 'Camera3D|Layer3D|phaser-ie9',
     'Camera3D/Layer3D plugins and phaser-ie9 were removed', []),
    ('math-tau', 'warn', '\\bMath\\.TAU\\b',
     'Phaser.Math.TAU is now PI * 2 (in Phaser 3 it was PI / 2) -> check intent; use Math.PI_OVER_2 for a quarter turn', []),
    ('render-texture-draw', 'warn', '\\b(rt|dt|\\w*Texture|\\w*RT)\\.(draw|drawFrame|stamp|erase|fill|repeat)\\(',
     'DynamicTexture/RenderTexture commands are buffered in Phaser 4 -> call .render() after drawing (mark the line guard: ok once it does)', []),
    ('round-pixels', 'warn', '\\broundPixels\\b',
     'roundPixels now defaults to false and only applies to unscaled, axis-aligned objects -> see GameObject#vertexRoundMode', []),
    ('grid-outline', 'warn', '\\b(outlineFillColor|outlineFillAlpha|setOutlineStyle)\\b',
     'Grid shape outline* properties were renamed to stroke* in Phaser 4', []),
    ('raw-gl', 'warn', '\\b(renderer\\.gl|getContext\\(\\s*[\\"\']webgl)',
     "direct WebGL calls desync Phaser 4's WebGL state -> use an Extern game object", []),
    ('phaser3-pin', 'error', '[\\"\']phaser[\\"\']\\s*:\\s*[\\"\'][~^]?3\\.',
     'package.json pins Phaser 3 -> phaser 4.x', ['package.json']),
]
FILES = ['*.ts', '*.tsx', '*.js', '*.mjs', '*.jsx', 'package.json']
COMMENT = '//'
SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", ".agents", ".claude", ".cursor", "dist", "build", "target", ".godot"}
COMPILED = [(rid, lvl, re.compile(rx), msg, globs) for rid, lvl, rx, msg, globs in RULES]


def strip_comment(line):
    """Drop a trailing comment, leaving string literals alone."""
    q = None
    i = 0
    while i < len(line):
        c = line[i]
        if q:
            if c == "\\":
                i += 2
                continue
            if c == q:
                q = None
        elif c in "\"'`":
            q = c
        elif line.startswith(COMMENT, i):
            return line[:i]
        i += 1
    return line


def wanted(name):
    return any(fnmatch.fnmatch(name, g) for g in FILES)


def walk(paths):
    for p in paths:
        if os.path.isfile(p):
            yield p
            continue
        for root, dirs, files in os.walk(p):
            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
            for f in sorted(files):
                if wanted(f):
                    yield os.path.join(root, f)


def scan(path):
    out = []
    name = os.path.basename(path)
    try:
        with open(path, encoding="utf-8", errors="replace") as fh:
            lines = fh.read().splitlines()
    except OSError as e:
        return [(path, 0, "error", "unreadable", str(e))]
    for n, raw in enumerate(lines, 1):
        code = strip_comment(raw)
        if not code.strip():
            continue
        accepted = "guard: ok" in raw  # a person accepted the warnings on this line
        for rid, lvl, rx, msg, globs in COMPILED:
            if accepted and lvl == "warn":
                continue
            if globs and not any(fnmatch.fnmatch(name, g) for g in globs):
                continue
            if rx.search(code):
                out.append((path, n, lvl, rid, msg))
    return out


def main(argv):
    if "--list" in argv:
        for rid, lvl, _, msg, globs in RULES:
            print(f"{lvl:5} [{rid}] {msg}" + (f"  (only {', '.join(globs)})" if globs else ""))
        return 0
    if any(a.startswith("-") for a in argv):
        print(__doc__)
        return 2
    paths = argv or ["."]
    for p in paths:
        if not os.path.exists(p):
            print(f"no such path: {p}", file=sys.stderr)
            return 2
    files = list(walk(paths))
    findings = []
    for f in files:
        findings.extend(scan(f))
    for path, n, lvl, rid, msg in findings:
        print(f"{os.path.relpath(path)}:{n}: {lvl} [{rid}] {msg}")
    errors = sum(1 for x in findings if x[2] == "error")
    warns = sum(1 for x in findings if x[2] == "warn")
    print(f"phaser4_guard: {len(files)} file(s), {errors} error(s), {warns} warning(s)")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

# Phaser 3 to Phaser 4, the calls agents get wrong

From the official migration guide shipped in `phaser` 4.2.1 (`node_modules/phaser/changelog/v4/4.0/MIGRATION-GUIDE.md`,
also in the package's v3-to-v4-migration skill). The replacements used in the verifier's Phaser 4 scene type-check against Phaser 4.2.1.

| Phaser 3 | Phaser 4 |
|---|---|
| `sprite.setPipeline("Light2D")` | `sprite.setLighting(true)`; `this.lights.enable()` |
| custom `WebGLPipeline` / `PostFXPipeline` | a render node registered with `RenderConfig#renderNodes` |
| `sprite.preFX.addGlow()` / `sprite.postFX.addBlur()` | `sprite.enableFilters()`; `sprite.filters.internal.addGlow()` / `sprite.filters.external.addBlur()` |
| `camera.postFX.addColorMatrix()` | `camera.filters.external.addColorMatrix()` |
| `cm.sepia()` | `cm.colorMatrix.sepia()` |
| `postFX.addBloom()` / `addShine()` / `addCircle()` | `Phaser.Actions.AddEffectBloom(obj)` / `AddEffectShine(obj)` / `AddMaskShape(obj)` |
| `addGradient()` FX | the `Gradient` game object |
| `new Display.Masks.BitmapMask(scene, obj)` + `setMask` | `sprite.filters.internal.addMask(obj)` |
| `GeometryMask` in WebGL | the `Mask` filter (GeometryMask is Canvas only) |
| `sprite.setTintFill(c)`, `tintFill` | `sprite.setTint(c).setTintMode(Phaser.TintModes.FILL)` |
| `new Geom.Point(x, y)` | `new Phaser.Math.Vector2(x, y)` |
| `Point.GetMagnitude(p)` | `v.length()` |
| `Phaser.Math.PI2` | `Phaser.Math.TAU` |
| `Phaser.Math.TAU` (was PI / 2) | `Phaser.Math.PI_OVER_2` (TAU is now PI * 2) |
| `Phaser.Structs.Set` / `Map` | native `Set` / `Map` |
| `rt.draw(obj)` drawing at once | `rt.draw(obj).render()` (commands are buffered) |
| `this.add.mesh()`, `this.add.plane()` | removed |
| `this.textures.generate(key, { data })` | draw to a `Graphics` and call `generateTexture(key, w, h)` |
| bundled `SpinePlugin` | the official Spine plugin from Esoteric Software |
| `roundPixels` true by default | false by default; `pixelArt: true` or `GameObject#vertexRoundMode` |
| Grid `outlineFillColor`, `setOutlineStyle` | the `stroke*` equivalents |

// A Phaser 3.90 scene, used to check the guard. Phaser 4 removed or changed every marked call.
import Phaser from "phaser";

export class GameScene extends Phaser.Scene {
  create() {
    const hero = this.add.sprite(100, 100, "hero");
    hero.setTintFill(0xff0000);
    hero.setPipeline("Light2D");
    hero.preFX?.addGlow(0xffffff);
    const glow = hero.postFX.addBloom();
    const mask = new Phaser.Display.Masks.BitmapMask(this, this.add.image(0, 0, "mask"));
    hero.setMask(mask);
    const p = new Phaser.Geom.Point(1, 2);
    const quarter = Phaser.Math.TAU;
    const full = Phaser.Math.PI2;
    const seen = new Phaser.Structs.Set<string>();
    const rt = this.add.renderTexture(0, 0, 64, 64);
    rt.draw(hero);
    const mesh = this.add.mesh(0, 0, "hero");
    const cm = this.cameras.main.postFX.addColorMatrix();
    cm.sepia();
    this.textures.generate("dot", { data: ["1"] });
    console.log(p, quarter, full, seen, glow, mesh);
  }
}