@@ -1,7 +1,7 @@
 {
 	"name": "melonjs",
 	"version": "20.9.0",
-	"description": "Build games with melonJS — 23 guides to the 2D, 2.5D and 3D HTML5 game engine, its conventions and idioms, so generated code runs the first time.",
+	"description": "Build games with melonJS — 24 guides to the 2D, 2.5D and 3D HTML5 game engine, its conventions and idioms, so generated code runs the first time.",
 	"author": {
 		"name": "melonJS",
 		"url": "https://melonjs.org"
@@ -32,6 +32,7 @@
 		"./packages/melonjs/skills/melonjs-deployment",
 		"./packages/melonjs/skills/melonjs-loading-assets",
 		"./packages/melonjs/skills/melonjs-renderer-backends",
+		"./packages/melonjs/skills/melonjs-display-and-scaling",
 		"./packages/melonjs/skills/melonjs-performance",
 		"./packages/melonjs/skills/melonjs-events",
 		"./packages/melonjs/skills/melonjs-plugins"
 
@@ -3,6 +3,7 @@
 ## [20.9.0] (melonJS 2) - _unreleased_
 
 ### Added
+- **`scaleRounding`**: `"integer"` constrains the automatic scale factor to a whole number of device pixels per source pixel, letterboxing whatever is left over, where the default `"fractional"` fills the container exactly. A 480 wide design in a 1280 wide container is scaled by 2.667, so some source pixels cover three device pixels and some cover two, which pixel art shows as uneven stems and shimmering edges and which browsers resolve differently, so the same scene looks crisp in one and soft in another. The rounding is applied in DEVICE pixels, since `devicePixelRatio` would otherwise put the fraction back. It affects `scaleMethod: "fit"` only, because every other method resizes the renderer to its container and so has no fixed factor to round
 - **Sprite-sheet particles** (`framewidth`, `frameheight`, `frames`, `randomFrame` on `ParticleEmitter`): a particle plays a frame sequence once over its own lifetime, or holds one frame picked at random when it is born. One sheet is one image, so a burst of varied debris still batches into a single draw call ([#1610](https://github.com/melonjs/melonJS/issues/1610), thanks @snowyukitty)
 - **`slerp(v, alpha)` on all four vector classes**: interpolate along the ARC between two directions at a constant angular rate, where `lerp` slows at the ends and shortens the vector through the middle. 2D takes the shorter way round, and the same and opposite cases are handled rather than returning `NaN`
 - **`Trail3d`**: a fading, tapering ribbon that recedes properly into a 3D scene, for an exhaust streak, a speed trail or a spell arc. It is a `Mesh`, so unlike the 2D `Trail` it narrows along its own length, takes a post effect and a `tint`, and costs one indexed draw call rather than a filled path per segment. It needs a `Camera3d` ([#1621](https://github.com/melonjs/melonJS/issues/1621))
 
@@ -11,7 +11,7 @@
 > Gemini CLI and anything else following the `AGENTS.md` convention will read it
 > from your project root. Claude Code users should install the plugin instead —
 > `/plugin marketplace add melonjs/melonJS` — which registers the same guidance
-> as 24 routed skills.
+> as 25 routed skills.
 
 This project uses **melonJS 20.x**, an open-source HTML5 game engine covering
 2D, 2.5D and 3D, running on WebGPU, WebGL 2 or Canvas with automatic fallback.
 
@@ -0,0 +1,273 @@
+---
+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, subPixel, 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, subPixel, 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.
+
+| job | setting | what it decides |
+|---|---|---|
+| how big the frame is drawn | `width`/`height` on `Application` | the design resolution everything is authored against |
+| how it uses the space | `scale`, `scaleMethod`, `scaleTarget` | fit, fill, stretch, and what it measures to decide |
+| may the factor be fractional | `scaleRounding` | whole device pixels per source pixel, or any factor |
+| how a texture is sampled | `antiAlias`, `textureFilter` | nearest 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.
+
+## Design resolution
+
+```js
+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.
+
+```js
+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
+
+```js
+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:
+
+| container | ratio | fit | integer | presented | area lost |
+|---|---|---|---|---|---|
+| 1920x1080 | 1 or 2 | 4.000 | 4 / 8 | 1920x1080 | none |
+| 1440x810 | 1 | 3.000 | 3 | 1440x810 | none |
+| 960x540 | 1 | 2.000 | 2 | 960x540 | none |
+| 1280x720 | 2 | 2.667 | 5 | 1200x675 | 12% |
+| 2560x1440 | 2 | 5.333 | 10 | 2400x1350 | 12% |
+| 1280x720 | 1 | 2.667 | 2 | 960x540 | **44%** |
+| 1366x768 | 1 | 2.844 | 2 | 960x540 | **51%** |
+
+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:
+
+- It applies to **`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.
+- The rounding happens in **device** pixels. `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 things
+
+This is the setting most likely to surprise, because it is not one switch:
+
+1. the texture filter, but only while `textureFilter` is `"auto"` (the
+   default), which TRACKS it: linear when on, nearest when off. Setting
+   `textureFilter` explicitly decouples the two
+2. `imageSmoothingEnabled` on the 2D context
+3. the canvas CSS `image-rendering`: `pixelated` when off, `auto` when on
+
+So `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.
+
+## `subPixel` is about position, not scale
+
+`subPixel: false` (the default) truncates a renderable's translation to whole
+pixels inside the frame. It is `|0`, so it truncates **toward zero** rather
+than rounding, which is worth knowing when something travels a short distance:
+an offset that should swing between -3 and +3 lands on -2 and +2, and parks at
+the extremes for longer than it should.
+
+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.
+
+## Soft text next to crisp sprites
+
+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.
+
+### Baking an atlas from a face you already use
+
+Swapping in a bitmap face means generating one, and three things decide
+whether it comes out looking like the original:
+
+- **Threshold the coverage.** Hard edges are the whole point, so every pixel
+  has to end up fully on or fully off. Hardening only the ALPHA is not enough:
+  an outlined glyph keeps a soft stroke-to-fill blend INSIDE the silhouette,
+  which still reads as blur once magnified. Pick the colours from a mask.
+- **Bake each size at that size, and draw it at a ratio of 1.** `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.
+- **Grow the outline outward, but carve it INWARD around a counter.** This is
+  the one that costs the most time. A stroke drawn by the canvas is centred on
+  the contour, so around an enclosed hole it eats into the letter and the hole
+  keeps its size. Dilating a mask outward instead grows black INTO the hole
+  from every side, which closes anything under about 3px: the letter loses its
+  counter and reads as a blob. Take the rim from the fill side and the hole
+  survives at every size. Neither leaving holes unrimmed nor closing the small
+  ones is a substitute — both were tried and both look wrong.
+
+Two traps in the generator itself:
+
+- A face whose glyphs overshoot the `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.
+- The threshold decides the TOPOLOGY, not just the weight. A notch or a narrow
+  gap in a letterform closes over at a full threshold and becomes an isolated
+  hole, which then bakes as a black blob sitting on the glyph. Thinner, the
+  same feature stays joined to the background and reads as the face intends.
+  So a small size may want a thinner fill than a large one, and the way to see
+  it is to magnify one glyph, not a whole line.
+
+## A pixel-art setup
+
+```js
+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
+});
+```
+
+## A smooth 3D setup
+
+```js
+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
+});
+```
+
+## Symptoms
+
+| symptom | cause |
+|---|---|
+| pixel art is blurry or shimmers | the frame is upscaled by a fractional factor; set `scaleRounding: "integer"` |
+| crisp in one browser, soft in another | the same fractional factor, which engines distribute differently under `pixelated` |
+| the canvas is cropped or overflows its box | automatic scaling measured the wrong element; name it with `scaleTarget` |
+| the canvas grows on every resize | the measured ancestor is auto-sized around the canvas itself |
+| things shimmer as they move | fractional positions; check `subPixel`, and that the scale factor is whole |
+| 3D model edges are jagged | `antiAlias: false` also disables MSAA; turn it on and use `textureFilter` for textures |
+| textures are smoothed when they should be blocky | `antiAlias: true` makes the default texture filter linear; set `textureFilter: "nearest"` |
+| `scaleRounding: "integer"` changes nothing | 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 |
@@ -49,6 +49,7 @@ dependencies.
 | [melonjs-deployment](../melonjs-deployment/SKILL.md) | Scaffolding a project, building, browser support and transpiling, native and mini-game platforms. |
 | [melonjs-loading-assets](../melonjs-loading-assets/SKILL.md) | Resource descriptors, the asset type list, base URLs, cross-origin, progress events, unloading. |
 | [melonjs-renderer-backends](../melonjs-renderer-backends/SKILL.md) | A feature works on one machine but not another; choosing or pinning a backend; degrading gracefully. |
+| [melonjs-display-and-scaling](../melonjs-display-and-scaling/SKILL.md) | Blurry, soft or cropped output; the design resolution, how the canvas fills its page, and pixel-perfect integer scaling. |
 | [melonjs-events](../melonjs-events/SKILL.md) | The event bus, per-frame and lifecycle events, and subscribing without leaking. |
 | [melonjs-performance](../melonjs-performance/SKILL.md) | Dropped frames, draw-call counts, pooling, batching, culling, baking, profiling. |
 | [melonjs-plugins](../melonjs-plugins/SKILL.md) | Registering the debug, Spine or Tiled-inflate plugins, physics adapters, or writing your own plugin. |
 
@@ -24,6 +24,7 @@ export const defaultApplicationSettings = {
 	gpuTilemap: true,
 	failIfMajorPerformanceCaveat: true,
 	highPrecisionShader: true,
+	scaleRounding: "fractional",
 	subPixel: false,
 	verbose: false,
 	backgroundColor: "#000000",
 
@@ -33,6 +33,34 @@ function scale(game: Application, x: number, y: number): void {
 	game.repaint();
 }
 
+/**
+ * The largest scale at or below `scale` that covers each source pixel with a
+ * WHOLE number of device pixels.
+ *
+ * Rounded down, and rounded in DEVICE pixels rather than CSS ones. That
+ * distinction is the whole of it: the canvas is given a CSS size and the
+ * browser multiplies by `devicePixelRatio` on the way to real pixels, so
+ * flooring the CSS factor lets the fraction come straight back. A factor of
+ * 2 at a ratio of 1.25 is 2.5 device pixels per source pixel, which is the
+ * unevenness the setting exists to remove.
+ *
+ * Worked through at a ratio of 2, fitting a 480 wide design into 1280: the
+ * raw factor is 2.667 CSS, which is 5.333 device pixels. Flooring here gives
+ * 5 device pixels, so a CSS factor of 2.5. Flooring the CSS factor instead
+ * would give 2, which is 4 device pixels: also whole, and a whole device
+ * pixel smaller than the container could have afforded.
+ *
+ * Never returns less than one device pixel per source pixel. A container
+ * smaller than the design resolution has no whole factor to give, and a
+ * scale of zero does not draw at all.
+ * @param scale - the unconstrained factor, in CSS pixels
+ * @param ratio - `devicePixelRatio`
+ * @returns the constrained factor, still in CSS pixels
+ */
+export function integerDeviceScale(scale: number, ratio: number): number {
+	return Math.max(1, Math.floor(scale * ratio)) / ratio;
+}
+
 /**
  * callback for window resize event
  * @param game - the game application instance triggering the resize
@@ -138,6 +166,9 @@ export function onresize(game: Application): void {
 			} else {
 				scaleX = scaleY = _max_height / settings.height;
 			}
+			if (settings.scaleRounding === "integer") {
+				scaleX = scaleY = integerDeviceScale(scaleX, device.devicePixelRatio);
+			}
 		}
 	}
 	// adjust scaling ratio