Skip to content

Determinism

The same inputs and the same seed give the same game, frame for frame, on every platform. A session recorded on a Linux desktop and replayed in melonDS takes the same steps, draws the same random numbers, writes the same saves and shows the same pictures.

This is a rule for every crate that runs game logic (the project’s code conventions), not a hope. It holds because of four choices, each below.

The DS’s ARM9 has no floating-point unit. Floats would be slow there, and their results can differ between processors and compilers. So the crates that run on DS use no floating point at all. Numbers with a fraction use one shared fixed-point type from pl-core:

/// A fixed-point number: `i32` with 12 fractional bits (1.0 is 4096).
pub struct Fx(pub i32);

Twelve fractional bits is the DS’s own 3D format, so positions and matrices go to the hardware unchanged. Every operation is integer arithmetic with a stated rounding: multiplication rounds towards negative infinity, as the DS hardware does, and dividing by zero gives zero, because on the DS there is nothing to report it to. Angles are 16-bit, 65,536 units to a turn, so adding angles wraps by itself; sines come from a table.

Integer arithmetic gives the same bits on every machine. That is the whole point.

Floats are allowed in exactly two places, both of which only draw pixels: the desktop’s post-processing and the planned GPU renderer (plan 42). Neither can reach the game’s state.

All randomness goes through one generator in pl-core, Rng. It is the generator Pokémon Showdown’s simulator calls “gen5”: a 64-bit linear congruential generator whose upper 32 bits are the output, with Showdown’s ways of turning an output into a range, a chance or a shuffle.

pub fn next_u32(&mut self) -> u32 {
self.seed = self.seed.wrapping_mul(MUL).wrapping_add(ADD);
(self.seed >> 32) as u32
}

Why Showdown’s: a battle in PokeLoom and the same battle in Showdown must draw the same numbers in the same order, so their logs can be compared line by line (see Battle rules checked against Showdown). Using the same generator everywhere also means one implementation to test.

Rules that follow from it:

  • Nothing reads system randomness or the time of day. Seeds are constants of the program, or drawn from another generator that was itself seeded so. The battle takes its seed from the game’s own generator; the scripts have their own.
  • A generator’s state is part of the game’s state. It is saved, and it is in the digests below.
  • Drawing is never skipped. A roll whose outcome is certain still draws, if Showdown draws there; otherwise the sequence would part.
  • What only draws pixels draws no game numbers. Weather particles use a hash of their own index, never the game’s generator, so a setting that shows more rain cannot change the next battle. The replay proof plays a session in the rain at four times the particles and requires the same state at every tick.

Logic runs at a fixed 60 ticks a second on every platform. At each tick a game reads the outside world through one value and nothing else:

/// Everything a game may read about the outside world for one tick.
pub struct Tick {
pub n: u32, // ticks since the session started
pub pads: [Input; MAX_PLAYERS], // each player's buttons and pen
pub clock_secs: i64, // local date and time in seconds
}

The game never asks the platform for the time, a file’s age or the screen’s size in the middle of a tick. What it reads is what the tick gives it, and what the tick gives it can be recorded.

The clock. The game clock is the clock at tick 0 plus the ticks run. A DS frame is not exactly a sixtieth of a second, and a desktop window can be paused, so while the input is live the runner compares the game clock with the platform’s now and then and moves it by the difference. Each move is written into the input log; a replay makes the same moves at the same ticks and never reads the platform’s clock.

pl-game records the input of every tick to an input log: four bytes a tick (buttons, the pen’s x and y), the clock at tick 0 in the header, and records for the clock’s moves, for bytes received from the network, and for other players’ inputs. Replaying the log reproduces the session exactly, on any platform.

Because every source of difference goes through the log, a replay needs nothing else: not the original machine, not the network, not the clock.

Tests. A recorded session is a test. cargo xtask test-nds plays sessions on the desktop with no window and in melonDS with no window; their logs must be equal, 2D pictures equal pixel for pixel, 3D pictures within 1 %. Most bugs are caught on the host, in ordinary cargo test runs that replay logs, long before an emulator is started.

Proofs. The runner can log digests of the game’s logic every N ticks: a hash of the world (positions, facing, flags, variables, people, the generator, the clock), of the scripts’ state and of the battle. Two runs that must agree are compared digest by digest, and a failure names the first tick that differs. This is how presentation settings are proved harmless; see Presentation and game state.

Bug reports. A player’s input log is the bug report: it replays the bug.

Link battles and co-op. Two machines that start from the same state and apply the same inputs stay in step, so only inputs need to cross the network (lockstep). Online replies enter the input log, so a replay of an online session is exact and needs no network. A link battle works between two desktops today; see Multiplayer overview.

Anything that lets the outside world into a tick another way. The rules that keep it out:

  • No floats, no std, no reading the platform from logic crates (only pl-game talks to the platform layer).
  • No presentation setting in a logic crate (a test refuses pl-present there).
  • No per-frame heap allocation in the game loop, so running out of memory cannot happen on one platform and not the other.
  • Every randomness through Rng, every input through Tick.