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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-performance技能说明
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
TextureAtlasand prefer one large tileset over several small ones, so a screenful of sprites fits inside the pool with room to spare. - Changing
blendMode—setBlendModeflushes 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
ShaderEffecton 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:
-
onResetEventmust 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
onDestroyEventon removal. Removal always callsonDeactivateEvent, then tries to return the object to the pool that built it; only when nothing owns it does it fall through todestroy(), which is what callsonDestroyEvent. So a successfully recycled object never sees it. Pair event subscriptions withonActivateEvent/onDeactivateEventinstead, or you leak handlers. -
removeChildis 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 throwsChild 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)withkeepalivetrue 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