engine

<p align="center">
  <img alt="pkmn/engine" width="192" height="192" src="https://pkmn.cc/engine.svg" />
  <br />
  <br />
  <a href="https://github.com/pkmn/engine/actions/workflows/test.yml">
    <img alt="Test Status" src="https://github.com/pkmn/engine/actions/workflows/test.yml/badge.svg" />
  </a>
  <a href="#status">
    <img alt="WIP" src="https://img.shields.io/badge/status-WIP-red.svg" />
  </a>
  <a href="https://github.com/pkmn/engine/blob/master/LICENSE">
    <img alt="License" src="https://img.shields.io/badge/License-MIT-blue.svg" />
  </a>
</p>

> [!WARNING]
> **This project is under heavy development** and currently the `main` branch contains numerous breaking
> changes which may not work and which are not fully documented. Please **wait for the forthcoming
> initial v0.1 release** before depending on this project.

<hr />

A minimal, complete, Pokémon battle simulation engine optimized for performance and
[designed](docs/DESIGN.md) for tooling, embedded systems, and [artificial
intelligence](https://github.com/pkmn/0-ERROR) use cases. This engine aims to be a frame-accurate and
[bug-for-bug compatible](http://www.catb.org/jargon/html/B/bug-for-bug-compatible.html)
implementation of both Pokémon battles as defined by the original game code and the [Pokémon
Showdown](https://pokemonshowdown.com/)[^1] simulator which represents Pokémon battling as practically
interpreted online.

The pkmn engine is [**more than 1000× faster**](docs/TESTING.md#results) than the
[patched](docs/TESTING.md#patches) [Pokémon Showdown simulator
code](https://github.com/smogon/pokemon-showdown) when playing out supported formats in
compatibility mode and is extensively [tested](docs/TESTING.md) and [documented](docs). Note,
however, that the engine is **not a fully featured simulator** but is instead a low-level library
which can be used as a building block for more advanced use cases.

## Installation

This repository hosts both the engine code (written in [Zig](https://ziglang.org/)) and the
reference driver code (written in [TypeScript](https://www.typescriptlang.org/)).

### `libpkmn`

Binaries of the engine code can be downloaded from the
[releases](https://github.com/pkmn/engine/releases) tab on GitHub, or you can [download the source
code](https://github.com/pkmn/engine/archive/refs/heads/main.zip) directly and build it with the
latest `zig` compiler, see `zig build --help` for build options:

```sh
$ curl https://github.com/pkmn/engine/archive/refs/heads/main.zip -o engine.zip
$ unzip engine.zip
$ cd engine
$ zig build --prefix /usr/local -Doptimize=ReleaseFast
```

The Zig website has [installation instructions](https://ziglang.org/learn/getting-started/) which
walk through how to install Zig on each platform - the engine code should work on Zig v0.16.0 or
greater, though tracks Zig's master branch so this may change in the future if breaking language
changes are introduced.

`libpkmn` can be built with `-Dshowdown` to instead produce the Pokémon