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.
4.1 KiB
4.1 KiB
tags, status, candidates
| tags | status | candidates | ||||
|---|---|---|---|---|---|---|
|
undecided |
|
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
- 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* }; - 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. - One small backend interface:
Once a language is picked, collapse this into a concrete class. A permanent two-language abstraction isn't worth keeping.
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; };
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:
- Fireball card: a targeted area effect.
- "When an enemy dies, draw 1" relic: event subscription.
- Tower
on_hithook: 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
AssemblyLoadContextand 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.