Melonjs 3d Assets Agent Skill

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

| option | default | what it does |

|---|---|---|

| scale | 1 | pixels per glTF unit, applied to the whole scene. Blender's metre-scale export usually needs 20–100. |

| container | game.world | where the nodes are added |

| onLoaded | game.onLevelLoaded | called with the level id, not the scene |

| async | false | return a promise that settles once the scene is in the world, instead of a boolean |

| rightHanded | true | see below |

| lights | true | instantiate 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 unless

you pass rightHanded: true. A model that is subtly wrong — text backwards, a

character's gear on the wrong side — is this and nothing else.

Do not add a flip of your own on top; two corrections cancel back to wrong.

Materials — what actually arrives

The importer covers a deliberate subset:

• pbrMetallicRoughness base colour texture and factor
• metallic/roughness factors converted to the engine's specular model
• emissiveFactor, including KHR_materials_emissive_strength
• KHR_materials_unlit — honoured, for baked/stylised workflows
• alphaMode: "MASK" — the cutout threshold is applied
• doubleSided

Not imported: normal maps, metallic/roughness *textures*, occlusion maps,

morph targets, KHR_texture_transform. Nothing errors — the material simply

arrives without them, which reads as "flatter than the preview in my authoring

tool". Bake what you need into the base colour.

Draco compression is the exception that does error. Its geometry sits in

accessors with no buffer view, which the parser rejects outright, so the whole

asset fails to load. Export uncompressed.

textureFilter on the Application settings ("nearest" / "linear" /

"auto") drives sampling; glTF materials that declare their own sampler carry

it through. Pixel-art models want "nearest".

baseColorFactor is LINEAR; a tint is sRGB

Pass the factor as a setting and the encoding is done for you. Mesh

takes baseColorFactor — [r, g, b] in 0..1, linear, which is the form the

loader hands back — so a mesh built from a node passes the node's own field

straight through:

const node = loader.getGLTF("palm").nodes[0];
const mesh = new Mesh(x, y, {
    vertices: node.vertices, normals: node.normals,
    uvs: node.uvs, indices: node.indices, normalize: false,
    baseColorFactor: node.baseColorFactor,   // encoded, not scaled
});

The setting's type admits undefined, because the loader declares the field

optional and that line has to compile under exactOptionalPropertyTypes.

Sprite3d forwards it too, and mesh.setBaseColorFactor(f) applies one after

construction. For an ordinary sRGB colour use setTint instead — the rest of

this section is why the two are different.

The loader handles this for you. It only bites when you build meshes yourself

from loader.getGLTF(name).nodes — which is what you do for per-node control,

since there is no public per-node Mesh factory — and reach for the obvious

* 255:

// WRONG — every untextured material renders far too dark
mesh.tint.setColor(f[0] * 255, f[1] * 255, f[2] * 255, 1);

glTF defines pbrMetallicRoughness.baseColorFactor in linear space (spec

3.9.2), while a melonJS tint is 8-bit sRGB — the same space as a CSS

colour or a texel out of a PNG. They are not the same number, and the gap is

widest exactly where art tends to live:

| linear | * 255 | correct |

|---|---|---|

| 0.05 | 13 | 63 |

| 0.20 | 51 | 124 |

| 0.42 | 107 | 173 |

| 0.72 | 184 | 221 |

| 1.00 | 255 | 255 |

Color.setLinear does the encoding for you — it is the linear-space sibling of

setFloat, which takes the same 0..1 range but treats it as already-sRGB:

mesh.tint.setLinear(...node.baseColorFactor);   // encodes; what you want
mesh.tint.setFloat(...node.baseColorFactor);    // does NOT encode; too dark

It clamps, so the slightly out-of-range factors some exporters emit cannot turn

into NaN, and it keeps the encoded value as a float rather than rounding

through 8 bits.

Measured on a scene whose every material went through * 255: mean frame luma

85.5 against 147.8 once encoded, with each channel sitting 60 to 73 counts low.

Fix it early. It is nearly invisible as a bug, because the scene still

looks coherent — just moody — so lighting and bloom thresholds get tuned

against the wrong values. Correcting the encoding afterwards blows the frame

out and forces a lighting retune, which is a much bigger job than the encode.

This applies only to factors coming out of glTF. Colours you author for the

screen, a HUD tint or a glow, are already sRGB: * 255 is right for those.

Lights

Authored KHR_lights_punctual lights — sun, point, spot — become Light3d

world children, plus a soft ambient fill, and each keeps its authored name.

A scene carrying any of them renders through the lit path automatically.

glTF stores physical units — lux for suns, candela for lamps — and a Blender

daylight sun is 1000+, which blows out the engine's stylised shading. So every

light is normalised to intensity 1 by default. To keep the *ratios* the artist

set, scale instead of normalising:

// a 1000-lux sun lands at 1, a 500-lux fill lands at 0.5
level.load("diorama", { scale: 50, lightIntensityScale: 0.001 });

Pass lights: false to manage lighting yourself.

Animation

Node-TRS animation is supported: translation, rotation and scale channels,

the rigid hierarchical animation used by blocky/low-poly character packs. An

animated asset instantiates as a single GLTFModel keeping the node hierarchy

intact, with an API deliberately mirroring Sprite. The model carries the asset

name, which is how you get hold of it after loading:

const model = app.world.getChildByName("hero")[0];   // the GLTFModel

model.getAnimationNames();                           // ["idle", "walk", ...]
model.setCurrentAnimation("walk", { loop: true, speed: 1, onComplete });
model.setCurrentAnimation("jump", { next: "idle" }); // chain
model.isCurrentAnimation("walk");
model.play();
model.pause();

speed is a playback multiplier (1 = authored speed), not a frame delay. Only

an explicit loop: false stops looping. setCurrentAnimation throws on a

clip name the asset does not define — check getAnimationNames() first.

Placing and moving a model

A GLTFModel is placed like any other renderable — pos, depth, rotate

and scale move the whole rig, and compose with whatever the active clip

is doing, so a walk cycle plays wherever the character stands:

const boat = new me.GLTFModel(me.loader.getGLTF("boat"), { scale: 40, lit: false });
boat.setCurrentAnimation("paddle", { loop: true });
app.world.addChild(boat);

boat.pos.set(steerX, waterLevel);
boat.depth = travelled;
boat.rotate(lean - lastLean, AXIS_Z);   // `rotate` is RELATIVE — feed it the delta
boat.animationspeed = 0.85 + 0.9 * pace; // one authored tempo, many run speeds

Constructing one directly from loader.getGLTF(name) is fine and is the way to

go when the model is a game object rather than a scene — level.load is for

loading a whole scene into the world.

Vertex skinning is out of scope — JOINTS_0 / WEIGHTS_0 are not read, and

neither are morph targets. A smoothly-deforming character will not deform. The

options are: rig it hierarchically instead (separate meshes parented into a

node tree), use Sprite3d billboards, or use the Spine plugin for 2D skeletal

work.

Instancing

A node using EXT_mesh_gpu_instancing loads as an InstancedMesh — one draw

call for every copy, which is the difference between a hundred trees and a

hundred thousand. Export with instancing enabled where your tool supports it.

Sparse accessors on the instancing attributes are rejected with a clear error

rather than silently misplacing every instance.

Ground shadows

level.load("diorama", { scale: 50, castGroundShadow: true, shadowGroundY: 0 });

castGroundShadow is tri-state: set it and it overrides the application setting

for this scene in both directions; omit it and the scene inherits — and that

setting is true by default, so shadows are already on. As a scene-wide opt-in

it skips nodes with no vertical extent — a ground plane is exactly that, and

shadowing it with itself smears a blob across the whole floor. Blob shadows need

a GPU backend and a Camera3d; nothing is drawn on the 2D-camera or Canvas

paths.

Omit shadowGroundY and each blob sits at its own object's base at full

strength, which is right for props already resting on the ground. Set it when

things jump or fly, so the shadow stays on the floor and shrinks with height.

A blob sits on its caster's x/z by default, so a wide flat-bottomed prop hides

its own shadow under itself. The knob for that is shadowScale, which widens

the blob until its edge shows past the prop, or shadowOffset plus a direction,

which slides it clear. Not shadowGroundY: raising that floats the blob up

over the object as a dark ring instead of sliding it out, because it is for

things that leave the ground, not a visibility control.

For a light that is not overhead, name one: shadowLight takes the direction

from a Light3d and is re-read every draw, so a day or night cycle carries

every shadow in the scene with it. Nothing is inferred — a scene with no named

light and no shadowDirectionX/Z gets no direction, because a scene with

several lights has no non-arbitrary answer. shadowStretch lengthens the blob

along that direction and fades it as it pulls; shadowGroundNormal lays it on

a floor that is not level. All of these apply to an InstancedMesh too, as one

value for the whole set.

OBJ/MTL

A different shape entirely: OBJ produces raw geometry you hand to a Mesh,

not a scene. Preload the two files and name them in the Mesh settings — the

model and material names are independent, the same name for both is just a

convention:

await loader.preload([
    { name: "fox", type: "obj", src: "models/fox.obj" },
    { name: "fox", type: "mtl", src: "models/fox.mtl" },
]);

const mesh = new Mesh(400, 300, {
    model: "fox",
    material: "fox",        // texture resolved from the material's map_Kd
    width: 200,
    height: 200,
    rightHanded: true,      // the Mesh default is false — see above
});
world.addChild(mesh);

The MTL loader fetches the textures it references itself — map_Kd,

map_d and map_bump are resolved relative to the .mtl and preloaded for

you, so there is no image entry in the manifest above. Passing texture:

explicitly overrides that and pins *one* binding over the whole model, which on

a multi-material model suppresses the per-material texture split; leave it out

unless you mean that.

MTL contributes Kd (diffuse tint), d / Tr (opacity), Ke (emissive),

Ks + Ns (specular highlight), map_Kd (diffuse texture), map_d

(per-texel opacity) and map_bump / bump / norm (tangent-space normal

map — needs lit: true, and the tangent frame is derived per fragment, so the

model needs no tangent attribute). All three normal-map spellings are read as

normal maps even though the format specifies two of them as height maps, which

is what every exporter actually writes. Specular *maps* (map_Ks) and the PBR

extension's map_Pr / map_Pm are not supported and warn — the Pr / Pm

*scalars* are read and approximated onto the specular terms, the maps would

need a real PBR model.

Ka (ambient) and illum (illumination model) are read onto the material and

readable from loader.getMTL(name), but take no part in shading. That is

deliberate rather than pending: Ka predates scene-wide ambient light and would

fight Stage.ambientLightingColor, and illum enumerates fixed-function

behaviours this renderer has no equivalent for. In particular an illum of 0 or

1 nominally means "no specular", and the engine does not honour that — Ns

stays the only gate, so a model that renders correctly today is not restyled by

a field its exporter wrote inconsistently.

loader.getOBJ(name) and loader.getMTL(name) return the parsed data if you

want it directly. OBJ has no scene graph, no lights, no animation — use glTF for

anything beyond a single static model.

Authoring assets for the engine

Notes from modelling props and a rigged character against this loader. They are

Blender-specific in the API details, general in the traps.

One clip means one action

glTF names an animation after the action it came from, so three objects

each carrying their own action export as three separate clips — and a game can

only play one clip at a time, so the other two never move. Put every animated

object in one action, using slots (Blender 4.4+):

shared = bpy.data.actions.new("paddle")
for ob in (pivot, shoulder_l, shoulder_r, body):
    ad = ob.animation_data_create()
    ad.action = shared
    ad.action_slot = shared.slots.new('OBJECT', ob.name)

Exporting with the scene/whole-timeline mode does not merge per-object

actions into one clip — it still emits one per action. Slots are the fix.

In Blender 5.x, action.fcurves no longer exists; curves live under

action.layers[].strips[].channelbags[].fcurves, and a channelbag identifies

its slot as cb.slot.identifier (there is no slot_identifier).

Never re-parent or join a rig that is mid-pose

Both parenting and joining bake the objects' current world transforms.

Parenting a child while the parent sits in an animated pose writes the inverse

of that pose into matrix_parent_inverse, which silently cancels the animation

— the part renders rigid while the curves still exist. Detach the action, zero

the rig, do the surgery, then reattach:

saved = [(o, o.animation_data.action_slot) for o in animated]
for ob, _ in saved:
    ob.animation_data.action = None
    ob.rotation_euler = (0, 0, 0)
# ...re-parent / join here...
for ob, slot in saved:
    ob.animation_data.action = act
    ob.animation_data.action_slot = slot

A joined mesh also inherits the active object's scale, so joining into a

box that was scaled to (0.8, 2.0, 0.1) leaves a node with that non-uniform

scale and geometry divided back through it. It renders in the right place but

skews flat-shaded normals — apply transforms (rotation=True, scale=True)

after joining. Watch for a related trap: setting ob.scale.x on a mesh whose

size was already applied *multiplies* rather than replaces it.

A model only needs to stay split where something animates it

Every glTF primitive is a draw call. Merge everything static into one mesh and

keep separate nodes only for the parts a clip actually drives — a boat with a

rabbit and a paddle went from 28 primitives to 5 that way, with no visible

change.

One palette strip beats one material per colour

An InstancedMesh is one geometry and one material, so a prop that wants

five colours cannot use five materials. Give the whole model a single material

whose image is an *N*×1 strip, one pixel per shade, and point each face's UVs

at a cell centre (u = (cell + 0.5) / N, v = 0.5) with the sampler set to

nearest. A whole scene's palette then costs one tiny texture, a merged mesh can

be twenty colours, and there is nothing to bleed between cells.

Colour-space trap when generating that strip programmatically: Blender's

image.pixels are scene-linear floats, but this export path writes them out

verbatim, so pre-converting sRGB→linear darkens every colour. White is the

tell — it is the one value identical in both spaces, so if white survives and

everything else came out dark, that is the bug. Verify by decoding the PNG back

out of the GLB and comparing bytes to the source palette.

Feeding an authored mesh into an InstancedMesh

EXT_mesh_gpu_instancing covers instances authored *in the file*. When the

game places them itself, take the geometry off the parsed descriptor instead:

const node = me.loader.getGLTF("palm").nodes[0];
const trees = new me.InstancedMesh(0, groundY, {
    vertices: node.vertices, uvs: node.uvs,
    normals: node.normals, indices: node.indices,
    texture: palette, textureFilter: "nearest", scale: 40,
    instanceCount: count,
});

nodes is one entry per primitive, each in its own local space with a

separate world matrix — so this only works cleanly when the asset is a single

merged primitive exported with an identity node transform. Model it at the

origin, base on the floor, and apply transforms before exporting.

One geometry stamped out hundreds of times reads as one object *copied*

hundreds of times, so vary each instance in its transform. Rotate after

translating, or the instance swings around the group origin instead of turning

where it stands:

placement.identity().translate(x / s, -y / s, z / s)
         .rotate(math.randomFloat(0, Math.PI * 2), AXIS_Y);
const j = math.randomFloat(0.82, 1.18);
placement.scale(j, j, j);

Sizing every prop against one scale constant, rather than giving each its

own, keeps "this looks wrong" a modelling question instead of a scaling one.

Packaging

A self-contained GLB is one file with nothing to resolve — the safest thing to

ship. External references still work in both formats: .bin buffers and image

uris are resolved relative to the asset's own URL (a GLB with an external

texture loads as-shipped). But an external file that 404s rejects the parse, so

the whole asset fails to load rather than arriving partially — no untextured

fallback. Note that loader.setBaseURL("*", …) deliberately skips gltf,

glb, obj and mtl for this reason; set those types individually if you

need a prefix.

Symptom → cause

| symptom | cause |

|---|---|

| model mirrored — text backwards, gear on the wrong side | Mesh defaults rightHanded to false; pass true |

| model upside down | a manual axis flip on top of the loader's conversion |

| scene is enormous or invisibly small | scale left at 1 against a metre-scale export |

| the asset fails to load entirely | an external buffer/image uri that 404s, or Draco-compressed geometry |

| everything is blown out white | authored lux/candela intensities; use lightIntensityScale |

| materials flatter than the authoring-tool preview | no normal or metallic/roughness *textures* are imported |

| a character does not deform | vertex skinning is out of scope; rig hierarchically or billboard |

| animation names come back empty | the asset has no node-TRS channels (skin-only rig) |

| a hundred copies tank the frame rate | exported without EXT_mesh_gpu_instancing |

| a whole scatter looks like one object repeated | every instance shares the group transform — vary yaw/scale per instance, rotating *after* the translate |

| three clips where you authored one | one action per object; use a single action with a slot each |

| one part of a rig renders rigid while its curves exist | it was re-parented mid-pose, baking the inverse into matrix_parent_inverse |

| a merged mesh lights wrong along one axis | it inherited the active object's non-uniform scale on join — apply transforms |

| an authored palette comes out uniformly dark, but white is correct | linear values written to a strip that is saved verbatim |

| every untextured glTF material renders too dark, white unaffected | baseColorFactor is linear and a tint is sRGB — tint.setLinear(...), not * 255 or setFloat |

| getGLTF(name).nodes[0] geometry lands in the wrong place | nodes is per primitive, each with its own world; merge to one primitive and export at the origin |

| a prop casts no visible shadow | wide and flat-bottomed — the blob is under it; shadowGroundY haloes it rather than revealing it |

| shadows only show on casters near the camera | shadowGroundY is on the wrong side — Y-down means the floor is a greater y, so a pos.y - lift puts the blob inside the caster and the depth test leaves only a hairline ring |

| a shadow smeared across the whole floor | a ground plane cast its own blob — use the scene-wide opt-in |

| onLoaded gets a string, not the scene | it is called with the level id; load into your own container instead |

| scene renders flat and unlit | no Camera3d — the 2D-camera path is CPU-projected and unlit (with a Camera3d on Canvas you get a black canvas instead) |

Related skills

• melonjs-3d — conventions, Camera3d, meshes, Light3d, instancing, and

camera.setFog (an outdoor scene almost always wants it; it is set on the

camera, so a loaded scene needs no per-node work)

• melonjs-lighting — how Light3d behaves once imported
• melonjs-loading-assets — the loader, asset types and base URLs
• melonjs-plugins — the Spine plugin, for skeletal characters