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.

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

type = "game"

Draws the game view.

Typical fields:

• x, y
• width, height
• aspect
• alpha

type = "image"

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

Typical fields:

• source
• fallback
• x, y
• width, height
• scaling
• alpha

Supported image formats:

• PNG
• JPEG / JPG

Practical recommendation:

• Prefer PNG for overlays/panels when possible.

type = "text"

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

Typical fields:

• text
• x, y
• width, height
• color
• size
• align

type = "leaderboard"

Draws leaderboard entries from play stats.

Typical fields:

• play_stat
• order
• header
• include_players
• x, y, width, height

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

Sizing controls how large each element is.

Size formats

width and height can be:

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

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