Skip to content

Battles

A battle is the one part of the game where the rules are not yours alone. The rules themselves come from pl-battle, which plays the same battle as Pokémon Showdown from the same teams, choices and seed (see Showdown conformance). What a game decides is who fights, where, how it looks and sounds, and how clever the other side is. This page covers those. The rules a game may switch on are in Battle rules and gimmicks; mechanics of a game’s own are in Your own battle mechanics.

  • Wild battles start from the field with no script: a step in grass, a cave or water, a rod, a tree, a rock. The tables are in pbs/encounters.txt (Wild encounters).
  • Trainers who see you walk up and challenge the player. Their sight is an on sight script on the map (Characters); the example below is one.

Every other battle, and every trainer’s, is started by a script command. Each one waits for the battle to end and gives its outcome, so the script can react to a win or a loss:

Command Battle
wildbattle one wild creature
wilddouble two wild creatures at once
trainerbattle a trainer, one creature a side
doublebattle a trainer, two creatures a side
tagbattle two trainers, each with a team of their own, against the player
multibattle the player and a partner trainer against two trainers

Their arguments are in the script language reference.

The sample’s gate watchman, from scripts/town.pfs, is a trainer who sees the player. The intro: line is said before the battle, defeat: when the trainer loses:

on sight beat_watch, 5 when STORY >= 5 && !BEAT_GATE_WATCH {
lock
emote self, alert
approach
trainerbattle NIGHT_WATCH, "Harl", 0,
intro: "The station's been robbed and here you are.",
defeat: "Go on, then. I never saw you."
if lastresult() == 1 {
set BEAT_GATE_WATCH
setbadge 0
setrule level_cap, 20
# ... (shortened: he steps aside and hands over capsules)
}
release
}

Once beaten he offers a spar. The extra arguments make it a practice battle: the party is healed after a loss and the script goes on (lose: rest), no money changes hands (money: false), the battle sits outside the rules of a challenge run (exempt: true), and the trainer plays at the hard level whatever his class says:

trainerbattle NIGHT_WATCH, "Harl", 1,
defeat: "Hm. You've got the hang of it.",
lose: rest, money: false, exempt: true, mode: hard

Without lose: a lost battle sends the player back to where the party was last healed, and the script ends. That is the default because it is what the handheld games do; a story battle the player is meant to be able to lose says lose: stay.

The weir keeper in scripts/weir.pfs offers all three shapes for two: a double battle, a multi battle with his sister at the player’s side, and a tag battle against two watchmen.

doublebattle OLD_HANDS, "Wyn & Tam", 0,
defeat: "Two at once suits you.",
lose: rest, money: false, exempt: true

A trainer is a section of pbs/trainers.txt, named by class, name and an optional version number. Versions let one person have several teams: the watchman’s spar above is version 1. The format is Essentials’ PBS, so existing tools and habits carry over.

[RANGER,Odell]
LoseText = The woods taught you well.
Pokemon = THORNTAIL,18
Moves = LEAFLASH,SPOREPUFF,NEWGROWTH,GLOWER
Gender = male
Pokemon = GUSTREL,19
Item = SWIFTFEATHER
AbilityIndex = 1
Pokemon = COILBOLT,20

Lines indented under a Pokemon line belong to that creature: moves, item, ability, nature, IVs and EVs, form, nickname, shininess, ball. A trainer’s Items line gives the items it may use in battle. Classes are sections of pbs/trainer_types.txt, with their name, prize money and skill level.

A script can change a team just before its battle. The editing hook on trainerparty runs once a trainer’s team is made, and its pend* commands read and change each member. The sample uses it for level scaling; see Scripts and events and the scripting guide.

How a trainer picks its moves is a level, weakest first:

Level What it does
random any move it can use (wild creatures always play this way)
basic at random among moves that would not fail: no status on a creature that has one, no move the target is immune to, no stage already at its limit
medium the move that does the most by the damage formula’s main terms, with a little noise; a status or stage move when it plainly helps
hard each move, and switching when losing the matchup, tried one turn ahead on a copy of the battle
expert as hard, two turns ahead against the player’s two best replies; also switches out of a knockout and sends in the best matchup

Trying moves “on a copy of the battle” is possible because the battle is deterministic: the AI can play a turn forward and look at the result without touching the real battle. No level reads the choice the player is making this turn.

A trainer’s level is, in order: the script’s mode:; an AI = Expert line in the trainer’s section (an extension of PBS); otherwise its class’s SkillLevel (under 33 random, under 66 medium, else hard), or its BaseMoney when the class has no SkillLevel. The sample’s rangers have SkillLevel = 48 (medium) and its warden SkillLevel = 100 (hard).

Whatever its level, a trainer uses its Items as the handheld games’ trainers do: a healing item when its creature is low, a cure for a status, a stat item on a creature’s first turn. The first item is always at hand; the others become available as the trainer’s team runs down. Using an item is the trainer’s turn.

A battle is drawn in front of a picture of its place, a battle scene. Each scene is a folder of graphics/battle/scenes/, and a map names its scene in map.toml:

sample/maps/hill/map.toml
battle = "meadow"
graphics/battle/scenes/meadow/
background.png the place by day (256 x 192, up to 320 wide)
night.png optional: by night
near.png optional: the player's platform
far.png optional: the foe's platform
near_night.png, far_night.png optional

A map without battle uses the scene called default, and a project with neither has a plain scene of sky and ground bands. After dark, outdoors, the night picture is shown.

The DS shows such a picture as 8 × 8 tiles in a handful of 16-colour palettes, so the build fits it: only the top 144 rows are kept (the rest is behind the message box), at most 7 palettes of 15 colours and at most 352 different tiles. A picture that needs more is reduced until it fits, and the build says how much it changed. Repeated and mirrored tiles count once, so bands and symmetric shapes are cheap. The sample’s meadow uses 144 tiles in 2 palettes by day.

Battle grounds choose the platforms apart from the scene, as the DS games choose theirs by what the player stands on. Each folder of graphics/battle/platforms/ is a ground with its own near.png and far.png. A battle stands on the ground of the cell it begins on (the map’s battle_ground layer), else the map’s battle_ground in map.toml, else the scene’s own platforms. The build bakes each scene with each ground it can meet into one picture, so the battle still draws one.

A battle begun while surfing uses the scene named by surf_scene in game.toml’s [battle] table, on any map. A map’s weather carries into its battles.

graphics/trainers/ holds one folder a person: player/back.png (the player from behind; back_female.png for a player whose gender is 1), a class’s folder by its identifier in lower case (night_watch/front.png), or a trainer’s own by name, which wins over the class. A picture is a PNG of at most 15 colours; what is drawn may be 64 wide and 80 tall. The battle draws it pixel for pixel, so draw to size: an opponent about 68 pixels tall, feet on the lowest row; the player from behind about 59 tall, cut at the waist by the message box. Anyone without a picture is a plain card.

For a private game on official sprites, ploom fetch-trainers downloads trainer pictures from Showdown’s sprite server into git-ignored folders. Those pictures are Nintendo’s: never commit or share them. The command refuses a folder git does not ignore.

The two health boxes and the touch screen’s two panels can be the game’s own pictures. Without them the engine paints its own shapes in the skin’s colours. With them it lays the pictures where it painted and still draws everything that changes on top: names, levels, gender marks, HP and experience bars, HP figures, status marks, captions, move names and PP, the cursor and the balls.

graphics/battle/ui/
ui.toml where the text and bars go, and their colours
foe.png, player.png the health boxes
actions.png the action panel (fight, bag, run, party): 256 x 192
moves.png the move panel: 256 x 192
actions_pressed.png, moves_pressed.png optional pressed looks
move_types.png the move buttons' colours: a row a type
ball.png, foe_ball.png optional party balls

Every picture is optional. The limits are the DS’s: both boxes share one palette of 15 colours, including the colours the engine draws text and bars in, so give the text colours your picture already has. Move buttons are tinted by their move’s type, as on the DS: the button is drawn in the first row of move_types.png’s colours and shown in its type’s row, matched to types by name. ploom build reports what each part costs in colours, palettes and tiles, and refuses what does not fit with what to change.

The buttons sit at fixed rectangles of the engine’s ds layout; the pen and the cursor use them. Making those places part of the record too is plan 45’s work. Planned (plan 45): the battle interface is a record of the one UI system, like every other screen, so its places, looks and motions are data a project edits (Menus and UI styles).

[battle.music] names a track for wild battles, trainers, the rival (a trainerbattle ... called: rival), a final battle (music: final), victory and danger. [battle.sounds] names the hit, stat, status, capsule and alarm effects, and low_hp says what the player hears when a creature is in danger. Anything not named is silent. The sample names them all, from its own few sounds:

[battle]
low_hp = "alarm"
[battle.music]
wild = "town_night"
trainer = "town_night"
victory = "found_it"
[battle.sounds]
hit = "bump"
catch = "click"
alarm = "whistle"

The keys are in the game.toml reference; Audio covers tracks and effects.

Each move plays an animation after its name is shown: a short script of sprites, tints, shakes and battler motions, with fallbacks by type and category so every move shows something. See Move animations.

Format State
Singles built; checked against Showdown
Doubles built in the core and on the screen (four places, the target menu)
Tag, multi, wild doubles built: each place has an owner, each trainer its own AI
Triples the core assumes nothing about two a side, but triples are not written (plan 08)
Rotation not written: Showdown has no reference for it, and the owner decides first
SOS, raids Planned (plan 34): seams in the core that let a rule add a battler mid-battle or act more than once a turn; the rules themselves live in a game’s own Rust

Planned (plan 34): a battle can carry scripted events, such as a line from the foe at half health, a change of music, or a question to the player between turns. They are rule hooks on battle events that change the battle’s state on its own random numbers, and show themselves through the battle log, so replays stay exact.