Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

melonjs-performance

Use this skill when a melonJS game drops frames, allocates heavily, or needs to scale to many objects. Covers object pooling, draw-call batching, atlases, baking with CanvasRenderTarget, instancing, culling and alwaysUpdate, the debug plugin, and where the real costs are. Triggers on: performance, slow, frame rate, fps, lag, pool, pool.register, pool.pull, batching, draw calls, InstancedMesh, culling, alwaysUpdate, inViewport, CanvasRenderTarget, optimise, profiling, debug plugin, memory, render targets, hdr.

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-performance

About this skill


name: melonjs-performance description: "Use this skill when a melonJS game drops frames, allocates heavily, or needs to scale to many objects. Covers object pooling, draw-call batching, atlases, baking with CanvasRenderTarget, instancing, culling and alwaysUpdate, the debug plugin, and where the real costs are. Triggers on: performance, slow, frame rate, fps, lag, pool, pool.register, pool.pull, batching, draw calls, InstancedMesh, culling, alwaysUpdate, inViewport, CanvasRenderTarget, optimise, profiling, debug plugin, memory, render targets, hdr." license: MIT

Performance

Measure first

Register the debug plugin and read the numbers before changing anything:

import { plugin } from "melonjs";
import { DebugPanelPlugin } from "@melonjs/debug-plugin";

await app.init();
plugin.register(DebugPanelPlugin, "debugPanel");

It reports frame time, draw calls, object counts, and can overlay collision shapes and bounds. Draw calls is usually the number that matters.

Batching: the biggest lever

Both GPU backends batch across textures, not just within one: the quad batcher assigns each source image a texture unit and embeds the unit in the vertex data, so several different images still flush as a single draw. The pool is finite — the WebGL batcher gets renderer.maxTextures units (the maxTextures application setting, "auto" = the device limit capped at 32), the WebGPU batcher eight per segment. Overflow the pool and the batch flushes.

So the goal is not "one image" but "few state changes". What actually ends a batch:

  • Overflowing the texture-unit pool — pack sprites into a TextureAtlas and prefer one large tileset over several small ones, so a screenful of sprites fits inside the pool with room to spare.
  • Changing blendMode — setBlendMode flushes before it touches GL state. Group by blend mode where you can.
  • Switching batcher — interleaving primitives (strokeRect, fillRect, debug shapes) or meshes between sprites flushes the quad batcher and rebinds. Draw all the sprites, then all the primitives.
  • Binding a custom shader — a ShaderEffect on the quad batcher also turns multi-texture batching off for the duration, dropping you back to one texture per draw.

The advanced blend modes are the expensive ones: overlay, difference, hard-light, soft-light, color-dodge, color-burn, darken and lighten cannot be expressed as fixed-function blending, so each such draw is bracketed on its own — capture the destination, redraw offscreen, composite through a shader. Right for accents, wrong for hundreds of objects. normal, additive, multiply, screen and exclusion are plain fixed-function state and cost nothing extra.

Pooling

Anything spawned frequently — bullets, particles, pickups, damage numbers — should be pooled rather than allocated:

import { createPool } from "melonjs";

const bulletPool = createPool((x, y) => {
    const instance = new Bullet(x, y);
    return { instance, reset: (x, y) => instance.onResetEvent(x, y) };
});

const b = bulletPool.get(x, y);   // recycled: reset(x, y)
                                  // fresh:    new Bullet(x, y)
world.removeChild(b);             // returns to bulletPool automatically

The container returns a child to whichever pool built it, so removal is enough; you only call release() yourself for something that was never added to the world.

me.pool is the older, string-keyed version and is deprecated since 18.0.0. pool.register(name, Class, true) / pool.pull(name) still work and print a one-off console notice, but a recycled object is no longer returned on removal, so pooling through it now costs an allocation per spawn. To register a class so a Tiled map can name it, use registerTiledObjectClass — that is a separate registry and is not deprecated.

Two rules that cause subtle bugs when missed:

  • onResetEvent must restore everything the object's lifetime mutates — alpha, tint, scale, animation, velocity. Anything you forget carries into the next use, which looks like a random visual glitch.

  • Pooled objects do not fire onDestroyEvent on removal. Removal always calls onDeactivateEvent, then tries to return the object to the pool that built it; only when nothing owns it does it fall through to destroy(), which is what calls onDestroyEvent. So a successfully recycled object never sees it. Pair event subscriptions with onActivateEvent / onDeactivateEvent instead, or you leak handlers.

  • removeChild is DEFERRED, which breaks a pool you re-lend in the same frame. The removal is queued and runs after the update and draw stack has unwound, so an object you remove and immediately hand out again is torn out from under its new owner when the queue drains: it vanishes, and the frame after that the removal throws Child is not mine. Take it out immediately instead, keeping the instance alive for reuse:

    world.removeChildNow(bullet, true);   // keepalive: do NOT destroy it
    this.freeList.push(bullet);
    

    removeChildNow(child, keepalive) with keepalive true skips the destroy, which is what you want for anything you own the lifetime of. This is the usual cause of a pooled effect that flickers out one frame after it is recycled.

The engine's own classes are NOT in this pool. They were registered in it once, which bought nothing: most had recycling off, so pool.pull("Sprite") was a plain construction behind a string key. The ones worth recycling have typed pools instead, reached by key and fully typed:

const tween = getPool("tween").get(target);
const label = getPool("text").get(x, y, { font: "Arial", size: 12 });
getPool("text").release(label);          // yours to release, as with particles

A recycled label comes back with its base-class state reset as well as its own: floating, blendMode, alpha, tint, the transform, the anchor

Read the complete source ↗