--- tags: - engine - scripting status: undecided candidates: - Lua 5.4 / Luau - AngelScript --- # Scripting > [!warning] Language not chosen yet > The shortlist is **Lua (5.4 or Luau)** and **AngelScript**. Keep the boundary language-agnostic until a spike settles it. Don't add a script runtime to CMake before then. ## The core rule **Scripts run on events, never per entity per tick.** - **Scripted hooks:** card play, tower placed, hit, kill, wave start, turn start, relic triggers. - **Stays in C++:** movement, targeting scans, projectile integration and damage application. Towers are *configured* by scripts (targeting mode, attack stats, an `on_hit` hook) and *executed* by C++ systems. ## Language-agnostic boundary 1. **Definitions are C++ structs.** A loader's only job is to fill them in. The rest of the engine never sees a script value. ```cpp struct CardDef { StringId id; int cost; TargetSpec target; ScriptHook onPlay; // opaque: a Lua function ref or an asIScriptFunction* }; ``` 2. **The game API is defined once in C++** (`PlayContext::DamageArea`, `ApplyStatusArea`, `Draw`, …). Each backend binds the same surface; only the binding code is language-specific. 3. **One small backend interface:** ```cpp class IScriptBackend { public: virtual ~IScriptBackend() = default; virtual Result LoadModule(const Path& file) = 0; // fills DefinitionDBs virtual void Invoke(ScriptHook hook, PlayContext& ctx, const Tile& tile) = 0; virtual void Reload(const Path& file) = 0; }; ``` Once a language is picked, collapse this into a concrete class. A permanent two-language abstraction isn't worth keeping. ## Host responsibilities (either language) - Sandbox: no file or OS access; randomness only through engine RNG streams (see [[Randomness]]). - Module loading from `Assets/Scripts`. - Errors are caught, logged and shown in the debug UI. A broken script never crashes the game. - Hot reload refills the `DefinitionDB`s (see [[Assets#Definition databases]]). ## Candidates ### Lua 5.4 / Luau Lua tables are the data format, so data and behaviour live in one file. ```lua --!strict (Luau only) local fireball: Card = { id = "fireball", cost = 2, target = Target.tile(1), on_play = function(ctx: PlayContext, tile: Tile) ctx:damage_area(tile, 1, 12, "fire") ctx:apply_status_area(tile, 1, "burn", 3) end, } return fireball ``` - **Lua 5.4:** tiny and well known; sol2 bindings; dynamic typing. - **Luau:** gradual static types, a type checker and language server, a built-in sandbox, faster than 5.4. Its C API is close to Lua 5.1's, and sol2 would need adapting. It ships its own CMake build. ### AngelScript C++-like syntax with static types. C++ functions are registered directly with native calling conventions, so there's very little glue. ```cpp class Fireball : ICard { string id() const { return "fireball"; } int cost() const { return 2; } void onPlay(PlayContext@ ctx, const Tile &in tile) { ctx.damageArea(tile, 1, 12, DamageType::Fire); ctx.applyStatusArea(tile, 1, "burn", 3); } } ``` ```cpp engine->RegisterObjectMethod("PlayContext", "void damageArea(const Tile &in, int, int, DamageType)", asMETHOD(PlayContext, DamageArea), asCALL_THISCALL); ``` - There's no table literal, so pure stat blocks (enemy HP, wave lists) need TOML or JSON, or have to be written as classes. ## Decision spike Implement the same three things in each candidate: 1. **Fireball card:** a targeted area effect. 2. **"When an enemy dies, draw 1" relic:** event subscription. 3. **Tower `on_hit` hook:** called at high frequency during a wave. Compare authoring ergonomics, lines of binding code, hot-reload behaviour and error messages. ## Considered and dropped - **C#:** hosting CoreCLR, maintaining an interop layer, reload through `AssemblyLoadContext` and shipping the runtime cost too much for event-only hooks. It would only make sense as the *main game language*, which isn't the goal. See [[Decision Log]]. - **Wren, Squirrel, QuickJS/TypeScript, pocketpy, Daslang, WebAssembly, C++ hot-reload DLLs:** reviewed and not shortlisted.