** weighted points
- PixiJS 8.18: **** weighted points
Decisive MATRIX rows:
- **MX-RENDER-01** — Sprite rendering with origin/bbox/mask: Phaser 3 native (4); PixiJS manual (2). Heavy weight.
- **MX-COLLIDE-01** — Per-object Collision events: Phaser 3 native via Arcade physics; PixiJS would require manual integration.
- **MX-SCENE-01** — Room/scene model: Phaser 3 native via Scene API; PixiJS lacks first-class scene model.
- **MX-AUDIO-01** — Audio playback: low weight (1) per Phase 2 audio finding (no embedded audio); not a differentiator.
- **MX-UI-01** — DOM-overlay UI for chat HUD: both engines support; Phaser 3 has slightly cleaner integration.
**Phaser 4.1 considered** (npm `latest` as of 2026-05-02 per `npm view phaser dist-tags`). Rejected
for MVP because: (a) v4 is "still settling" per STACK.md decision-gate language; (b) ecosystem
(plugins, tutorials, AI scaffolding) is less mature than v3; (c) CLI-08 ship pressure favours the
safer choice. v4 has the same scores as v3 on most rows (rendering pipeline rewritten but Sprite
API compatible per migration guide), so the migration cost at Phase 7 retro is low if v4 ecosystem
matures.
Re-evaluation gate: Phase 6 start AND Phase 7 retro. If either gate surfaces a v4-specific
advantage that v3 cannot match, the migration is feasible per the official Phaser 3 → 4
migration guide ("biggest release ever, migration mostly automatic but still recent").
## Consequences
- **Phase 6 (CLI-01, CLI-04, CLI-06)** commits to Phaser 3.90 patterns: `pixelArt: true` config,
`roundPixels: true` camera, Phaser.GameObjects.Sprite for movement+animation, Phaser.Tilemaps
for room rendering.
- **AST-01 (Phase 6)** targets Phaser atlas JSON format. `pnpm add phaser@3.90.0` in `apps/client`.
- **AST-02 (Phase 7 MIDI→OGG)** targets Phaser audio loader. (Note: low weight per audio finding.)
- **AST-03 (Phase 7 fonts)** targets Phaser BitmapText format (sprite-strip atlases for `OCRA` and
`Fixedsys` fonts referenced in action 523/525).
- If Phaser 4 ecosystem matures by Phase 7 retro, migration cost is one `apps/client` refactor
(per migration guide, "mostly automatic"). Re-evaluation timing: post-CLI-08, pre-Phase-7-PR-01.
- PixiJS deferred. If Phase 6 surfaces a Phaser 3 hard-knockout missed by this matrix, fall back
to PixiJS 8.18.1 + `@pixi/tilemap@5.0.2` + `howler@2.2.4` per D-13 hard-knockout rule.
## References
- `docs/extracted-engine/MATRIX.md` (rows MX-RENDER-01, MX-COLLIDE-01, MX-SCENE-01, MX-AUDIO-01, MX-UI-01)
- `docs/extracted-engine/MATRIX-rows.json` (canonical scoring data)
- `docs/extracted-engine/README.md` (subsystem index)
- `.planning/research/STACK.md` §"Phaser 3 → Phaser 4"
- [Phaser 3 → 4 Migration Guide](https://phaser.io/news/2026/04/migrating-from-phaser-3-to-phaser-4-what-you-need-to-know)
- CLAUDE.md (hard rule #6: extract → document → rewrite — this ADR closes the "document" stage and unlocks "rewrite" Phase 6)
```
**CRITICAL: substitute actual computed numbers** from Task 1's MATRIX.md totals. If the matrix winner is NOT Phaser 3.90 (e.g. PixiJS pulls ahead because audio is weighted low and PixiJS scores higher elsewhere), update the Decision section accordingly — the ADR follows the matrix, not the pre-recorded position. The pre-recorded position is a starting hypothesis, not a foregone conclusion.
**CRITICAL: cite at least 3 unique MX-* row IDs in the Decision section.** lint-adr.mjs enforces this in Step 4.
**Step 3: Create the docs/adr/ directory** if it doesn't exist:
```bash
mkdir -p docs/adr
```
**Step 4: Implement tools/asset-catalog/scripts/lint-adr.mjs** — replace Plan 01 TODO:
```javascript
#!/usr/bin/env node
// tools/asset-catalog/scripts/lint-adr.mjs
// Validates ADR sections + every MX-* citation resolves in MATRIX-rows.json.
// Exit codes: 0 success, 1 validation failure, 2 usage error
import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
function printUsage() {
process.stderr.write('Usage: lint-adr.mjs []\n');
process.stderr.write(' adr-path: path to ADR .md file (e.g. docs/adr/0001-client-engine.md)\n');
process.stderr.write(' matrix-rows-json-path: path to MATRIX-rows.json (default docs/extracted-engine/MATRIX-rows.json)\n');
}
const adrArg = process.argv[2];
const matrixArg = process.argv[3] ?? 'docs/extracted-engine/MATRIX-rows.json';
if (adrArg === '--help' || adrArg === '-h') { printUsage(); process.exit(0); }
if (!adrArg) { printUsage(); process.exit(2); }
if (!existsSync(adrArg)) { process.stderr.write(`ADR not found: ${adrArg}\n`); process.exit(1); }
const adr = readFileSync(adrArg, 'utf-8');
let errors = 0;
// Required sections (Michael Nygard format per D-14)
for (const section of ['## Status', '## Context', '## Decision', '## Consequences']) {
if (!adr.includes(section)) {
process.stderr.write(`ADR missing required section: ${section}\n`);
errors++;
}
}
// Phaser 4 caveat: ADR must mention Phaser 4 explicitly
if (!/[Pp]haser\s*4/.test(adr)) {
process.stderr.write(`ADR missing Phaser 4 discussion (Phaser 4 caveat per RESEARCH §908-922)\n`);
errors++;
}
// Pitfall 6: every MX-* citation must resolve in MATRIX-rows.json
const mxIds = [...adr.matchAll(/\bMX-[A-Z]+-\d+\b/g)].map(m => m[0]);
const uniqueIds = [...new Set(mxIds)];
if (uniqueIds.length < 3) {
process.stderr.write(`ADR cites ${uniqueIds.length} unique MX-* row IDs; need ≥ 3 (Pitfall 6 + RESEARCH validation row CDOC-04)\n`);
errors++;
}
if (existsSync(matrixArg)) {
let rows;
try { rows = JSON.parse(readFileSync(matrixArg, 'utf-8')); }
catch (e) { process.stderr.write(`MATRIX-rows.json invalid JSON: ${e.message}\n`); process.exit(1); }
const validIds = new Set(rows.map(r => r.rowId));
for (const id of uniqueIds) {
if (!validIds.has(id)) {
process.stderr.write(`ADR cites ${id} but it does not resolve in MATRIX-rows.json (Pitfall 6 mitigation)\n`);
errors++;
}
}
} else {
process.stderr.write(`MATRIX-rows.json not found at ${matrixArg}; skipping rowId citation check\n`);
}
// References section should mention MATRIX.md
if (!/MATRIX\.md/.test(adr)) {
process.stderr.write(`ADR References section should mention MATRIX.md\n`);
errors++;
}
if (errors > 0) {
process.stderr.write(`\nlint-adr: ${errors} error(s)\n`);
process.exit(1);
}
process.stdout.write(`OK: ADR ${adrArg} validated (${uniqueIds.length} MX-* citations resolved)\n`);
process.exit(0);
```
**Step 5: Add tools/asset-catalog/tests/lint-adr.test.ts:**
```typescript
import { describe, it, expect } from 'vitest';
import { execFileSync } from 'node:child_process';
import { existsSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
function runLint(...args) {
try {
const stdout = execFileSync('node', ['tools/asset-catalog/scripts/lint-adr.mjs', ...args], { encoding: 'utf-8' });
return { code: 0, stdout, stderr: '' };
} catch (e) {
return { code: e.status, stdout: e.stdout?.toString() ?? '', stderr: e.stderr?.toString() ?? '' };
}
}
describe('lint-adr.mjs', () => {
it('no arg → exit 2', () => {
try { execFileSync('node', ['tools/asset-catalog/scripts/lint-adr.mjs'], { encoding: 'utf-8' }); throw new Error('expected exit 2'); }
catch (e) { expect(e.status).toBe(2); }
});
it('--help → exit 0', () => {
const out = execFileSync('node', ['tools/asset-catalog/scripts/lint-adr.mjs', '--help'], { encoding: 'utf-8' });
expect(out).toBeTruthy();
});
it('missing ADR file → exit 1', () => {
const r = runLint('/nonexistent.md');
expect(r.code).toBe(1);
});
it('ADR missing Decision section → exit 1', () => {
const tmp = mkdtempSync(join(tmpdir(), 'lint-adr-'));
try {
const p = join(tmp, 'bad.md');
writeFileSync(p, '# ADR\n## Context\nfoo\n## Consequences\nbar\n');
const r = runLint(p);
expect(r.code).toBe(1);
expect(r.stderr).toMatch(/Decision/);
} finally { rmSync(tmp, { recursive: true }); }
});
it('ADR missing Phaser 4 mention → exit 1', () => {
const tmp = mkdtempSync(join(tmpdir(), 'lint-adr-'));
try {
const p = join(tmp, 'no-v4.md');
writeFileSync(p, '## Status\n## Context\n## Decision\nUse Phaser 3.\n## Consequences\nMX-RENDER-01\nMX-INPUT-01\nMX-COLLIDE-01\nMATRIX.md\n');
const r = runLint(p);
expect(r.code).toBe(1);
expect(r.stderr).toMatch(/[Pp]haser\s*4/);
} finally { rmSync(tmp, { recursive: true }); }
});
it('committed ADR validates → exit 0', () => {
if (!existsSync('docs/adr/0001-client-engine.md')) return;
const r = runLint('docs/adr/0001-client-engine.md', 'docs/extracted-engine/MATRIX-rows.json');
expect(r.code).toBe(0);
});
});
```
**Step 6: Run all final checks.**
```bash
node tools/asset-catalog/scripts/lint-adr.mjs docs/adr/0001-client-engine.md docs/extracted-engine/MATRIX-rows.json
# MUST exit 0
cd tools/asset-catalog && pnpm test # full suite green
cd tools/asset-catalog && pnpm test:full # includes integration
# Final round-trip stability (Wave 2 + Wave 3 deliverables)
pnpm catalog:client && pnpm catalog:client && git diff --exit-code docs/extracted-engine/
# Repo-level catalog regen + lint chain (recommended for CI gate)
pnpm catalog:client && \
node tools/asset-catalog/scripts/lint-docs.mjs docs/extracted-engine && \
node tools/asset-catalog/scripts/lint-matrix.mjs docs/extracted-engine && \
node tools/asset-catalog/scripts/lint-adr.mjs docs/adr/0001-client-engine.md docs/extracted-engine/MATRIX-rows.json
```