Melonjs 3d

3D and 2.5D in melonJS

melonJS is a 2D engine that grew a real 3D tier: perspective cameras, meshes, instancing, glTF scenes and 3D lights. Most of what a model "knows" about 3D graphics comes from the OpenGL convention, and melonJS's is the inverse. Read the conventions section before writing any 3D code.

Coordinate conventions — the inverse of OpenGL

This is the single most important thing on this page.

Rotations are extrinsic XYZ, and Camera3d exposes all three: camera.pitch (X, look up/down), camera.yaw (Y, look left/right) and camera.roll (Z, bank the horizon). The view is R(yaw) ∘ R(pitch) ∘ R(roll) inverted, and the frustum planes come off that same matrix — so culling follows a banked view.

camera.rotate() is NOT the way to bank a 3D camera. It writes the inherited currentTransform, which a 3D view never reads, so the call is silently inert. Set roll. (On a Camera2d it is the other way round: roll IS that transform's rotation, which is why worldToLocal / localToWorld compensate for it.)

The payoff is that 2D code translates directly — anywhere you used pos.x / pos.y, add pos.z and the maths still holds. The cost is that every OpenGL-shaped instinct is backwards.

Consequence that bites immediately: "behind everything" is the largest depth when the camera looks along +Z. Put a backdrop on the wrong side and it either paints over the whole scene (it is nearer than everything else) or disappears without trace (it falls in front of the near plane and the GPU clips it). Which sign means "far" depends on which side the camera sits, so check the camera before picking a backdrop depth.

glTF assets are authored Y-up right-handed. level.load converts them by rotation (rightHanded: true is its default), so you do not apply a flip yourself. The Mesh constructor defaults rightHanded to false, which bridges by mirroring instead — geometry you hand to a Mesh directly comes in flipped left/right unless you pass rightHanded: true. See melonjs-3d-assets.

Opting in

3D starts with the camera class, and nothing else has to change. Set it once on the Application:

import { Application, Camera3d } from "melonjs";

const app = new Application(1024, 768, {
    parent: "screen",
    cameraClass: Camera3d,      // ← the opt-in
});
await app.init();

That flips the world's sort to "depth", switches the broadphase to a 3D index, and renders sprites and meshes with perspective projection. Camera3d extends Camera2d, so follow, fade, shake and post effects all still work.

Per-stage opt-in also works, which is useful when the loading screen is 2D:

class GameStage extends Stage {
    constructor() {
        super({ cameras: [new Camera3d(0, 0, 1024, 768, { fov: Math.PI / 3 })] });
    }
}

Camera traps

• There is no sky. The frame clears to renderer.backgroundColor (opaque black unless the renderer was created transparent), and world.backgroundColor clears over it when you set one — both are flat colours. Anything more is a backdrop renderable, screen-fixed or placed at a far depth.
• Set the clip planes for your scene scale. Defaults are near 0.1 / far 1000. Objects beyond the far plane clip or project with bad w-divides; a near that is too small wastes depth precision and distant props z-fight. Use camera.setClipPlanes(near, far).
• camera.pos.set(x, y) is 2-argument and zeroes z. Use camera.depth — the documented z accessor — or assign pos.x/pos.y individually.
• worldToLocal does not project. It is a 2D camera's offset subtraction. To pin a label or marker to a point in the scene use camera.worldToScreen(x, y, z), which applies the projection and returns null behind the camera. See melonjs-camera-and-drawing.

Depth sorting

Under Camera3d the world sorts on "depth" every frame (recursively), so unlike 2D you can assign depth after addChild and it will reorder. That is the one place where the usual z-ordering rule is relaxed — see melonjs-renderables for the 2D rules, which still apply everywhere else.

You will often have to. A Container has autoDepth: true by default, so addChild(child) with no explicit z overwrites pos.z with the child's index — a real world depth in a 3D scene, and never the one you wanted. Pass it (world.addChild(mesh, z)), or set mesh.depth afterwards. The glTF importer turns autoDepth off on the container it loads into for this reason.

floating does not opt out of this sort. It skips the camera transform, not the depth order. A floating child is ordered by |pos.z| alone — its pos.x/y are screen pixels, and the camera does not move relative to it — so the magnitude is the distance and the sign is ignored:

world.addChild(hud, -150);       // small -> nearer than anything -> on top
world.addChild(skybox, -10000);  // large -> farther -> behind everything
world.addChild(skybox, 100000);  // equally far: sign does not matter

Both hold at any camera position. A HUD given the huge z that would put it on top in 2D lands at the far end of the level instead, with the scenery drawing over it.

Transparency

A mesh fades by setting its opacity — there is nothing else to switch on:

ghost.setOpacity(0.4);

Meshes render in two phases. The opaque pass writes depth in sort order; the transparent pass replays afterwards, back-to-front, blending and writing no depth. A draw lands in the second whenever its alpha is fractional.

That default matters because the opaque path writes premultiplied colour with blending off, so before this a faded mesh came out darkened toward black rather than see-through — the background contributed nothing.

transparent: true when the transparency is in the TEXTURE rather than the opacity — a soft-edged glow, smoke, a glTF material with alphaMode: "BLEND". The automatic check reads the draw's alpha and cannot see into a texture. Watch alphaCutoff here: it discards texels before blending sees them, so a soft edge needs a low cutoff (Sprite3d drops its own default to 1/255 when you set transparent: true). The cutoff thresholds the MATERIAL's alpha, not the drawn alpha, so a fading cutout mesh keeps its shape instead of disappearing at its own threshold.

The glTF loader does not set this for you: one loaded mesh can merge several materials and the flag routes the whole mesh, so a "BLEND" material sharing geometry with an opaque one would drag the opaque half into the transparent pass.

transparent: false pins a mesh to the opaque pass however it is faded.

Blending uses the renderable's existing blendMode, so a glow is one property. The advanced modes ("overlay", "difference", and the rest that need a compositing pass) fall back to "normal" here, on both backends:

const glow = new Mesh(0, 0, {
    ...quad, texture: glowTexture,
    transparent: true, blendMode: "additive", alphaCutoff: 0,
});

Ground shadows ride the same pass — a blob is a decal, and decals are its first client rather than a feature of their own.

Distance fog

Off until you ask for it, and one call on the camera:

camera.setFog({ near: 2000, far: 7000 });   // linear: name the two distances
camera.setFog({ mode: "exp2", density: 4e-4 }); // or one density
camera.setFog(null);                         // off

It is the cheapest thing that stops a 3D scene reading as flat cut-outs, and it lets props arrive at the far plane without a visible edge.

Every parameter is optional, and the omitted ones track live. Distances default to the camera's own clip planes, so fog cannot silently disagree with them after a later setClipPlanes. The colour defaults to renderer.backgroundColor and follows it, so geometry dissolves into whatever sky you already set — including through a day/night fade. Pass color only when the fog should deliberately differ from the backdrop:

camera.setFog({ far: 5000, color: "#8899aa" });

A Color is held by reference, so mutating it animates the fog.

Height falloff makes mist pool in low ground instead of hanging at every altitude equally — the difference between fog reading as weather and as a global desaturation:

camera.setFog({ near: 1200, far: 7000, fogHeight: 0, heightFalloff: 0.0015 });

heightFalloff defaults to 0, which is uniform fog — not a special case, the same integral with the dial at zero, so leaving it out changes nothing. Render space is Y-down, so fogHeight is the floor and density rises below it; every published form of this formula assumes Y-up and has the opposite sign.

Fog is measured radially from the camera and applied per fragment, so it does not slide as the camera turns and does not band across large triangles. It lives on the camera, so a split-screen or minimap view fogs independently — and a Camera2d never fogs at all.

Per object: fog: false exempts a mesh however far away it is — for a waypoint or objective marker that has to stay readable. It exempts the mesh and not the ground shadow it casts: a blob is a mark on the floor and fogs with the floor. Emissive surfaces fog like everything else (light travelling through fog is attenuated too), so a neon sign that should punch through wants fog: false, not a brighter emissive.

Only meshes fog. 2D content, HUDs and floating renderables never reach the mesh shaders, so a screen-space overlay stays clean with no work.

A custom mesh shader is not fogged unless it asks to be. Fog is compiled into the engine's own mesh programs — #define FOG on WebGL, an enable_fog overridable constant on WebGPU — and a shader you supply is yours: the engine binds it as written and never substitutes a fogged variant. So a mesh carrying a ShaderEffect keeps full contrast while the scene around it recedes. It is safe — nothing throws, and the camera's fog is simply not applied — but it is usually surprising.

To opt in, declare the same uniforms and the engine will feed them, because the fog values are pushed to any mesh program that declares them rather than only to the built-in ones:

uniform vec3 uFogColor;   // straight (unpremultiplied) fog colour
uniform vec4 uFogParams;  // x = mode (0 off / 1 linear / 2 exp2),
                          // y = near, z = 1/(far - near), w = density

Your vertex stage computes the distance itself — length((uViewMatrix * uModelMatrix * vec4(aVertex, 1.0)).xyz), radially so it does not swim as the camera turns — and the blend must scale the fog colour by the fragment's own alpha, mix(uFogColor * a, rgb, f), because vColor arrives premultiplied. Mixing toward the unscaled colour haloes every alpha-cutout edge.

The flip side is the reason fog costs nothing when unused: with no camera fog, the mesh programs are compiled without any of it, on both backends. It is not a branch that is skipped at runtime — the code is not there.

Meshes

const cube = new Mesh(x, y, {
    model: "cube",          // a preloaded OBJ name — no built-in primitives
    texture: atlas,         // TextureAtlas, image, or a preloaded image name
    width: 64, height: 64,
    cullBackFaces: true,    // the default
    lit: true,
});

A mesh pivots about its model origin (0, 0, 0), not an anchor point. Under Camera3d it opts out of the anchor offset entirely, so anchorPoint is inert there — place the origin where you want the pivot at authoring time, or nest the mesh under a transformed parent. The anchor is only honoured on the legacy 2D-camera path.

InstancedMesh, and when it is the wrong tool

InstancedMesh draws one mesh many times in a single draw call — the difference between a hundred trees and a hundred thousand. glTF scenes using EXT_mesh_gpu_instancing load as one automatically; by hand it is a Mesh with a count:

const trees = new InstancedMesh(0, 0, { ...treeGeometry, instanceCount: 400 });
const at = new Matrix3d();               // one scratch, reused
for (let i = 0; i < trees.instanceCount; i++) {
    at.identity().translate(x, y, z);
    trees.setInstance(i, at);
}
world.addChild(trees, 0);

trees.visibleInstanceCount = 120;        // draw fewer, without re-uploading

It is not a free upgrade. One InstancedMesh is one geometry and one material, and four things move from per-object to per-group:

So the question is not "how many are there" but "does the game address them individually":

• Scenery — instance it. Trees, rocks, grass, debris: the game never asks about one of them.
• Collision-tested props — still fine. You test against positions you already own; instancing only changes how they are drawn.
• Collectibles and enemies — usually not. Anything removed one at a time makes removeInstance's swap your problem: you have to keep an index↔object map and repair it on every removal. At small counts a pooled Mesh each is less code and no slower.

Under a few hundred objects the draw-call saving is not what limits you anyway — reach for it when the count is in the thousands, or when the objects are pure scenery and it costs nothing to.

Normals are generated for you

A lit mesh needs per-vertex normals for the shader to light with. Supply them if you have them; omit them and the engine computes them from the geometry:

const mesh = new Mesh(x, y, { vertices, uvs, indices, lit: true });
// normals derived from the triangles — nothing else to do

You do not choose flat or smooth, because the geometry already decides. Face normals accumulate into their vertices weighted by area, so where faces share a vertex they average and the surface shades smoothly, and where every triangle carries its own three vertices — a triangle soup, which is how most hand-built geometry comes out — each vertex belongs to one face and the result is that face's normal, so it shades flat. Want faceted edges: duplicate the vertices. Want smooth: share them.

An explicit settings.normals always wins, and an unlit mesh gets none — there would be nothing to read them.

A lit mesh with no normals used to render fullbright, which looks like the lighting is broken rather than absent. If an older scene suddenly picks up shading, that is why.

Colouring a mesh

There are four levels, and picking the wrong one is the usual reason a colour "does not apply". They all multiply together.

tint is per object. That is the trap: build a terrain as one big mesh and you can tint the whole valley or none of it. Anything that varies across a single mesh is per-vertex.

// fade a procedural terrain toward the sky the further out it goes
const ground = new Color(217, 230, 244);
const sky = new Color(207, 230, 247);
const haze = new Color();
for (let i = 0; i < mesh.vertexCount; i++) {
    const t = Math.min(1, mesh.originalVertices[i * 3 + 2] / 6000);
    mesh.setVertexColor(i, haze.copy(ground).lerp(sky, t));
}

Supply the whole array at construction when you already have it — vertexColors takes a packed Uint32Array (the form the batchers read, so no conversion) or one Color per vertex. A length that does not match vertexCount throws; it is not padded, because a short array would leave the tail of the mesh mis-coloured and that reads as a lighting bug.

Mutating the array directly is fine, but say so afterwards:

mesh.vertexColors[i] = color.toUint32(color.alpha);
mesh.needsUpdate = true;   // the retained Camera3d path uploads once

setVertexColor does that for you. Skip it and the colour applies under a 2D camera and silently does not under Camera3d.

On a lit mesh the colour multiplies the lit result, so it behaves as albedo rather than as an emissive override — a vertex colour will not make an unlit face bright.

alpha hides a mesh as it hides anything else: at 0 the draw is skipped. There is no partial mesh transparency though — the mesh path renders opaque, so a mesh at alpha = 0.5 draws fully opaque rather than half see-through. Fade a mesh out and it will stay solid until it vanishes.

Moving a mesh in 3D

Mesh and Sprite3d inherit the ordinary Renderable transform helpers, and both are already 3D:

mesh.rotate(Math.PI / 2, new Vector3d(1, 0, 0));   // axis overload
mesh.scale(2, 1, 0.5);                             // z is a real argument

rotate(angle) alone is the 2D case (about Z); pass a Vector3d and it rotates about that axis. Both write to currentTransform, a Matrix3d, which Mesh folds into its model matrix — so orienting a mesh costs a matrix update, not new geometry.

This matters most for the case it is least obvious for: a horizontal plane. Sprite3d with billboard: false is a quad in the sprite plane — upright — and the way to lay one flat (water, a road, a shadow decal) is to rotate it a quarter turn about X, not to hand-build vertices. The one reason to build geometry instead is tiling: a Sprite3d bakes its UVs 0..1 from its atlas frame, so a surface that needs textureRepeat across many world units still wants an explicit vertices/uvs mesh.

The mesh pass is opaque

Worth stating plainly, because the symptom does not look like a blending problem: the mesh pass disables blending. A soft-edged texture — a glow, a sun, a halo, anything with a gradient alpha — composites as a hard-edged disc with a grey rim, which reads as a broken texture rather than as a missing feature.

transparent: true routes it through the transparent pass, and blendMode: "additive" on top of that makes a light source add to the sky instead of sitting on it. This is the same feature a translucent water surface needs.

Textures under a perspective camera

A tiling texture on a large ground plane is seen at a grazing angle, and that changes which detail survives:

• Nothing straight and parallel to the direction of travel. Every such run converges on the vanishing point, so a few current bands on a river become a fan of rays radiating out of the horizon. Narrowing them and tiling more often only multiplies the rays. Short, scattered, direction-free detail minifies into an even shimmer instead.
• textureFilter: "linear" for a floor — "nearest" opts out of mipmaps and anisotropy, and detail aliases into a wash exactly where the camera looks most.

Ground must outlast the props standing on it

Scenery scattered up a slope is placed by its own rule, and terrain is built by another. When the planting reaches further than the mesh does, a low camera sees trees standing over open sky at the corners of the frame. Build the ground wider than the widest thing planted on it — past the profile's clamp it is a flat plateau, so the extra columns cost two triangles and no silhouette.

Recycling has the same trap in Z: an endless runner that recycles tiles a fixed distance behind the player forgets that the camera trails further back still, and the bottom of the frame falls off the world.

Sprite3d and billboards

Sprite3d is the 2.5D workhorse: a flat sprite living at a real depth, with billboard controlling how it faces the camera.

"cylindrical" is what you want for paper-thin characters in a 2.5D game. Billboarding needs a Camera3d drawing the frame; under a 2D camera the quad renders fixed-orientation. Any other string falls through to the spherical branch, so a guessed value like "upright" silently gives you spherical.

Lighting

Light3d takes one argument — the options object (it has no x, y, z pair; a light carries its own position). Types are "directional" (the default), "ambient", "point" and "spot".

world.addChild(new Light3d({ type: "directional", direction: [0.3, 1, 0.2] }));
world.addChild(new Light3d({ type: "ambient", intensity: 0.3 }));
// a Vector3d works too, wherever the game already has one
world.addChild(new Light3d({ type: "spot", position: torch.pos, range: 400 }));

direction and position take an [x, y, z] array or a Vector3d, and color takes a Color, a CSS string or an [r, g, b] array — so a value the game already holds can go straight in. Each is read, not retained: move your vector afterwards and the light stays where it was.

Two things still bite, both silently:

• new Light3d(0, 0, {…}) — the constructor takes options alone. JavaScript drops the extra arguments, so options becomes the number 0 and every setting in your literal is discarded. The light still appears, on pure defaults: a type: "ambient" written this way is a second DIRECTIONAL light, and the scene looks plausible enough that nobody checks. TypeScript stops checking a literal once the argument count is wrong, so nothing inside it is verified either.

• direction is where the light GOES, and this is a Y-down space — so a sun overhead travels downward and its Y is positive. Get the sign wrong and the scene is lit from underneath: faces that should be in shade are bright, the ground glows and the sky-facing surfaces go dark.

  direction: [-0.35, 0.8, 0.45]   // sun overhead, late afternoon
  direction: [-0.35, -0.8, 0.45]  // lit from below — almost never what you want
  

  position follows the same convention: a lamp above the floor has a smaller y than the floor.

Use both halves: with a key light but no ambient, the shadow side of a mesh goes black. With no Light3d in the world at all, a lit: true mesh falls back to a white ambient and renders fullbright — indistinguishable from unlit, which is why "I added lit: true and nothing changed" is the usual first report.

Other defaults worth knowing: intensity 1, color white, range 1000 (point and spot, a stylised quadratic falloff, not inverse-square), innerConeAngle 0 and outerConeAngle π/4 (spot).

Light2d is 2D-only and produces visible artifacts under perspective projection. Do not combine it with Camera3d.

Ground shadows are on by default (the castGroundShadow application setting), and need a GPU backend and a Camera3d. As a blanket default they skip geometry with no vertical extent — a ground plane. Per object, castGroundShadow: true/false overrides the app setting and is obeyed as given, safeguard included; shadowGroundY names the floor the blob lands on.

The blob is an ellipse sized to the caster's own footprint and placed at the caster's x/z — it is never offset by light direction. So a tall or narrow object (a character, a tree, a pickup) shows its shadow clearly, while a wide, flat-bottomed one resting on the floor covers its own completely from a camera looking down at it. That is the shadow behaving correctly, not a bug.

Do not chase it by raising shadowGroundY. Lifting the plane does not slide the blob out from under the object, it floats the blob up — and past a few units it projects over the top of the caster as a dark halo ringing it. If an object needs a visible shadow, give it a smaller footprint relative to its height, or accept that a boulder bedded in the ground has none.

Get the sign right: the floor is a GREATER y

Render space is Y-down, so the floor an object stands on is a larger y than the object itself. Nudging a shadow plane below a surface is therefore a plus:

mesh.shadowGroundY = WATER_LEVEL + 8;   // just under the surface — correct
mesh.shadowGroundY = mesh.pos.y - 8;    // eight units ABOVE its own base — wrong

Get it backwards and the blob becomes a horizontal quad slicing through the caster's own body. It is still drawn at full strength — the height fade sees a negative height and clamps to 1, so nothing warns you — but the depth test hides every part of it that falls inside the caster's silhouette. What survives is a thin ring, only as wide as the blob overhangs the object.

The symptom is distinctive and easy to misread: shadows appear to switch on as casters approach the camera. That ring is a few pixels on the nearest object and sub-pixel further out, so a scene reads as "only nearby things have shadows" — which looks like culling, an LOD stage or a fog problem, none of which it is. Before chasing any of those, dump shadowGroundY against the caster's own y and check which one is larger.

Collision in 3D

Use Box3d bodies, not a hand-rolled distance check. Box3d-vs-Box3d is the engine's 3D narrowphase and the only contact that pushes back along Z; the response carries overlapNZ / overlapZ for the depth axis. See the physics skill for the contract and the mixed-pair caveat.

glTF / GLB scenes

Loaded through the same level director as everything else:

await loader.preload([{ name: "diorama", type: "glb", src: "data/diorama.glb" }]);
level.load("diorama", { scale, castGroundShadow, shadowGroundY, onLoaded });

.obj / .mtl are also supported loader types.

An animated asset instantiates as a GLTFModel, which is a game object as much as a scene: construct it straight from the parsed descriptor, and place it with pos / depth / rotate / scale like any other renderable — the placement drives the whole rig and composes with the playing clip.

const model = new GLTFModel(loader.getGLTF("boat"), { scale: 40, lit: false });
model.setCurrentAnimation("paddle", { loop: true });
model.pos.set(x, y);
model.depth = z;

To scatter an authored mesh yourself, read the geometry off the descriptor and hand it to an InstancedMesh — loader.getGLTF(name).nodes[0] carries vertices / uvs / normals / indices. That wants a single merged primitive exported at the origin; see melonjs-3d-assets.

melonjs-3d-assets covers the rest: every level.load option, which material features are imported, imported lights and their intensity units, node-TRS animation (and the skinning that is out of scope), and OBJ/MTL.

Requires a GPU backend

The whole 3D tier needs WebGPU or WebGL 2. The Canvas renderer has no depth buffer, no perspective path and no drawMesh, so a Camera3d scene does not render correctly there — usually a black canvas. Light3d and shader effects are inert too. A Mesh under a 2D camera still renders, CPU-projected by painter's algorithm and unlit.

Application does warn: constructing with a cameraClass whose defaultSortOn is "depth" on a renderer with no depth buffer logs a console.warn. But video.AUTO falls back silently to Canvas, so the strong gate is to ask for a GPU backend by name — renderer: video.WEBGL (or video.WEBGPU) makes await app.init() reject instead of misrendering:

const app = new Application(1024, 768, {
    parent: "screen",
    renderer: video.WEBGL,      // init() rejects if WebGL 2 is unavailable
    cameraClass: Camera3d,
});
await app.init();

To branch rather than fail, read app.renderer.supportsDepthBuffer after init().

Symptom → cause

Related skills

• melonjs-renderables — the 2D z-ordering rules, anchors, custom draw
• melonjs-getting-started — Application settings and the renderer fallback