melonjs-renderables
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, and z-ordering. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating.
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-renderablesAbout this skill
name: melonjs-renderables description: "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, and z-ordering. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating." license: MIT
Renderables, input and effects
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.
1. A custom draw() must position itself from this.pos
The 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
}
2. isKinematic must be false to receive input or collisions
Renderable.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 the Body constructor on its
owner (which covers Entity and anything you give a body to) — so a plain
Renderable or Sprite subclass with no body is the case that catches people.
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. The builtin
narrowphase likewise requires both partners to be non-kinematic.
3. Draw order: only addChild(child, z) works
There are three separate traps here and they compound.
world.addChild(sprite, 10); // ✓ the only reliable form
renderable.zdoes not exist. There is nozaccessor anywhere onRenderable(nor onRect/Polygonabove it) — onlydepth, which proxiespos.z, and the container's defaultsortOn: "z"comparator readspos.z. Writingsprite.z = 100creates an inert property that nothing reads. Several shipped examples still containthis.z = Number.POSITIVE_INFINITY; those HUDs draw on top only because they happen to be added last. (Azkey in aSprite/ImageLayersettings object is a different thing and is real — it assignspos.zin the constructor — but trap 2 then overwrites it.)- Setting
depthbeforeaddChildis overwritten. WithautoDepthon (the default),addChildwithout an explicitzassignschild.pos.z = children.lengthafter the push, discarding whatever you set. - Setting
depthafteraddChilddoes not reorder. A"z"sort runs when a child is added (autoSort, deferred to the next tick), not whenpos.zchanges. If you must change it later, callcontainer.sort()yourself, or usemoveToTop/moveUp/moveDown/moveToBottom, which reorder the children themselves. (An"x"/"y"sort is different: see below.)
Sorting on "y" (or "x"), and sortOffset
A 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.
- Moving a child re-sorts by itself. With
autoSorton (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 nosort()call. A frame where nothing moved costs one pass over the children and does not cause a redraw. TurnautoSortoff to keep the children in the order you put them. - Ties keep insertion order, and the child added LAST is drawn BEHIND. A torch placed at its wall's exact position disappears behind the wall.
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)