03 05 Config Display Layouts

03 05 Config Display Layouts

This page covers layout definitions used by [display].

If you have not read the display overview yet, start with:

• 03 05 Config display

What is a layout

A layout is a named screen arrangement under:

• display.layouts.<layout_name>

Each layout contains an ordered list of elements that Sprint Boost draws in order.

Layout-level optional fields:

• background_color (string, optional)
  • #RRGGBB or #RRGGBBAA.
  • If unset, uses global display.background_color.
• enable_game_border_background_color (bool, default false)
  • When true, layout background follows game border color when available.
  • Falls back to layout/global background color if game color is unavailable.

Basic layout example

[display]
default_layout = "fullscreen"

[display.layouts.fullscreen]

[[display.layouts.fullscreen.elements]]
type = "game"
x = 0
y = 0
width = "100%"
height = "100%"
aspect = "force_4x3"

Draw order (important)

Elements render in the order they are listed.

Common pattern:

1. Draw type = "game" first
2. Draw overlays/images/text after that

This makes overlays appear on top of gameplay.

Multi-element layout example

This example shows a common layered layout:

• game viewport
• themed image panel
• live text value

[display]
default_layout = "with_panel"

[display.layouts.with_panel]

[[display.layouts.with_panel.elements]]
type = "game"
x = { anchor = "right", offset = 0 }
y = 0
width = "75%"
height = "100%"
aspect = "force_4x3"
alpha = 1.0

[[display.layouts.with_panel.elements]]
type = "image"
source = "{gv.assets_images}/status_panel.png"
fallback = "none"
x = { anchor = "left", offset = 0 }
y = 0
width = "25%"
height = "100%"
scaling = "none"
alpha = 1.0

[[display.layouts.with_panel.elements]]
type = "text"
text = "{gi.score}"
x = 20
y = 620
width = 260
height = 70
color = "#DEEF00"
align = "center"
size = 42
alpha = 1.0

Because draw order is top-to-bottom, this renders as:

1. game first
2. panel image on top
3. text on top of both

Common element types

Shared properties for all element types:

• x, y (position)
• width, height (size)
• alpha (opacity, 0.0..1.0)

See Positioning guide and Sizing guide below for valid formats.

type = "game"

Draws the game view.

Properties:

• aspect (string, default maintain)
  • Controls how the game framebuffer fits inside the element box.
  • Common values: maintain, stretch, force_4x3, force_16x9, integer_scale.
• border (table, optional)
  • Only valid on type = "game".
  • If used under non-game element types, Sprint Boost warns and ignores it.

Border table fields:

• enabled (bool, default false)
• mode (string, default fit; currently supported: fit)
• base_size (pixels or percent string, default 0)
• left_adjust, right_adjust, top_adjust, bottom_adjust (i32, default 0)
• color (string, default display_background)
  • game, display_background, or hex (#RRGGBB / #RRGGBBAA)
• center_on (string, default game_frame)
  • game_frame or bordered_frame

type = "image"

Draws an image file (overlay, frame, guide art, etc.).

Properties:

• source (string, required)
  • Primary image path.
  • Supports substitutions like {game_folder}, {game_file}, {game_file_ext}, {gv.<key>}.
• fallback (string, optional)
  • Used if source cannot be loaded.
  • Use "none" to disable fallback.
• scaling (string, default fit)
  • none, fit, fill, stretch.
• blend (string, default normal)
  • normal, multiply, add, overlay.
• trim_transparent_edges (bool or table, default disabled)
  • true is shorthand for { alpha_threshold = 0 }.
  • Removes fully transparent outer rows and columns before drawing.
  • alpha_threshold > 0 is allowed, but lossy.
• transparent_region_optimization (bool or table, default disabled)
  • true is shorthand for { mode = "transparent_hole_split", min_hole_width = 192, min_hole_height = 128, alpha_threshold = 0 }.
  • Current supported mode: transparent_hole_split.
  • Detects one large interior transparent rectangle and splits the image into 2 to 4 bounded pieces that reuse the same texture.
  • min_hole_width / min_hole_height default to 192 / 128.
  • alpha_threshold > 0 is allowed, but lossy.

Supported image formats:

• PNG
• JPEG / JPG

Practical recommendation:

• Prefer PNG for overlays/panels when possible.

Transparent optimization notes:

• Both features are opt-in; existing image behavior is unchanged unless enabled.
• If both are enabled, Sprint Boost trims transparent edges first and then evaluates transparent-hole splitting on the trimmed bounds.
• If no qualifying interior hole is found, Sprint Boost falls back to the normal single-image draw.
• Layouts using either optimization automatically bypass display.cache_static_layer for that active base layout.

Example:

[[display.layouts.old_tv.elements]]
type = "image"
source = "art/old_tv_bezel.png"
x = 0
y = 0
width = "100%"
height = "100%"
scaling = "stretch"
trim_transparent_edges = true
transparent_region_optimization = { mode = "transparent_hole_split", min_hole_width = 192, min_hole_height = 128, alpha_threshold = 0 }

type = "text"

Draws text values (for example game info or tracked stats).

Properties:

• text (string, required)
  • Rendered label content.
  • Supports substitutions (for example {gi.score}, {ps.p1.score}).
• color (string, default #FFFFFF)
  • #RRGGBB or #RRGGBBAA.
• size (u32, default 24)
  • Text pixel size.
• align (string, default left)
  • left, center, right.

type = "leaderboard"

Draws leaderboard entries from play stats.

Properties:

• play_stat (string, required)
  • Tracked stat key from play_stats.players.<player>.tracked.<stat_key>.
• order (string, default desc)
  • desc or asc.
• header (string, optional)
  • Header label text.
  • If blank, runtime uses play_stat.
• include_players (array of strings, optional)
  • Filters current-session overlay rows only.
• background_color (string, default #FFFFFF)
  • #RRGGBB or #RRGGBBAA.
  • Use alpha 00 for transparent panel background (for example #00000000).
• historical_color (string, default #000000)
  • Text color for historical rows.
• current_color (string, default #1A1DAF)
  • Text color for current-session rows.
• header_color (string, default #000000)
  • Text color for header.
• font_size (string, default normal)
  • Presets: small, normal, large.
  • Also supports percent scaling string (for example "125%") relative to normal.
  • Percent values are normalized/clamped to 50%..300%.

Positioning guide

Positioning controls where an element appears on screen.

Coordinate basics

• x = 0, y = 0 is the top-left corner of the screen.
• Increasing x moves right.
• Increasing y moves down.

Position formats

You can set position with:

• Pixel values (example: x = 10)
• Percent values (example: x = "70%")
• Anchor tables (example: x = { anchor = "right", offset = -10 })

Anchors and offsets

Anchors are relative to screen edges/center.

Common anchors:

• left, right, top, bottom, center

Valid anchors by axis:

• For x: left, right, center
• For y: top, bottom, center

Using axis-matching anchors keeps layout intent clear and easier to maintain.

Offset direction rule:

• Positive x offset moves right; negative moves left
• Positive y offset moves down; negative moves up

Examples:

x = { anchor = "right", offset = -20 }   # 20 px left from right edge
y = { anchor = "bottom", offset = -20 }  # 20 px up from bottom edge

Use anchor + offset when you want layouts that adapt cleanly to different display sizes.

Sizing guide

background_color = "#101010" enable_game_border_background_color = true

Sizing controls how large each element is.

Size formats

width and height can be:

• Pixels (example: width = 320)
• Percent (example: width = "75%")

[display.layouts.with_panel.elements.border] enabled = true mode = "fit" base_size = "10%" color = "game" center_on = "game_frame" left_adjust = 0 right_adjust = 0 top_adjust = 0 bottom_adjust = 0

Game element ratio guidance

For Intellivision content, using standard game ratios is usually best:

• aspect = "force_4x3" is the most common choice
• aspect = "force_16x9" is useful only when your layout is intentionally widescreen

This helps keep gameplay shape consistent across layouts.

Quick 4:3 sizing reference (1280×720)

When the game is 4:3 inside a 1280x720 display area, the game region is typically:

• 960x720

That leaves:

• 160 px side margins each (if centered), or
• 320 px on one side (if game is anchored fully left or right)

This is a practical reference when designing side panels and overlay assets.

Image sizing and scaling tip

For image overlays/panels, a good practice is:

• Design assets at the size you intend to display
• Use scaling = "none" when possible

This avoids unnecessary stretch/fit behavior and gives more predictable visual results.

Valid scaling options (image elements)

type = "image" supports:

• none (best for pre-sized assets)
  • Uses the image’s native size.
  • Ignores configured width/height for scaling.
• fit (default)
  • Fits image inside the target box.
  • Preserves aspect ratio (no distortion).
  • Can leave empty space (letterbox/pillarbox).
• fill
  • Fills the full target box.
  • Preserves aspect ratio.
  • Can crop part of the image.
• stretch
  • Fills the full target box.
  • Does not preserve aspect ratio.
  • Can visually distort image proportions.

Secondary layout pattern (overlay without game)

A useful layout pattern is a secondary overlay layout that does not include a game element.

Example:

[[display.layouts.secondary_layout_default.elements]]
type = "image"
source = "{game_folder}/{game_file}_big_overlay.png"
fallback = "none"
x = 5
y = { anchor = "top", offset = 20 }
width = "100%"
height = "100%"
scaling = "none"
alpha = 1.0

How it is used:

• Base layout stays active for normal play
• Hotkeys or menu actions show/hide/toggle secondary layout as needed

Layout overrides

Layout overrides are usually done at game level.

Common approaches:

• Define a new game-specific layout name and switch to it
• Redefine a layout’s elements list when a game needs a different composition

For list-style layout sections, game-level definitions typically replace the list section you define.

Practical tips

• Start with one simple layout first (game only).
• Add one overlay element at a time.
• Keep layout names short and descriptive.
• Use game-specific layout names when experimenting.
• Prefer anchor-based placement for reusable layouts.
• For game view, default to aspect = "force_4x3" unless you have a specific reason not to.
• For overlays, create assets at target size and prefer scaling = "none".

Next step

Continue to:

• 03 06 Config menus