@pkmn/engine 0.1.0-dev.84cc1a02 → 0.1.0-dev.89cc1c98

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;
@@ -168,11 +170,11 @@ const install = async () => {
   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 +189,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 +208,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');
   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 {
@@ -229,14 +231,14 @@ const downloadHeaders = async () => {
   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}`);
+  log(`Downloading Node headers from ${url} to ${targz}`);
 
   try {
     await download(url, targz);
     await unpack(targz, dir);
     fs.renameSync(path.join(unpacked, 'node'), dest);
 
-    console.log('Node headers:', dest);
+    log('Node headers:', dest);
 
     return dest;
   } finally {
@@ -248,7 +250,7 @@ const downloadHeaders = async () => {
 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;
   }
 
@@ -256,10 +258,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 {
@@ -268,24 +270,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 {
@@ -317,14 +336,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});
@@ -335,8 +358,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;
@@ -355,7 +379,7 @@ 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') {

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/binding/node.zig

@@ -1,6 +1,8 @@
 const std = @import("std");
 const pkmn = @import("../pkmn.zig");
 
+const js = @import("../common/js.zig");
+
 const assert = std.debug.assert;
 
 const c = @cImport({
@@ -10,38 +12,49 @@ const c = @cImport({
 
 export fn napi_register_module_v1(env: c.napi_env, exports: c.napi_value) c.napi_value {
     const properties = [_]c.napi_property_descriptor{
-        Property.init("options", .{ .value = options(env) }),
-        Property.init("bindings", .{ .value = bindings(env) }),
+        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 properties = [_]c.napi_property_descriptor{
+        js.Property.init("options", .{ .value = options(env) }),
+        js.Property.init("bindings", .{ .value = bindings(env) }),
+    };
+    assert(c.napi_define_properties(env, object, properties.len, &properties) == c.napi_ok);
+    return object;
+}
+
 fn options(env: c.napi_env) c.napi_value {
-    var object = Object.init(env);
+    var object = js.Object.init(env);
     const properties = [_]c.napi_property_descriptor{
-        Property.init("showdown", .{ .value = Boolean.init(env, pkmn.options.showdown) }),
-        Property.init("trace", .{ .value = Boolean.init(env, pkmn.options.trace) }),
+        js.Property.init("showdown", .{ .value = js.Boolean.init(env, pkmn.options.showdown) }),
+        js.Property.init("log", .{ .value = js.Boolean.init(env, pkmn.options.log) }),
+        js.Property.init("chance", .{ .value = js.Boolean.init(env, pkmn.options.chance) }),
+        js.Property.init("calc", .{ .value = js.Boolean.init(env, pkmn.options.calc) }),
     };
     assert(c.napi_define_properties(env, object, properties.len, &properties) == c.napi_ok);
     return object;
 }
 
 fn bindings(env: c.napi_env) c.napi_value {
-    var array = Array.init(env, .{ .length = 1 });
-    Array.set(env, array, 0, bind(env, pkmn.gen1));
+    var array = js.Array.init(env, .{ .length = 1 });
+    js.Array.set(env, array, 0, bind(env, pkmn.gen1));
     return array;
 }
 
 fn bind(env: c.napi_env, gen: anytype) c.napi_value {
-    const options_size = @intCast(u32, gen.OPTIONS_SIZE);
-    const logs_size = @intCast(u32, gen.LOGS_SIZE);
-    var object = Object.init(env);
+    const choices_size: u32 = @intCast(gen.CHOICES_SIZE);
+    const logs_size: u32 = @intCast(gen.LOGS_SIZE);
+    var object = js.Object.init(env);
     const properties = [_]c.napi_property_descriptor{
-        Property.init("OPTIONS_SIZE", .{ .value = Number.init(env, options_size) }),
-        Property.init("LOGS_SIZE", .{ .value = Number.init(env, logs_size) }),
-        Property.init("update", .{ .method = update(gen) }),
-        Property.init("choices", .{ .method = choices(gen) }),
+        js.Property.init("CHOICES_SIZE", .{ .value = js.Number.init(env, choices_size) }),
+        js.Property.init("LOGS_SIZE", .{ .value = js.Number.init(env, logs_size) }),
+        js.Property.init("update", .{ .method = update(gen) }),
+        js.Property.init("choices", .{ .method = choices(gen) }),
     };
     assert(c.napi_define_properties(env, object, properties.len, &properties) == c.napi_ok);
     return object;
@@ -61,28 +74,32 @@ fn update(gen: anytype) c.napi_callback {
             assert(len == @sizeOf(gen.Battle(gen.PRNG)));
             assert(data != null);
 
-            var aligned = @alignCast(@alignOf(*gen.Battle(gen.PRNG)), data.?);
-            var battle = @ptrCast(*gen.Battle(gen.PRNG), aligned);
-            const c1 = @bitCast(pkmn.Choice, Number.get(env, argv[1], u8));
-            const c2 = @bitCast(pkmn.Choice, Number.get(env, argv[2], u8));
+            var battle: *gen.Battle(gen.PRNG) = @alignCast(@ptrCast(data.?));
+            const c1: pkmn.Choice = @bitCast(js.Number.get(env, argv[1], u8));
+            const c2: pkmn.Choice = @bitCast(js.Number.get(env, argv[2], u8));
 
             var vtype: c.napi_valuetype = undefined;
             assert(c.napi_typeof(env, argv[3], &vtype) == c.napi_ok);
             const result = switch (vtype) {
-                c.napi_undefined, c.napi_null => battle.update(c1, c2, pkmn.protocol.NULL),
+                c.napi_undefined, c.napi_null => battle.update(c1, c2, &gen.NULL),
                 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 = @ptrCast([*]u8, data.?)[0..gen.LOGS_SIZE];
-                    var stream = pkmn.protocol.ByteStream{ .buffer = buf };
-                    var log = pkmn.protocol.FixedLog{ .writer = stream.writer() };
-                    break :result battle.update(c1, c2, log);
+                    var 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() },
+                        gen.chance.NULL,
+                        gen.calc.NULL,
+                    );
+                    break :result battle.update(c1, c2, &opts);
                 },
             } catch unreachable;
 
-            return Number.init(env, @bitCast(u8, result));
+            return js.Number.init(env, @as(u8, @bitCast(result)));
         }
     }.call;
 }
@@ -101,129 +118,17 @@ fn choices(gen: anytype) c.napi_callback {
             assert(len == @sizeOf(gen.Battle(gen.PRNG)));
             assert(data != null);
 
-            var aligned = @alignCast(@alignOf(*gen.Battle(gen.PRNG)), data.?);
-            var battle = @ptrCast(*gen.Battle(gen.PRNG), aligned);
-
-            const player = @intToEnum(pkmn.Player, Number.get(env, argv[1], u8));
-            const request = @intToEnum(pkmn.Choice.Type, Number.get(env, argv[2], u8));
+            var battle: *gen.Battle(gen.PRNG) = @alignCast(@ptrCast(data.?));
+            const player: pkmn.Player = @enumFromInt(js.Number.get(env, argv[1], u8));
+            const request: pkmn.Choice.Type = @enumFromInt(js.Number.get(env, argv[2], u8));
 
             assert(c.napi_get_arraybuffer_info(env, argv[3], &data, &len) == c.napi_ok);
-            assert(len == gen.OPTIONS_SIZE);
+            assert(len == gen.CHOICES_SIZE);
             assert(data != null);
 
-            var out = @ptrCast([*]pkmn.Choice, data.?)[0..gen.OPTIONS_SIZE];
+            var out = @as([*]pkmn.Choice, @ptrCast(data.?))[0..gen.CHOICES_SIZE];
             const n = battle.choices(player, request, out);
-            return Number.init(env, @bitCast(u8, n));
+            return js.Number.init(env, @as(u8, @bitCast(n)));
         }
     }.call;
 }
-
-const Array = struct {
-    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;
-    }
-
-    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);
-    }
-};
-
-const Boolean = struct {
-    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;
-    }
-};
-
-const Number = struct {
-    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;
-    }
-
-    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(T, 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(T, result);
-                    },
-                },
-                33...63 => {
-                    var result: i64 = undefined;
-                    assert(c.napi_get_value_int64(env, value, &result) == c.napi_ok);
-                    return @intCast(T, result);
-                },
-                else => {
-                    var result: i64 = undefined;
-                    assert(c.napi_get_value_int64(env, value, &result) == c.napi_ok);
-                    return switch (info.signedness) {
-                        .signed => @as(T, value),
-                        .unsigned => if (0 <= value) @intCast(T, value) else unreachable,
-                    };
-                },
-            },
-            else => @compileError("expected number, got: " ++ @typeName(T)),
-        }
-    }
-};
-
-const Object = struct {
-    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;
-    }
-};
-
-const Property = union(enum) {
-    method: c.napi_callback,
-    value: c.napi_value,
-
-    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,
-        };
-    }
-};

package/src/lib/binding/wasm.zig

@@ -2,9 +2,11 @@ const std = @import("std");
 const pkmn = @import("../pkmn.zig");
 
 export const SHOWDOWN = pkmn.options.showdown;
-export const TRACE = pkmn.options.trace;
+export const LOG = pkmn.options.log;
+export const CHANCE = pkmn.options.chance;
+export const CALC = pkmn.options.calc;
 
-export const GEN1_OPTIONS_SIZE =
-    std.math.ceilPowerOfTwo(u32, @intCast(u32, pkmn.gen1.OPTIONS_SIZE)) catch unreachable;
+export const GEN1_CHOICES_SIZE =
+    std.math.ceilPowerOfTwo(u32, @as(u32, @intCast(pkmn.gen1.CHOICES_SIZE))) catch unreachable;
 export const GEN1_LOGS_SIZE =
-    std.math.ceilPowerOfTwo(u32, @intCast(u32, pkmn.gen1.LOGS_SIZE)) catch unreachable;
+    std.math.ceilPowerOfTwo(u32, @as(u32, @intCast(pkmn.gen1.LOGS_SIZE))) catch unreachable;

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