melonjs-3d
Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Trail3d, ribbon, exhaust trail, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit, setBasis, getBasis, lookAt, up vector, gimbal, slerp, great circle, turn a direction.
melonjs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add melonjs/melonJS --skill melonjs-3dAbout this skill
name: melonjs-3d description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Trail3d, ribbon, exhaust trail, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit, setBasis, getBasis, lookAt, up vector, gimbal, slerp, great circle, turn a direction." license: MIT
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.
| melonJS | OpenGL convention | |
|---|---|---|
| vertical | Y-down — higher y is lower on screen | Y-up |
| depth | +Z forward — higher z is farther away | −Z forward |
Camera3d exposes three rotation angles: 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.
The basis those angles produce is readable and writable: getBasis(right, up, forward) reads it, setBasis(right, up, forward) poses the camera from
one.
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.
Keep the camera, do not fish it back out
app.viewport is the active stage's default camera, so it is typed
Camera2d: a stage overrides the application's cameraClass, and the
built-in loading screen does exactly that. Reading your Camera3d back out of
it therefore needs a cast, and a cast that is wrong while the loader is up:
const camera = app.viewport as Camera3d; // works, until it does not
Own it instead. Pass the camera in and keep the typed reference, and nothing downstream ever narrows:
class GameStage extends Stage {
readonly camera: Camera3d;
constructor(app) {
const camera = new Camera3d(0, 0, app.renderer.width, app.renderer.height);
super({ cameras: [camera] });
this.camera = camera;
}
}
A freshly built camera is named "default", and a stage registers its
cameras by name, so this IS the stage's default camera: app.viewport
returns the same instance.
The two patterns differ in LIFETIME, and that decides which you want
This is the part that bites. cameraClass builds a fresh camera for each
stage, which the engine does deliberately so "Camera3d state shouldn't
bleed across stages". An owned camera passed through super({ cameras }) is
built once and lives as long as the stage object, which for a stage you
register with state.set() means as long as the application.
So anything you attach to the camera now outlives the visit:
// in onResetEvent — runs EVERY time the stage is entered
app.viewport.addPostEffect(bloom);
With cameraClass that lands on a fresh camera each time and is harmless.
With an owned camera it stacks: a second bloom on the second visit, a third
on the third. The symptom is text and edges appearing to double or smear,
because the scene is being post-processed once per accumulated effect.
Note that removePostEffect DESTROYS the effect rather than detaching it, so
"just remove it on the way out" is not a free undo.
Choose on lifetime, not on typing:
| your effects / camera state are | use |
|---|---|
set up per stage visit, in onResetEvent | cameraClass — fresh camera per stage |
| set up once, in the stage constructor | an owned camera in super({ cameras }) |
If you want the typed reference but your setup is per-visit, keep `cam
Read the complete source ↗