Game Dialogue Engine

Project roadmap

1. 01

   Set up the library

   ~1h

   Create a Lua 5.4 (or LuaJIT) project with a dialogue/ module folder, a play.lua script and a spec/ folder. Install busted through LuaRocks, and add a rockspec file listing the dependencies. The module exports a new(story) function that returns an engine object. Done when: lua play.lua runs and busted runs an empty test.

2. 02

   Define the story format

   ~2h

   Stories are Lua table files, loaded with loadfile in an empty environment so they can't run other code. A story has a start node id and a list of nodes. Each node has a speaker, text and choices; each choice has text, next (a node id), an optional condition string and optional effects such as set = {met_guard = true} or add = {trust = 1}. A node without choices ends the conversation. Write a sample story with at least 12 nodes. Done when: the sample story loads into a table.

3. 03

   Validate stories

   ~2h

   Write validate(story) that returns a list of problems: a missing start node, choices pointing to nodes that don't exist, nodes that can never be reached from the start, and conditions that can't be parsed. The engine refuses to start an invalid story and prints every problem. Done when: a broken copy of the sample story reports each mistake you put in it.

4. 04

   Evaluate conditions safely

   ~2.5h

   Write a small parser for conditions instead of running them as Lua code with load, which would let story files execute anything. Support flag names (has_key), not, and, or, parentheses, and comparisons of numbers with >=, <=, ==, >, <. Unknown flags count as false or 0. Done when: expressions like has_key and trust >= 3 give the correct result for different flag values, and something like os.exit() is rejected as invalid.

5. 05

   Run a conversation

   ~2h

   Give the engine these methods: current() returns the speaker, the text and only the choices whose conditions are true; choose(index) applies the choice's effects to the flags and moves to the next node; and is_finished(). Choosing an invalid index returns an error instead of changing state. Done when: stepping through the sample story with different choices follows the right branches.

6. 06

   Save and load state

   ~1.5h

   Add save() returning a plain table (the current node, the flags and a story version) and load(state) that restores it. Serialize it to a file with a simple table serializer you write yourself or a library like serpent. Loading a save from a different story version returns an error. Done when: saving in the middle of a conversation and loading later continues from the same node with the same flags.

7. 07

   Build the terminal player and tests

   ~2h

   play.lua loads a story, prints each node as speaker: text, lists the numbered choices, reads the player's choice, and supports save and load commands. Write busted tests for the condition parser, the validator, effects on flags, hidden choices, and save and load. Done when: you can play the sample story in the terminal, and busted passes.

Resources

• DocsLua 5.4 reference (DevDocs)
• ArticleLearn Lua in Y minutes
• Docsbusted testing framework
• DocsLuaRocks documentation
• DocsDefold game engine (uses Lua)