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.
104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
---
|
|
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<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 `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.
|