跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add melonjs/melonJS --skill melonjs-renderables

技能说明


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
  1. 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.)
  2. Setting 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.
  3. Setting 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.)

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 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.
  • 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)

阅读完整来源 ↗