Gadgets
Lower screen
Section titled “Lower screen”On a DS the touch screen is always there. During a battle or in a two-screen menu the screen owns it; in the field, the game decides what it shows. The handheld games each put a device there or a menu: a watch with apps, a phone and radio, a ring of link buttons, a touch menu. PokeLoom models all of these the same way, because they differ in art and in which apps they carry, not in shape: a screen that shows one thing at a time, buttons that change what it shows or start something, events from the field, and a little saved state.
Today: [ui.bottom]
Section titled “Today: [ui.bottom]”The field’s touch screen is the skin’s picture, graphics/ui/skin/bottom.png, with
parts the game places on it. [ui.bottom] in game.toml chooses a style. Rectangles
are [x, y, width, height] in tiles of 8 pixels, on the screen’s 32 × 24 tiles.
Without the table the picture is all there is.
The menu style
Section titled “The menu style”The Start menu’s entries (party, bag, journal, map, save, options, as the player has them) become large buttons the pen opens. The X key gives the pad to them.
[ui.bottom]style = "menu"columns = 2 # 1 to 4menu = [1, 0, 30, 20] # where the buttons gocontext = [21, 20, 11, 4] # a button that does what A doesyes_no = true # a yes-or-no question is also two buttonsparty = [0, 18, 20, 6] # the party at a glance: level and healthopen = [26, 18, 6, 6] # a button that opens the menu and closes itThe context button’s caption follows what A would do: check, talk or next (the strings
panel_check, panel_talk and panel_next of the game’s text). The open button’s is
panel_menu.
The map page. With nav, the menu’s buttons show only while the menu is open; in
their place otherwise is a region map with the player’s square marked, the way a
third-generation remake’s device shows it. Its files are in graphics/ui/bottom/:
map.png, here.png (the marker, 16 × 16) and nav.toml, which gives each map’s
square of map.png, and whether the marker follows the player across it (routes) or
stays put (indoors).
The apps style
Section titled “The apps style”One small app at a time on the picture, as on a wrist device:
[ui.bottom]style = "apps"apps = ["clock", "party", "steps"] # in the order they turnscreen = [2, 2, 26, 20] # where an app drawsnext = [28, 2, 4, 20] # touching here shows the next app; R does tooapp_flag = 300 # app n is there once flag 300 + n is setink = [1, 3] # two colours of the picture's palette the apps draw inapp_flag lets the story hand out apps: a script’s set on the flag adds one.
Without it every app is there from the start.
What holds for both
Section titled “What holds for both”Nothing needs the pen. The entries open with X and A, the context button is A, and a question’s answers are on the top screen too. A player on desktop with a pad, or one who cannot use a pen, loses nothing.
The tile-map style takes the same table in its tiles.toml
(The tile-map style). An import of Emerald from its
decompilation writes it all: the PokéNav’s region map, the player’s icon and the
device’s background as the skin’s bottom.png.
Every key is in the game.toml reference.
Framework
Section titled “Framework”Planned (plan 45): a gadget is a shell and a set of apps. The shell owns the lower
screen; one app shows at a time. Today’s three styles become three small default
gadget records, and [ui.bottom] is replaced by a gadget/ folder in the project.
The shell
Section titled “The shell”The shell is a record, gadget/gadget.toml. From the plan:
[gadget]shows = "always" # "always" (the lower screen), "opened" (a screen from the menu), or "both"earned = "GADGET_ON" # a flag; before it, [off] showspower = true # the player may switch it offdim = { amount = 8, after = 8 } # darkened while a script has the gameswitch = "shutter" # the motion between appsboot = "zones" # the motion when switched on
[[app]] name = "clock"; record = "apps/clock.toml"[[app]] name = "steps"; record = "apps/steps.toml"; flag = "APP_STEPS"
[[zone]] name = "ring0"; layer = 2; schemes = 6 # a region the player may recolour[[skin]] name = "plain"; art = "skins/plain/"
[[part]] kind = "button"; action = "app.next"; hit = "rect"; at = [224, 80]; size = [24, 40][[part]] kind = "clock"; at = [96, 8]; digits = 4; blink = 30[notify] at = [16, 120]; size = [224, 56]; motion = "slide"; queue = 4[off] picture = "off.png"What the shell does, all from its record:
- A dock of buttons, each bound to one action: the next or previous app, a named app, a Start-menu entry, power, edit mode, the next skin, a script label, or a connected service such as the nearby link or the co-op session (decision 321). A button may be movable: in edit mode the player drags it to one of the record’s resting spots.
- Colour zones and skins. A zone is a set of palette slots with several schemes the player picks; a skin swaps the art. Creators ship skins; players choose.
- Status parts: a clock, the battery, the signal, lamps that blink by the link’s state, and swatches in the colours of nearby players.
- Notifications: one queue of cards for a script’s
notify, a phone call, a co-op ready card or a link request. A card slides over the app; A or a touch answers it. - Motions from the record’s ticks: boot, switching apps, dimming, blinks.
What the lower screen shows is a fixed order: a scene that owns it (a battle, a menu
screen), then a notification, then the gadget’s app, then its off picture.
Planned (plan 45): an app is a record plus one behaviour from a closed list, written once in Rust:
| Behaviour | Does |
|---|---|
clock |
time and date, digital or hands, an optional alarm |
counter |
a number from a source (steps, a variable, taps), with a reset |
party |
members’ icons, health and status |
menu |
the Start menu’s entries |
list |
a source as a scrolling list with a detail pane |
toggles |
rows that set an option, a zone’s scheme or the skin |
map |
the region map, the player’s square, markers, notes |
timer, calendar, keypad, canvas, finder, mood, matchup, chance |
the smaller watch apps: stopwatch, calendar, calculator, drawing, hidden-item finder, friendship, type matchups, coin and wheel |
phone, radio |
contacts and calls by a ring rule; a tuner with stations by map and hour |
graph |
a condition polygon |
link, players |
the link entries and who is in the session or near |
help |
pages of text |
script |
a creator’s own |
An app’s record places its parts, as a menu screen’s does. From the plan:
behaviour = "counter"[counter] source = "steps"; max = 99999; reset = true[[part]] kind = "number"; bind = "value"; at = [72, 64]; digits = 5; font = "big"[[part]] kind = "button"; action = "reset"; at = [96, 128]; size = [64, 32]A creator’s own app without Rust uses behaviour = "script": parts bind to script
variables and text registers, and a button’s action names a label of the app’s
script. App scripts may use only commands that finish at once, since they run beside
the game; the compiler refuses a waiting command there. A new hook, on app, receives
the app’s events. A game crate may also add behaviours in Rust.
The field feeds apps through a small set of events (stepped, moved, saved, a minute passed, the link changed, a call), and each app keeps a few bytes in one save section, capped at 1 KB for the whole gadget.
The originals as imports
Section titled “The originals as imports”The four devices of the handheld games are imports of this one shape:
| Device | Game | How it maps |
|---|---|---|
| Pokétch | Platinum | always on the lower screen; a frame, two buttons, colour themes as a zone; a tile shutter between apps; its apps as records over the watch behaviours |
| Pokégear | HeartGold | opened from the menu, on both screens; a bar of app buttons; skins; phone, radio, map |
| C-Gear | Black 2 | always on; rings in colour schemes; three link buttons the player drags between resting spots; lamps, a boot animation, skins by the player’s look |
| PokéNav | Emerald | opened from the menu, one screen; menu, map, condition graph, match calls |
The importer reads a device’s art and numbers from the player’s own ROM into the
import, never the repository. Black 2’s C-Gear is read today: its pictures, layers,
skins and a shell record with its zones, spots, lamps, motions and help pages land in
the import’s ui/gadget/. The engine does not run that record yet: that is the shell
above. The other three are Planned (plan 45).
Mixing is the point of one shape. Planned (plan 45): [style.ui] gadget = "black2"
takes an import’s gadget into any project, and an app row may name another source’s
app, so a C-Gear shell with a Pokétch calculator and a Pokégear radio is three lines.
ploom new gadget writes a shell with a dock, a clock and one script app to start
from.
What the C-Gear’s buttons do
Section titled “What the C-Gear’s buttons do”In the original, the C-Gear’s three buttons start Nintendo’s link services. Here they start PokeLoom’s own (decision 321): the nearby link (battle, trade or join a player beside you), the co-op session, and online play. They are bindings, not fixed behaviour: a creator can bind them to an app, a module or a script label instead. Offline, the buttons show the original’s dimmed look and refuse; everything else (the rings, colour schemes, dragging, skins, the boot animation, the clock) works without a network. See Multiplayer.
Desktop
Section titled “Desktop”Today the desktop window shows the two screens stacked (the default) or side by side, scaled to fit, and the mouse is the pen on the lower screen.
Planned (decision 321): the desktop shows the lower screen by need; the details below are the research’s proposal. When a scene needs it (a battle’s panels, a two-screen menu, the naming keyboard) it is shown large; while an app shows something live, such as the map while walking, it is docked smaller; a notification slides in on its own; at rest the top screen fills the window with a handle to open the gadget. A player can always choose the classic two screens instead. On DS nothing changes: the lower screen is always there.
Planned (plan 45): a DS build links only the shell and the app behaviours its records name. The plan’s estimate is about 7 KB for the shell, 7 KB for the core apps, and about 55 KB for every behaviour of all four devices together, against the game’s 1.5 MB of code. Those figures are estimates until the shell is built and measured (Budgets).