melonjs-camera-and-drawing
Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels.
melonjs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-camera-and-drawing技能说明
name: melonjs-camera-and-drawing description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, shake, fadeIn, fadeOut, worldToLocal, localToWorld, colorMatrix, renderer.fill, renderer.stroke, Rect, Ellipse, Polygon, Line, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels." license: MIT
Camera and immediate-mode drawing
Following a target
app.viewport.follow(player, app.viewport.AXIS.BOTH, 0.1);
Pass the renderable, not renderable.pos. follow() accepts a Renderable,
a Vector2d or a Vector3d and throws invalid target for me.Camera2d.follow
for anything else. A renderable's pos is an ObservableVector3d, which is not
a Vector3d subclass, so follow(player.pos, …) throws.
The third argument is a damping factor in [0 .. 1] — lower is smoother and
laggier, 1 snaps. Omit it for a hard lock (it defaults to 1). It is
frame-rate independent since 19.7. AXIS.HORIZONTAL / AXIS.VERTICAL /
AXIS.BOTH / AXIS.NONE.
Call it from the followed entity's onActivateEvent, using this.parentApp.
To frame the target off centre, set offset; do not follow a helper
object. It shifts the view without moving the camera, in world units, and is
applied after following and the bounds, so the view can show past them:
app.viewport.follow(player, app.viewport.AXIS.BOTH, 0.1);
app.viewport.offset.set(0, -70); // look a little above the feet
// or ahead of where the player faces, eased (see math.damp below)
const ahead = facingLeft ? -80 : 80;
app.viewport.offset.x = math.damp(app.viewport.offset.x, ahead, 4, dt / 1000);
Culling, tile layers, parallax ImageLayers, lights and the pointer
(localToWorld, worldToLocal) all count it. shake() adds its jitter on top
and gives the value back when it ends, so setting it before or during a shake
is fine. reset() clears it.
For anything that is NOT the camera, the same smoothing is math.damp.
follow() is frame-rate independent for you; a value you smooth yourself is
not, and lerp(current, target, alpha) once per frame moves further on a slow
frame than on a fast one, so the feel changes with the frame rate:
import { math } from "melonjs";
// dt is milliseconds, damp wants seconds
this.speed = math.damp(this.speed, targetSpeed, 5, dt / 1000);
this.turret.angle = math.damp(this.turret.angle, wanted, 8, dt / 1000);
damp(current, target, lambda, dt). Higher lambda converges faster; it is
the rate, not a per-frame fraction.
For a DIRECTION rather than a scalar, the tool is slerp, on Vector2d
and Vector3d alike. Two reasons, and the second is the one that bites:
// a turret, a ship, a camera: a facing that chases another facing
facing.slerp(toTarget, 1 - Math.exp((-6 * dt) / 1000));
- Damping a facing component by component drags it through the inside of the circle, so it slows at the ends, rushes the middle and comes out shorter than it went in.
- Damping a scalar heading goes the wrong way round the wrap. From 170
degrees to -170 degrees is 20 degrees apart, and the numbers are 340 apart,
so the turret sweeps all the way round the back.
slerpworks on the directions, takes the shorter arc by construction, and has no wrap to cross.
See melonjs-3d for the rest, including what happens between two exactly
opposite directions. Use it for camera pans you drive yourself,
turret tracking, zoom, input smoothing and any value that should chase another
one — it is the tool that is easy to miss and easy to hand-write slightly
wrong.
Bounds are the thing people forget
The camera's bounds default to the renderer size, so it cannot scroll until you widen them to the world:
app.viewport.setBounds(0, 0, mapWidth, mapHeight);
Symptom: follow() is called, looks right, and the view never moves. Note a
canvas resize resets the default camera's bounds to (0, 0, w, h), so re-apply
them from a CANVAS_ONRESIZE handler if your game resizes. Loading a Tiled map
sets them for you from the map size.
Camera effects
app.viewport.shake(4, 200); // intensity, ms
app.viewport.fadeIn("#000000", 500); // fade TO black
app.viewport.fadeOut("#000000", 500); // start black, fade back to normal
app.viewport.colorMatrix.contrast(1.1).saturate(1.1);
app.viewport.addPostEffect(new VignetteEffect(app.renderer));
The fade pair is named from the colour's point of view, not the scene's:
fadeIn fades the colour in (screen goes to color), fadeOut fades it out
(screen starts at color and clears). Both default to a 1000 ms duration and
take an optional completion callback.
fadeIn does not HOLD the colour. The effect completes, the camera's own
update destroys it, and the screen snaps back — which is why the engine's
idiom does the work in the completion callback and then calls fadeOut. To
keep a filled screen across a state change, own the effect: a completed one
marked isPersistent is left alone, and taking it away again is yours to do.
const hide = camera.addCameraEffect(
new FadeEffect(camera, { color: "#000", duration: 400, direction: "in" }),
);
hide.isPersistent = true; // survives completion AND Camera2d#reset()
// ... later, once the new stage is up
camera.removeCameraEffect(hide); // which destroys it for you
That is exactly what state.transition() is bui