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.
This commit is contained in:
@@ -0,0 +1,103 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user