- name
SKILL.md
技能文件保留在发布者的仓库中。
在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add melonjs/melonJS --skill melonjs-display-and-scaling -a cursor -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add melonjs/melonJS --skill melonjs-display-and-scaling -a claude-code -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add melonjs/melonJS --skill melonjs-display-and-scaling -a codex -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add melonjs/melonJS --skill melonjs-display-and-scaling -a grok -y在 Grok Bot 聊天中发送复制的消息。Bot 会从 GitHub 获取这个 SKILL.md,并添加到你所有 Bot 共享的技能中。
Install this skill: https://github.com/melonjs/melonJS/tree/HEAD/packages/melonjs/skills/melonjs-display-and-scaling来自发布者
Seven settings decide how a game looks on screen, and they are easy to get individually right and collectively wrong. This is what each one actually does, and which one to reach for.
A pixel travels from your source art to a physical pixel through four separate decisions. Knowing which setting owns which is most of the work.
subPixel is a fifth, orthogonal to all of them: it decides whether a
renderable may sit on a fractional position WITHIN the frame. syncToDisplay
is about the frames in a row rather than one frame: whether motion advances
by the same amount on each.
const app = new Application(480, 270, { scale: "auto" });
The game is drawn at 480x270 whatever the window is, and the canvas is scaled to the container. Everything in world coordinates is in those units. This is the usual arrangement: author once, scale to whatever you are given.
scale and scaleMethodscale: "auto" turns on automatic scaling, and so does naming any
scaleMethod other than "manual", even with no scale given:
{ scaleMethod: "flex" } alone scales to its container. A number is a fixed
multiplier, used only while scaleMethod is "manual" (the default); with
automatic scaling on, the number is ignored.
scaleMethod decides how the available space is used:
"fit" keeps the design resolution and the aspect ratio, scaling to the
largest factor that fits. Leftover space becomes margin. This is the one to
use when the game is authored for a fixed frame."fill-min" / "fill-max" keep the aspect ratio but RESIZE the
renderer, so the design resolution changes with the window and the game sees
more or less of the world."flex", "flex-width", "flex-height" resize the renderer on one or
both axes."stretch" scales each axis independently, so the aspect ratio is not
preserved and circles become ovals."manual", the default, does nothing automatic with a numeric scale.
With scale: "auto" it scales as "fit" does.The distinction that matters: fit scales a fixed frame; everything else
changes how much of the world is visible. A game whose layout assumes a
known frame wants fit.
scaleTarget: what gets measuredAutomatic scaling measures the parent of the element the canvas is mounted in, not the element itself. If that grandparent is not the box you meant, the canvas is sized wrongly, and the failure is quiet.
The case that bites: a canvas container that is position: fixed or
absolute contributes no height to its parent, so the parent measures only
whatever else is in it. If that parent is <body>, the engine falls back to
the window size and the canvas ends up larger than the box it lives in,
cropped by whatever sits above it.
new Application(1024, 576, {
parent: "screen",
scale: "auto",
// measure THIS, rather than guessing from the DOM shape
scaleTarget: document.getElementById("stage"),
});
Either name the element with scaleTarget, or give the canvas container a
parent whose box is the area you want filled. If the canvas is cropped or
overflows on resize, this is the first thing to check.
scaleRounding: whole device pixelsnew Application(480, 270, {
scale: "auto",
scaleMethod: "fit",
scaleRounding: "integer", // default "fractional"
});
"fractional" fills the container exactly, at whatever factor that takes. A
480 wide design in a 1280 wide container is scaled by 2.667, so some source
pixels cover three screen pixels and some cover two. Pixel art shows this as
uneven glyph stems and shimmering edges, and browsers resolve the unevenness
differently, so the same scene can look crisp in one and soft in another.
"integer" rounds the factor DOWN so every source pixel covers the same whole
number of device pixels, and letterboxes with the space left over. That trade,
crisp pixels for black bars, is the whole decision.
More than "some letterboxing", and the size of it is decided by
devicePixelRatio as much as by the window. A higher ratio has more device
pixels to round among, so it lands closer to the factor it wanted. For a
480x270 design, which is exactly a quarter of 1920x1080:
So the decision is mostly made when the design resolution is chosen, not when this setting is. One that divides the sizes you expect costs nothing; one that does not can give up half the screen on a 1x display, and 1366x768 laptops are not rare. A game that must fill the window on any machine should stay fractional and accept the uneven pixels.
Two things to know:
scaleMethod: "fit" only. Every other method resizes the
renderer to the container, so the design resolution moves and there is no
fixed factor to round.devicePixelRatio multiplies the
CSS size on the way to real pixels, so rounding the CSS factor would let the
fraction straight back in: a factor of 2 at a ratio of 1.25 is 2.5 device
pixels per source pixel.antiAlias does three thingsThis is the setting most likely to surprise, because it is not one switch:
textureFilter is "auto" (the
default), which TRACKS it: linear when on, nearest when off. Setting
textureFilter explicitly decouples the twoimageSmoothingEnabled on the 2D contextimage-rendering: pixelated when off, auto when onSo antiAlias: false gives hard-edged textures AND a hard-edged upscale of
the whole frame. That is usually what a pixel-art game wants, and usually NOT
what a smooth 3D scene wants, because it also disables MSAA.
textureFilter: "nearest" | "linear" separates the texture half, so a scene
can have smooth model edges and nearest-sampled sprites. The presentation half
is not separable: there is no way to get MSAA silhouettes and a hard-edged
upscale at the same time.
textureFilter: "linear-mipmap"A sprite drawn much smaller than its texture (a zoomed-out camera, a minimap,
a scaled-down sprite) shimmers as it moves, even with linear sampling: each
screen pixel covers many texels and linear sampling blends only four of them.
"linear-mipmap" samples the texture's mipmaps, smaller copies averaged in
advance, wherever something is drawn below its size:
const app = new Application(1280, 720, { textureFilter: "linear-mipmap" });
At its size or larger a texture draws as it does under "linear", so a game
whose main view is at its size and whose minimap is zoomed out gets a smooth
minimap and an unchanged view. It covers sprites, text and tile layers, not a
video nor a texture the engine renders into, and a nearest texture keeps to
its full size. GPU backends only; on WebGPU each texture it applies to takes
about a third more memory.
A small mipmap level's texels span many of the art's pixels, so a sample near
the edge of a frame would reach into the next frame of the atlas. Under
"linear-mipmap" every sprite and tile keeps its samples half a texel of the
level it reads inside its own frame, so the next frame no longer streaks along
its edges. Two limits:
ShaderEffect samples the texture in the effect's
own program, which is not kept to the frame.A repeating pattern is left to wrap.
subPixel is about position, not scalesubPixel: false (the default) draws everything on whole pixels. The snap
happens once, where a draw lands, the same on every renderer: each edge of
a sprite, a shape or a clip is rounded to the nearest pixel after every
translation and scale it is drawn under. So:
fillRect at the same position cover the same pixels, and a
shape has no half-grey edge on the Canvas renderer;223.99999999999997 after a collision
push-out, draws on that pixel (224), so it does not shake every other frame.The camera's view starts on a whole pixel too, in world units (zoomed 2x, it
moves in 2 px steps), and culling and the pointer use that same position:
things standing still stay still against each other while the view scrolls,
and a click lands on what is drawn under it. A rotated draw, and anything a
Camera3d draws, is left where it is.
It does nothing about how the frame reaches the screen. A game that carefully
snaps positions and is then scaled by 2.667 has thrown that work away at the
last step, which is the contradiction scaleRounding: "integer" exists to
resolve.
subPixel: true alone does not make motion smooth: with nearest sampling a
sprite between two pixels is still drawn on one of them, so a scene moving
4.5 pixels a frame jumps by 4 and 5 in turn. Rendered art (not pixel art)
moves smoothly with textureFilter: "linear" as well, which blends it across
the two, while the upscale stays crisp (antiAlias: true would also smooth the
whole canvas as it is scaled up, which is what makes it look blurry). A still
scene is only sharp when the camera rests on a whole pixel, so give it a
target on whole pixels:
const app = new Application(1280, 720, {
scale: "auto",
subPixel: true,
textureFilter: "linear",
syncToDisplay: true,
});
// the camera follows a point on whole pixels, kept on the hero: it glides
// between pixels while following, and comes to rest on one
const focus = new Vector2d();
app.viewport.follow(focus, app.viewport.AXIS.BOTH, 0.12);
// in the hero's update(dt)
focus.set(Math.round(this.pos.x), Math.round(this.pos.y));
syncToDisplay is about steady motionThe game updates in fixed steps, 60 a second by default, as many as the time since the last frame holds. Browsers report that time with up to a millisecond of jitter, so on a 60 Hz display a frame now and then gets no update and the next one gets two: the world holds still for a frame, then moves twice as far. Scrolling, and anything else moving steadily, stutters while the frame rate reads a solid 60.
const app = new Application(1280, 720, { scale: "auto", syncToDisplay: true });
With it on, frame times are counted in whole display frames and what is
rounded off is carried to the next frame: one update every frame at 60 Hz, one
every other frame at 120 Hz, and the game keeps its speed. A display within 2%
of timer.maxfps (60 by default), or of 2, 3 or 4 times it, or a half, a third
or a quarter of it, is counted at exactly that rate, so a 59.94 Hz screen runs
the game 0.1% slower than the wall clock; leave it off when the updates must
keep to the wall clock exactly. The display's rate is learned as the game runs,
and again when it changes (the window moved to another screen). At a refresh
that is no multiple of the update rate (144 Hz, 165 Hz) the steps cannot fall
evenly however the time is counted.
It is off by default. It sets timer.syncToDisplay when the application is
initialized, which a game can also switch at any time.
If everything is crisp EXCEPT the text, the scale factor is not the cause: a fractional factor softens the whole frame equally. The text is different because of how it is made.
Text draws through the browser's fillText, which anti-aliases glyph edges
into partial-alpha pixels. Measured on one label at 16px: 171 distinct
partial alpha levels. Nothing in the canvas API turns that off. antiAlias
and the imageSmoothingEnabled that CanvasRenderTarget sets govern IMAGE
drawing, not glyph rasterisation.
So the label arrives already soft, and the upscale then magnifies each grey edge pixel into a grey block, sitting beside sprites that were hard-edged to begin with and stay hard-edged under nearest sampling.
It also explains the same scene looking crisp in one browser and soft in another at identical size and settings: engines use different font rasterisers, with different hinting and anti-aliasing, so they bake DIFFERENT textures from the same font at the same size.
Use BitmapText for a game that upscales. A pixel-font atlas is
hard-edged source art like every other texture, so it survives magnification
the way the sprites do. Raising the design resolution only shrinks the
magnification of anti-aliasing that is still there, so it softens the symptom
rather than removing it, and scaleRounding does nothing for this at all.
Keep Text where the frame is not upscaled much, or where the label is meant
to look smooth.
Swapping in a bitmap face means generating one, and three things decide whether it comes out looking like the original:
size on
BitmapText is a ratio of the authored size, and a bitmap face has the sizes
it was baked at. Doubling a smaller atlas halves the detail; a ratio below 1
drops whole stems; a fractional ratio resamples hard pixels unevenly. One
atlas per step of the type scale.Two traps in the generator itself:
textBaseline origin is clipped by a tight
cell, and the symptom is an outline that goes missing along one edge of some
glyphs. Pad the cell by a fraction of the size, and assert that no glyph's
ink reaches its border.const app = new Application(480, 270, {
scale: "auto",
scaleMethod: "fit",
scaleRounding: "integer", // whole device pixels, letterbox the rest
antiAlias: false, // nearest textures, hard-edged upscale
// subPixel: false is already the default
});
const app = new Application(1024, 576, {
scale: "auto",
scaleMethod: "fit",
antiAlias: true, // MSAA and a filtered upscale
textureFilter: "nearest", // but keep blocky textures if the art is blocky
});
Use this skill when a melonJS game looks blurry, soft, shimmering or cropped, or when choosing how the canvas fills its page. Covers the design resolution, scale and scaleMethod, scaleTarget, scaleRou
---name: melonjs-display-and-scalingdescription: Use this skill when a melonJS game looks blurry, soft, shimmering or cropped, or when choosing how the canvas…---# packages/melonjs/skills/melonjs-display-and-scaling/SKILL.md概览
Use this skill when a melonJS game looks blurry, soft, shimmering or cropped, or when choosing how the canvas fills its page. Covers the design resolution, scale and scaleMethod, scaleTarget, scaleRounding for pixel-perfect integer scaling, antiAlias, textureFilter and linear-mipmap for what is drawn small, subPixel, syncToDisplay for steady motion, devicePixelRatio, and which setting does which job. Triggers on: blurry, soft, fuzzy, shimmering, pixel art, pixel perfect, crisp, nearest, linear, scale, scaleMethod, scaleTarget, scaleRounding, integer scaling, antiAlias, textureFilter, linear-mipmap, mipmaps, minimap shimmer, zoomed out, subPixel, syncToDisplay, stutter, judder, uneven scrolling, devicePixelRatio, retina, hidpi, design resolution, canvas size, canvas cropped, letterbox, image-rendering, upscale, resolution.
常见问题
从发布者处下载 packages/melonjs/skills/melonjs-display-and-scaling/SKILL.md,或复制路径后打开仓库。PlugMCP 只收录该技能,不托管文件。
发布者将它存放在 https://github.com/melonjs/melonJS。
Claude、Cursor、Codex 和 Grok Build 可以读取你从发布者仓库添加的 SKILL.md。在聊天中发送技能的 GitHub 文件夹链接,Grok Bot 就会安装它。
it applies to scaleMethod: "fit" only; the others resize the renderer |
| text is soft but sprites are crisp | the glyphs were anti-aliased when Text baked them; use BitmapText (see below) |
| the game shows more world on a bigger window | that is fill-* or flex-* doing their job; use "fit" to keep a fixed frame |
a numeric scale (say 2) is ignored | a scaleMethod other than "manual" turns automatic scaling on, which ignores the number |