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

melonjs-display-and-scaling

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.

melonjs · 已有静态检查记录

安装与使用

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

npx skills add melonjs/melonJS --skill melonjs-display-and-scaling

技能说明


name: melonjs-display-and-scaling description: "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." license: MIT

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.

The four jobs

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.

jobsettingwhat it decides
how big the frame is drawnwidth/height on Applicationthe design resolution everything is authored against
how it uses the spacescale, scaleMethod, scaleTargetfit, fill, stretch, and what it measures to decide
may the factor be fractionalscaleRoundingwhole device pixels per source pixel, or any factor
how a texture is sampledantiAlias, textureFilternearest or linear, and the CSS upscale filter

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.

Design resolution

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 scaleMethod

scale: "auto" turns on automatic scaling; a number is a fixed multiplier and scaleMethod is then 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" does nothing automatic.

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 measured

Automatic 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 pixels

new 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.

What it costs

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:

containerratiofitintegerpresentedarea lost
1920x10801 or 24.0004 / 81920x1080none
1440x81013.00031440x810none
960x54012.0002960x540none
1280x72022.66751200x67512%
2560x144025.333102400x135012%
1280x72012.6672960x54044%
1366x76812.8442960x54051%

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

阅读完整来源 ↗