Scripts

This page documents the OpenW3D Code/Scripts source tree. It is an overview of the gameplay script system used by the released Renegade codebase and should not be confused with TT Scripts 4.x / Scripts 5.x.

OpenW3D Script Reference

Overview

In current OpenW3D CMake builds, Code/Scripts is compiled as a shared library named scripts. The output name is scripts.dll in release builds and scriptsd.dll in debug builds.

The tree contains the script runtime, factory/registration helpers, reusable toolkit scripts, mission-specific logic, and a large set of test or prototype scripts carried forward from the original source tree.

Script Runtime

Most concrete scripts derive from ScriptImpClass in scripts.h. This helper sits on top of the engine ScriptClass interface and provides:

owner attach/detach handling
parameter-string parsing and typed accessors
save/load helpers
auto-save variable registration
default empty implementations for common engine callbacks

The most common callbacks exposed by ScriptImpClass are Created, Destroyed, Killed, Damaged, Custom, Sound_Heard, Enemy_Seen, Action_Complete, Timer_Expired, Animation_Complete, Poked, Entered, and Exited.

Registration Model

Scripts are registered through ScriptFactory and ScriptRegistrar. ScriptRegistrar maintains the global list of known script factories, can look them up by name, and creates instances on demand.

Most source files use the convenience macro from scripts.h:

#define DECLARE_SCRIPT(x, d) \
    REGISTER_SCRIPT(x, d) \
    class x : public ScriptImpClass

The script name exposed to the engine is the class name passed as x. The second argument d is a parameter-description string stored by the factory.

Parameter Strings

Each script instance can be attached with a comma-separated parameter string. ScriptImpClass exposes helpers such as Get_Parameter, Get_Int_Parameter, Get_Float_Parameter, and Get_Vector3_Parameter to read those values back.

The registration string passed to DECLARE_SCRIPT documents the expected parameter names and types. For example:

DECLARE_SCRIPT(
    M00_Action,
    "Start_Now=0:int, Receive_Type=14:int, Action_Priority=99:int, "
    "Action_ID=0:int, _Move_Destination:vector3"
)

This means the runtime script name is M00_Action and the expected parameters are described inline in the factory metadata.

Source Layout

The OpenW3D Code/Scripts tree is organized into a few broad buckets:

Files	Purpose
`scripts.h`, `scripts.cpp`	Core script implementation, callback stubs, parameter parsing, and save/load support.
`ScriptFactory.`, `ScriptRegistrar.`, `ScriptRegistrant.h`	Factory and registration infrastructure used to expose scripts by name.
`Toolkit*.cpp`	Reusable gameplay helpers such as actions, animations, broadcasters, objectives, sounds, powerups, triggers, spawners, and object helpers.
`Mission00.cpp` through `Mission11.cpp`, `mission08.cpp`, `MissionDemo.cpp`, `MissionX0.cpp`, `MissionS04.cpp`	Mission-specific logic for campaign, demo, or scenario content.
`PRDemo.cpp`	Prototype/demo mission scripts and mission-specific support code.
`Test_*.cpp`	Engine tests, gameplay experiments, and sample scripts used during development.
`Group*.cpp`, `unitcombat.cpp`, `DrMobius.cpp`	Miscellaneous gameplay helpers and one-off script implementations.
`Common.`, `DPrint.`, `CustomEvents.h`, `strtrim.*`, `DLLmain.cpp`	Utility and support code used by the scripts DLL.

Naming Patterns

The registered names are preserved exactly as written in DECLARE_SCRIPT. Common prefixes in the source tree include:

M00_ for general-purpose Renegade mission or toolkit scripts
M01_ through M11_ for mission-specific logic
MPR_ for the PRDemo.cpp prototype/demo scripts
Test_ or author-tagged names such as BMG_, DME_, RAD_, JDG_, and RMV_ for test, prototype, or contributor-specific work

Scope

This page is intentionally an overview of the script system and source layout. The generated per-script reference lives under scripts/reference and is produced from active DECLARE_SCRIPT registrations in the local OpenW3D source tree. It combines:

manual summaries from scripts/openw3d-script-overrides.json
nearby source comments when they exist
heuristic summaries derived from callback overrides and Commands-> usage

The machine-readable export for future LevelEditQt integration is scripts/openw3d-script-catalog.json.

To regenerate the catalog and RST pages, run:

python tools/generate_openw3d_scripts_reference.py