Skip to content

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 money
level_cap = 20 # no training past it, no catch above it
exp_all = true # experience to the whole party
no_battle_items = true # only balls from the bag in a battle
battle_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.

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 game
lost = "box" # or "release"
box = 18 # the box the lost are kept in, 1 to 20
first = true # only the first creature met in an area may be caught
over = "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: true is 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’s on gameover hook 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
}

[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 EVs
opt_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.
  • label and about are keys of text.txt: the row’s name and the line shown under the table.
  • values lists two to four keys for the values’ names; without it the option is a switch named by the engine’s opt_off and opt_on. default is 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.

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.

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.

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.

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 (a kind key): 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.