The false choice: "3D or 2D?"

My original question was framed wrong. I asked: "Do I need a 3D engine to get realistic water?" That led me down a path of evaluating Three.js and Babylon.js alongside Phaser and PixiJS. But the actual answer was hiding in the question.

What I'm building is 2.5D: a projected plane with custom depth cues, layered sprites, and a deformable water surface. The water isn't volumetric — it's a height field that drives displacement, lighting, particle spawns, and a dot-matrix rendering pass. The "3D" feel comes from the 45-degree perspective projection, not from a Z-buffer or mesh transforms.

Once I reframed the problem from "3D water" to 2.5D surface rendering with custom shaders, the engine landscape shifted completely. I didn't need a 3D engine at all. What I needed was a renderer that gives me direct control over geometry, shaders, particles, and perspective projection — without fighting a framework's abstractions.

What Phaser 4 does well

Phaser 4 is a genuinely impressive release. The April 2026 v4.1.0 ("Salusa") ships with:

• A completely rebuilt render node architecture
• SpriteGPULayer: store member data in static GPU buffers, rendering over a million animated sprites in a single draw call
• TilemapGPULayer: entire tilemaps rendered as a single GPU quad, supporting up to 4096×4096 tiles
• A unified filter system with bloom, glow, shadow, and image-based lighting
• Built-in Arcade and Matter.js physics, audio, cameras, input, tweening, and particles
• AI-ready with skills files for Claude Code, Codex, and Cursor

For a conventional 2D roguelike MMO — think top-down tilemaps with hundreds of entities, fog of war, and stock physics — Phaser 4 would be the right call. The time from "engine chosen" to "first playable multiplayer prototype" is dramatically shorter with Phaser's batteries-included approach.

Why Phaser didn't fit

The problem with my project is that it's not a conventional 2D game. Every Phaser feature that makes it a great game framework became an abstraction I'd have to work around:

TilemapGPULayer is documented as orthographic maps only. My sea surface uses a custom 45-degree perspective projection. There's no tilemap to speak of — the "map" is a flat height field.

SpriteGPULayer trades runtime flexibility for raw throughput. It's great for crowds, rain, or debris that don't change behaviour per-frame. My water dots need individual displacement per-vertex based on wave physics. Constant state updates would negate the GPU-layer advantage.

The render pipeline is Phaser's RenderNode architecture. It's powerful, but it's still an abstraction you work through. For a hand-built water/pixel stack where I need to control every vertex, every shader binding, and every draw call — PixiJS's Mesh and Filter APIs are simply closer to the metal.

WebGPU presence: Phaser 4 runs on WebGL/WebGL2. As of April 2026, there is no documented WebGPU runtime path. For a project that wants GPU compute shaders for wave simulation, that's a significant gap.

None of these are Phaser's fault — they're design choices that serve Phaser's primary audience (people building games, not renderers). My project just falls outside that audience.

The three PixiJS primitives that changed my mind

Once I started evaluating PixiJS 8.18.1 with fresh eyes, three things stood out:

1. Mesh — full control over geometry and shaders

Pixi's Mesh API gives me direct control over geometry buffers, UV coordinates, indices, and the vertex/fragment shader pipeline. This maps directly to my needs:

• A grid of vertices representing the sea surface
• Each vertex displaced by sampling a wave heightmap texture
• 45-degree perspective projection in the vertex shader
• Per-vertex coloring from deep blue to crest white based on wave height

In a GLSL vertex shader, that's ~40 lines. The same shader runs on WebGL or gets auto-translated to WGSL for Pixi's WebGPU backend.

2. Filters — shader passes for surface effects

Pixi's filter system lets me apply post-processing to scene objects. Instead of building wake shimmer, foam thresholding, or mist overlays as engine plugins, I can express them as custom shader passes. The sea surface becomes a mesh, and every visual effect on top of it is a filter or a particle system.

3. ParticleContainer — GPU-batched secondary effects

Pixi's ParticleContainer handles thousands of particles (foam, spray, wake, mist) in a single draw call. It gives me explicit control over which properties are static vs dynamic per frame. This is exactly what I need for:

• Crest foam: white particles that drift on wave peaks
• Bow spray: upward-bursting particles at ship-wave intersections
• Wake: trailing particles behind the ship
• Mist: alpha-blended overlay during wave impacts

The architecture that emerged

Combining these pieces gives a layered rendering architecture:

WebGPU Device
├── Compute Pass: shallow water wave simulation
│   └── Output: heightmap texture (updated each frame)
│
└── PixiJS Render
    ├── DotMatrix Mesh (custom vertex/fragment shaders)
    │   └── Samples heightmap → displaces vertices → projects into 45° perspective
    ├── Ship sprites (standard sprites, depth-sorted on the perspective plane)
    ├── ParticleContainer (foam, spray, wake, mist)
    └── Custom filters (wake shimmer, color grading, horizon fade)

The wave simulation runs as a WebGPU compute shader (WGSL), completely outside PixiJS's rendering pipeline. PixiJS renders the output texture via its Mesh/Shader system. The two share the same GPU device but don't compete for pipeline slots.

This is the Option C approach — GPU-first with a fallback path. WebGPU is not yet Baseline across browsers, so a real shipping game needs a WebGL-based CPU wave simulation fallback. But for the prototype and for browsers that support it, the compute shader path is both faster and easier to iterate on.

Multiplayer: the orthogonal concern

The multiplayer decision is independent of the rendering choice. Both Phaser and PixiJS connect to the same networking stack.

I'm using Colyseus — an open-source Node.js framework for authoritative multiplayer with delta-compressed state sync and room-based matchmaking. It's engine-agnostic, with documented patterns for both Phaser and PixiJS.

The important architectural insight is the bandwidth boundary: synchronize what the server owns (ship position, velocity, wind conditions, wave state seeds) and let the client own everything cosmetic (per-frame foam particles, local shader noise, spray intensity). This is the sane split for any water-heavy multiplayer game, regardless of renderer.

When Phaser wins (and when Pixi wins)

I don't think there's a single right answer between these two engines. The answer depends on what you're building:

Choose Phaser 4 when:

• Your game is a conventional 2D tilemap-based roguelike or MMO-like
• You want built-in physics, cameras, audio, and tilemap systems
• You want the fastest route to a playable multiplayer prototype
• Your primary bottleneck is game logic, not custom rendering

Choose PixiJS 8 when:

• Your game's differentiator is a custom rendering technique
• You need direct control over shaders, geometry, and draw calls
• You want WebGPU compute path for simulation workloads
• You have your own game architecture and want a renderer, not a worldview
• You need the option to mix with Three.js later for true 3D elements

Choose Three.js or Babylon.js when:

• The design proves a 2.5D surface model is no longer economical
• You need free camera pitch/yaw, arbitrary occlusion, or true volumetric effects
• You're already building immersive 3D, not approximating it

What I'd tell someone making the same decision

The single most important thing I learned: name your actual rendering problem before you evaluate engines.

I spent a week comparing Phaser and PixiJS on generic dimensions — bundle size, star count, documentation quality, community size. The answer kept changing because I was comparing them as abstract engine A vs engine B.

The answer became clear only when I wrote down exactly what the sea surface needed to do each frame:

1. Update a height field with shallow water physics
2. Displace 65,536 vertices by sampling that field
3. Project into 45-degree perspective
4. Render each vertex as a soft circle with wave-height-dependent coloring
5. Spawn particles at crest-height thresholds
6. Apply post-processing for wake and mist effects

Once I had that list, it was obvious that PixiJS's Mesh/Filter/ParticleContainer primitives map directly to items 2-6, while Phaser's abstractions would require working around them for every item.

The default choice (Phaser) was wrong for my project. But it would be right for most projects. The difference isn't in the engines — it's in the specific rendering problems you're solving.

The stack I'm shipping with

• PixiJS 8.18.1 (WebGPU preferred, WebGL fallback)
• GLSL + WGSL custom shaders for the dot-matrix sea surface
• WebGPU compute for wave simulation (WGSL, with CPU fallback)
• Colyseus 0.17 for authoritative multiplayer
• Svelte 5 for UI overlays (inventory, chat, HUD)
• All open source, MIT licensed, zero proprietary lock-in

The demo code is at B:\Dev\pixi-wave-demo\ on my dev machine, and the full rationale is documented in the AI Wiki at /02_Wiki/phaser-vs-pixi-deep-research-20260529.md.