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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-3d-assets技能说明
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
| 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