Tutorial Widescreen and Scaling

Tutorial: Widescreen and Window Scaling

Your project chooses its logical frame — and, optionally, how that frame breathes when the player resizes the window. Both live in presentation/version.json under one knob:

{
 "viewport": {
  "width": 256, "height": 144,
  "policy": "bounded",
  "max_width": 320, "max_height": 176
 }
}

The design frame

width × height (multiples of 16, from 160×144 up to 640×360) is the frame your game is designed for: world constants, UI anchoring, and the link handshake all derive from it. 256×144 is exact 16:9 at the classic vertical extent; leave the knob out entirely and you get the classic 160×144.

Full-screen menus keep an authentic 160×144 canvas centered in the frame, with the margins darkened under modals — you never re-lay-out the UI for a wider game.

The bounded policy

Without policy, the frame is fixed and the window integer-scales it. With policy: "bounded":

• the engine integer-scales the design frame to the window,
• then widens what is visible toward floor(window / scale), up to your max_width/max_height clamp (snapped even),
• and letterboxes only the remainder.

Resize freely — pixels stay crisp and the world simply shows more or less of itself within your authored envelope.

Rules stay rules

A wider frame changes what the player sees, never how the game behaves: trainer sightlines, encounter ranges, and scripts are cell data, identical at every window size. Headless runs (tests, bots) always use the design frame, so automation is deterministic by construction.

Validation

An invalid frame (wrong multiple, out of range), an unknown policy, or a clamp smaller than the design frame refuses at boot naming the value.