@pkmn/engine 0.1.0-dev.a324c50f → 0.1.0-dev.a5846b2d

package/package.json

@@ -1,19 +1,31 @@
 {
   "name": "@pkmn/engine",
-  "version": "0.1.0-dev.a324c50f",
+  "version": "0.1.0-dev.a5846b2d",
   "description": "A minimal, complete, Pokémon battle simulation engine optimized for performance",
   "repository": "github:pkmn/engine",
   "license": "MIT",
   "sideEffects": false,
   "main": "build/pkg/index.js",
   "types": "build/pkg/index.d.ts",
+  "browser": {
+    "./build/pkg/addon/node.js": "./build/pkg/addon/browser.js"
+  },
   "files": [
     "build.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/addon/browser.d.ts",
+    "build/pkg/addon/browser.js.map",
+    "build/pkg/addon/browser.js",
+    "build/pkg/addon/node.d.ts",
+    "build/pkg/addon/node.js.map",
+    "build/pkg/addon/node.js",
+    "build/pkg/addon/wasm.d.ts",
+    "build/pkg/addon/wasm.js.map",
+    "build/pkg/addon/wasm.js",
+    "build/pkg/data.d.ts",
+    "build/pkg/data.js.map",
     "build/pkg/data.js",
     "build/pkg/data/ids.json",
     "build/pkg/data/layout.json",
@@ -27,33 +39,52 @@
     "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/bin/install-pkmn-engine",
-    "src/lib/binding/node.zig",
-    "src/lib/binding/wasm.zig",
+    "build/tools/display/index.js.map",
+    "build/tools/display/index.js",
+    "build/tools/display/debug.jsx.map",
+    "build/tools/display/debug.jsx",
+    "build/tools/display/ui.jsx.map",
+    "build/tools/display/ui.jsx",
+    "build/tools/display/util.js.map",
+    "build/tools/display/util.js",
+    "src/lib/bindings/node.zig",
+    "src/lib/bindings/wasm.zig",
+    "src/lib/common/array.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",
     "src/lib/gen1/data/types.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/generated.zig",
     "src/lib/gen2/helpers.zig",
     "src/lib/gen2/mechanics.zig",
+    "src/lib/node.zig",
     "src/lib/pkmn.zig",
-    "src/test/display/pkmn.html.tmpl"
+    "src/lib/wasm.zig",
+    "src/tools/display/dom.ts",
+    "src/tools/display/ui.css"
   ],
   "engines": {
     "node": ">=16.0.0"
@@ -66,138 +97,54 @@
     "access": "public"
   },
   "dependencies": {
-    "@pkmn/data": "^0.7.44",
-    "@pkmn/protocol": "^0.6.12"
+    "@pkmn/data": "^0.9.20",
+    "@pkmn/protocol": "^0.6.27"
   },
   "devDependencies": {
-    "@pkmn/eslint-config": "^3.2.0",
-    "@pkmn/img": "^0.2.12",
-    "@pkmn/sets": "^5.0.4",
-    "@pkmn/sim": "0.7.44",
-    "@types/html-minifier": "^4.0.2",
-    "@types/jest": "^29.5.2",
-    "@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",
+    "@pkmn/eslint-config": "^9.0.0",
+    "@pkmn/img": "^0.2.32",
+    "@pkmn/sets": "^5.1.2",
+    "@pkmn/sim": "0.9.20",
+    "@pkmn/smogon": "^0.5.14",
+    "@types/html-minifier": "^4.0.5",
+    "@types/jest": "^29.5.13",
+    "@types/minimist": "^1.2.5",
+    "@types/mustache": "^4.2.5",
+    "@types/node": "^22.7.6",
+    "@types/react": "^18.3.11",
+    "@types/semver": "^7.5.8",
+    "@types/vscode": "^1.94.0",
+    "@vitest/coverage-v8": "^2.1.3",
+    "@vscode/vsce": "^3.2.0",
+    "binaryen": "^119.0.0",
+    "esbuild": "^0.24.0",
+    "eslint": "^9.12.0",
     "html-minifier": "^4.0.0",
     "json-stringify-pretty-compact": "3.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.1.3",
-    "vitest": "^0.32.2"
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3"
   },
   "scripts": {
-    "lint": "eslint --cache src --ext ts,js && eslint src/bin/*",
-    "fix": "eslint --fix src --ext ts,js && eslint --fix src/bin/*",
+    "lint": "eslint --cache src",
+    "fix": "eslint --fix src",
     "compile": "tsc -p .",
     "build": "npm run compile",
     "test": "vitest src/pkg",
     "test:integration": "vitest src/test",
     "debug": "npm run compile && node build/tools/debug",
+    "demo": "npm run compile && node build/tools/demo",
     "fuzz": "npm run compile && node build/test/fuzz",
     "generate": "npm run compile && node build/tools/generate",
     "release": "npm run compile && node build/tools/release",
     "benchmark": "npm run compile && node build/test/benchmark",
     "integration": "npm run compile && node build/test/integration",
+    "extension": "npm -C src/tools/vscode run build",
     "postinstall": "node src/bin/install-pkmn-engine"
-  },
-  "eslintConfig": {
-    "extends": "@pkmn",
-    "ignorePatterns": [
-      "dist/",
-      "node_modules/",
-      "src/examples/zig",
-      "build/"
-    ],
-    "env": {
-      "es6": true,
-      "node": true,
-      "browser": true
-    },
-    "overrides": [
-      {
-        "files": [
-          "**/*.ts"
-        ],
-        "parserOptions": {
-          "project": [
-            "./tsconfig.json",
-            "./src/examples/js/tsconfig.json"
-          ]
-        }
-      },
-      {
-        "files": [
-          "src/pkg/index.ts",
-          "src/test/display.ts",
-          "src/test/integration.ts"
-        ],
-        "rules": {
-          "no-control-regex": "off",
-          "@typescript-eslint/no-empty-interface": "off",
-          "@typescript-eslint/no-shadow": "off"
-        }
-      },
-      {
-        "files": [
-          "src/pkg/addon.ts"
-        ],
-        "rules": {
-          "@typescript-eslint/no-var-requires": "off"
-        }
-      },
-      {
-        "files": [
-          "src/test/benchmark*.ts"
-        ],
-        "rules": {
-          "@typescript-eslint/no-unused-vars": "off"
-        }
-      },
-      {
-        "files": [
-          "src/test/*.test.ts",
-          "src/test/regression/*.test.ts"
-        ],
-        "rules": {
-          "jest/no-standalone-expect": "off"
-        }
-      },
-      {
-        "files": [
-          "src/test/showdown/**"
-        ],
-        "rules": {
-          "jest/expect-expect": [
-            "warn",
-            {
-              "assertFunctionNames": [
-                "expect",
-                "expectLog",
-                "verify"
-              ]
-            }
-          ]
-        }
-      },
-      {
-        "files": [
-          "src/tools/generate.ts"
-        ],
-        "rules": {
-          "@typescript-eslint/restrict-template-expressions": [
-            "error",
-            {
-              "allowBoolean": true
-            }
-          ]
-        }
-      }
-    ]
   }
 }

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';
@@ -163,8 +163,10 @@ 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);
@@ -255,7 +257,7 @@ const downloadImportLib = async () => {
   }
 
   const dir = path.join(ROOT, 'build', 'lib');
-  const url = new URL('./win-x64/node.lib', process.release.headersUrl).href;
+  const url = process.release.libUrl;
   const dest = path.join(dir, path.basename(url));
   if (fs.existsSync(path.join(dest))) {
     log('Node import library:', dest);
@@ -283,19 +285,19 @@ const downloadImportLib = async () => {
   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(' ');
-    }
+      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) {
@@ -358,7 +360,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});
   }
@@ -370,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');
     }
@@ -386,8 +390,14 @@ const downloadImportLib = async () => {
       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(path.join(ROOT, actual), path.join(ROOT, artifact));
+      try {
+        const actual = path.join(ROOT, 'build', 'lib', `${prefix}pkmn${suffix}.node.${ext}`);
+        fs.renameSync(actual, artifact);
+      } catch {
+        // 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

@@ -15,7 +15,7 @@ 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']) {
+for (const dep of ['@pkmn/img', 'html-minifier', 'esbuild']) {
   try {
     require.resolve(dep);
   } catch (e) {

package/src/lib/{binding → bindings}/node.zig

@@ -1,7 +1,6 @@
-const std = @import("std");
-const pkmn = @import("../pkmn.zig");
-
 const js = @import("../common/js.zig");
+const pkmn = @import("../pkmn.zig");
+const std = @import("std");
 
 const assert = std.debug.assert;
 
@@ -10,16 +9,8 @@ const c = @cImport({
     @cInclude("node_api.h");
 });
 
-export fn napi_register_module_v1(env: c.napi_env, exports: c.napi_value) c.napi_value {
-    const properties = [_]c.napi_property_descriptor{
-        js.Property.init("engine", .{ .value = register(env) }),
-    };
-    assert(c.napi_define_properties(env, exports, properties.len, &properties) == c.napi_ok);
-    return exports;
-}
-
 pub fn register(env: c.napi_env) c.napi_value {
-    var object = js.Object.init(env);
+    const object = js.Object.init(env);
     const properties = [_]c.napi_property_descriptor{
         js.Property.init("options", .{ .value = options(env) }),
         js.Property.init("bindings", .{ .value = bindings(env) }),
@@ -29,7 +20,7 @@ pub fn register(env: c.napi_env) c.napi_value {
 }
 
 fn options(env: c.napi_env) c.napi_value {
-    var object = js.Object.init(env);
+    const object = js.Object.init(env);
     const properties = [_]c.napi_property_descriptor{
         js.Property.init("showdown", .{ .value = js.Boolean.init(env, pkmn.options.showdown) }),
         js.Property.init("log", .{ .value = js.Boolean.init(env, pkmn.options.log) }),
@@ -41,7 +32,7 @@ fn options(env: c.napi_env) c.napi_value {
 }
 
 fn bindings(env: c.napi_env) c.napi_value {
-    var array = js.Array.init(env, .{ .length = 1 });
+    const array = js.Array.init(env, .{ .length = 1 });
     js.Array.set(env, array, 0, bind(env, pkmn.gen1));
     return array;
 }
@@ -49,7 +40,7 @@ fn bindings(env: c.napi_env) c.napi_value {
 fn bind(env: c.napi_env, gen: anytype) c.napi_value {
     const choices_size: u32 = @intCast(gen.CHOICES_SIZE);
     const logs_size: u32 = @intCast(gen.LOGS_SIZE);
-    var object = js.Object.init(env);
+    const object = js.Object.init(env);
     const properties = [_]c.napi_property_descriptor{
         js.Property.init("CHOICES_SIZE", .{ .value = js.Number.init(env, choices_size) }),
         js.Property.init("LOGS_SIZE", .{ .value = js.Number.init(env, logs_size) }),
@@ -72,7 +63,6 @@ fn update(gen: anytype) c.napi_callback {
             var len: usize = 0;
             assert(c.napi_get_arraybuffer_info(env, argv[0], &data, &len) == c.napi_ok);
             assert(len == @sizeOf(gen.Battle(gen.PRNG)));
-            assert(data != null);
 
             var battle: *gen.Battle(gen.PRNG) = @alignCast(@ptrCast(data.?));
             const c1: pkmn.Choice = @bitCast(js.Number.get(env, argv[1], u8));
@@ -85,10 +75,9 @@ fn update(gen: anytype) c.napi_callback {
                 else => result: {
                     assert(c.napi_get_arraybuffer_info(env, argv[3], &data, &len) == c.napi_ok);
                     assert(len == gen.LOGS_SIZE);
-                    assert(data != null);
 
-                    var buf = @as([*]u8, @ptrCast(data.?))[0..gen.LOGS_SIZE];
-                    var stream = pkmn.protocol.ByteStream{ .buffer = buf };
+                    const buf = @as([*]u8, @ptrCast(data.?))[0..gen.LOGS_SIZE];
+                    var stream: pkmn.protocol.ByteStream = .{ .buffer = buf };
                     // TODO: extract out
                     var opts = pkmn.battle.options(
                         pkmn.protocol.FixedLog{ .writer = stream.writer() },
@@ -116,7 +105,6 @@ fn choices(gen: anytype) c.napi_callback {
             var len: usize = 0;
             assert(c.napi_get_arraybuffer_info(env, argv[0], &data, &len) == c.napi_ok);
             assert(len == @sizeOf(gen.Battle(gen.PRNG)));
-            assert(data != null);
 
             var battle: *gen.Battle(gen.PRNG) = @alignCast(@ptrCast(data.?));
             const player: pkmn.Player = @enumFromInt(js.Number.get(env, argv[1], u8));
@@ -124,9 +112,8 @@ fn choices(gen: anytype) c.napi_callback {
 
             assert(c.napi_get_arraybuffer_info(env, argv[3], &data, &len) == c.napi_ok);
             assert(len == gen.CHOICES_SIZE);
-            assert(data != null);
 
-            var out = @as([*]pkmn.Choice, @ptrCast(data.?))[0..gen.CHOICES_SIZE];
+            const out = @as([*]pkmn.Choice, @ptrCast(data.?))[0..gen.CHOICES_SIZE];
             const n = battle.choices(player, request, out);
             return js.Number.init(env, @as(u8, @bitCast(n)));
         }

package/src/lib/bindings/wasm.zig

@@ -0,0 +1,59 @@
+const pkmn = @import("../pkmn.zig");
+const std = @import("std");
+
+const assert = std.debug.assert;
+
+const Enum = if (@hasField(std.builtin.Type, "enum")) .@"enum" else .Enum;
+const Strong = if (@hasField(std.builtin.GlobalLinkage, "strong")) .strong else .Strong;
+
+pub const options = pkmn.options;
+
+pub fn gen(comptime num: comptime_int) type {
+    const g = @field(pkmn, "gen" ++ std.fmt.comptimePrint("{d}", .{num}));
+    return struct {
+        pub const CHOICES_SIZE = size(g.CHOICES_SIZE);
+        pub const LOGS_SIZE = size(g.LOGS_SIZE);
+
+        pub fn update(
+            battle: *g.Battle(g.PRNG),
+            c1: pkmn.Choice,
+            c2: pkmn.Choice,
+            options_: ?[*]u8,
+        ) callconv(.C) pkmn.Result {
+            return (if (options_) |o| result: {
+                const buf = @as([*]u8, @ptrCast(o))[0..g.LOGS_SIZE];
+                var stream: pkmn.protocol.ByteStream = .{ .buffer = buf };
+                // TODO: extract out
+                var opts = pkmn.battle.options(
+                    pkmn.protocol.FixedLog{ .writer = stream.writer() },
+                    g.chance.NULL,
+                    g.calc.NULL,
+                );
+                break :result battle.update(c1, c2, &opts);
+            } else battle.update(c1, c2, &g.NULL)) catch unreachable;
+        }
+
+        pub fn choices(
+            battle: *g.Battle(g.PRNG),
+            player: u8,
+            request: u8,
+            buf: [*]u8,
+        ) callconv(.C) u8 {
+            assert(player <= @field(@typeInfo(pkmn.Player), @tagName(Enum)).fields.len);
+            assert(request <= @field(@typeInfo(pkmn.Choice.Type), @tagName(Enum)).fields.len);
+
+            const n = CHOICES_SIZE;
+            return battle.choices(@enumFromInt(player), @enumFromInt(request), @ptrCast(buf[0..n]));
+        }
+    };
+}
+
+pub fn exports() type {
+    @export(gen(1).update, .{ .name = "GEN1_update", .linkage = Strong });
+    @export(gen(1).choices, .{ .name = "GEN1_choices", .linkage = Strong });
+    return struct {};
+}
+
+fn size(n: usize) u32 {
+    return std.math.ceilPowerOfTwo(u32, @as(u32, @intCast(n))) catch unreachable;
+}

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: std.builtin.Type.Int = .{ .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 };
+}