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

melonjs-3d-assets

Use this skill when loading 3D models into melonJS — glTF and GLB scenes, OBJ/MTL models, materials, imported lights, node animation, ground shadows and GPU instancing. Covers level.load options including the async flag, the rightHanded conversion, and exactly what the loader does and does not support. Triggers on: glTF, gltf, glb, OBJ, MTL, 3D model, getGLTF, getOBJ, getMTL, GLTFModel, GLTFScene, level.load glb, rightHanded, lightIntensityScale, castGroundShadow, shadowGroundY, EXT_mesh_gpu_instancing, KHR_lights_punctual, skinning, Blender export, 3D asset.

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-assets

About this skill


name: melonjs-3d-assets description: "Use this skill when loading 3D models into melonJS — glTF and GLB scenes, OBJ/MTL models, materials, imported lights, node animation, ground shadows and GPU instancing. Covers level.load options including the async flag, the rightHanded conversion, and exactly what the loader does and does not support. Triggers on: glTF, gltf, glb, OBJ, MTL, 3D model, getGLTF, getOBJ, getMTL, GLTFModel, GLTFScene, level.load glb, rightHanded, lightIntensityScale, castGroundShadow, shadowGroundY, EXT_mesh_gpu_instancing, KHR_lights_punctual, skinning, Blender export, 3D asset." license: MIT

Loading 3D assets

glTF/GLB is the primary path for 3D content, and it goes through the level director rather than the world directly: level.load("scene"), the same call a Tiled map uses. OBJ/MTL is the simpler path for a single static model.

Loading a glTF/GLB scene

await loader.preload([
    { name: "diorama", type: "glb", src: "data/scenes/diorama.glb" },
]);

level.load("diorama", { scale: 50 });

type: "gltf" (JSON plus external buffers) and type: "glb" (single binary) are both loader types. A self-contained GLB is the better shipping format — one request, nothing to resolve relatively.

The scene loads under whatever camera the stage has; view it under a Camera3d or it renders flat. See melonjs-3d for the camera.

level.load options for glTF/GLB

optiondefaultwhat it does
scale1pixels per glTF unit, applied to the whole scene. Blender's metre-scale export usually needs 20–100.
containergame.worldwhere the nodes are added
onLoadedgame.onLevelLoadedcalled with the level id, not the scene
asyncfalsereturn a promise that settles once the scene is in the world, instead of a boolean
rightHandedtruesee below
lightstrueinstantiate authored KHR_lights_punctual lights as Light3d world children
lightIntensityScale—keep authored intensity ratios instead of normalising every light to 1

Those game. defaults are the engine's, not a recommendation. game is whichever Application finished init() last, so pass container explicitly from a Stage, where the right one is in your hand:

level.load("sceneId", { container: this.app.world, scale: 40 });

| castGroundShadow | inherits the app setting (on) | blob shadows for this scene's meshes | | shadowGroundY | each object's own base | world Y of the floor the blobs land on | | shadowOpacity | 0.45 | how dark the blobs are | | shadowScale | 1 | blob footprint multiplier; 0 or less hides them | | shadowOffset | 0 | slide them along the light, in blob radii; needs shadowGroundY, which is the only way a scene load can name its floor | | shadowStretch | 1 | lengthen them along it, clamped to 3 | | shadowDirectionX / shadowDirectionZ | 0 | the ground direction they are cast along | | shadowGroundNormal | world up | up normal of the floor, for a scene that is not level | | shadowLight | — | a Light3d to take the direction from, re-read every draw |

shadowGroundPoint is not on that list, and a scene load drops it without a warning. One floor POINT shared by every part of a scene would stack the whole thing's blobs on a single spot, which is nonsense where one floor HEIGHT is perfectly sensible. Ground that is not flat is a per-object answer: set it on the parts you want once the load has finished.

onLoaded receives the level id — it is a "done" signal, not a handle on the scene. You need it, or async: with the game loop running, level.load stops the loop and defers the actual load to a timer, so by default it returns before anything is in the world.

await level.load("diorama", { scale: 50, async: true });
// the scene is in the world here

Note await level.load("diorama") without the flag does not await the load — the call returns a boolean, and await true resolves immediately. To get at what was loaded, load into a container you own, or look the nodes up by their authored names:

level.load("diorama", { scale: 50, onLoaded: () => {
    const sun = app.world.getChildByName("Sun")[0];   // note: returns an array
    sun.intensity = 2;
}});

The same options from a Tiled Trigger

A Trigger authored in Tiled forwards these to level.load(), so a trigger that walks the player into a glTF level carries the scene's settings as Tiled properties:

world.addChild(new Trigger(x, y, {
    shapes: [new Rect(0, 0, 100, 100)],
    to: "diorama",              // the level id — `to`, not `level`
    scale: 50,
    rightHanded: false,
    castGroundShadow: false,
}));

Every level.load option above travels, including the whole ground-shadow set, and so do container, onLoaded, flatten and setViewportBounds. The list is derived from level.loadOptions rather than restated, so an option added to a level format arrives here for free. It used to be hand-written and had fallen three releases behind the glTF path (#1649).

async is deliberately excluded. A trigger with a color + duration sets it itself, because it needs the promise to sequence its fade and reveal; a trigger without one loads fire-and-forget and never sets it. Either way an authored async property is ignored rather than honoured.

rightHanded — and the default that differs between the two APIs

glTF is authored Y-up, right-handed; melonJS is Y-down, +Z forward. There are two ways to bridge that, and they are not equivalent:

  • a rotation — preserves chirality, matches the authoring tool
  • a mirror (negate Y only) — flips the scene left/right

level.load defaults rightHanded: true, so a scene loaded through the level director comes in correctly. The Mesh constructor defaults it to false, so glTF or OBJ geometry you feed to a Mesh yourself comes in mirrored

Read the complete source ↗