- name
SKILL.md
O arquivo da skill permanece no repositório do publicador.
Cole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderables -a cursor -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderables -a claude-code -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderables -a codex -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add melonjs/melonJS --skill melonjs-renderables -a grok -yEnvie a mensagem copiada em um chat do Grok Bot. O Bot busca este SKILL.md no GitHub e o adiciona às skills que todos os seus Bots compartilham.
Install this skill: https://github.com/melonjs/melonJS/tree/HEAD/packages/melonjs/skills/melonjs-renderablesDo publicador
Subclassing
Renderable, custom drawing, receiving pointer events, and applying post effects — with the traps that produce silently wrong output rather than an error.
Everything here is a silent failure: the code runs, nothing throws, and the result is wrong. Those are the cases worth memorising, because nothing in the type signatures warns you.
draw() must position itself from this.posThe renderer is not pre-translated to the renderable's position when draw()
is called. Container.draw translates by the container's own pos and then
calls child.preDraw / draw / postDraw; preDraw never translates by the
child's pos. Read this.pos and draw relative to it.
class Marker extends Renderable {
draw(renderer) {
// ✗ draws at the parent container's origin, not at the marker
renderer.fillRect(0, 0, this.width, this.height);
// ✓
renderer.fillRect(this.pos.x, this.pos.y, this.width, this.height);
}
}
The symptom is an object that renders correctly at position (0, 0) and appears stuck at the top-left as soon as you move it.
Zero the anchor in custom-draw renderables. preDraw does not translate to
pos, but it does apply the anchor offset (-width * anchorPoint.x, -height * anchorPoint.y). With the default centred anchor, drawing at
this.pos therefore lands half a size off:
constructor(x, y, w, h) {
super(x, y, w, h);
this.anchorPoint.set(0, 0); // ← or every custom draw is offset by -w/2, -h/2
}
isKinematic must be false to receive input or collisionsRenderable.isKinematic defaults to true, which means "physics collision
and input events will not impact this renderable". A kinematic renderable is
skipped by the pointer-event dispatcher entirely.
class Button extends Renderable {
constructor(x, y) {
super(x, y, 100, 40);
this.isKinematic = false; // ← required, or clicks never arrive
input.registerPointerEvent("pointerdown", this, () => { /* … */ });
}
}
The symptom is a handler that is registered, looks correct, and never fires.
Note that Container, Camera2d, Draggable, DropTarget and the UI*
elements set it to false for you, and so does giving a renderable a body (a
bodyDef, on every physics adapter, or a Body, which covers Entity) — so a
plain Renderable or Sprite subclass with no body is the case that catches
people. Before melonJS 20.14, matter-adapter 1.6.0 and planck-adapter 1.7.0,
only the built-in adapter cleared it: under matter or planck a renderable with
a bodyDef stayed kinematic and missed pointer events.
The same flag has a second, less obvious effect: it is also the opt-in to the
world broadphase. The quadtree/octree insert skips any child with
isKinematic === true, so body-less objects you want adapter.queryAABB /
querySphere to find need isKinematic = false as well. That is the built-in
adapter; the queryAABB of matter, planck and Rapier only ever returns
renderables with a body. The builtin
narrowphase likewise requires both partners to be non-kinematic.
addChild(child, z) worksThere are three separate traps here and they compound.
world.addChild(sprite, 10); // ✓ the only reliable form
renderable.z does not exist. There is no z accessor anywhere on
Renderable (nor on Rect/Polygon above it) — only depth, which proxies
pos.z, and the container's default sortOn: "z" comparator reads pos.z.
Writing sprite.z = 100 creates an inert property that nothing reads.
Several shipped examples still contain this.z = Number.POSITIVE_INFINITY;
those HUDs draw on top only because they happen to be added last. (A z key
in a Sprite/ImageLayer settings object is a different thing and is real
— it assigns pos.z in the constructor — but trap 2 then overwrites it.)depth before addChild is overwritten. With autoDepth on
(the default), addChild without an explicit z assigns
child.pos.z = children.length after the push, discarding whatever you set.depth after addChild does not reorder. A "z" sort runs
when a child is added (autoSort, deferred to the next tick), not when
pos.z changes. If you must change it later, call container.sort()
yourself, or use moveToTop / moveUp / moveDown / moveToBottom, which
reorder the children themselves. (An "x" / "y" sort is different: see
below.)"y" (or "x"), and sortOffsetA container with sortOn = "y" draws its children from the smallest pos.y to
the largest, so whatever is lower on screen covers what is above it (top-down and
isometric games). "x" does the same along x. A different pos.z still decides
first, so keep the children that should interleave at one z.
autoSort on (the default), the
container checks its order at the end of every update, after physics and the
children's own updates, and re-sorts when anything is out of place: a walking
character needs no sort() call. A frame where nothing moved costs one pass
over the children and does not cause a redraw. Turn autoSort off to keep
the children in the order you put them.sortOffset changes the ORDER only, never where anything is: the child is lined
up as if it stood that many pixels lower (positive) or higher (negative), and is
drawn exactly where it was. Use it when pos is not the point to sort by:
torch.sortOffset = 1; // win the tie with the wall it hangs on
dust.sortOffset = door.pos.y - dust.pos.y; // an emitter's pos is the top of its
// spawn area: line it up with the door
prop.sortOffset = prop.height; // sort by the bottom of the image
A container that keeps itself sorted picks a change up at its next update (with
autoSort off, call its sort()). "z" and "depth" sorting ignore it. It must be a finite number (a string
or NaN throws, rather than scrambling every sibling), and a pooled renderable
starts again at 0.
The exception: under Camera3d the world's sortOn is "depth", and the
camera calls container.sortNow(true) every frame. Note that mode does not
sort by pos.z as a layer index — it sorts by squared distance from the camera
in world space (nearest first in the array, painted far→near). So changing
depth does reorder there, but as a position change, not as a layer number.
// ✗ overwritten by autoDepth
sprite.depth = 10;
world.addChild(sprite);
// ✗ no resort happens (except under Camera3d)
world.addChild(sprite);
sprite.depth = 10;
// ✓
world.addChild(sprite, 10);
removePostEffect() destroys the effectTo disable an effect temporarily, toggle it. Removing it frees its GPU resources and leaves you holding a dead object.
// ✗ effect is destroyed; re-adding it will not work
sprite.removePostEffect(effect);
// ✓
effect.enabled = false;
Exception worth knowing: an effect with effect.shared === true opts out of
auto-destroy, because it is reused across renderables.
Use addPostEffect() / getPostEffect() / removePostEffect(). Assigning
renderable.shader = … is deprecated since 19.2.0.
Post effects need a programmable pipeline. A ShaderEffect constructed against
the Canvas renderer (renderer.shaderLanguage === null) stays at
enabled === false and no-ops every method rather than throwing — and
beginPostEffect filters disabled effects out. The first one logs a warning,
the rest stay quiet, so a decorative effect needs no renderer check. Since video.AUTO picks the
backend at runtime, an effect that works on your machine may do nothing on
another.
setChildsProperty assignsalpha composes down the tree. Fading a container fades everything inside
it, and the values multiply — a child at 0.5 inside a parent at 0.5 draws
at 0.25. Each renderable keeps its own value; the composition happens at
draw time and is undone when the renderable is finished.
model.alpha = 0.3; // fades the whole rig
container.setChildsProperty("alpha", 0.3, true); // REWRITES each child's alpha
The two are not interchangeable. setChildsProperty is a bulk assignment: it
changes what the children are, so their own alpha now reads 0.3 and
stays that way after the container goes back to full. Reach for it when you
mean to change the children, and for alpha when you mean to fade a subtree.
Do not assign alpha down a hierarchy by hand. The renderer composes it as it
walks the tree, so setting it at more than one level multiplies: in a rig
nested three deep, 0.3 applied at every level lands parts on 0.3, 0.09
and 0.027 depending where they sit. The symptom does not look like an
opacity problem — a model whose parts hold different opacities, and which
appears to change opacity as it turns, because turning changes which parts
face the camera.
A useful consequence: a GLTFModel is a Container, so model.alpha fades
every part of a loaded rig — which is what you want for a ghost, a fade-in,
or a reflection.
Vector3d.set(x, y) silently zeroes zv.set(10, 20); // z becomes 0, not "unchanged"
v.set(10, 20, v.z); // keep it
pos is an ObservableVector3d, whose set(x = 0, y = 0, z = 0) does the same
— so this.pos.set(x, y) wipes the object's depth.
Renderable#setPosition(x, y, z?) is the renderable-level form and does not:
omit z and the depth is left exactly as it was. Reach for it whenever you
are moving an object rather than editing a vector, and keep v.set(x, y, v.z)
for the vector itself.
A settings object is a plain literal: nothing rejects a key, so a name that belongs somewhere else does nothing at all and says nothing about it.
// WRONG — only the RENDERER reads a `blendMode` setting, never a renderable
const glow = new Sprite3d(x, y, { image: "sun", blendMode: "additive" });
// right: it is a property
glow.blendMode = "additive";
The same shape catches transparent on a GLTFModel (its parts carry it —
model.setChildsProperty("transparent", true, true)) and any Mesh setting
handed to a class that forwards only a curated subset. If a visual option
appears to do nothing, check whether the class actually reads it before
tuning the value.
isRenderable does not hide anythingIt gates updateBounds, not drawing. Setting it false leaves the object on
screen and merely stops its bounds tracking, which is worse than doing nothing.
sprite.isRenderable = false; // WRONG — still drawn, bounds now stale
sprite.alpha = 0; // hides it
Use alpha for a blink, or remove the child for a long absence.
renderable.mask takes a shape you created, and destroy() releases the
reference without recycling it: the same instance may still be masking
something else, so the engine has no claim on it. If you pool masks, release
them yourself.
Before 20.7.0 destroy() tried to recycle it and threw for every type
mask accepts, because it used the legacy name-keyed pool and no geometry
class is registered there. It failed mid-teardown, so a masked renderable
could not be destroyed or removed without keepalive at all.
class Enemy extends Renderable {
update(dt) {
this.pos.x += this.speed * (dt / 1000);
return true; // ← true means "redraw me"
}
draw(renderer) { /* … */ }
}
update() returns a boolean meaning "this object changed and needs
redrawing". The parent accumulates it into the container's isDirty, and the
application skips the whole draw pass while nothing is dirty — so returning
nothing (falsy) can leave the scene frozen even though state is updating. The
base implementation returns this.isDirty, so return super.update(dt) is the
other correct ending.
update() is only called when obj.inViewport === true or
obj.alwaysUpdate === true. An off-screen object with the default
alwaysUpdate = false does not tick at all.
A Container is culled by its own bounds, which do not follow its children
unless it has a size of its own (resize) or enableChildBoundsUpdate is on.
With the flag, the bounds are the children's union, re-measured on every update
and, while the group is off screen, before each culling check — so a squad that
walks back into view is drawn again.
clipping = true crops a container's children to its own rectangle, so it
needs a size of its own: a sizeless container (the default) does not clip.
Since 20.13 the pointer skips a child where it is cropped away, and
container.clipContains(x, y) tells whether the container shows its children
at a point (screen pixels for a floating one). A clip inside a clip shows
their overlap, on WebGL and WebGPU as on Canvas.
anchorPoint defaults to centre (0.5, 0.5) on Renderable, but Container
forces (0, 0). Mixing them up shifts children by half their size.floating = true pins a renderable to the screen rather than the world, which
is what you want for HUD elements. It opts the object out of camera transforms
and out of ancestor position accumulation.visibilityLayer decides which cameras draw a renderable: a camera draws it
only if it shares a bit with the camera's cullMask (every camera, by
default). See melonjs-camera-and-drawing for keeping something off a
minimap.Before writing custom draw() code, check whether the engine already covers it —
ParticleEmitter, Tween, the ShaderEffect presets, the UI widgets
(UITextButton, UISpriteElement, UIPanel, ProgressBar and the rest, see
melonjs-ui-and-text), NineSliceSprite, the physics adapters, and the Tiled
tilemap renderers all exist.
Hand-rolled equivalents miss the batching and the multi-backend support.
melonjs-scenes-and-state — Tween and the easing families, for animating any of this
melonjs-getting-started — Application lifecycle and the scene graph
melonjs-ui-and-text — the UI widgets, before drawing your own
melonjs-20-migration — the deprecated shader property and other pre-20 APIs
Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the p
---name: melonjs-renderablesdescription: Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events…---# packages/melonjs/skills/melonjs-renderables/SKILL.mdVisão geral
Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, z-ordering, y-sorting with sortOn and sortOffset, and Container clipping. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, sortOn, sortOffset, autoSort, clipping, clipContains, anchorPoint, floating.
Perguntas frequentes
Baixe packages/melonjs/skills/melonjs-renderables/SKILL.md do publicador ou copie o caminho e abra o repositório. O PlugMCP lista a skill e não hospeda o arquivo.
O publicador o mantém em https://github.com/melonjs/melonJS.
Claude, Cursor, Codex e Grok Build conseguem ler um SKILL.md que você adiciona a partir do repositório do publicador. O Grok Bot o instala quando você envia em um chat o link da pasta da skill no GitHub.
| before 20.13 the pointer ignored the clip: update |