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.
Starting a battle
Section titled “Starting a battle”- 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 sightscript 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: hardWithout 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: trueTrainers and their teams
Section titled “Trainers and their teams”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 = malePokemon = GUSTREL,19 Item = SWIFTFEATHER AbilityIndex = 1Pokemon = COILBOLT,20Lines 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.
Trainer AI
Section titled “Trainer AI”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.
Battle scenes
Section titled “Battle scenes”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:
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 optionalA 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.
Trainer pictures
Section titled “Trainer pictures”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.
Interface
Section titled “Interface”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 ballsEvery 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).
Music and sound
Section titled “Music and sound”[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.
Animations
Section titled “Animations”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.
Formats
Section titled “Formats”| 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.