Skip to content

Creature data

A creature game needs species, moves, abilities, items, a type chart, trainers and wild tables. PokeLoom reads them from two sources and compiles them into the game’s pack:

Source What it is Where it lives
Pokémon Showdown’s data The battle simulator’s published files: species, moves, abilities, items, learnsets, the type chart Fetched by ploom fetch-data into a cache on your machine and the project’s external/showdown-data/
PBS files The text format of Pokémon Essentials v21.1: pokemon.txt, moves.txt, types.txt, items.txt, trainers.txt, encounters.txt and the rest The project’s pbs/ folder
ploom fetch-data fetch Showdown's files once; afterwards no network is needed
ploom pack compile the data into pack/game.pak and write pack/game.sym
ploom build does the pack step too, with everything else

Showdown is the default because the battle rules are checked against Showdown (hard rule 5): the same data the rules are tested on is the data a game plays. ploom fetch-data takes the commit the engine’s rules are checked against unless you name another, and writes it to showdown-data.lock so the project builds the same data tomorrow. What Showdown does not have (catch rates, yields, prices, trainers, wild tables) comes from the PBS folder. With both, Showdown is the base and PBS fills the rest. [game] data in game.toml chooses "showdown", "pbs" or "both"; without it, the build uses what the project has. See the game.toml reference.

The species, moves and descriptions of the official games are Nintendo’s. The repository holds none of them, in code, tests, fixtures or history (hard rule 1). Identifiers are allowed: a test may name a move by its ID. Values are not.

So the data is fetched on the creator’s machine, into folders git ignores, and never committed. The only data in the repository is the sample’s sample/pbs/: sixteen invented creatures, forty invented moves, original types and items, in the PBS format so it doubles as a template.

Every game, made or imported, plays on one modern data set (decision 204). A species has the same stats, types and learnset in an imported generation-3 game as in a new one, and the battle rules are the same. What a game owns is its content: which species appear, its dex lists and dex text, its machines and tutors, its shops, trainers, wild tables and gifts. An import maps its game’s numbers to shared identifiers and keeps its content.

Why one set: five reference games and a creator’s own game can share every creature, every rule and every test, and a game can mix content from several sources without two copies of the same species disagreeing. See One model.

PBS names an effect; it does not hold it. A move’s FunctionCode and each ability and item identifier map to behaviour written in the engine. ploom pack --coverage prints every function code, ability and held item the data uses and whether the engine runs it. A code the engine does not understand does only its damage, and --release refuses such moves and abilities unless you --allow them.

A game’s types are the sections of pbs/types.txt; nothing in the engine lists them. A ninth type in the sample’s format is data only:

[GLOOM]
Name = Gloom
IconPosition = 8
IsSpecialType = true
Weaknesses = EMBER,GLOOM
Resistances = SHADE
Immunities = PLAIN

Weaknesses, Resistances and Immunities are what the type takes when it defends; other types’ own lines say what they take from it. The chart is built from these lines. StatusImmunities = par,brn is this engine’s own key. A game may have up to 255 types.

The type’s look is its name, a row of colours and an icon (decision 277):

  • Icon. graphics/ui/types.png is a sheet of icons 32 pixels wide and 12 tall, one above another; IconPosition is the row. A type without an icon shows its name.
  • Colours. With a move_types.png in the battle interface, the battle’s move buttons take a row of 16 colours a type, in the order of types.txt.

ploom check --art says which type has no icon or no colour row, with the fix.

A move is a section of pbs/moves.txt; a creature learns it from its species’ Moves, TutorMoves or EggMoves, or from a machine item whose Move = names it.

[GLOOMBOLT]
Name = Gloombolt
Type = GLOOM
Category = Special
Power = 70
Accuracy = 100
TotalPP = 15
Target = NearOther
FunctionCode = None
Flags = CanProtect,CanMirrorMove
Description = A bolt of darkness that rises from the ground.

With data alone a move can be plain damage of any type, power, accuracy, priority and target; raise or lower stages (RaiseUserAtk1Spd2, LowerTargetSpeed1, with EffectChance for a secondary effect); give a status the engine has (ParalyzeTarget, BurnTarget); or behave as a built-in move of the same identifier, which runs the engine’s own code, checked against Showdown.

A genuinely new effect needs more. Three routes are designed (plan 34):

  1. Planned (plan 34): effect lines in the record that combine the engine’s primitives (“power doubles in rain”), with no code.
  2. Planned (plan 34): a script hook on a battle event.
  3. Rust in the game’s own crate: a table of new moves, types and abilities and overrides of built-in ones, reported by the build. This runs on desktop today; Planned (plan 46): the same crate on DS.

See Custom mechanics.

graphics/creatures/ holds one folder a species, named by its identifier in lower case:

graphics/creatures/
sproutail/
front.png as the other side sees it in battle; the summary's portrait
back.png as its own side sees it
icon.png the party and storage screens' small picture
follow.png the creature walking behind the player (a game with followers)
  • Ordinary PNGs. What is transparent around the drawing is trimmed, so margins do not matter. A front or back may be 96 × 96 at most.
  • 15 colours and transparency a picture: a DS sprite has 16 colours, one of them clear. More are reduced, and the build says which.
  • In battle a creature stands on the middle of its lower edge: draw its feet at the bottom.
  • An icon may have two frames, shown in turns as the generation-4 games do. A front_2.png of the same size is a second front frame.
  • Any picture may be missing. With only a front, the back is the front and the icon is the front made small. A species with no folder gets a plain card with its name, so a game can be played before it has art.

The pack keeps a record a species and reads only the pictures on screen, so a large roster costs cartridge space, not memory. Not built yet: shiny battle pictures and pictures by gender.

The sixteen creatures in sample/graphics/creatures/ are an openly licensed sprite pack (CC BY 4.0), credited in CREDITS.md. A game that keeps them must credit their author.

ploom fetch-sprites downloads creature fronts, backs and icons, item icons and type icons in the style of the project into its folders, as one merged set: each species takes the best source. --community adds pictures the community drew, whose projects ask for credit; --cries adds cries as cry lines of audio/audio.txt. ploom fetch-trainers does the same for trainer pictures.

These pictures are Nintendo’s or their artists’. The command writes only into folders git ignores, refuses tracked paths unless told otherwise, and writes a manifest and a credits file beside them. Never commit them and never ship them.

Scripts read the pack’s records with speciesget, moveget and itemget, and the party with monget, partyfind and partytally:

if speciesget(partyspecies(0), type1) == FIRE_TYPE { ... }

The fields are listed in the reference.

A story can be played on another roster. Its scripts name creatures, items and trainer classes only by the part they play, in one symbol file:

scripts/roles.pfsym
species STARTER_A = 4
item MEDICINE = 19
trainer WATCH = 4

A copy gives each role the number its own pack gives the thing that plays it. Its own files go in overlay/ (a game.toml, a text.txt of changed lines, a whole PBS set), and ploom sync <source> copies the source and lays the overlay on top. Edit the overlay, never the synced files: the next sync writes them again. Teams, wild tables, shops and prices are data, so they follow the copy’s roster. See Assets and style chains for borrowing another project’s look.