Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

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-3d

About 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.

melonJSOpenGL convention
verticalY-down — higher y is lower on screenY-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 areuse
set up per stage visit, in onResetEventcameraClass — fresh camera per stage
set up once, in the stage constructoran owned camera in super({ cameras })

If you want the typed reference but your setup is per-visit, keep `cam

Read the complete source ↗