Extra Utilities

Extra Utilities (EXU) is a native Lua extension for Battlezone 98 Redux. It adds engine, renderer, UI, object, multiplayer, and gameplay controls that are not exposed by the stock mission API.

EXU currently targets the 32-bit Windows build of Battlezone 98 Redux 2.2.301, including that same Win32 exu.dll under Steam Proton. It does not support a native Linux or macOS game binary, or Battlezone 1.5. Native addresses and hooks are build-specific and must be revalidated when the game updates.

Windows/GOG, Windows/Steam, Linux/Steam via Proton, and Linux/GOG through a compatible Wine/Proton prefix are maintained together. See the shared BZR platform and distribution compatibility policy.

Features

• Camera and display — camera modes, matrices, origins, field of view, zoom limits, clip distances, aspect ratio, projection mode, polygon mode, game resolution, UI scaling, and fullscreen state.
• Environment and lighting — fog, gravity, ambient and sun lighting, time of day, shadow distance, skybox/skydome/skyplane controls, visibility masks, retro-lighting schemes, and viewport shadow or overlay toggles.
• Particles and debug rendering — create and control Ogre particle systems, attach them to the camera, a game object, or a skeleton bone, tune live emitter rate/direction/velocity/lifetime/spread/colour, toggle wireframe, and show bounding boxes. (DrawLine, DrawBox and ClearVisuals are placeholders that draw nothing yet.)
• Materials, terrain, and entities — inspect and replace entity or sub-entity materials, clone materials, modify textures and pass colors, control visibility and render queues, manipulate lights and animations, and re-theme the live terrain material without reloading the map.
• Overlays and HUD layout — create Ogre overlays and text elements, position and style them, move or recolor stock scrap and pilot readouts, manipulate HUD sprite rectangles, and inspect the command-menu bounds.
• Radar, reticle, and satellite — radar mode and scale, edge-path layout, reticle position/range/object data, satellite positions, pan speed, zoom, and state.
• Game objects and AI — object pointers and handles, mass, radar and jamming values, weapon selection masks, construction-rig selection, AI process/task inspection, selected task-state writes, and Lua replacement of the selected-unit Hunt command.
• Gameplay hooks — global and per-unit turbo, shot convergence, ordnance velocity inheritance, engine-flame colors, silent scrap changes, infinite ammo/scrap controls, unit-VO behavior, AI targeting and tuning, turret pitch, attack reveal, and mission-scoped hook resets.
• Ordnance and physics — build ordnance, inspect ordnance attributes, adjust the ballistic coefficient, and use matrix/vector helpers including screen-to-world conversion.
• Multiplayer — synchronized or asynchronous object creation, lives, scoreboard visibility, network player ID, custom kill messages, and starting-recycler control. Gameplay and physics setters (turbo, infinite ammo/scrap, ordnance velocity inheritance, the ballistic coefficient) stay available in network games but apply only on the calling machine: every peer's mission script must make the same call.
• Input, preferences, and system utilities — game-key state, pause-menu detection, play and sound settings, native save requests, screen resolution, Steam ID, and diagnostic message boxes.
• OpenShim integration — optional runtime bridges for shared turbo, HUD, convergence, reticle-range, music, radar, and related ownership. EXU retains standalone fallbacks where supported and fails closed when an optional bridge is unavailable.
• Native consumers — a small exported C API for version checks, access to the registered Lua state, and selected integration callbacks.

Detailed Lua API descriptions and editor annotations are kept in Definitions/ExtraUtils.lua. That file is for editor tooling only and must not be loaded at runtime; the runtime export table in src/luaexport.cpp remains the definitive list of registered functions.

Additional focused documentation lives in Docs/, including the animation API and persistent storage/continuity API.

Using EXU

Windows

Install exu.dll through the EXU Steam Workshop item or download it from the latest release, then load it from a mission script:

local exu = require("exu")

exu.dll needs the Microsoft Visual C++ 2015-2022 Redistributable (x86), which the game itself does not install. Without it, require("exu") fails as if the module could not be found. Under Proton, Wine's built-in runtime is used and nothing extra is needed.

Depending on the shared Workshop installation is preferred to bundling a private DLL copy with each mod. A shared installation receives fixes and avoids conflicts when multiple mods expect different EXU versions.

See examples/ for focused demonstrations. C++ consumers can include include/ExtraUtils.h and link against the import library produced by the build.

Linux (Proton)

The shipped exu.dll is a Win32 Lua C module. Linux hosts deploy that same DLL into a Proton game folder; there is no native Linux .so.

Native Steam or Flatpak — paste in a terminal:

curl -fsSL https://raw.githubusercontent.com/GrizzlyOne95/ExtraUtilities/main/scripts/install_linux.sh | bash -s -- --native

Snap Steam — paste in a terminal:

curl -fsSL https://raw.githubusercontent.com/GrizzlyOne95/ExtraUtilities/main/scripts/install_linux.sh | bash -s -- --snap

Both commands download exu.dll from the latest release and verify it against the SHA256SUMS.txt published with that release; a mismatched or unverifiable download installs nothing.

No Steam launch options are required. Proton loads exu.dll as a Windows DLL (this is not an OpenShim winmm.dll proxy).

To copy a local Windows build instead of a GitHub release:

./scripts/deploy_linux_proton.sh

Building

Requirements:

• Visual Studio 2022 with Desktop development with C++ for the Win32 exu.dll
• MSVC v143 14.43 or newer
• Python 3 for validation tooling and Linux host checks

The Ogre headers required to compile EXU are committed under third_party/ogre-1.10.0-bzr/include/; a normal build does not require downloading or cloning Ogre first.

Build ExtraUtilities.sln as Release|x86 on Windows. The project-level target is Release|Win32 and writes Release/exu.dll.

msbuild ExtraUtilities.sln /p:Configuration=Release /p:Platform=x86

Linux can run the host-side validation lane directly:

bash tests/linux/run.sh

Lua 5.1, OgreMain, and OgreOverlay build dependencies required by EXU are included in the repository. If several MSVC toolsets are installed, pass /p:VCToolsVersion=<version> to select a recent one explicitly.

The optional third_party/ogre-1.10.0-bzr/Build-Ogre-BZR.ps1 workflow is only for rebuilding/comparing Battlezone-compatible Ogre binaries; it is not part of a normal EXU build.

Updating for a game patch

• Revalidate the addresses and signatures documented in exu.json against the new executable.
• Update the corresponding declarations in src/bzr.h and record the verified game version.
• Run python tools/qualify_bzr_build.py <path-to-battlezone98redux.exe> --write-report and review missing/ambiguous targets. Qualify the GOG executable or an unpacked image: the Steam executable's code is SteamStub-encrypted on disk and every anchor reports MISS.
• Regenerate the build profile with python tools/generate_bzr_build_profile.py, then confirm with --check and python tools/validate_hardening.py.
• Build Release|x86, run the validation suites, and smoke-test Lua loading plus the affected feature groups in game.
• Update the EXU version in src/About.h, include/ExtraUtils.h, Definitions/ExtraUtils.lua, and Resource/Resource.rc together before tagging a release.

Diagnostics

EXU writes logs/exu.log next to the game executable (falling back to the game folder). Failures and patch refusals always land there. Verbose per-call tracing (exu_environment_debug.log, exu_material_debug.log, and success lines for overlay setters) is off by default because several of those bindings run every frame; set EXU_DEBUG_LOG=1 in the game's environment (Steam launch options: EXU_DEBUG_LOG=1 %command%) to enable it for a session.

Workshop publication

Workshop-source metadata is kept in Workshop/, workshop_description.txt, and workshop_changenote.txt. Maintainer notes for publishing are in Docs/WORKSHOP_RELEASE.md.

Credits

• VTrider — original EXU implementation and much of the native script-extender foundation.
• GrizzlyOne95 — ongoing maintenance, integrations, rendering features, and stability work.
• Janne — original Lua DLL project that helped establish the approach.
• DivisionByZero — DLL loader work used by later integrations.
• Business Lawyer — bug hunting and technical collaboration.

See COPYING and COPYING.LESSER for license terms.