notque/vexjoy-agent / skills/game/game-dev
game-dev
FlaggedGame development: design, asset pipelines, Phaser, Unity CLI and builds, vanilla JS frontend, GM mode, match booking.
references/pixijs-combat-renderer.md
View on GitHub# PixiJS v8 Combat Renderer
PixiJS v8 2D WebGL combat rendering: `@pixi/react` alongside React 19 DOM UIs, replacing DOM particle systems with GPU particles, and layering normal-map lighting and post-processing filters over combat sprites.
Scope: PixiJS v8 rendering only. TypeScript types, React state architecture, and Vite config patterns: `skills/frontend/frontend/references/typescript-frontend.md`. Design tokens and layout: `skills/frontend/frontend/references/ui-design.md`.
Not for: CSS or Framer Motion effects that need no WebGL (`combat-effects-upgrade.md`); skeletal character animation and state machines (`rive-skeletal-animator.md`); 3D or Three.js scenes (`frontend` skill, THREEJS mode); general React component architecture (`typescript-frontend.md` in the `frontend` skill).
Domains:
- **@pixi/react v8**: `extend()` API, `<Application>` canvas setup, React 19 compatibility, hybrid canvas/DOM mounting, `useTick` for animation, `useApp` for app access
- **PixiJS v8 Rendering**: `Sprite`, `AnimatedSprite`, `Container`, `ParticleContainer`, GPU-accelerated rendering pipeline, WebGL and WebGPU backends
- **Particle Systems**: `@spd789562/pixi-v8-particle-emitter` (v8-compatible fork), `EmitterConfig`, particle pooling, burst vs. continuous emission, wrestling-specific presets
- **2D Lighting**: Normal map custom filters (GLSL ES 3.0), per-pixel light source uniforms, dynamic light reactions to combat events, NormalMap-Online / Laigter / SpriteIlluminator tooling
- **Post-Processing**: `pixi-filters` v6+ for v8, `AdvancedBloomFilter`, `CRTFilter`, `VignetteFilter`, `ColorMatrixFilter`, filter chain ordering, mobile performance budgets
- **Performance**: Ticker-driven animation (not React re-renders), `ParticleContainer` for 100K+ elements, `manualChunks` Vite config for ~250KB gzipped PixiJS bundle
---
## Instructions
### Phase 1: ASSESS — Detect project setup and combat component surface
Read `package.json` to confirm PixiJS v8 and @pixi/react versions. Check for `@pixi/react ^8`, `pixi.js ^8`. If v7 or lower is present, flag it before proceeding — v7 and v8 APIs are incompatible and migration is a prerequisite, not a patch.
Identify combat render surface:
```bash
# Find existing combat render components
grep -rl "CombatArena\|PlayerCharacter\|EnemyCharacter\|effects" src/ --include="*.tsx" --include="*.ts"
# Find DOM particle anti-pattern
grep -rn "document.createElement\|setTimeout.*remove\|classList.add.*particle" src/ --include="*.ts" --include="*.tsx"
```
Flag the DOM particle failure mode immediately if found — `document.createElement` + `setTimeout` removal is the primary replacement target. Each DOM particle adds reflow cost; GPU particles are free by comparison.
Identify what Zustand stores drive combat state. Read the store file before writing any PixiJS component — display object updates must subscribe to the same state atoms as React UI components.
Gate: do not proceed to SETUP until you know (1) PixiJS version, (2) which components render the combat scene, (3) which Zustand store slice drives HP/animation state.
---
### Phase 2: SETUP — Lazy-load PixiJS and mount hybrid canvas
Load [pixi-react-integration.md](pixijs-combat-renderer/pixi-react-integration.md) for complete code examples.
PixiJS adds ~250KB gzipped. Lazy-load the entire combat screen to keep initial bundle small:
```typescript
// src/screens/CombatScreen.tsx
import React, { Suspense } from 'react';
const PixiCombatCanvas = React.lazy(() =>
import('../combat/PixiCombatCanvas').then(m => ({ default: m.PixiCombatCanvas }))
);
export function CombatScreen(): React.JSX.Element {
return (
<div className="relative w-full h-full">
{/* PixiJS canvas — combat scene only */}
<Suspense fallback={<div className="absolute inset-0 bg-black" />}>
<PixiCombatCanvas />
</Suspense>
{/* React DOM UI — HP bars, card hand, action buttons */}
<CombatHUD />
</div>
);
}
```
Vite `manualChunks` to isolate PixiJS from the main bundle — add to `vite.config.ts`:
```typescript
build: {
rollupOptions: {
output: {
manualChunks(id) {
if (id.includes('pixi.js') || id.includes('@pixi/')) {
return 'pixi-vendor';
}
},
},
},
},
```
The `extend()` call must happen at module top level, not inside a hook or effect — it is a one-time registry operation, and re-running it on each render breaks component resolution:
```typescript
import { extend } from '@pixi/react';
import { Container, Sprite, AnimatedSprite, ParticleContainer } from 'pixi.js';
extend({ Container, Sprite, AnimatedSprite, ParticleContainer });
```
Canvas renders ONLY the combat scene. React DOM renders all UI chrome (HP bars, card hand, buttons). Never render interactive UI inside the PixiJS canvas — these elements have accessibility requirements that PixiJS cannot satisfy.
---
### Phase 3: RENDER — Migrate sprites and set up ticker loop
Load [pixi-react-integration.md](pixijs-combat-renderer/pixi-react-integration.md) for sprite migration patterns.
Replace Framer Motion idle bob animations on `PlayerCharacter` and `EnemyCharacter` with PixiJS ticker-driven animation. Framer Motion runs on the React render cycle; PixiJS ticker runs on `requestAnimationFrame` and mutates display objects directly — no React state, no re-renders:
```typescript
// ❌ Framer Motion idle bob — triggers React re-render every frame
<motion.img animate={{ y: [0, -8, 0] }} transition={{ repeat: Infinity, duration: 2 }} />
// ✅ PixiJS ticker idle bob — pure RAF mutation, zero React overhead
useTick((ticker) => {
if (!spriteRef.current) return;
const t = performance.now() / 1000;
spriteRef.current.y = Math.sin(t * Math.PI) * 8;
});
```
Use `useRef` for display object references — never store PixiJS display objects in React state because state updates trigger reconciliation on every mutation.
---
### Phase 4: ENHANCE — Normal maps, particles, and post-processing
Load the relevant reference for the enhancement type:
- Normal map lighting → [pixi-2d-lighting.md](pixijs-combat-renderer/pixi-2d-lighting.md)
- Particle effects → [pixi-particle-systems.md](pixijs-combat-renderer/pixi-particle-systems.md)
- Post-processing → [pixi-post-processing.md](pixijs-combat-renderer/pixi-post-processing.md)
**Particle replacement priority**: Replace `effects.ts` DOM particles first — highest-impact change. Each DOM particle creates a reflow; GPU particles cost near-zero. Map each effect type in `effects.ts` to the wrestling presets in the particle reference.
**Normal maps**: Apply only to hero and enemy character sprites. Background normal maps are low-value and expensive. Start with one directional light per scene; add event-reactive lights (tied to card plays) after baseline is working.
**Post-processing filter chain order**:
1. Scene-level effects first (bloom, vignette) — applied to the root container
2. Character-level effects (normal map filter) — applied to character containers
3. Never apply bloom to UI overlay elements — degrades text readability
Apply filters in the PixiJS display tree, not to the HTML canvas element. HTML canvas CSS filters are CPU-only and bypass PixiJS's batched render pipeline.
---
### Phase 5: VALIDATE — Performance budget and mobile testing
Target metrics:
| Metric | Desktop budget | Mobile budget |
|--------|---------------|---------------|
| Draw calls per frame | < 20 | < 10 |
| Texture count | < 50 | < 30 |
| Filter passes | < 4 | < 2 |
| Particle count peak | < 500 | < 150 |
| FPS (combat active) | 60 | 30 minimum |
Mobile filter budget is strict — disable bloom and normal map lighting on mobile:
```typescript
const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent);
combatContainer.filters = isMobile ? [] : [bloomFilter, vignetteFilter];
```
Texture atlas verification — all combat sprites must be packed into a spritesheet. Individual texture loads cause draw call explosion. Verify with:
```bash
grep -rn "new Texture\|Texture.from\|Assets.load" src/combat/ --include="*.ts" --include="*.tsx"
```
Individual `Texture.from()` calls per sprite are a hard block — batch them into a spritesheet JSON loaded via `Assets.load()` before final ship.
---
## Reference Loading Table
| Task | Load This Reference |
|------|-------------------|
| @pixi/react setup, canvas mounting, Zustand wiring, lazy loading, Vite config | [pixi-react-integration.md](pixijs-combat-renderer/pixi-react-integration.md) |
| Normal maps, per-pixel lighting, light reactions to combat events | [pixi-2d-lighting.md](pixijs-combat-renderer/pixi-2d-lighting.md) |
| GPU particles, wrestling presets, DOM particle replacement | [pixi-particle-systems.md](pixijs-combat-renderer/pixi-particle-systems.md) |
| Bloom, vignette, chromatic aberration, color grading, mobile budgets | [pixi-post-processing.md](pixijs-combat-renderer/pixi-post-processing.md) |
| Custom GLSL hit filters, glow chaining, shockwave displacement, Spine animation, z-ordering, UI masking | [combat-visual-effects.md](pixijs-combat-renderer/combat-visual-effects.md) |
| Sprite batching, texture atlases, RenderTexture caching, object pooling, ParticleContainer vs Container | [pixi-performance.md](pixijs-combat-renderer/pixi-performance.md) |
---
## Key Files Reference (Road to AEW)
| File | What it does | Migration target |
|------|-------------|-----------------|
| `src/components/combat/CombatArena.tsx` | Background image + CSS vignette overlay | Replace vignette with PixiJS filter |
| `src/components/combat/PlayerCharacter.tsx` | 400x400 sprite, Framer Motion idle bob | Replace bob with `useTick`, add normal map |
| `src/components/combat/EnemyCharacter.tsx` | 900px sprite, CSS animation | Replace with `AnimatedSprite` + ticker |
| `src/utils/effects.ts` | DOM createElement+setTimeout particles | Replace entirely with GPU particle emitter |
---
## Related references
| Need | Load |
|------|------|
| TypeScript frontend architecture: type-safe components, state management, build optimization | `skills/frontend/frontend/references/typescript-frontend.md` |
| UI/UX design: design systems, responsive layouts, accessibility, animations | `skills/frontend/frontend/references/ui-design.md` |
| Zero-dependency combat visual upgrades: CSS particle replacement, Framer Motion combat juice, CSS 3D card transforms | `combat-effects-upgrade.md` |
## Error Handling
### `Cannot read properties of undefined (reading 'render')`
**Cause**: PixiJS display object accessed before `<Application>` mounts. Canvas initialization is async.
**Fix**: Guard with `if (!app.renderer) return` in ticker callbacks. Use `onInit` callback on `<Application>` to set a mounted flag before rendering sprites.
### `extend() was called with an empty object`
**Cause**: `extend({})` called before the import resolves, or called inside a component render path.
**Fix**: Move `extend()` to module top level, outside any function or component. Verify the import from `pixi.js` is not aliased by the bundler.
### `Filter resolution mismatch: expected 1, got 2`
**Cause**: Device pixel ratio (retina display) causes filter input/output texture size mismatch.
**Fix**: Set `filter.resolution = window.devicePixelRatio` on every filter instance, or use `app.renderer.resolution` as the source of truth.
### `ParticleContainer: too many particles`
**Cause**: Default `maxSize` is 1500. Finisher explosions with 40+ continuous emission can hit this.
**Fix**: Set `maxSize` explicitly: `new ParticleContainer(5000, { position: true, alpha: true, scale: true })`. Pre-allocate to burst peak, not steady-state count.
### `@pixi/react: useTick called outside Application context`
**Cause**: A component using `useTick` is rendered outside the `<Application>` tree, typically during SSR or Suspense fallback render.
**Fix**: Wrap in a null guard: `if (!isPixiMounted) return null`. Ensure `useTick` components are children of `<Application>`, never siblings.
### Vite: `pixi-vendor chunk is larger than 500 KiB`
**Cause**: Normal — PixiJS v8 core is ~250KB gzipped, ~800KB raw. The warning is informational.
**Fix**: Suppress with `build.chunkSizeWarningLimit: 800` in `vite.config.ts`. Verify gzipped size via `npx vite-bundle-visualizer`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |