Menus
Every menu screen belongs to a family: party, summary, bag, storage, dex, trainer card, journal, options, the Start menu, shop, naming, the region map, and so on. A family’s behaviour is written once in Rust: what the cursor may reach, what choosing a member does, how switching works. Its look is data: where each window and button is, which colours mark the chosen panel, how many frames a slide takes, which pictures it draws.
The split exists because the handheld games’ screens differ much more in how they look than in how they work. Platinum’s party screen and Emerald’s do the same things; they place them differently and animate them differently. So the engine builds the behaviour once and lets each game’s look be numbers and pictures (decision 285). A creator picks a style, edits its numbers, swaps its pictures, or mixes styles from different games. An importer writes the numbers and pictures it reads from a game, and never has to turn a game’s menu code into ours.
A screen with no layout file of its own uses the engine’s own look: windows drawn from the project’s skin, in the engine’s places.
The engine’s own look is drawn from the skin: graphics/ui/skin.pfk (tiles, palettes,
frames, icons) and the font graphics/ui/font.pff. Both are copied into the pack as
they are. Two parts of the skin can be ordinary pictures laid over it:
graphics/ui/skin/window.png: 24 × 24, three tiles by three (corners, edges, middle). Its middle colour is the paper; its other colours, darkest first, are the outline, body and light of every window.graphics/ui/skin/frame_<n>.png: text box framen, the box as it is on the screen, 48 tall. The player chooses among the frames on the options screen.
The rest of the skin (buttons, gauges, icons) is not yet converted from pictures.
Styles
Section titled “Styles”A built-in style is the behaviour of one game’s screen, built into the engine, with every number and picture in the project. Today’s styles:
| Family | Style | Layout file | Pictures |
|---|---|---|---|
| Party | two-screen: six panels on the main screen, a round button a member on the touch screen (a touch counts only on the button’s drawn pixels), Platinum’s |
layouts/party.toml |
graphics/menus/party/ |
| Party | one-screen: the lead’s large panel beside the others, Emerald’s |
layouts/party.toml ([single]) |
graphics/menus/party/ |
| Summary | pages of information, skills and moves, with type icons, bars and touch buttons, Platinum’s | layouts/summary.toml |
graphics/menus/summary/ |
| Bag | pocket pictures, the list, the cursor, the description, pocket buttons on the touch screen, Platinum’s | layouts/bag.toml |
graphics/menus/bag/ |
| Start menu | window: a window of entries over the field, Emerald’s |
layouts/start.toml |
none |
| Signs | board: a frame and text colours for each kind of sign, printed at once or typed, sliding in and out, Platinum’s signposts |
layouts/sign.toml |
graphics/menus/sign/ |
Each layout file names its style and holds every number of it: rectangles, cursor
neighbours, inks, ticks of each motion, sounds, and the pictures under [art]. Any of
them may be edited. A file of the Start menu’s style, as the engine documents it:
variant = "window" # the style: "window" (or "engine")wrap = true # the cursor goes round at the endsfade = 9 # ticks of the fade to black before a screen openswindow = [22, 1, 7] # the window's inside: column, row, columnsrow = 16 # pixels a rowentries = ["dex", "party", "bag", "map", "card", "save", "options", "exit"]always = ["bag", "card", "save", "options"] # listed whatever the game has given
[text] # each entry's words: keys of text.txtparty = "start_party"Every key of each file is described at the top of its reader in tools/pl-assets
(layouts.rs, layouts_summary.rs, layouts_bag.rs, layouts_start.rs,
sign_layout.rs). The build fits each screen’s pictures into the DS’s tiles and
palettes (for the party screen, at most 8 palettes and 384 tiles on the main screen,
512 on the touch screen) and says when it had to bring colours or tiles down.
The build makes one layout file for the pack, a directory of screen blocks; each block
is read only when its screen opens. On DS a style is linked only if the game uses it
(the pl-game features style-window-menu, style-one-screen-party and
sign-board); a build without a style shows that screen in the engine’s look. The
desktop program carries every style.
ploom import writes the layout files and pictures of the game it reads, into the
import only: Platinum’s party, summary, bag and signs, Emerald’s Start menu and party.
An imported game’s menus are meant to look and behave exactly as the original’s, on
both screens and frame for frame, and that is checked by comparing pictures of the
real game and ours at the same moment (Fidelity pairs).
The menus’ layouts and art are the original’s, so they never go into a public
repository.
Screens
Section titled “Screens”| Screen | How a game reaches it |
|---|---|
| Start menu | the menu key; a list on the top screen of eight entries showing six, or the window style |
| Party | the Start menu; choosemon in a script |
| Summary, moves | from the party |
| Bag | the Start menu; a preset of [rules] bag sets its pockets and rules |
| Storage | storage in a script; the boxes on the touch screen, creatures dragged with the pen |
| Dex, trainer card, journal | the Start menu once a script gives them (menuentry) |
| Region map | menuentry map, in a game with a region map |
| Options | the Start menu; a game adds rows with [ui.options] |
| Naming | askname in a script |
| Shop | shop in a script |
| Evolution, hatching, Hall of Fame, credits | by the game’s events |
The field’s touch screen has never required the pen: everything on it has a key too. Planned (plan 45): that becomes a rule for every screen, checked by the build, so every screen works on desktop with a keyboard or pad and for players who cannot use a pen.
The journal, the trainer card and the dex
Section titled “The journal, the trainer card and the dex”Three screens a game gives the player when its story says, each one script line, usually where the player receives the thing that holds them:
menuentry journal # the diary of recent daysmenuentry dex # the creatures seen and caughtmenuentry card # the trainer cardThe journal writes itself once given: arriving in a named area, meeting people,
battles won and lost, creatures caught. A script adds lines with journalnote. The
trainer card shows the player’s name, money, time played, badges and, once the dex is
given, the creatures seen and caught. The dex lists creatures up to the last one seen,
with an entry page each, in the order of pbs/regional_dexes.txt when the game has
one.
Title screen
Section titled “Title screen”Without anything of its own a game has the engine’s title: its name on a banner and a
list of “continue” and “new game”. A game can have its own: pictures in layers on both
screens, a “press start” line that blinks, a creature or a 3D model, music, and a main
menu whose continue window shows what the save holds. It is
graphics/title/title.toml with the layers’ pictures beside it:
music = "title" # a track of audio/audio.txtcontinue = "menu_continue" # keys of text.txt: the windows' wordsnew_game = "menu_new"
[press]text = "press_start"row = 19 # tile row on the main screenblink = [32, 16] # ticks shown, then hidden
[layers.back] # each layer: a picture, its screen and layerpicture = "back.png"screen = "top"layer = 3scroll = [-8, 0] # sixteenths of a pixel a tick: clouds driftingA [model] table puts an OBJ model behind the pictures on one screen, drawn slowly
rising and falling, its scrolling textures moving. Each screen’s layers share its
tiles and colours, and the build fits them together. Every key is listed at the top of
tools/pl-assets/src/titleart.rs.
The intro is a script: the on newgame hook runs when a new game begins, before
the first map is seen. With showpic, choosepic, showmon and askname it plays a
welcome, the choice of a character and the naming of the player and rival; when it
ends the map fades in. See Scripts and events.
Lower screen
Section titled “Lower screen”In the field, the touch screen shows a picture, the menu as touch buttons, or small apps. See Gadgets and the lower screen.
UI system
Section titled “UI system”Today’s styles each have a record shape and a drawing path of their own, beside the engine’s own look and the battle interface’s pictures: five shapes in all. Plan 45 replaces them with one.
Planned (plan 45): a screen is a family logic plus a record. The logic is Rust, written once per family, and knows nothing about where anything is drawn. It publishes the values it offers (a member’s name, its HP, an item’s count), the states a part may depend on (selected, fainted, empty, pressed) and the actions input may ask of it (pick, cancel, next page, swap). The record is data: a flat table of parts, their groups, cursor neighbours, looks, timings, sounds and pictures. One drawer and one input router run every record. The engine’s own look is the default record, built from the same kind of file by the same tool, so there is nothing special about it.
A record in a project, the engine’s party screen as the plan writes it (shortened):
# layouts/party.toml (planned format)family = "party"back = "cancel"[[group]] name = "members"; source = "members"; columns = 2; step = [128, 48]; at = [0, 8][[part]] kind = "picture"; group = "members"; picture = "panel"; look = "panel" action = "pick"; hit = "rect"; size = [126, 44][[part]] kind = "text"; group = "members"; bind = "member.name"; at = [38, 6]; ink = "name"[[part]] kind = "gauge"; group = "members"; bind = "member.hp"; at = [62, 30]; size = [48, 3][look.panel] plain = 1; selected = 2; fainted = 3; empty = 4; chosen = 5[motion] open = { kind = "wipe", steps = 6, ticks = 2, hold = 24 }What makes this hold together:
- Closed lists. About 25 part kinds (text, number, gauge, icon, button, list, dial,
drag area, canvas…), a short list of motions (cut, fade, wipe, slide, flip, hop,
blink, shutter…) and a few named rules per family (
wrap,hide_on_cancel). A record chooses and places them; it holds no expressions or conditions, so it can never grow into a programming language. A screen that needs more gets a new part kind or rule in the engine, or is a game crate’s own scene. - Checked at build.
ploom buildrefuses a part outside its screen, a value or action the family lacks, a focus no key can reach, an action only the pen can reach, text that cannot fit, and art over the DS’s tile and sprite limits. - Mixing.
[style.ui]ingame.tomlnames where each family’s record comes from: a default source and per-family exceptions (Platinum’s party, HeartGold’s bag, the engine’s battle). Mixing needs no code because every record of a family binds the same logic. - Tools.
ploom ui showdraws a record with sample values to a picture, both screens, without running the game;ploom ui eject partycopies the active record and its pictures into the project to edit; on desktop a changed layout reloads into the open screen. - Text. Records name strings by key and hold no words.
ploom check --textmeasures every string a part can show in every language with its font and lists what does not fit; a language may move parts in its own small file. - Accessibility. Text size is a save option with a
[profile.large]in every default record; colour filters and contrast apply to every UI palette; calm motions keep their tick counts, so a replay is the same with them on or off (Accessibility). - Several players. Every screen has an owner; a co-op player’s menu is theirs, and boxes wear the player’s colour (Co-op).
- Only what a game uses. A DS build links only the part kinds and behaviours its records name.
Today’s styles move into this system family by family: signs and the party screen first, then the summary and bag, the field’s overlays and Start menu, the battle interface, the title and the rest. The default records reproduce today’s pixels and timing, so a game with no layouts of its own sees no change. The engine’s UI code is budgeted to stay within about 15 KB of its size before the move.
How a DS menu is made from tiles explains the hardware these records are drawn on.