Ledger v3 is in active development what it isn't yet
Ledger is a deterministic gameplay ability system. Write your game's stats, abilities and effects as content, check them with plays, and ask the running world why any value is what it is. The core knows no engine; a Godot adapter and editor addon come with it.
ledger new Arena
C# on .NET 10 · fixed-point numbers · same state on every machine · Godot 4.7 .NET addon
stat Damage by type default 1stat Resist by type max 0.75 stages Attack Armour Resistance effect Hits before Damage by holder at Attack scale holder.Damage before Damage of holder having Physical at Armour scale 100 / (100 + holder.Armour) before Damage of holder at Resistance scale 1 - holder.Resist archetype Brute base MaxHealth 1000 base Armour 100 base Resist.Fire 0.5 base Resist.Cold 0.25 full Health has Hits ability Strike target one deal 40 Physical + 40 Fire + 40 Cold + 40 Lightning to target effect Searing Damage.Fire + 20% effect Sharpened Damage + 10%#10 tick 0 Health −125, sent 160, 125 after its rules, from #1 by Strike
The Attack rule read holder.Damage. Its receipt: --why 23 a.Damage.Fire
== at the end, tick 0: #2 Brute, Health Health = 875 of 1000 anchored at 875 at tick 0, no drift at least 0, at most 1000 its drift crosses no line its changes to Health, newest first: #10 tick 0: Health -125 (sent 160, 125 after its rules), 1000 -> 875, from #1 by Strike Hits scale Physical 4: 160 -> 164 Hits scale Fire 12: 164 -> 176 Hits scale Cold 4: 176 -> 180 Hits scale Lightning 4: 180 -> 184 Hits scale Physical -22: 184 -> 162 Hits scale Physical 0: 162 -> 162 Hits scale Fire -26: 162 -> 136 Hits scale Cold -11: 136 -> 125 Hits scale Lightning 0: 125 -> 125 == at the end, tick 0: #1 Exile, Damage.Fire Damage.Fire = 1.3 base 1 from Damage.Fire Searing: percent +0.2 Sharpened: percent +0.1 (1 + 0) x (1 + 0.3) x 1
An Exile carrying two affixes strikes a Brute for 40 of each of four types. Every line item
names the rule that made it, the rule's line names the stat it read, and the stat's receipt names the
affixes. Hover a line item to see the content behind it. The stage labels come from
ledger pipeline; the rest is the tool's own output, laid out as a ledger.
Each step answers one question about your game. Run them in this order after any change. Errors come back at their file, line and column, all of them at once.
The rules live in content\*.ledger; what they should do lives in a
.play beside them.
Does the content load, and do the plays read?
Does the content do what the plays say? A failing step is reported at its line.
Does the game around the content still work: a run, a recording replayed, a quickload's round trip?
Does it look and feel right?
A play makes actors, gives orders, moves time and expects values. Every expected number says
where it comes from, so a reviewer can check the arithmetic and ledger play checks the content.
effect Burning tags Fire stack add max 5 lasts 3s every 0.5s deal 3 * self.stacks Fire to holder from source ability Fireball tags Spell Fire target point within 14 cost Mana 20 cooldown 1s windup 0.8s broken by Damage of holder when event.landed >= 25 deal 30 Fire to all enemies within 2.5 of target apply Burning to all enemies within 2.5 of targetplay "wound up at (10, 0): nothing lands or is paid until 0.8 s; then 30 to each foe within 2.5, none to one 3 away, 20 Mana paid, each one hit burning" make r Side make b Side make h Hero with team = r at 0 0 make a Dummy with team = b at 10 0 make c Dummy with team = b at 11.5 1 make far Dummy with team = b at 13 0 act h Fireball at 10 0 expect done expect h active Fireball advance 0.5s expect a.Health = 1000 from content: the Dummy's 1000, nothing landed before the windup's 0.8 s expect h.Mana = 200 from content: the Hero's MaxMana 200, nothing paid before the commit advance 0.3s expect h idle expect a.Health = 970 from content: 1000 less Fireball's 30 at 0.8 s expect c.Health = 970 from content: 1.80 from the point, within 2.5: 1000 less 30 expect far.Health = 1000 from content: 3 from the point, past 2.5 expect h.Mana = 180 from content: the Hero's 200 less Fireball's 20 at the commit expect a has Burning 1 from content: Fireball's apply Burning to each foe within 2.5 expect far lacks Burning act h Fireball at 10 0 expect refused OnCooldownAt 60 ticks a second, advance 0.5s is 30 ticks. Jumping time and
stepping it run the same code, so a play can skip ahead without missing a beat.
Every order gets an outcome. expect refused OnCooldown checks
the refusal by name, the same outcome the game receives.
save mid-playAt any step, save saves the world and plays on from the
restored copy, as a quickload would. Every step after it checks the round trip.
The code that changes a value writes down how it changed. A tooltip, a debugger and a replay all read that same record, so the answer never drifts from what actually happened.
== at the end, tick 0: #1 Exile, Damage.Fire
Damage.Fire = 1.3
base 1 from Damage.Fire
Searing: percent +0.2
Sharpened: percent +0.1
(1 + 0) x (1 + 0.3) x 1
Its base, each term and the effect that gave it, the strongest of each category, and its bounds. Two percents sum before they multiply, the way an ARPG's increases do.
In a running game, the inspector shows the same receipt for the actor you pick, each effect a button to its line.
== at the end, tick 0: #2 Brute, Health
Health = 875 of 1000
anchored at 875 at tick 0, no drift
at least 0, at most 1000
its drift crosses no line
its changes to Health, newest first:
#10 tick 0: Health -125 (sent 160, 125 after its rules), 1000 -> 875, from #1 by Strike
Hits scale Physical 4: 160 -> 164
Hits scale Fire 12: 164 -> 176
…
A pool's anchor, its drift, its bounds and bands, and the next line its drift will cross. Then every change the journal holds, newest first, each with its line items: the rule, the verb, the portion and the amount, and the hit before and after.
Regeneration is closed form, so the receipt says where it was anchored instead of listing every tick.
Health: a change to it meets 3 rules, in this order before, at Attack Hits: Damage by holder at Attack (content/cookbook/backbone.ledger:20) scales it; held by Exile, Brute before, at Armour Hits: Damage of holder having Physical at Armour (content/cookbook/backbone.ledger:22) scales it; held by Exile, Brute before, at Resistance Hits: Damage of holder at Resistance (content/cookbook/backbone.ledger:24) scales it; held by Exile, Brute no archetype lacks a layer its like hold
Each stage's shields, armours and resistances in the order a hit meets them, who holds each, and any archetype missing a layer its like hold.
Add --hit Fire 40 Brute to send one hit of a type and an amount through a fresh actor and see
what each rule left.
== at the end, tick 48: #3, Fireball
Fireball, newest first:
#3/1 Fireball, by order: its Activate #7 at tick 0
windup on the world's clock: 48 long, from reading 0
ticks 0 to 48 at 1: 48 run
#8 tick 48: Commit
adds up: 48 run from reading 0 to 48 as its clock holds it, less 0 pushed, 48 of its 48
Each stretch of its clock at each rate, every push and beat, a flight's speed and time, its end, and a check that it adds up.
A 0.8 s windup at 60 ticks a second is 48 ticks. Under a haste or a slow, the receipt shows each stretch at its own rate.
The Godot adapter hosts the world and ticks it from _PhysicsProcess, and its kit
draws what a player may see. The editor addon puts the command line's answers in a dock, next to the game
they describe.
An ability bar, a cast bar and tooltips that preview what the world would do, and cues bound to tags your content already writes. An ability added in content alone shows up and can be used with no C#.
Highlighting, and the words and names that fit
what you typed, each with its kind. After holder. it offers what an actor holds.
Checks, plays, a preview, the Pipeline tab and the Run tab. Every rule and name is a button to its line.
Pick an actor in the running game and read its pools' and stats' receipts and the changes the journal holds.
Save a content file and it reloads into the running world between two ticks, with its report as Godot warnings.
when shown true or false as it stands.A sketch of the Pipeline tab. It lists the lines ledger pipeline prints.
A rule like these only holds if something refuses to let it slip. Each comes with the check that keeps it.
Time is ticks. Randomness is seeded, drawn from streams the world owns, and saved. Nothing reads the machine: no clock, no culture, no hash order, no floating-point function whose answer differs by machine. Two runs on two machines end in identical state.
Checked bythe same seeds replayed under another culture, time zone and operating system; every outside call the core makes held to an allowlist; its compiled code scanned for floats.
Games with hundreds of actors stutter on garbage collection, and the cost is invisible until it isn't. So it is measured in every build a game runs.
Measureda strike through a build of ten affixes: 3.4 to 3.5 µs, 0 bytes allocated.
A restored world holds exactly what the saved one held and plays on exactly as it would have. Saves, quickloads, replays and lockstep joins all depend on it.
Checked byroundtrip: saved again at once, the same file; then both
played on to one save.
A game can ask why a value is what it is, and why an action was refused, and get the real answer the world used. The author, the player reading a tooltip and the tester reading a replay all see the same one.
Asked with--why, ledger pipeline, ledger why,
and the inspector.
An engine-free core. Ledger knows no game engine. Space, AI and presentation stay the game's, behind ports, and an adapter joins the core to an engine. Godot's comes first.
Each recipe is a .ledger and its .play that load alone, cut down to one
mechanic from a game built on Ledger. Find the one nearest what you want, copy it, then change its numbers and
names.
Better to know before you start a game on it.
Ledger keeps the numbers on a game's actors and every way they change. Physics, AI and rendering stay your game's. Space sits behind a port: use the plane space it ships with, or bring your own.
Every value is a Num, a fixed-point decimal. The platform's
floating-point maths is kept out of the core, since its last digit can differ by machine. The host's trig reads
a committed table instead.
Rollback in place and client prediction under server authority are built, with side views so each player is sent only what their side can see. Ledger makes the bytes; sending them is your game's job. A game moved by Godot's float physics can't be a rollback or lockstep peer.
Content is plain text. You can diff it, review it and grep it, and a coding agent can write it.
ledger new makes a Godot C# game with its content, its plays and a headless runner,
ready for the loop above.
The authoring guide is an agent skill, ledger-author, and every new game's
CLAUDE.md points to it. ledger check --json and ledger play --json
print one object a line, each with a stable id, the line as written and a fix where one is known.
Add --turns for a turn-based game, or --space own to
bring your own space.
Edit content\Arena.ledger and its play, then check and
play them.
Build the game's project first; the build copies the addon in. Then open the folder in Godot 4.7 .NET.
Stats, abilities and effects as content, a world that runs them the same on every machine, and an answer for every number it holds.