Quality & performance

Game Settings ▸ Quality is your project's render budget — Quality Settings, creator side. Each control caps or coarsens one thing the GPU spends its frame on, so a heavy map can be made to run on weaker hardware without rebuilding it.

Two rules the whole section is built around:

1. Defaults do nothing. Every control ships in a "no effect" position. A project that never opens this section renders exactly as it did before Quality existed — same shadows, same resolution, same particle counts.
2. Quality only ever reduces. It caps, disables, and coarsens; it never raises a per-map value and never turns on something a map switched off. Forcing hard shadows on a map whose Scene Settings ▸ Shadows ▸ Enabled is off leaves it with no shadows, not hard ones.

Quality lives on the project (like Gravity and the player settings), so one setting covers every sub-map. Every runtime that draws the game honours it — the editor viewport, the play-test, exported standalone builds, and published multiplayer — and edits take effect live, no reload. Render Scale and FPS Cap are the two exceptions: those apply only while playing, so the editor viewport stays crisp and responsive while you work. The server never reads any of it: nothing here can touch physics, simulation, or anything another player sees, so it cannot affect multiplayer fairness.

The controls

Control	JSON key	Default	What it does
Shadows	shadowMode	'default'	hard forces crisp single-tap filtering on every light (cheaper than the soft default, and a stylized look); off stops every light casting, environment sun included. default leaves it to each map.
Shadow Dist. Cap	shadowDistanceMax	uncapped	Ceiling (4–200) on the per-map Shadow Distance — how far from the player shadows render. A map asking for 120 with a cap of 50 gets 50.
Player Blob Shadow	playerBlobShadow	off	Draw a soft disc under every player's character instead of a cast shadow — one quad in place of the whole shadow pass, fading out past the distance nameplates stop at. Needs shadowMode: 'off' in the same game and does nothing without it: "instead of" is the trade, and with shadows still on a character would wear a disc while casting for real. Players only; for a disc under an NPC or a prop, use the blobShadow component.
Shadow Map Cap	shadowMapSizeMax	uncapped	Ceiling in pixels on shadow texture resolution: the environment sun's Map Size and the 1024 a shadow-casting Directional Light entity uses. Quarter of the pixels per step down. (Point and spot lights already sit at 512.)
Shadow Lights	maxShadowCastingLights	unlimited	How many light entities may cast shadows at once — each casting light is another depth render of the scene. The environment sun is exempt (it is the scene's main light). First-applied lights win the budget; the rest still illuminate, they just stop casting. 0 means only the sun casts.
Render Scale	renderScale	1 (100%)	Multiplier on the render resolution, 0.25–1. The cheapest large win on a fill-rate-bound game, at the cost of a softer image.
FPS Cap	fpsCap	uncapped	Frame ceiling while playing. Skips whole frames; the next frame's delta covers the gap, so physics and scripts stay real-time.
Particles	particleScale	1 (100%)	Multiplier on every particle system's Max Particles, 0.1–1. A system never drops below 1 particle.
Detail Distance	detailDistanceScale	1 (100%)	Multiplier, 0.1–1, on terrain grass draw distance and density, plus how far ahead a block build streams its meshes. Block colliders never scale — that is simulation.
Aniso Filtering	anisotropyMax	per texture	Ceiling (1-16) on each texture's own Aniso Level, the sharpness of a surface seen at a grazing angle - floors, roads, walls running away from the camera. 1 turns anisotropic filtering off everywhere. A texture already below the ceiling is left alone: this caps, it never raises.
Monitors / Probe	rttInterval	every frame	Draw camera monitors (meshRenderer ▸ Camera Texture) and re-bake the reflection probe every Nth frame instead of every frame. A probe's first bake is never skipped, so nothing starts out unlit.

Out-of-range values in a hand-edited map file are clamped, not rejected: render scale floors at 25%, an FPS cap at 10, shadow maps at 256 pixels. A broken number degrades the look — it never bricks the game.

Pixel-perfect 2D: leave Render Scale at 100%

A fractional backing buffer defeats integer pixel snapping, so a pixel-art game scaled to 80% gets shimmering sprite edges. Cap the frame rate or the particles instead.

Starting points

Nothing here is a preset — they are the combinations worth reaching for first.

Runs on a weak laptop / integrated GPU. Shadows hard, Shadow Map Cap 1024, Shadow Lights 2, Render Scale 75%, Monitors / Probe every 2nd frame. Shadows are usually the single biggest cost, and hard + a capped map is a much smaller hit than turning them off.

Big open world. Shadow Dist. Cap 60 and Detail Distance 60%. Both trade the far distance — which a player reads as fog and haze anyway — for the near detail they actually look at.

Effects-heavy game (lots of emitters, explosions, weather). Particles 50% first; it scales every system at once, so you keep the composition of each effect and just thin it out.

Steady frame rate over peak frame rate. FPS Cap 60. A game that swings 45–140 fps feels worse than a flat 60, and on a laptop the cap is also a battery and fan-noise setting.

Stylized, not cheaper. Shadows hard is a legitimate art direction — crisp shadow edges, no soft gradient — and it happens to be the cheap option too.

Phones and Chromebooks. Shadows off with Player Blob Shadow on, plus blobShadow components on the things that need to read as grounded. No shadow pass at all, and the game still tells a player where they are standing and where a jump will land — which is most of what a shadow was doing for them.

How it stacks with per-map settings

Quality is a ceiling over Scene Settings ▸ Shadows, never a replacement for it:

Map says	Quality says	Result
shadowsEnabled: false	shadowMode: 'hard'	Still no shadows. Quality cannot enable what a map disabled.
shadowType: 'soft'	shadowMode: 'hard'	Hard. The override wins for every light in every map.
shadowCameraSize: 120	shadowDistanceMax: 50	50.
shadowCameraSize: 20	shadowDistanceMax: 50	20 — the map is already under the cap, and a cap never raises it.
shadowMapSize: 4096	shadowMapSizeMax: 1024	1024.

So the division of labour is: per-map Scene Settings decide how a level should look; Quality decides what the project can afford. Reach for Scene Settings when a map is too dark or its shadows too short, and for Quality only when the frame rate is the problem.

Editing it outside the panel

The AI editor can set the whole section from a sentence — "cap the frame rate at 30 and force hard shadows", "make this run on a weak laptop":

[ { "op":"setSceneSettings", "settings":{ "quality":{ "shadowMode":"hard", "fpsCap":30 } } } ]

quality replaces the object rather than merging into it, so an edit must repeat the fields it wants to keep; "quality":{} resets everything. The AI reads the current fields from the map snapshot each turn, and it will not touch them unless you bring up performance.

The terminal reaches individual fields, which is the easier way to try one knob:

set gameSettings.quality.fpsCap = 30
set gameSettings.quality.shadowMode = "off"
get gameSettings.quality

In a map file the same settings live under gameSettings.quality. Anything absent there is a control left at its default.

What Quality does not cover

• Physics and simulation. Nothing here changes gravity, tick rate, or collision — a game must play identically on a fast and a slow machine. Solver cost lives in Game Settings ▸ Physics ▸ CCD Substeps (see Physics).
• The edit viewport. Render Scale and FPS Cap apply while playing. The editor viewport's own resolution is in Editor Settings ▸ Pixel Ratio, which is a per-creator preference, not part of the game.
• Anti-aliasing, texture resolution, LOD bias. Not exposed: MSAA is fixed when the canvas is created, and the other two need pipelines the engine does not have yet.
• Per-player quality tiers. Quality is one ceiling for everyone. A player-side "Low/Medium/High" choice within these limits is a planned addition, not something a map can offer today.