Display and window sizing

ReGame separates the game’s design viewport from the desktop player window.

Design viewport

viewport.width and viewport.height define the coordinate space used to author the scene and its UI. They also define the pop-out player’s initial desktop size when no override is present.

{
  "viewport": {
    "width": 450,
    "height": 800
  },
  "handheld": {
    "orientation": "portrait"
  }
}

A portrait scene therefore opens in a portrait-shaped pop-out window. If the requested size is larger than the monitor’s usable work area, ReGame scales both dimensions uniformly so the whole window remains reachable.

Desktop window overrides

Use window.widthOverride and window.heightOverride when desktop testing should begin at a size different from the design viewport. Each dimension is optional; 0 or an omitted value falls back to the corresponding viewport dimension.

{
  "viewport": {
    "width": 720,
    "height": 1280
  },
  "window": {
    "widthOverride": 450,
    "heightOverride": 800,
    "resizable": true
  }
}

Overrides affect only the initial desktop window. They do not change the game’s design coordinates or mobile resolution.

Stretch behavior

Stretch settings control what happens when the actual window or device aspect ratio differs from the design viewport:

• ignore fills the window with non-uniform scaling and can distort the game.
• keep preserves the design aspect and adds bars when needed.
• keep_width preserves width and can expand vertically.
• keep_height preserves height and can expand horizontally.
• expand fills the window without distortion by showing more world on the unmatched axis.

Initial window sizing and stretch behavior are intentionally separate. For example, a 450×800 game with keep starts as a 450×800 desktop window without bars. If the player later resizes that window to landscape, keep adds side bars to preserve the authored portrait composition.

For mobile games with responsive HUDs, canvas_items with expand or keep_width usually makes better use of varying phone aspect ratios. Use keep when the exact authored aspect ratio must remain visible.

Embedded Game view

The editor's embedded Game view uses the same design viewport and stretch aspect as the standalone player. The embedded surface is always contained by the Game panel; it must not cover the Console, Debugger, Output, or neighboring docks.

For a portrait game shown inside a wider editor panel:

• keep and keep_width show the complete portrait frame with side bars.
• keep_height and expand may use the wider panel and expand the projection.

For a landscape game shown inside a taller editor panel, the corresponding rule is mirrored: keep and keep_height show the complete landscape frame with bars, while keep_width and expand may expand the projection.

Use a portrait pop-out player or mobile simulator for final device framing, but the embedded Game view should preserve the same visible composition whenever its stretch mode calls for letterboxing.

Player debug menu

The standalone and pop-out ReGame Player window has Reload and Debug buttons in its native window header. On macOS Reload appears as a circular-arrow icon beside the bug icon at the right side of the title bar; Windows exposes the equivalent header controls beside the native caption buttons. Reload rebuilds the currently running scene in the same Player process. Open Debug and choose Performance Metrics to show or hide the runtime FPS, frame-time, process, physics, script, object, draw-call, and vertex overlay. Choose Collision Shapes to show or hide live physics outlines without relaunching the Player. The same collision state is also available from the editor's View menu while an embedded or pop-out Player is connected.

Performance Metrics starts off for every direct player launch, so an editor preference from a previous session cannot unexpectedly cover game UI. Launching with --show-fps still enables it explicitly. Changing the option mutates the player debug state first and then emits player.performanceMetricsVisibilityChanged with the new boolean value. Changing Collision Shapes mutates the same authoritative Player debug state and then emits player.collisionShapesVisibilityChanged with the new boolean value. Reload emits the typed native reloadCompleted result after the scene has been recreated, and the reloaded game receives player.sceneReloadCompleted after authoritative runtime state has changed.

Reload is a complete runtime boundary. ReGame first emits player.sceneReloadStarted and the outgoing scene lifecycle event, cancels deferred scene/physics/destruction work, unmounts InterfaceHosts, runs component destroy hooks while object identities are still resolvable, cancels scene-owned listeners and suspended script work, resets physics and input, then loads the scene and emits the incoming scene lifecycle plus player.sceneReloadCompleted. Engine-owned Player header and IPC subscriptions survive because they are not owned by the discarded scene.

On macOS, development Player processes enable a bounded native core dump. If a native crash escapes the script recursion guard, inspect /cores/core.<pid> with LLDB. Apple controls whether ReportCrash also writes a .ips file under ~/Library/Logs/DiagnosticReports; ReGame logs macOS_ips=system_managed rather than claiming that an .ips was created. RGScript synchronous event cycles stop at the engine recursion boundary and report their recent event chain as a script error instead of exhausting the native stack.

Automation and accessibility clients can discover the same controls through:

• regame.player.debugMenu — opens the Debug menu.
• regame.player.reload — reloads the current scene and reports reloaded or failed.
• regame.player.debugMenu.performanceMetrics — toggles Performance Metrics and reports on or off.
• regame.player.debugMenu.collisionShapes — toggles Collision Shapes and reports on or off.