Files
siege_deck/Docs/SiegeDeck/Engine/Scripting.md
T
darman 45b246c1d7 docs: Initialize comprehensive project documentation
Migrates existing GDD and engine design notes from HacknPlan into a new Obsidian vault.

This establishes a centralized, version-controlled knowledge base covering engine architecture, game constraints, design decisions, and open questions.
2026-09-24 23:55:48 +02:00

4.1 KiB

tags, status, candidates
tags status candidates
engine
scripting
undecided
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.
    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:
    class IScriptBackend {
    public:
        virtual ~IScriptBackend() = default;
        virtual Result<void> 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 DefinitionDBs (see Assets#Definition databases).

Candidates

Lua 5.4 / Luau

Lua tables are the data format, so data and behaviour live in one file.

--!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.

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);
    }
}
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.