@pkmn/engine 0.1.0-dev.437f6a52 → 0.1.0-dev.46307385

package/README.md

@@ -12,6 +12,14 @@
     <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
@@ -49,9 +57,9 @@ $ 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 3859 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 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 Showdown compatible
 `libpkmn-showdown` library. Furthermore, protocol message logging can be enabled through `-Dlog`.
@@ -67,12 +75,12 @@ $ 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.**
@@ -100,7 +108,7 @@ configuring whether or not Pokémon Showdown compatibility mode or protocol mess
 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 +120,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,7 +136,7 @@ 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.
@@ -140,7 +148,7 @@ potential logs that may result.
 
 [`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>
@@ -161,17 +169,17 @@ if (pkmn_error(result)) exit(1);
 
 [(full code)](src/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
@@ -196,18 +204,18 @@ console.log(result);
 
 [(full code)](src/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`](src/examples/js) directory starts a server that can be used to demonstrate the engine
+running in the browser.
 
 ### Zig
 
@@ -240,7 +248,7 @@ std.debug.print("{}\n", .{result.type});
 
 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
@@ -251,7 +259,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                                  |
 | ---------- | --------- | ------------------------------------ |
@@ -279,7 +287,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
@@ -301,14 +309,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**:
@@ -326,10 +334,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.zig

@@ -35,6 +35,7 @@ pub fn build(b: *std.Build) !void {
     const strip = b.option(bool, "strip", "Strip debugging symbols from binary") orelse false;
     const pic = b.option(bool, "pic", "Force position independent code") orelse false;
     const emit_asm = b.option(bool, "emit-asm", "Output .s (assembly code)") orelse false;
+    const emit_ll = b.option(bool, "emit-ll", "Output .ll (LLVM IR)") orelse false;
 
     const cmd = b.findProgram(&.{"strip"}, &.{}) catch null;
 
@@ -65,16 +66,16 @@ pub fn build(b: *std.Build) !void {
         const addon = b.fmt("{s}.node", .{name});
         const lib = b.addSharedLibrary(.{
             .name = addon,
+            .main_pkg_path = .{ .path = "." },
             .root_source_file = .{ .path = "src/lib/binding/node.zig" },
             .optimize = optimize,
             .target = target,
         });
         lib.addOptions("build_options", options);
-        lib.setMainPkgPath("./");
-        lib.addSystemIncludePath(headers);
+        lib.addSystemIncludePath(.{ .path = headers });
         lib.linkLibC();
         if (node_import_lib) |il| {
-            lib.addObjectFile(il);
+            lib.addObjectFile(.{ .path = il });
         } else if ((try std.zig.system.NativeTargetInfo.detect(target)).target.os.tag == .windows) {
             try std.io.getStdErr().writeAll("Must provide --node-import-library path on Windows\n");
             std.process.exit(1);
@@ -94,6 +95,7 @@ pub fn build(b: *std.Build) !void {
     } else if (wasm) {
         const lib = b.addSharedLibrary(.{
             .name = name,
+            .main_pkg_path = .{ .path = "." },
             .root_source_file = .{ .path = "src/lib/binding/wasm.zig" },
             .optimize = switch (optimize) {
                 .ReleaseFast, .ReleaseSafe => .ReleaseSmall,
@@ -102,7 +104,6 @@ pub fn build(b: *std.Build) !void {
             .target = .{ .cpu_arch = .wasm32, .os_tag = .freestanding },
         });
         lib.addOptions("build_options", options);
-        lib.setMainPkgPath("./");
         lib.stack_size = wasm_stack_size;
         lib.rdynamic = true;
         lib.strip = strip;
@@ -120,14 +121,14 @@ pub fn build(b: *std.Build) !void {
     } else if (dynamic) {
         const lib = b.addSharedLibrary(.{
             .name = name,
+            .main_pkg_path = .{ .path = "." },
             .root_source_file = .{ .path = "src/lib/binding/c.zig" },
             .version = try std.SemanticVersion.parse(version),
             .optimize = optimize,
             .target = target,
         });
         lib.addOptions("build_options", options);
-        lib.setMainPkgPath("./");
-        lib.addIncludePath("src/include");
+        lib.addIncludePath(.{ .path = "src/include" });
         maybeStrip(b, lib, b.getInstallStep(), strip, cmd);
         if (pic) lib.force_pic = pic;
         b.installArtifact(lib);
@@ -135,17 +136,30 @@ pub fn build(b: *std.Build) !void {
     } else {
         const lib = b.addStaticLibrary(.{
             .name = name,
+            .main_pkg_path = .{ .path = "." },
             .root_source_file = .{ .path = "src/lib/binding/c.zig" },
             .optimize = optimize,
             .target = target,
         });
         lib.addOptions("build_options", options);
-        lib.setMainPkgPath("./");
-        lib.addIncludePath("src/include");
+        lib.addIncludePath(.{ .path = "src/include" });
         lib.bundle_compiler_rt = true;
         maybeStrip(b, lib, b.getInstallStep(), strip, cmd);
         if (pic) lib.force_pic = pic;
-        if (emit_asm) lib.emit_asm = .emit;
+        if (emit_asm) {
+            b.getInstallStep().dependOn(&b.addInstallFileWithDir(
+                lib.getEmittedAsm(),
+                .prefix,
+                b.fmt("{s}.s", .{name}),
+            ).step);
+        }
+        if (emit_ll) {
+            b.getInstallStep().dependOn(&b.addInstallFileWithDir(
+                lib.getEmittedLlvmIr(),
+                .prefix,
+                b.fmt("{s}.ll", .{name}),
+            ).step);
+        }
         b.installArtifact(lib);
         c = true;
     }
@@ -217,19 +231,15 @@ pub fn build(b: *std.Build) !void {
     fuzz_config.tool.name = "fuzz";
     const fuzz = tool(b, "src/test/fuzz.zig", fuzz_config);
 
+    const analyze = tool(b, "src/tools/analyze.zig", tools);
     const dump = tool(b, "src/tools/dump.zig", tools);
     const serde = tool(b, "src/tools/serde.zig", tools);
     const transitions = tool(b, "src/tools/transitions.zig", tools);
 
-    const lint_exe =
-        b.addExecutable(.{ .name = "lint", .root_source_file = .{ .path = "src/tools/lint.zig" } });
-    if (tests.build) tests.step.dependOn(&lint_exe.step);
-    const lint = b.addRunArtifact(lint_exe);
-
+    b.step("analyze", "Run LLVM analysis tool").dependOn(&analyze.step);
     b.step("benchmark", "Run benchmark code").dependOn(&benchmark.step);
     b.step("dump", "Run protocol dump tool").dependOn(&dump.step);
     b.step("fuzz", "Run fuzz tester").dependOn(&fuzz.step);
-    b.step("lint", "Lint source files").dependOn(&lint.step);
     b.step("serde", "Run serialization/deserialization tool").dependOn(&serde.step);
     b.step("test", "Run all tests").dependOn(&tests.step);
     b.step("tools", "Install tools").dependOn(&ToolsStep.create(b, &exes).step);
@@ -263,12 +273,6 @@ const Config = struct {
     cmd: ?[]const u8,
 };
 
-const TESTS = .{
-    "src/lib/common/test.zig",
-    "src/lib/gen1/test.zig",
-    "src/lib/gen2/test.zig",
-};
-
 const TestStep = struct {
     step: std.Build.Step,
     build: bool,
@@ -283,26 +287,27 @@ const TestStep = struct {
         const step = std.Build.Step.init(.{ .id = .custom, .name = "Run all tests", .owner = b });
         self.* = TestStep{ .step = step, .build = test_filter == null };
 
-        const paths: []const []const u8 =
-            if (test_file) |t| &.{t} else if (coverage != null) &.{"src/lib/test.zig"} else &TESTS;
-        for (paths) |path| {
-            const tests = b.addTest(.{
-                .name = std.fs.path.basename(std.fs.path.dirname(path).?),
-                .root_source_file = .{ .path = path },
-                .optimize = config.optimize,
-                .target = config.target,
-                .filter = test_filter,
-            });
-            tests.setMainPkgPath("./");
-            tests.addOptions("build_options", options);
-            tests.single_threaded = true;
-            maybeStrip(b, tests, &tests.step, config.strip, config.cmd);
-            if (config.pic) tests.force_pic = config.pic;
-            if (coverage) |c| {
-                tests.setExecCmd(&.{ "kcov", "--include-pattern=src/lib", c, null });
-            }
-            self.step.dependOn(&b.addRunArtifact(tests).step);
+        const path = test_file orelse "src/lib/test.zig";
+        const tests = b.addTest(.{
+            .name = b.fmt("{s}-{s}", .{
+                std.fs.path.basename(std.fs.path.dirname(path).?),
+                std.fs.path.stem(std.fs.path.basename(path)),
+            }),
+            .main_pkg_path = .{ .path = "." },
+            .root_source_file = .{ .path = path },
+            .optimize = config.optimize,
+            .target = config.target,
+            .filter = test_filter,
+        });
+        tests.addOptions("build_options", options);
+        tests.single_threaded = true;
+        maybeStrip(b, tests, &tests.step, config.strip, config.cmd);
+        if (config.pic) tests.force_pic = config.pic;
+        if (coverage) |c| {
+            tests.setExecCmd(&.{ "kcov", "--include-pattern=src/lib", c, null });
         }
+        self.step.dependOn(&b.addRunArtifact(tests).step);
+
         return self;
     }
 };
@@ -350,7 +355,7 @@ const ToolsStep = struct {
         const self = b.allocator.create(ToolsStep) catch @panic("OOM");
         const step = std.Build.Step.init(.{ .id = .custom, .name = "Install tools", .owner = b });
         self.* = ToolsStep{ .step = step };
-        for (exes.items) |t| self.step.dependOn(&b.addInstallArtifact(t).step);
+        for (exes.items) |t| self.step.dependOn(&b.addInstallArtifact(t, .{}).step);
         return self;
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pkmn/engine",
-  "version": "0.1.0-dev.437f6a52",
+  "version": "0.1.0-dev.46307385",
   "description": "A minimal, complete, Pokémon battle simulation engine optimized for performance",
   "repository": "github:pkmn/engine",
   "license": "MIT",
@@ -34,11 +34,18 @@
     "src/bin/install-pkmn-engine",
     "src/lib/binding/node.zig",
     "src/lib/binding/wasm.zig",
+    "src/lib/common/battle.zig",
     "src/lib/common/data.zig",
     "src/lib/common/debug.zig",
+    "src/lib/common/js.zig",
+    "src/lib/common/optional.zig",
     "src/lib/common/options.zig",
     "src/lib/common/protocol.zig",
+    "src/lib/common/rational.zig",
     "src/lib/common/rng.zig",
+    "src/lib/common/util.zig",
+    "src/lib/gen1/calc.zig",
+    "src/lib/gen1/chance.zig",
     "src/lib/gen1/data.zig",
     "src/lib/gen1/data/moves.zig",
     "src/lib/gen1/data/species.zig",
@@ -66,30 +73,30 @@
     "access": "public"
   },
   "dependencies": {
-    "@pkmn/data": "^0.7.44",
+    "@pkmn/data": "^0.7.46",
     "@pkmn/protocol": "^0.6.12"
   },
   "devDependencies": {
-    "@pkmn/eslint-config": "^3.2.0",
-    "@pkmn/img": "^0.2.12",
+    "@pkmn/eslint-config": "^5.0.0",
+    "@pkmn/img": "^0.2.13",
     "@pkmn/sets": "^5.0.4",
-    "@pkmn/sim": "0.7.44",
+    "@pkmn/sim": "0.7.46",
     "@types/html-minifier": "^4.0.2",
-    "@types/jest": "^29.5.2",
+    "@types/jest": "^29.5.3",
     "@types/minimist": "^1.2.2",
     "@types/mustache": "^4.2.2",
-    "@types/node": "^20.3.1",
-    "@vitest/coverage-c8": "^0.32.2",
-    "binaryen": "^113.0.0",
-    "eslint": "^8.43.0",
+    "@types/node": "^20.4.2",
+    "@vitest/coverage-c8": "^0.33.0",
+    "binaryen": "^114.0.0",
+    "eslint": "^8.44.0",
     "html-minifier": "^4.0.0",
     "json-stringify-pretty-compact": "3.0.0",
     "minimist": "^1.2.8",
     "mustache": "^4.2.0",
     "source-map-support": "^0.5.21",
     "trakr": "^0.2.0",
-    "typescript": "^5.1.3",
-    "vitest": "^0.32.2"
+    "typescript": "^5.1.6",
+    "vitest": "^0.33.0"
   },
   "scripts": {
     "lint": "eslint --cache src --ext ts,js && eslint src/bin/*",
@@ -140,7 +147,8 @@
         "rules": {
           "no-control-regex": "off",
           "@typescript-eslint/no-empty-interface": "off",
-          "@typescript-eslint/no-shadow": "off"
+          "@typescript-eslint/no-shadow": "off",
+          "@typescript-eslint/no-unsafe-declaration-merging": "off"
         }
       },
       {
@@ -156,7 +164,8 @@
           "src/test/benchmark*.ts"
         ],
         "rules": {
-          "@typescript-eslint/no-unused-vars": "off"
+          "@typescript-eslint/no-unused-vars": "off",
+          "@typescript-eslint/no-redundant-type-constituents": "off"
         }
       },
       {

package/src/bin/install-pkmn-engine

@@ -10,7 +10,7 @@ const path = require('path');
 const {pipeline} = require('stream/promises');
 const tty = require('tty');
 
-const ZIG_VERSION = {major: 0, minor: 11, patch: 0, dev: 3859};
+const ZIG_VERSION = {major: 0, minor: 11, patch: 0};
 const DEV = ZIG_VERSION.dev ? `-dev.${ZIG_VERSION.dev}` : '';
 const VERSION = `${ZIG_VERSION.major}.${ZIG_VERSION.minor}.${ZIG_VERSION.patch}${DEV}`;
 const INDEX = 'https://ziglang.org/download/index.json';
@@ -358,7 +358,7 @@ const downloadImportLib = async () => {
   // either the default options or whatever was passed in
   if (!configs.size) {
     node = true;
-    const DEFAULT = ['-Dshowdown', '-Dlog', '-Dchance', '-Dcalc'];
+    const DEFAULT = ['-Dshowdown'];
     configs.set('node', {type: 'node', options: options || DEFAULT});
     configs.set('wasm', {type: 'wasm', options: options || DEFAULT});
   }

package/src/lib/common/battle.zig

@@ -0,0 +1,17 @@
+/// Stores state required by optional features to the engine that can be passed to a generation's
+/// `Battle.update` function. All generations generically support protocol logging (enabled via
+/// `-Dlog`), chance actions and probability tracking (enabled via `-Dchance`), and damage
+/// computation and chance overrides (`-Dcalc`), though the concrete types for these features are
+/// generation dependent.
+pub fn Options(comptime Log: type, comptime Chance: type, comptime Calc: type) type {
+    return struct { log: Log, chance: Chance, calc: Calc };
+}
+
+/// Helper to create a battle `Options` object with the provided `log`, `chance`, and `calc`.
+pub fn options(
+    log: anytype,
+    chance: anytype,
+    calc: anytype,
+) Options(@TypeOf(log), @TypeOf(chance), @TypeOf(calc)) {
+    return .{ .log = log, .chance = chance, .calc = calc };
+}

package/src/lib/common/js.zig

@@ -0,0 +1,118 @@
+const std = @import("std");
+
+const assert = std.debug.assert;
+
+const c = @cImport({
+    @cDefine("NAPI_VERSION", "8");
+    @cInclude("node_api.h");
+});
+
+pub const Array = struct {
+    pub fn init(env: c.napi_env, o: struct { length: ?usize }) c.napi_value {
+        var result: c.napi_value = undefined;
+        assert(c.napi_ok == if (o.length) |n|
+            c.napi_create_array_with_length(env, n, &result)
+        else
+            c.napi_create_array(env, &result));
+        return result;
+    }
+
+    pub fn set(env: c.napi_env, array: c.napi_value, index: u32, value: c.napi_value) void {
+        assert(c.napi_set_element(env, array, index, value) == c.napi_ok);
+    }
+};
+
+pub const Boolean = struct {
+    pub fn init(env: c.napi_env, value: bool) c.napi_value {
+        var result: c.napi_value = undefined;
+        assert(c.napi_get_boolean(env, value, &result) == c.napi_ok);
+        return result;
+    }
+};
+
+pub const Number = struct {
+    pub fn init(env: c.napi_env, value: anytype) c.napi_value {
+        const T = @TypeOf(value);
+        var result: c.napi_value = undefined;
+        assert(c.napi_ok == switch (@typeInfo(T)) {
+            .Int => |info| switch (info.bits) {
+                0...32 => switch (info.signedness) {
+                    .signed => c.napi_create_int32(env, @as(i32, value), &result),
+                    .unsigned => c.napi_create_uint32(env, @as(u32, value), &result),
+                },
+                33...52 => c.napi_create_int64(env, @as(i64, value), &result),
+                else => @compileError("int can't be represented as JS number"),
+            },
+            else => @compileError("expected number, got: " ++ @typeName(T)),
+        });
+        return result;
+    }
+
+    pub fn get(env: c.napi_env, value: c.napi_value, comptime T: type) T {
+        switch (@typeInfo(T)) {
+            .Int => |info| switch (info.bits) {
+                0...32 => switch (info.signedness) {
+                    .signed => {
+                        var result: i32 = undefined;
+                        assert(c.napi_get_value_int32(env, value, &result) == c.napi_ok);
+                        return if (info.bits == 32) result else @intCast(result);
+                    },
+                    .unsigned => {
+                        var result: u32 = undefined;
+                        assert(c.napi_get_value_uint32(env, value, &result) == c.napi_ok);
+                        return if (info.bits == 32) result else @intCast(result);
+                    },
+                },
+                33...63 => {
+                    var result: i64 = undefined;
+                    assert(c.napi_get_value_int64(env, value, &result) == c.napi_ok);
+                    return @intCast(result);
+                },
+                else => {
+                    var result: i64 = undefined;
+                    assert(c.napi_get_value_int64(env, value, &result) == c.napi_ok);
+                    return switch (info.signedness) {
+                        .signed => value,
+                        .unsigned => if (0 <= value) @intCast(value) else unreachable,
+                    };
+                },
+            },
+            else => @compileError("expected number, got: " ++ @typeName(T)),
+        }
+    }
+};
+
+pub const Object = struct {
+    pub fn init(env: c.napi_env) c.napi_value {
+        var result: c.napi_value = undefined;
+        assert(c.napi_create_object(env, &result) == c.napi_ok);
+        return result;
+    }
+};
+
+pub const Property = union(enum) {
+    method: c.napi_callback,
+    value: c.napi_value,
+
+    pub fn init(comptime name: [:0]const u8, property: Property) c.napi_property_descriptor {
+        return .{
+            .utf8name = name,
+            .name = null,
+            .method = switch (property) {
+                .method => |m| m,
+                .value => null,
+            },
+            .getter = null,
+            .setter = null,
+            .value = switch (property) {
+                .method => null,
+                .value => |v| v,
+            },
+            .attributes = switch (property) {
+                .method => c.napi_default,
+                .value => c.napi_enumerable,
+            },
+            .data = null,
+        };
+    }
+};