Options
Three things a game sets up with data and scripts alone, no Rust: rules (how the game plays), options (what the player may choose) and creature editing (what a script may change on a creature). Together they make difficulty settings, rewards, the rules of a challenge run, and cheats a player turns on.
A new game starts with the rules of game.toml. Each is off unless its line is there:
[rules]lose_money = "by_badges" # losing a battle costs moneylevel_cap = 20 # no training past it, no catch above itexp_all = true # experience to the whole partyno_battle_items = true # only balls from the bag in a battlebattle_style = "set" # or "shift" (the default)tera = true # the player's creatures may terastallize| Rule word | What it does when on |
|---|---|
level_cap |
No creature of the player’s gains experience past this level, and a ball thrown at a wild creature above it is not used. 0 is none |
exp_all |
Every creature of the party that can fight gains experience; those not in the battle half |
no_battle_items |
The bag in a battle lists balls only |
battle_style |
1 is the set style. The shift style is not built yet, so neither style offers a switch when a foe faints; the rule is kept for when it is |
tera |
The player’s creatures may terastallize, one a battle |
challenge, challenge_box, challenge_first, challenge_over |
The challenge mode (below) |
A script reads a rule with rule and changes it with setrule. Until a script sets one,
the game follows game.toml; once one is set, the save keeps all of them, so a later
change to game.toml affects new games only. The sample’s town gives the first badge
for beating the gate watch, and a level cap with it:
if lastresult() == 1 { set BEAT_GATE_WATCH setbadge 0 setrule level_cap, 20}Other rules choose one game’s behaviour as a whole: daycare, wild and bag, each
"emerald", "platinum", "heartgold", "black2" or "modern", and
keep_field_moves. They are described where they act: Game systems,
Wild encounters, Items and shops.
The battle’s own rules are on Battle rules.
Challenge mode
Section titled “Challenge mode”A challenge run (a “nuzlocke”) is a creature lost when it faints. A game offers it on the
title screen with [rules.challenge]:
[rules.challenge]on = true # the title screen offers it on a new gamelost = "box" # or "release"box = 18 # the box the lost are kept in, 1 to 20first = true # only the first creature met in an area may be caughtover = "title" # or "script"- A creature that faints in a battle is lost. With
lost = "box"it is kept, marked, in a box it can never leave; with"release"it is let go. - A battle a script marks
exempt: trueis outside the rules: a spar, a fight the story needs you to survive. - When nothing left can fight,
over = "title"ends the run without saving;"script"runs the shared file’son gameoverhook instead, and the script decides.
A script can turn the mode on or off at any time, without the title’s entry. The sample asks as the player first walks into the field station:
if !ASKED_RULES { set ASKED_RULES if yesno("Play on as a challenge?\nA creature that faints is lost.") { setrule challenge, 1 setrule challenge_first, 1 } closetext}Custom options
Section titled “Custom options”[ui.options] adds rows to the options screen, after the engine’s text speed and frame.
Each is a switch or a choice of two to four values, saved with the game. The sample adds
one:
[ui.options]max_evs = { label = "opt_max_evs", about = "opt_max_evs_about" }opt_max_evs = Max EVsopt_max_evs_about = On: the party gets the most effort\nvalues the rules allow, once.- The name (
max_evs) is what scripts use:getoption max_evs,setoption max_evs, 1,on option max_evs. labelandaboutare keys oftext.txt: the row’s name and the line shown under the table.valueslists two to four keys for the values’ names; without it the option is a switch named by the engine’sopt_offandopt_on.defaultis a new game’s value.- At most 16 options.
On leaving the screen the player is asked to keep the changes. For each option kept
changed, the shared file’s on option NAME hook runs once the menu has closed.
setoption changes a value without running the hook.
Editing creatures
Section titled “Editing creatures”monget slot, field reads a field of a party creature (or, with box: b, a boxed one);
monset slot, field, value sets it. Every change is held to the engine’s rules: effort
values at most 252 a stat and 510 in all, individual values 0 to 31, a move the creature
does not already know, an ability slot the species has. The stats are worked out again.
The fields are species, level, exp, ev, iv, nature, ability, shiny,
move, pp, item, friendship and hp.
A change of level learns no move and starts no evolution; the level cap does not bind
monset.
Cheats
Section titled “Cheats”The sample’s cheat is the option above and a hook in scripts/common.pfs. Switched on,
it gives every creature of the party the most effort values the rules allow:
on option max_evs when getoption(max_evs) == 1 { lock temp(0) = 0 while temp(0) < partycount() { monset temp(0), ev, 0, all monset temp(0), ev, 252, atk monset temp(0), ev, 252, spe monset temp(0), ev, 252, hp # 6 left of 510: it gets 6 temp(0) += 1 } say "The party's effort values are\nas high as the rules allow." release}Why build cheats this way: the engine needs no list of cheats, a game words its own, and everything a cheat changes is held to the same rules as play, so a save stays valid.
Difficulty
Section titled “Difficulty”A level cap is a rule a script raises as the story goes (setrule level_cap, 30 after
the next badge). Level scaling is an editing hook. This one, in common.pfs, lifts every
trainer’s team to the party’s highest level, each member keeping its distance below the
team’s strongest:
on trainerparty(class, version) { let top = 0 for i in 0..partycount() { if monget(i, level) > top { top = monget(i, level) } } let most = 0 for m in 0..pendcount() { if pendget(level, m) > most { most = pendget(level, m) } } for m in 0..pendcount() { pendset level, top - (most - pendget(level, m)), m }}The same hook can add or remove members (pendadd, pendremove); on wildmon does the
same for wild creatures. A trainer’s AI level is chosen per battle with mode: on
trainerbattle (see Battles).
Planned (plan 46): level scaling as a setting, [rules.scale], for trainers and wild
creatures by the party’s highest or mean level or by badges, turned on and off by
setrule.
Planned
Section titled “Planned”Plan 44 sorts settings by what they touch. A row that changes when or how the game reads input is part of the game and is saved; a row that changes only pixels is presentation, kept on the device and never in the save (see Presentation settings).
- Planned (plan 44): battle options as built-in kinds of
[ui.options]rows (akindkey): battle speed, move animations on or off, a constant HP drain, a battle log, quick run and quick ball. A creator sets each default or fixes it. - Planned (plan 44): convenience: running by holding B, autosave, soft reset, a shorter day.
- Planned (plan 44): challenge modes chosen at a new game: Nuzlocke lives and a
ledger of first meetings, a seeded randomizer whose tables are made at load from the
save’s seed, and Soul Link for two players. A game offers them in a
[challenge]table.
The accessibility rows (colour-vision filters, less motion, less flashing) are built and can never be capped by a game: see Accessibility.