Text
String IDs
Section titled “String IDs”Every word the player reads is a string with a key. A script, a menu or a battle message names the string; the build turns the key into a number, and the game looks the number up when it draws.
Why not plain text in the code:
- Translation. A second language is a second table in the same order. Nothing in the engine or the scripts changes.
- Memory. On the DS the game keeps a small table in memory and reads the rest from the cartridge when it is said (banks, below).
- Checks. The build measures every line with the game’s font before the game runs. A line too wide for its box is an error with its line number, not a surprise on a player’s screen.
text.txt
Section titled “text.txt”text.txt at the project’s root is key = text lines. The engine’s own keys come first,
in the engine’s order (ploom new writes them); your own follow. From the sample:
# The engine's own words.yes = Yesno = Nomenu_party = Partymenu_bag = Bagplayer_name = Wrenrival_name = Sable
lab_door = The door does not give.\nA card in the glass: {color:red}CLOSED{color:default}\nuntil morning.player_name and rival_name are the names a new game starts with, before the player
types their own. Lines the engine shows on its screens (opt_speed, fish_bite,
title_new, cur_coins) are keys here too, so a game words its whole interface
itself.
A script says a line by its key or by text in quotes:
say lab_doorsay "Not tonight."Text in quotes is collected into the script’s own module. A key is a line of the project’s text, which the translation step and the width check both see.
Control codes
Section titled “Control codes”| Code | Meaning |
|---|---|
\n |
The sentence goes on on the next line. When both lines of the box are full, the box waits for a button and the text moves up a line |
\p |
A new paragraph: the box waits for a button, then it is wiped |
\r |
Wait, then scroll: the box waits for a button wherever it is, then the text moves up a line |
{player}, {rival} |
The names |
{var:0} to {var:7} |
What a script put in message buffers 0 to 7 |
{color:red}, {color:blue}, {color:default} |
The colour from here on |
{pause:N}, {wait} |
Stop for N ticks (1 to 255); wait for a button |
\s |
A space (a value is trimmed, so a leading or trailing space is written \s) |
Use \n inside a thought and \p between thoughts. They look different on screen, and
players read the difference. From the sample:
watch_crossing = Hold on.{pause:20} It is past the last bell.\nNobody walks these streets now.\pThe lab is shut till morning,\nand I keep count of who goes by.Text in quotes inside a script takes \n, \p, \r and the buffers as {0} to {7}.
Placeholders
Section titled “Placeholders”buffer puts a name or a number into a message buffer for the next lines:
buffer 0, species, temp(0)say "The {0} looks back at you."The kinds are number, item, species, move, map, player, rival, pocket,
tmmove and nickname. A line can also be made as the script runs, with text and
name, and kept in a variable (a text value):
temp(0) = menu(text("{0}'s books, read to pieces.", name(player)), columns: 2) { ... }Text values live in eight registers of 64 bytes, reused in turn and never saved. A script that needs a name later asks for it again. The language guide has the rules.
A large game puts more text in files of a text/ folder, also key = text lines,
without engine keys. Each file is a bank. text.txt is always in memory; a bank is read
from the game’s data when one of its strings is said, and the four banks used last stay
while they fit in 32 KB. The sample keeps one bank, text/gallery.txt:
gallery_scroll = The lamp at the crossing is out.\rSomeone will see to it\nbefore the last bell.A key is used once over all files. sayline first, n says the n-th line after
first, for a message chosen at run time.
Text box
Section titled “Text box”The box shows two lines. Letters appear at the speed the player picks on the options screen: slow, mid or fast, which is 8, 4 or 1 ticks a letter, measured from the original games (decision 88). Holding A or B speeds the text up only after a fresh press. A bobbing arrow waits at the end of each page.
The box’s frame is one of a set the player chooses from; signs have their own. A game
draws its frames as pictures laid over the engine’s skin:
graphics/ui/skin/window.png for windows and graphics/ui/skin/frame_<n>.png for text
box frame n. The picture rules are on the art page.
sign shows its text in the sign’s box instead of the talk box:
on read signpost { sign "ASHGROVE\nNorth: Field Station\nEast: the old road"}sign text, style, icon picks another frame of the skin (one look a kind of sign) and a
small picture from graphics/ui/sign_icons/ shown at the left, as some generation-4
signs show a map. The map settings page covers the location
banner, which shows a map’s name on arrival.
Naming
Section titled “Naming”askname player and askname rival open the naming screen with the current name
typed, and save what is confirmed. {player} and {rival} then show it everywhere.
namemon slot renames a creature (see Game systems). The
sample’s logbook asks for a name and saves:
askname playerbuffer 0, playerif save() { say "Signed: {0}."}The font is graphics/ui/font.pff, a bitmap font with a width for each glyph. A project
copies a ready-made one; the importer writes an imported game’s own font from its data.
The build refuses a font that lacks a character the text or the engine uses.
Planned: converting a creator’s own font from a picture and a width table. Until then a new font needs Rust (see Rust extensions).
Overflow
Section titled “Overflow”A line wider than its box is an error with its line number. [text] wide_text = "cut"
in game.toml turns it into a note and lets the box cut the line, for text written for
other windows, as an import’s is. Every key is in the
game.toml reference.
Translations
Section titled “Translations”A translation can be an overlay today: ploom sync merges an overlay’s text.txt into
the source’s by key, and a file of the overlay’s text/ replaces the source’s file of
that name.
Planned (plan 45): several languages in one project, ploom check --text measuring
every string of every menu part in every language, and a language that moves a part
when its words are longer. Planned (plan 44): a text size row on desktop that draws
text at two or three times over a scaled picture; the DS’s boxes stay fixed.