@pkmn/engine 0.1.0-dev.63cef311 → 0.1.0-dev.6be9a775

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pkmn/engine",
-  "version": "0.1.0-dev.63cef311",
+  "version": "0.1.0-dev.6be9a775",
   "description": "A minimal, complete, Pokémon battle simulation engine optimized for performance",
   "repository": "github:pkmn/engine",
   "license": "MIT",
@@ -9,86 +9,109 @@
   "types": "build/pkg/index.d.ts",
   "files": [
     "build.zig",
-    "src/bin/install-pkmn-engine",
-    "src/lib/binding/node.zig",
-    "src/lib/binding/wasm.zig",
+    "build/pkg/data.d.ts",
+    "build/pkg/data.js.map",
+    "build/pkg/addon.d.ts",
+    "build/pkg/addon.js.map",
+    "build/pkg/addon.js",
+    "build/pkg/data.js",
+    "build/pkg/data/ids.json",
+    "build/pkg/data/layout.json",
+    "build/pkg/data/protocol.json",
+    "build/pkg/gen1.d.ts",
+    "build/pkg/gen1.js.map",
+    "build/pkg/gen1.js",
+    "build/pkg/index.d.ts",
+    "build/pkg/index.js.map",
+    "build/pkg/index.js",
+    "build/pkg/protocol.d.ts",
+    "build/pkg/protocol.js.map",
+    "build/pkg/protocol.js",
+    "build/test/display.js.map",
+    "build/test/display.js",
+    "build/tools/debug.js.map",
+    "build/tools/debug.js",
+    "src/lib/common/battle.zig",
     "src/lib/common/data.zig",
     "src/lib/common/debug.zig",
+    "src/lib/common/js.zig",
+    "src/lib/common/array.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",
     "src/lib/gen1/data/types.zig",
-    "src/lib/gen1/data.zig",
     "src/lib/gen1/helpers.zig",
     "src/lib/gen1/mechanics.zig",
+    "src/lib/gen2/calc.zig",
+    "src/lib/gen2/chance.zig",
+    "src/lib/gen2/data.zig",
     "src/lib/gen2/data/items.zig",
     "src/lib/gen2/data/moves.zig",
     "src/lib/gen2/data/species.zig",
     "src/lib/gen2/data/types.zig",
-    "src/lib/gen2/data.zig",
+    "src/lib/gen2/generated.zig",
     "src/lib/gen2/helpers.zig",
     "src/lib/gen2/mechanics.zig",
+    "src/lib/node.zig",
     "src/lib/pkmn.zig",
-    "build/pkg/data/ids.json",
-    "build/pkg/data/layout.json",
-    "build/pkg/data/protocol.json",
-    "build/pkg/data.d.ts",
-    "build/pkg/data.js",
-    "build/pkg/data.js.map",
-    "build/pkg/gen1.d.ts",
-    "build/pkg/gen1.js",
-    "build/pkg/gen1.js.map",
-    "build/pkg/index.d.ts",
-    "build/pkg/index.js",
-    "build/pkg/index.js.map",
-    "build/pkg/protocol.d.ts",
-    "build/pkg/protocol.js",
-    "build/pkg/protocol.js.map"
+    "src/lib/wasm.zig",
+    "src/test/display/pkmn.html.tmpl"
   ],
   "engines": {
     "node": ">=16.0.0"
   },
   "bin": {
-    "install-pkmn-engine": "src/bin/install-pkmn-engine"
+    "install-pkmn-engine": "src/bin/install-pkmn-engine",
+    "pkmn-debug": "src/bin/pkmn-debug"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@pkmn/data": "^0.7.34",
-    "@pkmn/protocol": "^0.6.11"
+    "@pkmn/data": "^0.9.11",
+    "@pkmn/protocol": "^0.6.25"
   },
   "devDependencies": {
-    "@pkmn/eslint-config": "^3.0.0-alpha.0",
-    "@pkmn/img": "^0.2.8",
-    "@pkmn/sets": "^5.0.4",
-    "@pkmn/sim": "0.7.34",
-    "@types/html-minifier": "^4.0.2",
-    "@types/jest": "^29.5.0",
-    "@types/minimist": "^1.2.2",
-    "@types/mustache": "^4.2.2",
-    "@types/node": "^18.15.11",
-    "@vitest/coverage-c8": "^0.29.8",
-    "binaryen": "^112.0.0",
-    "eslint": "^8.37.0",
+    "@pkmn/eslint-config": "^8.1.0",
+    "@pkmn/img": "^0.2.31",
+    "@pkmn/sets": "^5.1.2",
+    "@pkmn/sim": "0.9.11",
+    "@types/html-minifier": "^4.0.5",
+    "@types/jest": "^29.5.12",
+    "@types/minimist": "^1.2.5",
+    "@types/mustache": "^4.2.5",
+    "@types/node": "^22.0.2",
+    "@types/semver": "^7.5.8",
+    "@vitest/coverage-v8": "^2.0.5",
+    "binaryen": "^118.0.0",
+    "eslint": "<=8",
     "html-minifier": "^4.0.0",
-    "json-stringify-pretty-compact": "3.0.0",
+    "json-stringify-pretty-compact": "4.0.0",
     "minimist": "^1.2.8",
     "mustache": "^4.2.0",
+    "semver": "^7.6.3",
     "source-map-support": "^0.5.21",
+    "table": "^6.8.2",
     "trakr": "^0.2.0",
-    "typescript": "^5.0.2",
-    "vitest": "^0.29.8"
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
   },
   "scripts": {
-    "lint": "eslint --cache src --ext ts,js && eslint src/bin/install-pkmn-engine",
-    "fix": "eslint --fix src --ext ts,js && eslint --fix src/bin/install-pkmn-engine",
+    "lint": "eslint --cache src --ext ts,js && eslint src/bin/*",
+    "fix": "eslint --fix src --ext ts,js && eslint --fix src/bin/*",
     "compile": "tsc -p .",
     "build": "npm run compile",
     "test": "vitest src/pkg",
     "test:integration": "vitest src/test",
+    "debug": "npm run compile && node build/tools/debug",
     "fuzz": "npm run compile && node build/test/fuzz",
     "generate": "npm run compile && node build/tools/generate",
     "release": "npm run compile && node build/tools/release",
@@ -101,7 +124,7 @@
     "ignorePatterns": [
       "dist/",
       "node_modules/",
-      "src/examples/zig",
+      "examples/zig",
       "build/"
     ],
     "env": {
@@ -117,10 +140,18 @@
         "parserOptions": {
           "project": [
             "./tsconfig.json",
-            "./src/examples/js/tsconfig.json"
+            "./examples/js/tsconfig.json"
           ]
         }
       },
+      {
+        "files": [
+          "src/test/display.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/no-unnecessary-type-assertion": "off"
+        }
+      },
       {
         "files": [
           "src/pkg/index.ts",
@@ -130,7 +161,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"
         }
       },
       {
@@ -146,12 +178,23 @@
           "src/test/benchmark*.ts"
         ],
         "rules": {
-          "@typescript-eslint/no-unused-vars": "off"
+          "@typescript-eslint/no-unused-vars": "off",
+          "@typescript-eslint/no-redundant-type-constituents": "off"
+        }
+      },
+      {
+        "files": [
+          "src/pkg/protocol.test.ts"
+        ],
+        "rules": {
+          "jest/no-standalone-expect": "off",
+          "jest/no-conditional-expect": "off"
         }
       },
       {
         "files": [
-          "src/test/*.test.ts"
+          "src/test/*.test.ts",
+          "src/test/regression/*.test.ts"
         ],
         "rules": {
           "jest/no-standalone-expect": "off"

package/src/bin/install-pkmn-engine

@@ -10,13 +10,15 @@ const path = require('path');
 const {pipeline} = require('stream/promises');
 const tty = require('tty');
 
-const ZIG_VERSION = {major: 0, minor: 11, patch: 0, dev: 2168};
+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';
 const ROOT = path.resolve(__dirname, '..', '..');
+let SILENT = false;
 
 const sh = (cmd, args) => execFileSync(cmd, args, {encoding: 'utf8', cwd: ROOT});
+const log = (...args) => { if (!SILENT) console.log(...args); };
 
 // This is hardly the browser fetch API, but it works for our primitive needs
 const fetch = url => new Promise((resolve, reject) => {
@@ -61,7 +63,7 @@ const unpack7 = (input, output) => new Promise((resolve, reject) => {
     require.resolve('7zip-min');
   } catch (err) {
     if (err.code !== 'MODULE_NOT_FOUND') throw err;
-    console.log('Installing 7zip-min package locally to unpack the archive...');
+    log('Installing 7zip-min package locally to unpack the archive...');
     sh('npm', ['install', '7zip-min', '--no-audit', '--no-save']);
   }
 
@@ -83,7 +85,7 @@ const unpack = async (input, output) => {
       sh('tar', ['xf', input, '-C', output]);
       return;
     } catch {
-      console.log('tar command not found, falling back to 7z');
+      log('tar command not found, falling back to 7z');
     }
   }
   // Try to use a 7z binary if we can, and only install 7zip-min as a last resort
@@ -120,10 +122,10 @@ const find = zig => {
         (!ZIG_VERSION.dev || (dev && dev >= ZIG_VERSION.dev)));
 
     if (compatible) {
-      console.log('Found existing compatible Zig executable:', zig_exe);
+      log('Found existing compatible Zig executable:', zig_exe);
       return zig_exe;
     } else {
-      console.log(`Existing Zig executable is not compatible (${version} < ${VERSION}):`, zig_exe);
+      log(`Existing Zig executable is not compatible (${version} < ${VERSION}):`, zig_exe);
     }
   } catch (err) {
     if (err.code !== 'ENOENT') throw err;
@@ -161,18 +163,20 @@ const install = async () => {
   }
 
   const index = JSON.parse(await fetch(INDEX));
-  const version = Object.keys(index)[+!ZIG_VERSION.dev];
-  const release = index[version][`${arch}-${platform}`];
+  // TODO: ziglang/zig#17768
+  // const version = Object.keys(index)[+!ZIG_VERSION.dev];
+  const version = VERSION;
+  const release = index[VERSION][`${arch}-${platform}`];
   const url = release.tarball;
 
   let base = path.basename(url);
   const archive = path.join(dir, path.basename(url));
 
-  console.log(`Downloading Zig tarball from ${url} to ${archive}`);
+  log(`Downloading Zig tarball from ${url} to ${archive}`);
   try {
     await download(url, archive, release.shasum);
 
-    console.log(`Extracting tarball and installing to ${dir}`);
+    log(`Extracting tarball and installing to ${dir}`);
     await unpack(archive, dir);
     if (archive.endsWith('.zip')) {
       base = base.slice(0, -4);
@@ -187,17 +191,17 @@ const install = async () => {
     } catch (err) {
       if (err.code !== 'ENOENT') throw err;
     }
-    console.log(`Zig${version === 'master' ? '' : ` v${version}`} executable:`, zig,
+    log(`Zig${version === 'master' ? '' : ` v${version}`} executable:`, zig,
       '(this version of Zig will be retained to speed up future updates)');
     const [pre, post] = tty.isatty(1) ? ['\x1b[1m\x1b[35m', '\x1b[0m'] : ['', ''];
-    console.log(
+    log(
       `${pre}Consider moving the ${path.dirname(zig)} directory and adding it to your PATH`,
       `to use Zig on other projects, or delete this if you wish to save space.${post}`
     );
 
     return zig;
   } finally {
-    console.log(`Cleaning up ${archive}`);
+    log(`Cleaning up ${archive}`);
     try { fs.rmSync(archive); } catch {}
   }
 };
@@ -206,17 +210,17 @@ const install = async () => {
 const downloadHeaders = async () => {
   const include = path.resolve(process.execPath, '..', '..', 'include', 'node');
   if (fs.existsSync(path.join(include, 'node.h'))) {
-    console.log('Node headers:', include);
+    log('Node headers:', include);
     return include;
   }
 
   const dir = path.join(ROOT, 'build', 'include');
-  const dest = path.join(dir, `node-${process.version}`, 'include', 'node');
+  const dest = path.join(dir, 'node');
   if (fs.existsSync(path.join(dest, 'node.h'))) {
-    console.log('Node headers:', dest);
+    log('Node headers:', dest);
     return dest;
   } else {
-    console.log(`Could not find Node headers at ${include}, downloading...`);
+    log(`Could not find Node headers at ${include}, downloading...`);
   }
 
   try {
@@ -227,20 +231,28 @@ const downloadHeaders = async () => {
 
   const url = process.release.headersUrl;
   const targz = path.join(dir, path.basename(url));
+  const unpacked = path.join(dir, `node-${process.version}`, 'include');
 
-  console.log(`Downloading Node headers from ${url} to ${targz}`);
-  await download(url, targz);
-  await unpack(targz, dir);
+  log(`Downloading Node headers from ${url} to ${targz}`);
 
-  console.log('Node headers:', dest);
+  try {
+    await download(url, targz);
+    await unpack(targz, dir);
+    fs.renameSync(path.join(unpacked, 'node'), dest);
 
-  return dest;
+    log('Node headers:', dest);
+
+    return dest;
+  } finally {
+    try { fs.rmSync(targz); } catch {}
+    try { fs.rmSync(unpacked, {recursive: true}); } catch {}
+  }
 };
 
 const downloadImportLib = async () => {
   const library = path.resolve(process.execPath, '..', 'node.lib');
   if (fs.existsSync(path.join(library, 'node.h'))) {
-    console.log('Node import library:', library);
+    log('Node import library:', library);
     return library;
   }
 
@@ -248,10 +260,10 @@ const downloadImportLib = async () => {
   const url = new URL('./win-x64/node.lib', process.release.headersUrl).href;
   const dest = path.join(dir, path.basename(url));
   if (fs.existsSync(path.join(dest))) {
-    console.log('Node import library:', dest);
+    log('Node import library:', dest);
     return dest;
   } else {
-    console.log(`Could not find Node import library at ${library}, downloading...`);
+    log(`Could not find Node import library at ${library}, downloading...`);
   }
 
   try {
@@ -260,24 +272,41 @@ const downloadImportLib = async () => {
     if (err.code !== 'EEXIST') throw err;
   }
 
-  console.log(`Downloading Node import library from ${url} to ${dest}`);
+  log(`Downloading Node import library from ${url} to ${dest}`);
   await download(url, dest);
-  console.log('Node import library:', dest);
+  log('Node import library:', dest);
 
   return dest;
 };
 
 (async () => {
-  const options = (process.argv[2] || '').startsWith('--options=')
-    ? process.argv[2].slice(10).split(' ') : undefined;
-  if (process.argv.length > 3 ||
-    process.argv.length === 3 && !(process.argv[2] === '--zig' || options)) {
+  let only = false;
+  let options = undefined;
+  let error = false;
+  for (let i = 2; i < process.argv.length; i++) {
+    switch (process.argv[i]) {
+      case "--silent": {
+        SILENT = true;
+        break;
+      }
+      case "--zig": {
+        if (options || only) error = true;
+        only = true;
+        break;
+      }
+      default: {
+        if (options || only || !process.argv[i].startsWith('--options=')) error = true;
+        options = process.argv[i].slice(10).split(' ');
+      }
+    }
+  }
+  if (error) {
     console.error('Invalid arguments');
     process.exit(1);
   }
 
   const zig = await install();
-  if (process.argv[2] === '--zig') process.exit(0);
+  if (only) process.exit(0);
 
   let tmp;
   try {
@@ -309,14 +338,18 @@ const downloadImportLib = async () => {
         node = true;
         if (!options) {
           const addon = require(copy);
-          if (addon.options.showdown) opts.push('-Dshowdown');
-          if (addon.options.trace) opts.push('-Dtrace');
+          if (addon.engine.options.showdown) opts.push('-Dshowdown');
+          if (addon.engine.options.log) opts.push('-Dlog');
+          if (addon.engine.options.chance) opts.push('-Dchance');
+          if (addon.engine.options.calc) opts.push('-Dcalc');
         }
       } else if (!options) {
         const addon = await WebAssembly.instantiate(fs.readFileSync(copy));
         const values = new Uint8Array(addon.instance.exports.memory.buffer);
         if (values[addon.instance.exports.SHOWDOWN.value]) opts.push('-Dshowdown');
-        if (values[addon.instance.exports.TRACE.value]) opts.push('-Dtrace');
+        if (values[addon.instance.exports.LOG.value]) opts.push('-Dlog');
+        if (values[addon.instance.exports.CHANCE.value]) opts.push('-Dchance');
+        if (values[addon.instance.exports.CALC.value]) opts.push('-Dcalc');
       }
       const key = `${type} ${opts.sort().join(' ')}`;
       if (!configs.has(key)) configs.set(key, {type, options: opts});
@@ -327,8 +360,9 @@ const downloadImportLib = async () => {
   // either the default options or whatever was passed in
   if (!configs.size) {
     node = true;
-    configs.set('node', {type: 'node', options: options || ['-Dshowdown']});
-    configs.set('wasm', {type: 'wasm', options: options || ['-Dshowdown']});
+    const DEFAULT = ['-Dshowdown'];
+    configs.set('node', {type: 'node', options: options || DEFAULT});
+    configs.set('wasm', {type: 'wasm', options: options || DEFAULT});
   }
 
   const headers = node ? await downloadHeaders() : undefined;
@@ -338,8 +372,10 @@ const downloadImportLib = async () => {
     const args = ['build', '-p', 'build', ...opts];
     if (!process.env.DEBUG_PKMN_ENGINE) args.push('-Doptimize=ReleaseFast', '-Dstrip');
     if (config.type === 'node') {
-      args.push(`-Dnode-headers=${headers}`);
-      if (process.platform === 'win32') args.push(`-Dnode-import-library=${lib}`);
+      args.push(`-Dnode-headers=${path.relative(ROOT, headers)}`);
+      if (process.platform === 'win32') {
+        args.push(`-Dnode-import-library=${path.relative(ROOT, lib)}`);
+      }
     } else {
       args.push('-Dwasm');
     }
@@ -347,15 +383,21 @@ const downloadImportLib = async () => {
       opts.includes('-Dshowdown') || opts.includes('-Dshowdown=true') ? '-showdown' : '';
     const flags = opts.length ? ` (${opts.join(' ')})` : '';
     const artifact = path.join('build', 'lib', `pkmn${suffix}.${config.type}`);
-    console.log(`Building ${artifact}${flags}`);
+    log(`Building ${artifact}${flags}`);
     sh(zig, args);
     // TODO: ziglang/zig#14647 broke emit_to so we get to rename the file ourselves...
     if (config.type === 'node') {
       const prefix = process.platform === 'win32' ? '' : 'lib';
       const ext = process.platform === 'darwin'
         ? 'dylib' : process.platform === 'win32' ? 'dll' : 'so';
-      const actual = path.join('build', 'lib', `${prefix}pkmn${suffix}.node.${ext}`);
-      fs.renameSync(actual, artifact);
+      try {
+        const actual = path.join(ROOT, 'build', 'lib', `${prefix}pkmn${suffix}.node.${ext}`);
+        fs.renameSync(actual, artifact);
+      } catch (err) {
+        // ziglang/zig#19743 changed this path
+        const actual = path.join(ROOT, 'build', 'bin', `${prefix}pkmn${suffix}.node.${ext}`);
+        fs.renameSync(actual, artifact);
+      }
     }
   }
 })().catch(e => {

package/src/bin/pkmn-debug

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+try {
+  require('source-map-support').install();
+} catch (err) {
+  if (err.code !== 'MODULE_NOT_FOUND') throw err;
+}
+
+const {execFileSync} = require('child_process');
+const {readFileSync} = require('fs');
+const {join, resolve} = require('path');
+
+const ROOT = resolve(__dirname, '..', '..');
+const packageJSON = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
+
+const missing = [];
+for (const dep of ['@pkmn/img', 'html-minifier', 'mustache']) {
+  try {
+    require.resolve(dep);
+  } catch (e) {
+    if (e.code !== 'MODULE_NOT_FOUND') throw e;
+    missing.push(`${dep}@${packageJSON.devDependencies[dep]}`);
+  }
+}
+
+let Dex = undefined;
+try {
+  Dex = require('@pkmn/sim').Dex;
+} catch (err) {
+  if (err.code !== 'MODULE_NOT_FOUND') throw err;
+  try {
+    Dex = require('@pkmn/dex').Dex;
+  } catch (e) {
+    if (e.code !== 'MODULE_NOT_FOUND') throw e;
+    missing.push(`@pkmn/dex@${packageJSON.dependencies['@pkmn/data']}`);
+  }
+}
+
+if (missing.length) {
+  if (+/^v(\d+)/.exec(process.version)[1] < 16) {
+    console.error('pkmn-debug requires Node v16+');
+    process.exit(1);
+  }
+
+  execFileSync('npm', ['install', ...missing, '--global'], {encoding: 'utf8'});
+
+  const node_modules = execFileSync('npm', ['root', '--global'], {encoding: 'utf8'}).trim();
+  if (!process.env.NODE_PATH || !process.env.NODE_PATH.includes(node_modules)) {
+    console.error(`NODE_PATH must include npm's global node_modules directory: '${node_modules}'`);
+    process.exit(1);
+  }
+}
+
+const {Generations} = require('@pkmn/data');
+
+const {run} = require('../../build/tools/debug');
+
+run(new Generations(Dex)).catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/src/lib/common/array.zig

@@ -0,0 +1,77 @@
+const std = @import("std");
+
+const expectEqual = std.testing.expectEqual;
+const assert = std.debug.assert;
+
+const Int = if (@hasField(std.builtin.Type, "int")) .int else .Int;
+const Enum = if (@hasField(std.builtin.Type, "enum")) .@"enum" else .Enum;
+
+/// Helpers for working with bit-packed arrays of non-powers-of-2 types.
+/// NOTE: ziglang/zig#12547
+pub fn Array(comptime n: comptime_int, comptime U: type) type {
+    return struct {
+        const size = @bitSizeOf(U);
+        const options = .{ .signedness = .unsigned, .bits = size * n };
+        pub const T = @Type(if (@hasField(std.builtin.Type, "int"))
+            .{ .int = options }
+        else
+            .{ .Int = options });
+
+        /// Returns the value stored at index `i` in the array `a`.
+        pub fn get(a: T, i: usize) U {
+            assert(i < n);
+            const shift = i * size;
+            const mask: T = (1 << size) - 1;
+            const result = (a >> @intCast(shift)) & mask;
+            return switch (@typeInfo(U)) {
+                Enum => @enumFromInt(result),
+                Int => @intCast(result),
+                else => unreachable,
+            };
+        }
+
+        /// Sets the value at index `i` to `val` in the array `a`.
+        pub fn set(a: T, i: usize, val: U) T {
+            assert(i < n);
+            const v: T = switch (@typeInfo(U)) {
+                Enum => @intFromEnum(val),
+                Int => @intCast(val),
+                else => unreachable,
+            };
+            const shift = i * size;
+            const mask: T = @as(T, @intCast((1 << size) - 1)) << @intCast(shift);
+            const result: T = a & ~mask;
+            return result | (v << @intCast(shift));
+        }
+    };
+}
+
+test Array {
+    const A = Array(5, u8);
+    var a: A.T = 0;
+    try expectEqual(u40, @TypeOf(a));
+
+    a = A.set(a, 4, 241);
+    try expectEqual(@as(u8, 241), A.get(a, 4));
+    a = A.set(a, 4, 1);
+    try expectEqual(@as(u8, 1), A.get(a, 4));
+
+    for (0..5) |i| a = A.set(a, i, @intCast(i));
+    for (0..5) |i| try expectEqual(@as(u8, @intCast(i)), A.get(a, i));
+
+    const Optional = @import("optional.zig").Optional;
+
+    const B = Array(4, Optional(bool));
+    var b: B.T = 0;
+    try expectEqual(u8, @TypeOf(b));
+
+    b = B.set(b, 2, .true);
+    try expectEqual(Optional(bool).None, B.get(b, 1));
+    try expectEqual(Optional(bool).true, B.get(b, 2));
+    try expectEqual(@as(u8, 0b00100000), b);
+    b = B.set(b, 2, .None);
+    b = B.set(b, 0, .false);
+    try expectEqual(Optional(bool).None, B.get(b, 2));
+    try expectEqual(Optional(bool).false, B.get(b, 0));
+    try expectEqual(@as(u8, 0b0000001), b);
+}

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 };
+}