MyPHP\Plugins\Scene renders hardware-accelerated 3D scenes across all five platforms — Metal on macOS and iOS, Direct3D 11 on Windows, OpenGL 3.3 Core on Linux, and OpenGL ES 3.0 on Android — directly into a GPU Canvas texture with zero CPU readback. A 3D viewport sits anywhere in a declarative view tree via SceneView(), with 2D UI controls or HUD overlays composited on top.
use MyPHP\Plugins\Scene\{Camera3D, Entity, Material, Mesh, Scene};
use MyPHP\Plugins\Scene\Math\Vec3;
$scene = new Scene(new Camera3D(position: new Vec3(0.0, 2.0, 5.0)));
$cube = new Entity(
Mesh::cube(1.5),
new Material(color: [0.25, 0.75, 1.0, 1.0], shininess: 64.0),
name: 'HeroCube',
);
$scene->add($cube);
$view = fn() => VStack(spacing: 12)(
Text('3D Viewport')->font(Font::headline),
SceneView(
$scene,
orbitControls: true,
onUpdate: function (float $dt) use ($cube): void {
$cube->rotation->y += $dt;
},
),
)->padding(16);
SceneView() provides built-in mouse drag and touch orbit camera controls, scroll/pinch zoom, automatic Scene::step($dt) advancement for 3D tweens, particles and billboards, and 3D raycast picking via onPick:.
Meshes, textures, OBJ and GLB models
Mesh stores 48-byte GPU-aligned vertices (position, normal, uv, color) and uploads them to VRAM once on first draw:
- Procedural primitives & Terrain:
Mesh::cube($size),Mesh::sphere($radius, $sectors, $rings),
Mesh::plane($width, $depth, $uvRepeat), Mesh::cylinder($topRadius, $bottomRadius, $height), Mesh::cone($radius, $height), Mesh::torus($majorRadius, $minorRadius), Mesh::capsule($radius, $cylinderHeight), Mesh::terrain($width, $depth, $subX, $subZ, $heightFn, $colorFn), and Mesh::skyDome($radius, $zenithColor, $horizonColor, $groundColor).
- Wavefront
.obj:Mesh::fromObj($src)orMesh::fromObjFile($path)
parses positions, UVs, normals, and triangulates n-gon faces.
- Binary glTF 2.0 (
.glb):Mesh::fromGlbFile($path)loads a single
mesh; Mesh::sceneFromGlbFile($path) parses a multi-mesh .glb hierarchy with PBR baseColorFactor materials and embedded PNG/JPEG textures into an Entity tree.
- Cook-Torrance PBR, Emissive/Unlit, Diffuse textures, Wireframe & Fresnel Rim:
Material::pbr($color, metallic: 0.5, roughness: 0.25) enables physically based GGX + Smith + Fresnel-Schlick metallic/roughness shading across all 5 platforms (and Mesh::sceneFromGlbFile() extracts metallicFactor and roughnessFactor automatically). Material::unlit($color, $texture, emissive: 1.0) (or $material->emissive = 1.0) creates self-illuminated surfaces (suns, magic orbs, selection rings, glowing eyes, sky domes) that bypass diffuse shadow darkening. Material::textured($image, shininess: 32.0) binds any MyPHP\UI\Image as a 3D surface texture. Set $material->wireframe = true for hardware triangle-line rendering, or $material->rimStrength = 1.0 for Fresnel hologram rim lighting.
use MyPHP\Plugins\Scene\{Entity, Material, Mesh, Scene};
$octahedron = Mesh::fromObj(<<<'OBJ'
v 0.0 1.0 0.0
v 0.8 0.0 0.8
v 0.8 0.0 -0.8
v -0.8 0.0 -0.8
v -0.8 0.0 0.8
v 0.0 -1.0 0.0
f 1 2 3
f 1 3 4
f 1 4 5
f 1 5 2
f 6 3 2
f 6 4 3
f 6 5 4
f 6 2 5
OBJ);
$scene = new Scene();
$scene->add(new Entity($octahedron, new Material([0.2, 0.9, 0.8, 1.0])));
$view = fn() => SceneView($scene);
Scene Graph hierarchy, billboards and frustum culling
Entities form a parent-child hierarchy via $parent->addChild($child). Child entities inherit their parent's world transform ($child->modelMatrix() and $child->worldPosition()), making orbiting moons, character attachments or multi-part vehicles straightforward.
Setting $entity->billboard = true causes Scene::step() to rotate the entity toward the active camera each frame — useful for 3D floating health bars, markers or sprites.
By default, $scene->frustumCulling = true extracts the 6 Gribb-Hartmann frustum planes from the camera's View-Projection matrix before each pass and skips any non-instanced entity whose world bounding sphere lies outside the view frustum ($scene->lastCulledCount records how many were skipped).
Lighting, PCF soft shadows and exponential fog
Every Scene includes a directional sun light ($scene->lightDirection, $scene->lightColor), ambient hemisphere light ($scene->ambientColor), up to two dynamic distance-attenuated PointLight sources, real-time 1024×1024 3×3 PCF soft shadows, and exponential distance fog:
use MyPHP\Plugins\Scene\{Entity, Mesh, PointLight, Scene};
use MyPHP\Plugins\Scene\Math\Vec3;
$scene = new Scene();
$scene->shadowsEnabled = true;
$scene->fogEnabled = true;
$scene->fogDensity = 0.035;
$scene->addPointLight(new PointLight(
position: new Vec3(0.0, 1.5, 0.0),
color: [0.2, 0.9, 1.0],
intensity: 2.5,
radius: 8.0,
));
$floor = new Entity(Mesh::plane(16.0, 16.0), position: new Vec3(0.0, -1.0, 0.0));
$floor->castShadow = false;
$scene->add($floor);
$scene->add(new Entity(Mesh::cube(1.2)));
$view = fn() => SceneView($scene);
Hardware GPU instancing, 3D particles and tweens
- Hardware Instancing (
Entity::setInstances): Renders thousands of
transformed, individually tinted copies of a mesh in a single GPU draw call (80 bytes per instance: Mat4 model matrix + float4 RGBA color).
- 3D Particle Emitter (
ParticleEmitter3D): Built on top of hardware
instancing; $emitter->burst($origin, count: 48, color: [...]) simulates 3D velocity, gravity, floor bounce, and size/alpha decay in one instanced draw call.
- 3D Transform Tweens (
Tween3D): Smoothly animates an entity's
position, rotation or scale with easing (EASE_OUT_CUBIC, EASE_IN_OUT_QUAD, BOUNCE_OUT) and optional ->yoyo(true).
use MyPHP\Plugins\Scene\{Entity, Mesh, ParticleEmitter3D, Scene, Tween3D};
use MyPHP\Plugins\Scene\Math\{Mat4, Vec3};
$scene = new Scene();
$pillars = new Entity(Mesh::cube(0.4));
$pillars->setInstances([
Mat4::translation(-2.0, 0.0, 0.0),
Mat4::translation( 2.0, 0.0, 0.0),
], [
[1.0, 0.4, 0.4, 1.0],
[0.4, 0.8, 1.0, 1.0],
]);
$scene->add($pillars);
$emitter = $scene->addEmitter(new ParticleEmitter3D(Mesh::cube(1.0), maxParticles: 128));
$emitter->burst(new Vec3(0.0, 0.5, 0.0), count: 24);
$scene->addTween(
(new Tween3D($pillars, duration: 0.4, easing: Tween3D::EASE_OUT_CUBIC))
->toScale(new Vec3(1.2, 1.2, 1.2))
->yoyo(true)
);
$view = fn() => SceneView($scene);
3D raycast picking, colliders and reference grid
Pass onPick: to SceneView() (or call $scene->pick($x, $y, $w, $h) / $scene->raycast($ray)) to unproject 2D pointer coordinates into a 3D world ray and find the closest intersected entity (['entity' => Entity, 'distance' => float, 'point' => Vec3]). Set $entity->pickable = false on ground planes, skyboxes or particle emitters so they do not intercept clicks. To project a 3D world position onto 2D viewport coordinates for floating labels or health bars, call $scene->camera->worldToScreen($worldPos, $width, $height).
For 3D collision detection and solid push-out resolution during Scene::step($dt), attach a Collider3D::sphere($radius) or Collider3D::box($halfExtents) to $entity->collider, and call $scene->addGridHelper($size, $divisions) to add a hardware-instanced 3D reference grid with color-coded XYZ axes.
Unity-style Sky Dome, 3D Terrain, Camera Shake and Hierarchical Animator3D
To build rich outdoor 3D worlds and animated creatures without hand-rolling vertex math or procedural animation loops:
- Procedural Sky Dome (
$scene->addSkyDome): Adds an unlit, non-pickable atmospheric sky sphere that smoothly blends from$groundColorthrough$horizonColorto$zenithColorand automatically centers on$scene->camera->positionduringScene::step($dt). - 3D Heightfield Terrain (
Mesh::terrain): Samples$heightFn($x, $z)across a grid, computes smooth central-difference normals for accurate directional/PCF shadows, and colors vertices by altitude and slope (valley grass → rocky slope → snow peak, or via custom$colorFn($y, $ny, $x, $z)). - 3D Camera Shake (
$scene->camera->shake):$scene->camera->shake(intensity: 0.2, duration: 0.25)applies a damped 3D vibration to the camera's eye and target duringScene::step($dt). - Hierarchical Creature Animator (
Animator3D): Drives organic root states (Animator3D::IDLEchest breathing,WALKbobbing/sway,LUNGEforward strike with wind-up and return,HURTrecoil shake,SPIN) plus synchronized child limb oscillations (addLimb($wingOrHead, axis: 'z', amplitude: 0.3, frequency: 4.0)):
use MyPHP\Plugins\Scene\{Animator3D, Entity, Material, Mesh, Scene};
use MyPHP\Plugins\Scene\Math\Vec3;
$scene = new Scene();
$scene->addSkyDome(
zenithColor: [0.14, 0.34, 0.68, 1.0],
horizonColor: [0.72, 0.85, 0.96, 1.0],
groundColor: [0.24, 0.28, 0.22, 1.0],
);
// 1. Procedural Mountain Terrain
$mountains = new Entity(
Mesh::terrain(32.0, 32.0, 32, 32, fn(float $x, float $z) => sin($x * 0.3) * cos($z * 0.3) * 1.8),
new Material([1.0, 1.0, 1.0, 1.0], shininess: 8.0),
position: new Vec3(0.0, -1.5, 0.0),
);
$mountains->pickable = false;
$scene->add($mountains);
// 2. Multi-part Creature with Animator3D (body + oscillating wings + glowing eyes)
$beast = new Entity(Mesh::sphere(0.5, 20, 14, [0.3, 0.65, 0.35, 1.0]), position: new Vec3(0.0, 0.5, 0.0));
$leftWing = new Entity(Mesh::cube(0.25, [0.4, 0.8, 0.45, 1.0]), position: new Vec3(-0.55, 0.1, 0.0));
$eye = new Entity(Mesh::sphere(0.08), Material::unlit([1.0, 0.9, 0.2, 1.0], emissive: 1.5), position: new Vec3(0.18, 0.2, 0.42));
$beast->addChild($leftWing);
$beast->addChild($eye);
$scene->add($beast);
$anim = $scene->addAnimator(new Animator3D($beast));
$anim->addLimb($leftWing, axis: 'z', amplitude: 0.4, frequency: 5.0);
$anim->play(Animator3D::IDLE);
$view = fn() => SceneView($scene);