@pkmn/engine 0.1.0-dev.d716e940 → 0.1.0-dev.d952b7c9

package/LICENSE

@@ -1,6 +1,4 @@
-The MIT License (MIT)
-
-Copyright (c) 2021-2023 pkmn contributors
+Copyright (c) 2021-2024 pkmn contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -3,7 +3,7 @@
   <br />
   <br />
   <a href="https://github.com/pkmn/engine/actions/workflows/test.yml">
-    <img alt="Test Status" src="https://github.com/pkmn/engine/workflows/Tests/badge.svg" />
+    <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" />
@@ -12,13 +12,21 @@
     <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 (code from the
+> [`old`](https://github.com/pkmn/engine/releases/tag/old) tag can also be used to experiment with a
+> more stable version of the codebase).
+
 <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
+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.
 
@@ -49,9 +57,11 @@ $ 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.11.0 dev
-build 2750 or greater, though tracks Zig's master branch so this may change in the future if
-breaking language changes are introduced:
+walk through how to install Zig on each platform - the engine code should work on Zig v0.11.0,
+though tracks Zig's master branch so this may change in the future if breaking language changes are
+introduced. Note that **due to a [bug in the Zig
+compiler](https://github.com/ziglang/zig/issues/17768), compiling with a version of Zig before
+`0.12.0-dev.876+aaf46187a` is recommended for performance**.
 
 `libpkmn` can be built with `-Dshowdown` to instead produce the Pokémon Showdown compatible
 `libpkmn-showdown` library. Furthermore, protocol message logging can be enabled through `-Dlog`.
@@ -67,40 +77,65 @@ $ npm install @pkmn/engine
 ```
 
 The driver depends on being able to find compiled Node/WASM addons in
-`node_modules/@pkmn/engine/build/lib` in order to be useful. When you install the package a
-[`postinstall` lifecycle script](https://docs.npmjs.com/cli/v8/using-npm/scripts) will run
-[`install-pkmn-engine`](src/bin/install-pkmn-engine) which will check for a compatible `zig`
-compiler (see above regarding minimum version) and download one to
-`node_module/@pkmn/engine/build/bin` if it can't find one, as well as looking for (and downloading,
-if necessary) the required Node headers needed to successfully build the addons natively.
+`node_modules/@pkmn/engine/build/lib` to be useful. When you install the package a [`postinstall`
+lifecycle script](https://docs.npmjs.com/cli/v8/using-npm/scripts) runs
+[`install-pkmn-engine`](src/bin/install-pkmn-engine) which checks for a compatible `zig` compiler
+(see earlier regarding minimum version) and download one to `node_module/@pkmn/engine/build/bin` if
+it can't find one, as well as looking for (and downloading, if necessary) the required Node headers
+needed to successfully build the addons natively.
 
 **If you have configured `npm` to `--ignore-scripts` you must either run `npx install-pkmn-engine`
 directly or build the addons manually and place the artifacts in the expected paths.**
 
 ### `pkmn`
 
-Until the [Zig package manager](https://github.com/ziglang/zig/projects/4) is completed, the
-recommended way of using the `pkmn` package in Zig is by either copying this repository into your
-project or by using [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) and then
-adding the following to your `build.zig`:
+To include `pkmn`, add it as a dependency in your project's
+[`build.zig.zon`](https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md) using [Zig's
+Package Management
+system](https://ziglang.org/download/0.11.0/release-notes.html#Package-Management):
+
+
+```zig
+.dependencies = .{
+    .pkmn = .{
+        .url = "https://github.com/pkmn/engine/archive/RELEASE.tar.gz",
+    },
+},
+```
+
+Replace `RELEASE` with the tag for the [release](https://github.com/pkmn/engine/releases) you wish
+to use (e.g. `0.1.0` or `nightly`) or the specific hash of any commit. Next, run `zig build` and
+copy the expected hash from the error message into your `build.zig.zon` alongside the `.url`:
+
+```sh
+$ zig build
+error: dependency is missing hash field
+            .url = "https://github.com/pkmn/engine/archive/nightly.tar.gz",
+                   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+note: expected .hash = "122056b93b403033cb7d9bed96a02c2eb8cc1275515976167726ada6eb4207e8ef8a",
+```
+
+Note that this hash is **not** going to be the same as the commit hash. After adding the hash to
+your `build.zig.zon` you will be able to import the `pkmn` package's build helpers into your
+`build.zig`:
 
 ```zig
 const std = @import("std");
-const pkmn = @import("lib/pkmn/build.zig");
 
-pub fn build(b: *std.build.Builder) void {
+pub fn build(b: *std.Build) void {
     ...
-    exe.addModule("pkmn", pkmn.module(b, .{ .showdown = true, .log = true }));
+    const pkmn = b.dependency("pkmn", .{ .showdown = true, .log = true });
+    exe.root_module.addImport("pkmn", pkmn.module("pkmn"));
     ...
 }
 ```
 
-The engine's `build.zig` exposes a `module` function that takes an options structure to allow for
-configuring whether or not Pokémon Showdown compatibility mode or protocol message logging should be
-enabled. Alternatively, you may set options via a `pkmn_options` [root source file
+The `pkmn` package can be configured with various options such as whether or not Pokémon Showdown
+compatibility mode or protocol message logging should be enabled. Alternatively, you may set options
+via a `pkmn_options` [root source file
 declaration](https://ziglang.org/documentation/master/#Root-Source-File). There are several
 undocumented internal options that can be tweaked as well via build or root options, though these
-options are not officially supported, affect correctness, and may change meaning or behavior without
+options aren't officially supported, affect correctness, and may change meaning or behavior without
 warning. Use at your own risk.
 
 ```zig
@@ -112,11 +147,11 @@ pub const pkmn_options = .{ .showdown = true, .log = true };
 For each Pokémon generation, the engine provides a battle structure with two functions - a function
 to `update` the battle's state based on both players' choices and a function that defines which
 `choices` are valid at that decision point (at the beginning of a battle both player's must "pass"
-as their first choice in order to switch in the first member of their party). If `-Dlog` protocol
-logging is enabled each update will produce logs which can be decoded into a buffer (`LOGS_SIZE`
-constants are provided to make it easy to allocate a buffer of the correct size). Each `update` will
-return a result to indicate either that the battle has terminated or which types of choices will be
-available for each player.
+as their first choice to switch in the first member of their party). If `-Dlog` protocol logging is
+enabled each update produces logs which can be decoded into a buffer (`LOGS_SIZE` constants are
+provided to make it easy to allocate a buffer of the correct size). Each `update` returns a result
+to indicate either that the battle has terminated or which types of choices are available for each
+player.
 
 Unlike [Pokémon Showdown's
 SIM-PROTOCOL](https://github.com/smogon/pokemon-showdown/blob/master/sim/SIM-PROTOCOL.md#choice-requests)
@@ -128,47 +163,50 @@ state or cause the engine to crash.**
 
 Battles may be played out from any point but to freshly initialize a battle which is yet to start
 the turn count and active Pokémon should be zeroed out (driver code should handle this for you).
-Most driver code should also provide helpers to make initialize a battle convenient - check the
+Most driver code should also provide helpers to make initializing battle convenient - check the
 respective documentation and examples for the bindings being used. The engine's [protocol
 documentation](docs/PROTOCOL.md) goes into greater detail on the specifics of updates and the
 potential logs that may result.
 
 *The snippets below are meant to merely illustrate in broad strokes how the pkmn engine can be used
-\- the [`examples`](src/examples) directory contains fully commented and runnable code.*
+\- the [`examples`](examples) directory contains fully commented and runnable code.*
 
 ### C
 
 [`pkmn.h`](src/include/pkmn.h) exports the C API for `libpkmn`. Symbols are all prefixed with
 `pkmn_` to avoid name collisions. If `-Dlog` is enabled and logging throws an error then the error
-will be encoded in the `pkmn_result` and can be checked with `pkmn_error`.
+is encoded in the `pkmn_result` and can be checked with `pkmn_error`.
 
 ```c
 #include <pkmn.h>
 
+pkmn_battle_options options;
+pkmn_gen1_battle_options_set(&options, ...);
 pkmn_battle battle = ...;
-uint8_t buf[PKMN_LOGS_SIZE];
+
 pkmn_result result;
 pkmn_choice c1 = 0, c2 = 0;
-while (!pkmn_result_type(result = pkmn_battle_update(&battle, c1, c2, buf, PKMN_LOGS_SIZE))) {
+while (!pkmn_result_type(result = pkmn_battle_update(&battle, c1, c2, &options))) {
   c1 = choose(PKMN_PLAYER_P1, pkmn_result_p1(result));
   c2 = choose(PKMN_PLAYER_P2, pkmn_result_p2(result));
+  pkmn_gen1_battle_options_set(&options, ...);
 }
 if (pkmn_error(result)) exit(1);
 ```
 
-[(full code)](src/examples/c/example.c)
+[(full code)](examples/c/example.c)
 
-The C API does not export any helpers for creating or accessing the opaque battle objects - it is
+The C API doesn't export any helpers for creating or accessing the opaque battle objects - it's
 instead intended to be used as the foundation for more ergonomic bindings in [other
 languages](#other) (the lack of namespaces and bit fields having an implementation-defined layout in
 C are the main contributing factors to the sparseness of what `libpkmn` chooses to expose).
 
 ### JavaScript / TypeScript
 
-`@pkmn/engine` depends on the [`@pkmn/data`](https://www.npmjs.com/package/@pkmn/data) which
+`@pkmn/engine` depends on the [`@pkmn/data`](https://www.npmjs.com/package/@pkmn/data) package which
 requires a `Dex` implementation to be provided as well. The `Battle.create` function can be used to
 initialize a `Battle` from the beginning, or `Battle.restore` can be used to re-instantiate a battle
-which is in already progress. If logging is enabled the output can be turned into Pokémon Showdown
+which is already in progress. If logging is enabled the output can be turned into Pokémon Showdown
 protocol via `Log.parse`.
 
 ```ts
@@ -191,20 +229,20 @@ while (!(result = battle.update(c1, c2)).type) {
 console.log(result);
 ```
 
-[(full code)](src/examples/js/example.ts)
+[(full code)](examples/js/example.ts)
 
-By default, the `@pkmn/engine` package will compile the engine with `-Dshowdown`, though by running
+By default, the `@pkmn/engine` package compiles the engine with `-Dshowdown`, though by running
 `install-pkmn-engine` directly and passing in `--options` you can override this default and build
 different configurations of the extension for the driver to use. The driver can support
 configurations both with and without Pokémon Showdown compatibility simultaneously if present. On
-update, the post-install script will attempt to rebuild whichever extensions it finds with the same
+update, the post-install script attempts to rebuild whichever extensions it finds with the same
 configuration parameters that were originally used meaning updating to the newest version of the
 library should be seamless.
 
 Despite relying on the native engine code, the `@pkmn/engine` code is designed to also work in
 browsers which support [WebAssembly](https://webassembly.org/). Running `npm run start:web` from the
-[`examples`](src/examples/js) directory will start a server that can be used to demonstrate the
-engine running in the browser.
+[`examples`](examples/js) directory starts a server that can be used to demonstrate the engine
+running in the browser.
 
 ### Zig
 
@@ -215,17 +253,17 @@ be used when logging is enabled to allow for easily printing e.g. to standard ou
 const std = @import("std");
 const pkmn = @import("pkmn");
 
-var random = std.rand.DefaultPrng.init(seed).random();
+var random = std.Random.DefaultPrng.init(seed).random();
 var choices: [pkmn.CHOICES_SIZE]pkmn.Choice = undefined;
 
 var battle = ...
-var log = ...
+var options = pkmn.battle.options(...);
 
 var c1 = pkmn.Choice{};
 var c2 = pkmn.Choice{};
 
-var result = try battle.update(c1, c2, log);
-while (result.type == .None) : (result = try battle.update(c1, c2, log)) {
+var result = try battle.update(c1, c2, &options);
+while (result.type == .None) : (result = try battle.update(c1, c2, &options)) {
     c1 = choices[random.uintLessThan(u8, battle.choices(.P1, result.p1, &choices))];
     c2 = choices[random.uintLessThan(u8, battle.choices(.P2, result.p2, &choices))];
 }
@@ -233,11 +271,11 @@ while (result.type == .None) : (result = try battle.update(c1, c2, log)) {
 std.debug.print("{}\n", .{result.type});
 ```
 
-[(full code)](src/examples/zig/example.zig)
+[(full code)](examples/zig/example.zig)
 
 The Zig package also supports some APIs which are difficult to expose elsewhere such as the
 `FixedRNG` which allows you to fully specify the exact RNG frames (which can be useful for ensuring
-certain outcomes/effects always occur) for a battle, though doing so will change the size of the
+certain outcomes/effects always occur) for a battle, though doing so changes the size of the
 `Battle` object.
 
 ### Other
@@ -248,7 +286,7 @@ simplify the process even further [`src/data`](src/data) contains JSON dumps of
 data, structure sizes and offsets, and protocol information used by the reference driver code. The
 following is a list of known `libpkmn` bindings written by developers outside of the [pkmn
 organization](https://github.com/pkmn) that may be helpful (though note that these projects may not
-necessarily be up-to-date/complete/correct - inclusion in this list does not imply endorsement):
+necessarily be up-to-date/complete/correct - inclusion in this list doesn't imply endorsement):
 
 | Language   | License   | URL                                  |
 | ---------- | --------- | ------------------------------------ |
@@ -276,7 +314,7 @@ By default, `pkmn-debug` expects to read [binary debug protocol](docs/PROTOCOL.m
 $ <cmd> | pkmn-debug > index.html
 ```
 
-Alternatively, if a single filename argument is passed to the `pkmn-debug` it will read from that
+Alternatively, if a single filename argument is passed to the `pkmn-debug` it reads from that
 instead:
 
 ```sh
@@ -298,14 +336,14 @@ Currently, most of the foundational work from stage 0 is done:
   
 - [benchmark and integration testing](src/test) infrastructure
 - [documentation](docs) about design, research, methodology, etc
-- definition and implementation of the [protocol](docs/PROTOCOL.md) that will be used by the engine
+- definition and implementation of the [protocol](docs/PROTOCOL.md) that's used by the engine
 
-**Stage 1 is currently in progress** and will see the implementation of the actual Generation I & II
+**Stage 1 is currently in progress** and involves the implementation of the actual Generation I & II
 battle engines, followed by Generation III & IV in stage 2. The implementation of further Pokémon
-generations is in scope for the project but should not be considered as part of the immediate
-roadmap (i.e. exploring the options for broadening support for old generation APIs will be given
-higher priority than implementing more modern generations). Furthermore, implementation of modern
-generations is soft-blocked on the [availability of high quality
+generations is in scope for the project but shouldn't be considered part of the immediate roadmap
+(i.e. exploring the options for broadening support for old generation APIs is given higher priority
+than implementing more modern generations). Furthermore, implementation of modern generations is
+soft-blocked on the [availability of high quality
 decompilations](https://github.com/orgs/pret/repositories) of the original games in question.
 
 Certain features will always be deemed **out of scope**:
@@ -323,10 +361,10 @@ The pkmn engine is distributed under the terms of the [MIT License](LICENSE).
 [^1]: In the case of Pokémon Showdown, only bugs which stem from a misimplementation of specific
   effects are reproduced in the engine, bugs which are the result of a misunderstanding of the
   fundamental mechanics of Pokémon or which simply arise due to specific Pokémon Showdown
-  implementation details that are not replicable without making the same (incorrect) architectural
-  choices are not. Furthermore, the "Pokémon Showdown" code referenced by this project includes
+  implementation details that aren't replicable without making the same (incorrect) architectural
+  choices aren't. Furthermore, the "Pokémon Showdown" code referenced by this project includes
   several [patches](docs/TESTING.md#patches) to improve accuracy and smooth over some of the more
   egregious implementation issues. In practical terms, the vast majority of games played out in the
-  pkmn engine's compatibility mode and on this patched Pokémon Showdown simulator will be the same,
-  it is only in a well defined and documented set of circumstances where the two implementations
+  pkmn engine's compatibility mode and on this patched Pokémon Showdown simulator are the same,
+  it's only in a well defined and documented set of circumstances where the two implementations
   diverge.

package/build/pkg/addon/browser.d.ts

@@ -0,0 +1,3 @@
+import type { Argument } from '../addon';
+export declare function load(showdown: boolean, addon?: Argument): Promise<WebAssembly.Exports>;
+export declare function loadSync(): void;

package/build/pkg/addon/browser.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.load = load;
+exports.loadSync = loadSync;
+async function load(showdown, addon) {
+    if (typeof addon === 'string' && addon !== 'wasm') {
+        throw new Error('Unable to load native addons in the browser!');
+    }
+    let wasm;
+    if (addon instanceof WebAssembly.Module) {
+        try {
+            wasm = (await WebAssembly.instantiate(addon));
+        }
+        catch (err) {
+            if (!(err instanceof Error))
+                throw err;
+            throw new Error(`Could not instantiate WASM module!\n${err.message}`);
+        }
+    }
+    else {
+        const name = `pkmn${showdown ? '-showdown' : ''}.wasm`;
+        try {
+            const response = !addon || addon === 'wasm' ? fetch(name)
+                : addon instanceof URL ? fetch(addon) : addon;
+            wasm = (await WebAssembly.instantiateStreaming(response)).instance;
+        }
+        catch (err) {
+            if (!(err instanceof Error))
+                throw err;
+            const message = !addon || addon === 'wasm'
+                ? `Could not find ${name} - did you run \`npx install-pkmn-engine\`?`
+                : addon instanceof URL
+                    ? `Could not fetch WASM module from '${addon.href}'!`
+                    : 'Could not instantiate WASM module!';
+            throw new Error(`${message}\n${err.message}`);
+        }
+    }
+    return wasm.exports;
+}
+function loadSync() {
+    throw new Error('You must `initialize` the WASM addon before using the engine!');
+}
+//# sourceMappingURL=browser.js.map

package/build/pkg/addon/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../src/pkg/addon/browser.ts"],"names":[],"mappings":";;AAGA,oBA+BC;AAED,4BAEC;AAnCM,KAAK,UAAU,IAAI,CAAC,QAAiB,EAAE,KAAgB;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,IAA0B,CAAC;IAC/B,IAAI,KAAK,YAAY,WAAW,CAAC,MAAM,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;gBAAE,MAAM,GAAG,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GAAG,OAAO,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;gBACvD,CAAC,CAAE,KAAiC,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7E,IAAI,GAAG,CAAC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;gBAAE,MAAM,GAAG,CAAC;YACvC,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,KAAK,KAAK,MAAM;gBACxC,CAAC,CAAC,kBAAkB,IAAI,6CAA6C;gBACrE,CAAC,CAAE,KAAiC,YAAY,GAAG;oBACjD,CAAC,CAAC,qCAAsC,KAAa,CAAC,IAAI,IAAI;oBAC9D,CAAC,CAAC,oCAAoC,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC;AACtB,CAAC;AAED,SAAgB,QAAQ;IACtB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;AACnF,CAAC"}

package/build/pkg/addon/node.d.ts

@@ -0,0 +1,3 @@
+import type { Argument } from '../addon';
+export declare function load(showdown: boolean, addon?: Argument): Promise<any>;
+export declare function loadSync(showdown: boolean): any;

package/build/pkg/addon/node.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.load = load;
+exports.loadSync = loadSync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ROOT = path.join(__dirname, '..', '..', '..');
+const LIB = path.join(ROOT, 'build', 'lib');
+const NODE = [path.join(LIB, 'pkmn.node'), path.join(LIB, 'pkmn-showdown.node')];
+const WASM = [path.join(LIB, 'pkmn.wasm'), path.join(LIB, 'pkmn-showdown.wasm')];
+async function load(showdown, addon) {
+    if (addon === undefined || typeof addon === 'string' && addon !== 'wasm') {
+        try {
+            return require(!addon || addon === 'node' ? NODE[+showdown] : addon).engine;
+        }
+        catch (err) {
+            if (!(err instanceof Error))
+                return err;
+            if (addon && addon !== 'node') {
+                throw new Error(`Unable to load native addon: '${addon}'\n${err.message}`);
+            }
+            else {
+                throw error(NODE[+showdown], err);
+            }
+        }
+    }
+    let wasm;
+    if (addon === 'wasm') {
+        try {
+            wasm = (await WebAssembly.instantiate(fs.readFileSync(WASM[+showdown]))).instance;
+        }
+        catch (err) {
+            throw error(WASM[+showdown], err);
+        }
+    }
+    else if (addon instanceof WebAssembly.Module) {
+        try {
+            wasm = (await WebAssembly.instantiate(addon));
+        }
+        catch (err) {
+            if (!(err instanceof Error))
+                throw err;
+            throw new Error(`Could not instantiate WASM module!\n${err.message}`);
+        }
+    }
+    else {
+        try {
+            const response = addon instanceof Promise ? addon : fetch(addon);
+            wasm = (await WebAssembly.instantiateStreaming(response)).instance;
+        }
+        catch (err) {
+            if (!(err instanceof Error))
+                throw err;
+            throw new Error(`Could not instantiate WASM module!\n${err.message}`);
+        }
+    }
+    return wasm.exports;
+}
+function loadSync(showdown) {
+    try {
+        return require(NODE[+showdown]).engine;
+    }
+    catch {
+        return undefined;
+    }
+}
+function error(file, err) {
+    if (!(err instanceof Error))
+        return err;
+    const message = `Could not find ${path.basename(file)} addon`;
+    return new Error(`${message} - did you run \`npx install-pkmn-engine\`?\n${err.message}`);
+}
+//# sourceMappingURL=node.js.map

package/build/pkg/addon/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/pkg/addon/node.ts"],"names":[],"mappings":"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"}

package/build/pkg/addon.d.ts

@@ -1,4 +1,6 @@
 import { Choice, Player, Result } from '.';
+export type Argument = string | URL | WebAssembly.Module | Promise<Response>;
+export declare function initialize(showdown: boolean, addon?: Argument): Promise<void | undefined>;
 export declare function check(showdown: boolean): void;
 export declare function supports(showdown: boolean, log?: boolean): boolean;
 export declare function update(index: number, showdown: boolean, battle: ArrayBuffer, c1?: Choice, c2?: Choice, log?: ArrayBuffer): Result;

package/build/pkg/addon.js

@@ -1,77 +1,58 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.size = exports.choose = exports.choices = exports.update = exports.supports = exports.check = void 0;
-const path = __importStar(require("path"));
+exports.initialize = initialize;
+exports.check = check;
+exports.supports = supports;
+exports.update = update;
+exports.choices = choices;
+exports.choose = choose;
+exports.size = size;
+const node_1 = require("./addon/node");
 const _1 = require(".");
-const ROOT = path.join(__dirname, '..', '..');
-let ADDON = undefined;
-function load() {
-    if (ADDON)
-        return ADDON;
-    let pkmn = undefined;
-    let showdown = undefined;
-    try {
-        pkmn = require(path.join(ROOT, 'build', 'lib', 'pkmn.node'));
-    }
-    catch { }
-    try {
-        showdown = require(path.join(ROOT, 'build', 'lib', 'pkmn-showdown.node'));
+const ADDONS = [];
+const loading = [];
+async function initialize(showdown, addon) {
+    if (loading[+showdown]) {
+        throw new Error(`Cannot call initialize more than once with showdown=${showdown}`);
     }
-    catch { }
-    if (!pkmn && !showdown) {
-        throw new Error('Could not find native addons - did you run `npx install-pkmn-engine`?');
-    }
-    return (ADDON = [pkmn, showdown]);
+    loading[+showdown] = (0, node_1.load)(showdown, addon);
+    loading[+showdown].then(a => {
+        ADDONS[+showdown] = a;
+    }).catch(() => {
+        loading[+showdown] = undefined;
+    });
+    return loading[+showdown]?.then(() => { });
 }
 function check(showdown) {
-    if (!load()[+showdown]) {
-        const opts = ADDON[+!showdown].options.log ? ['-log'] : [];
+    if (!addons(showdown)[+showdown]) {
+        const opts = ADDONS[+!showdown].options.log ? ['-log'] : [];
         if (showdown)
             opts.push('-Dshowdown');
         throw new Error(`@pkmn/engine has ${showdown ? 'not' : 'only'} been configured to support Pokémon Showdown.` +
             `\n(running \`npx install-pkmn-engine --options='${opts.join(' ')}'\` can fix this issue).`);
     }
 }
-exports.check = check;
 function supports(showdown, log) {
-    if (!load()[+showdown])
+    if (!addons(showdown)[+showdown])
         return false;
     if (log === undefined)
         return true;
-    return ADDON[+showdown].options.log === log;
+    return ADDONS[+showdown].options.log === log;
+}
+function addons(showdown) {
+    if (ADDONS[+showdown])
+        return ADDONS;
+    // If we havem't been initialized attempt to autoload if we're on Node
+    ADDONS[+showdown] = (0, node_1.loadSync)(showdown);
+    return ADDONS;
 }
-exports.supports = supports;
 function update(index, showdown, battle, c1, c2, log) {
-    return _1.Result.decode(ADDON[+showdown].bindings[index]
+    return _1.Result.decode(ADDONS[+showdown].bindings[index]
         .update(battle, _1.Choice.encode(c1), _1.Choice.encode(c2), log));
 }
-exports.update = update;
 function choices(index, showdown, battle, player, choice, buf) {
     const request = choice[0] === 'p' ? 0 : choice[0] === 'm' ? 1 : 2;
-    const n = ADDON[+showdown].bindings[index].choices(battle, +(player !== 'p1'), request, buf);
+    const n = ADDONS[+showdown].bindings[index].choices(battle, +(player !== 'p1'), request, buf);
     // The top-level API signature means our hands our tied with respect to
     // writing really fast bindings here. The simplest approach would be to return
     // the ArrayBuffer the bindings populate as well as its size and only decode a
@@ -95,17 +76,14 @@ function choices(index, showdown, battle, player, choice, buf) {
         options[i] = _1.Choice.decode(data[i]);
     return options;
 }
-exports.choices = choices;
 function choose(index, showdown, battle, player, choice, buf, fn) {
     const request = choice[0] === 'p' ? 0 : choice[0] === 'm' ? 1 : 2;
-    const n = ADDON[+showdown].bindings[index].choices(battle, +(player !== 'p1'), request, buf);
+    const n = ADDONS[+showdown].bindings[index].choices(battle, +(player !== 'p1'), request, buf);
     const data = new Uint8Array(buf);
     return _1.Choice.decode(data[fn(n)]);
 }
-exports.choose = choose;
 function size(index, type) {
-    const bindings = (ADDON[1] ?? ADDON[0]).bindings[index];
+    const bindings = (ADDONS[1] ?? ADDONS[0]).bindings[index];
     return type[0] === 'c' ? bindings.CHOICES_SIZE : bindings.LOGS_SIZE;
 }
-exports.size = size;
 //# sourceMappingURL=addon.js.map