Skip to content

README.md

Latest commit

 

History

History
225 lines (175 loc) · 7.7 KB

README.md

File metadata and controls

225 lines (175 loc) · 7.7 KB

Phaser 3D — Experimental 3D extension for Phaser 4

Live examples gallery: https://phaserjs.github.io/phas3d/

Warning

This project is experimental research code and must not be used in production.

The 3D pipeline is unstable: APIs may change without notice, features may regress or disappear between revisions, and the project may be abandoned at any time with no support, no migration path and no guarantees of further updates. Performance characteristics, file formats, shader interfaces and the public surface of add3D, cameras3d, lights3d and WebGL3DRenderer are all subject to breaking changes.

If you are shipping a game, use the upstream Phaser 4 release instead. This fork exists for prototyping, R&D and educational purposes only.

This is a research fork of Phaser 4 with an opt-in 3D rendering pipeline bolted alongside the classic 2D renderer. The 2D side of Phaser is untouched and continues to work exactly as upstream. The 3D side is minimal by design and ships behind the WEBGL3D_RENDERER build flag.

The Phaser 4 base is © Phaser Studio Inc. and the open-source community.

What is this

A fork of Phaser 4 that adds a small, web-first 3D rendering pipeline that lives next to the existing 2D renderer. Games opt in with type: Phaser.WEBGL3D and get a purposefully minimal stack on top of WebGL2:

  • A scene-graph (Object3D), perspective + orthographic cameras with fixed / follow / orbit / first-person helpers, frustum culling.
  • Lit and unlit materials (Lambert + optional Blinn-Phong specular) with emissive, normal maps, ambient occlusion, alpha modes, texture transforms and a second UV channel.
  • A lighting rig with ambient + directional + up to four point lights and four spot lights.
  • A glTF 2.0 loader (.glb and .gltf), with skinning, animations driven by AnimationMixer3D, and KHR_lights_punctual, KHR_materials_unlit, KHR_texture_transform honoured natively.
  • GPU instancing through InstancedMesh3D — one draw call for tens of thousands of cubes / sprites / props.
  • Picking via add3D.raycastFromPointer, blob shadows, camera-facing billboards, mesh / node finders.

The renderer is not PBR. It is intentionally diffuse-first, with optional stylization knobs (vertex snap, affine UV, flat shading) to support a wide range of stylised looks without dragging in shadow maps, post-processing or IBL.

Running locally

This fork ships with two sandboxes you can run in parallel.

1. Build the engine

npm install
npm run build

This produces build/phaser.js (the UMD bundle the sandboxes consume).

2. Reference sandbox — examples/vite-3d

A Vite + React + Monaco gallery with ~30 examples covering every shipped feature.

Live build: https://phaserjs.github.io/phas3d/ — automatically deployed from main by .github/workflows/pages.yml.

cd examples/vite-3d
npm install
npm run dev          # http://localhost:5173

Each example carries a Game / Code toggle. The Code tab opens the source verbatim via @monaco-editor/react. npm run build produces a fully self-contained static drop in dist/ you can host anywhere — the build hook copies build/phaser.js into dist/phaser-build.js automatically.

3. Comparative sandbox — examples/three

A standalone Vite + Three.js sandbox that rebuilds the stress and instancing demos on Three.js, used for honest cross-engine draw-call comparisons.

cd examples/three
npm install
npm run dev          # http://localhost:5273

Two pages: / (one mesh per cube) and /instanced.html (one THREE.InstancedMesh). Compare against the Phaser equivalents at #/stress-test and #/instanced-cubes in the reference sandbox.

Documentation

File Purpose
docs/WEBGL3D.md Primary API reference for the 3D pipeline.
docs/WEBGL3D_GAME_OPPORTUNITIES.md Honest matrix of game genres viable with the current renderer (Spanish). The English version surfaces on the gallery home page.
rewrite.md List of upstream Phaser 2D files modified by this fork, with patches and a sync procedure. Required reading before pulling a new upstream version.
changelog/v4/4.0/CHANGELOG-v4.NEXT.md All 3D-related changelog entries.

The agent skill at .cursor/skills/webgl3d-api/SKILL.md keeps Cursor / Codex / Claude aligned with the project's conventions when editing the 3D code.

Quick taste

import Phaser from 'phaser';

class WorldScene extends Phaser.Scene
{
    preload () {
        this.load.gltf('hero', 'assets/hero.glb');
    }

    create () {
        this.cameras3d.main.fixed([ 0, 2.5, 6 ], [ 0, 0, 0 ]);
        this.lights3d.preset('moody');
        this.lights3d.addSpot({
            position: [ 0, 4, 0 ],
            direction: [ 0, -1, 0 ],
            innerCone: Math.PI / 12,
            outerCone: Math.PI / 6,
            color: 0xfff1c4,
            intensity: 2.4
        });
        this.hero = this.add3D.gltf('hero', { animation: 0 });
    }

    update (time, delta) {
        this.hero.rotation.y += delta / 1000;
    }
}

new Phaser.Game({
    type: Phaser.WEBGL3D,
    width: 960,
    height: 540,
    scene: WorldScene
});

The full add3D / cameras3d / lights3d surface is documented in docs/WEBGL3D.md, with one runnable example per feature in the gallery.

What this fork is not

  • Not PBR. Lit materials are diffuse + optional Blinn-Phong specular. No metallic-roughness, no IBL.
  • Not a real-time shadow renderer. Blob shadows are provided as a contact cue. Shadow maps are on the backlog, not shipped.
  • Not a physics engine. Phaser.Geom, Phaser.Math.Vector3 and raycasts are available, but physics integration is meant to live in a separate package (e.g. a future Rapier3D bridge).
  • Not a replacement for Three.js or Babylon.js. It targets compact, stylised web-first 3D games using the same ergonomics you already know from Phaser 2D. See docs/WEBGL3D_GAME_OPPORTUNITIES.md for the honest matrix of genres that fit.

Status of the 2D engine

The 2D side of Phaser is untouched by this fork — every patch we applied to the upstream src/ is documented (and gated behind the WEBGL3D_RENDERER build flag where possible) in rewrite.md. A build of this fork without the 3D flag behaves identically to vanilla Phaser 4. Pulling a new upstream version is a matter of merging the 2D files outside of rewrite.md's patch list straight in and rebasing the small list of patches by hand.

The full upstream Phaser 4 README, with all its 2D-specific information, lives at the official project: https://github.com/phaserjs/phaser.

Credits

  • Phaser 4 — Richard Davey and the rest of Phaser Studio Inc., with the open-source Phaser community. The 2D engine, scene system, loader, input, audio, tweens, animation system, plugin architecture, glTF cache plumbing and everything else not listed below.
  • 3D pipeline (WEBGL3D renderer, materials, lighting, glTF loader, animation mixer, instancing, helpers, sandboxes and docs in this fork) — Francisco Pereira.

This README, the contents of docs/WEBGL3D*.md, the examples/vite-3d and examples/three sandboxes and every file under src/{renderer/webgl3d, cameras/3d, gameobjects3d, lights3d, loader3d, animation3d}/ were written for and as part of this fork.

License

Released under the same MIT license as upstream Phaser.