Skip to content

Installation

There is no release of PokeLoom yet. Today you build it from the repository, which needs the Rust toolchain. This page says what to install for each thing you want to do, and nothing more.

You want to You need
Make and play a game on desktop Git, Rust (rustup), on Linux two system libraries; Tiled to draw maps
Build a DS ROM and play it The above, plus the BlocksDS toolchain and melonDS 1.1
Fetch creature data A network connection, once per project
Run the battle conformance checks Node and a built Pokémon Showdown checkout (contributors only)

1. Rust. Install rustup. You do not choose a version: the repository pins a nightly toolchain in rust-toolchain.toml, and rustup fetches it on the first cargo command.

Terminal window
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none

Why nightly: the DS build needs to compile Rust’s core library for the DS’s processor (-Zbuild-std), which only nightly allows. The desktop build uses the same toolchain so that one pinned version serves both.

2. System libraries (Linux). The desktop program plays sound and reads gamepads, which need the development packages of ALSA and libudev:

Terminal window
sudo dnf install alsa-lib-devel systemd-devel # Fedora, RHEL, AlmaLinux
sudo apt-get install libasound2-dev libudev-dev # Debian, Ubuntu

Without them, build the desktop program with cargo build --release -p pl-desktop --no-default-features instead of the cargo xtask build-desktop below; it then runs without sound or gamepads. Windows and macOS need nothing here, but neither has been run yet.

3. The repository and the two programs.

Terminal window
git clone <this repository> PokeLoom && cd PokeLoom
cargo xtask build-desktop # the desktop program: target/release/pl-desktop
cargo build --release -p pl-cli # the ploom command: target/release/ploom

ploom run and ploom build desktop look for the desktop program beside ploom, so keep the two in the same folder. Put that folder on your PATH:

Terminal window
export PATH="$PWD/target/release:$PATH"
ploom help

4. Tiled. Maps are drawn in Tiled, a free map editor. Any recent version works; What Tiled features work lists what the build reads.

That is all an ordinary game needs. Continue with Your first project.

A DS ROM is built today with the engine’s own build, which calls the DS toolchain.

Tool Version Why
The Wonderful toolchain and BlocksDS BlocksDS 1.25.0 Links the DS program, packs the ROM, builds the sound bank
melonDS 1.1 The reference emulator; every DS check runs in it
Python 3 any 3.x Runs the hidden emulator checks

The exact commands, and the one administrator step (creating /opt/wonderful), are in the repository’s docs/SETUP.md. Then, for a project folder anywhere:

Terminal window
cargo xtask build-nds --project DIR # DIR/<folder name>.nds
cargo xtask run-nds --project DIR # builds it and opens it in melonDS

To save in melonDS, turn on its DLDI setting: a homebrew ROM saves to a file on an emulated SD card.

Planned (plan 13, plan 26): ploom build nds writes the ROM from prebuilt runtimes, including its file system and sound bank, with no Rust and no DS toolchain installed.

The repository has a Nix flake that gives every tool above, pinned, without touching the system: the Rust toolchain, BlocksDS, melonDS, Node, Python and the libraries.

Terminal window
git clone <this repository> PokeLoom && cd PokeLoom
nix develop

Nix needs flakes turned on. The first nix develop downloads about 3 GiB; later ones take seconds. The DS toolchain and melonDS are Linux only in the flake; Windows needs the manual route. A DS program built inside the shell is the same file, byte for byte, as one built outside it.

The repository holds no creature data (hard rule 1). Each project fetches Pokémon Showdown’s published data onto your machine, once, with a network connection:

Terminal window
ploom fetch-data # inside the project

It is cached outside any repository and copied into the project’s external/showdown-data, which gets its own .gitignore. A lock file records exactly what was fetched; commit that, never the data. See Creatures, moves and data.

The sample game needs none of this: its sixteen creatures and their data are original, in sample/pbs/.

Planned (plan 13, plan 26):

  • A download of ploom with the desktop runtime for each operating system and the DS runtime, built by CI.
  • ploom build nds and ploom build desktop on a machine with no Rust and no DS toolchain.
  • A game with Rust of its own still needs rustup; ploom checks for it and prints the exact install command (decision 326). A game without Rust needs nothing.

Until then, “no Rust needed” is true of making a game’s files, not of building PokeLoom itself.