Skip to content

Gadgets

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.

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 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 4
menu = [1, 0, 30, 20] # where the buttons go
context = [21, 20, 11, 4] # a button that does what A does
yes_no = true # a yes-or-no question is also two buttons
party = [0, 18, 20, 6] # the party at a glance: level and health
open = [26, 18, 6, 6] # a button that opens the menu and closes it

The 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).

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 turn
screen = [2, 2, 26, 20] # where an app draws
next = [28, 2, 4, 20] # touching here shows the next app; R does too
app_flag = 300 # app n is there once flag 300 + n is set
ink = [1, 3] # two colours of the picture's palette the apps draw in

app_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.

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.

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 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] shows
power = true # the player may switch it off
dim = { amount = 8, after = 8 } # darkened while a script has the game
switch = "shutter" # the motion between apps
boot = "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:

gadget/apps/steps.toml
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 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.

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.

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).