Odin · bytecode VM · a build-along book

Odin Speaks Odin

Building a real embedded scripting language from scratch in Odin: a lexer, a parser, a bytecode compiler, a resumable virtual machine, and the host-embedding layer that turns it into the thing that scripts a game engine.

Odin Speaks Odin is the shelf's advanced volume. It assumes you've already built one non-trivial Odin project (Yo Odin's Destroids or Odin't Know That's Sköll, or equivalent) and walks you through building Muspel: a hand-written lexer, a recursive-descent parser, a tree-walking interpreter, a bytecode compiler, and a resumable stack-based VM whose scripts can wait() across frames with no OS threads at all. It ends with Embers, a small arcade game whose entire enemy-wave and boss-pattern layer is .mus script files you can edit and reload while the game is running.

â–¶ Play Embers Start reading Jump to Chapter 1

Contents

  1. -PrefaceWhy this book exists, who it's for, and the ground rules.
  2. 1Why embed a language at allA tour of the finished Embers, and why building your own scripting layer is worth it.
  3. 2Turning text into tokensA hand-written lexer with source spans and automatic semicolon insertion.
  4. 3Grammar and a first parserMuspel's grammar in EBNF, the AST, and a first recursive-descent parser.
  5. 4Precedence, operators, and error recoveryPrecedence climbing for expressions, functions, and multi-error recovery.
  6. 5Structs and enums: modelling structured dataUser-defined structs and enums: named fields, variants, and the value model they share.
  7. 6Arrays: fixed-capacity sequencesFixed-capacity arrays and for-in iteration, without per-frame allocation.
  8. 7Scope, and catching mistakes before running anythingA static resolver that catches undefined variables and arity errors up front.
  9. 8A tree-walking interpreterThe fastest way to validate Muspel's semantics before investing in a VM.
  10. 9Why tree-walking isn't enoughBenchmarking the tree-walker to feel, not just assert, why a bytecode VM earns its keep.
  11. 10Designing the instruction setA stack-machine bytecode ISA, constant pools, and the single-source-of-truth opcode table.
  12. 11The compiler, part 1: expressions and control flowAST-to-bytecode codegen and the jump-patching technique that makes if/while work.
  13. 12The compiler, part 2: functions and callsCall frames, CALL/RETURN, and an honestly-scoped subset of closures.
  14. 13The VM coreThe dispatch loop, the value stack, and every example program finally running for real.
  15. 14Disassembly, debugging, and runtime errorsA real disassembler, source-line-accurate stack traces, and a single-step debugger.
  16. 15The resumable VM: yield, wait, and cooperative scriptsThe book's central chapter: suspending and resuming a script across host frames with one opcode.
  17. 16The embedding boundaryHost-callable builtins and the value-marshalling layer between Odin and Muspel.
  18. 17Events, callbacks, and many scripts at onceCallback registration and scaling to one VM instance per scripted entity.
  19. 18Fault isolation: making a script crash-proofInstruction budgets, stack-depth limits, and graceful failure instead of a hung host.
  20. 19Live reload: editing a script while it runsWatching .mus files and safely hot-swapping bytecode into running VM instances.
  21. 20Modules: scripts that import scriptsimport: one script reusing another's declarations, a whole graph resolved and compiled once.
  22. 21Embers: a game entirely scripted by MuspelThe capstone: a playable arcade game whose waves and boss are pure data, live-edited while it runs.
  23. App AThe full Muspel grammarEvery EBNF production from the language chapters, collected in one place.
  24. App BThe full opcode referenceEvery instruction in Muspel's bytecode ISA, one row each.
  25. App CFull source listingsThe complete, verified source of the finished project.
  26. App DTroubleshootingThe recurring traps, in one place.
  27. App ELinks and referencesEverything the book cites, grouped.
  28. App FAttaching Muspel to DestroidsA sketch of the same script API bolted onto Yo Odin's Destroids.
  29. App GExtending MuspelFor loops, a new operator, and field access: what it actually takes to grow the language.
  30. App HA browser IDE for MuspelAn in-browser editor that runs games from a textarea and highlights them with Muspel's own lexer.

The finished project

Every code sample in the book is real and compiled. The complete source is in Appendix C, and you can play the exact build the book produces, then try editing one of its .mus scripts yourself. Yo Odin's Destroids and Odin't Know That's Sköll are the shelf's other two build-along games.

Prerequisite

This book does not teach Odin from first principles: it assumes the entire content of Yo Odin (or equivalent Odin comfort) and moves straight to lexer design. If you haven't built a non-trivial Odin project yet, start there.

Going further

This book's structure owes a large debt to Robert Nystrom's Crafting Interpreters, credited throughout and warmly recommended for the topics this book scopes out: a garbage collector, full closures, and a from-scratch type system.