Lua

Lua Deep Dive: Coroutines, State Machines, DSLs, and Game Scripting Architecture

A comprehensive deep dive into Lua’s most powerful techniques: coroutine pipelines, state machines, DSL building, and production-grade scripting architectures.

Leeting Yan 6 min read 1137 words

Lua is not just a lightweight script language.
It is a runtime toolbox capable of building state machines, pipelines, schedulers, entity systems, and even domain-specific languages (DSLs).

This deep dive focuses on production-level techniques heavily used in:

  • Game engines (Defold, Love2D, custom C/C++ engines)
  • AI scripting
  • UI scripting
  • Simulation and animation
  • Networking and asynchronous flows
  • Configuration languages and DSLs

1. Coroutine Pipelines (The Real Power of Lua)

Coroutines allow cooperative multitasking, enabling sequential code that behaves like async flows.

Let’s build coroutine pipelines step by step.

1.1 Basic Coroutine Pipeline

local function pipeline()
  print("Load data")
  coroutine.yield()

  print("Process data")
  coroutine.yield()

  print("Save result")
end

local co = coroutine.create(pipeline)

while coroutine.status(co) ~= "dead" do
  coroutine.resume(co)
end

This creates a resumable sequence—a common structure in:

  • Cutscene scripts
  • Quest/action scripting
  • Animation timelines
  • Network event handling

1.2 Coroutine-Based Task Scheduler

A small scheduler that runs many coroutines “simultaneously”:

local Scheduler = {}
Scheduler.__index = Scheduler

function Scheduler.new()
  return setmetatable({tasks = {}}, Scheduler)
end

function Scheduler:add(fn)
  local co = coroutine.create(fn)
  table.insert(self.tasks, co)
end

function Scheduler:update()
  local alive = {}
  for _, co in ipairs(self.tasks) do
    local ok = coroutine.resume(co)
    if ok and coroutine.status(co) ~= "dead" then
      table.insert(alive, co)
    end
  end
  self.tasks = alive
end

-- Demo
local s = Scheduler.new()

s:add(function()
  for i = 1, 3 do
    print("A", i)
    coroutine.yield()
  end
end)

s:add(function()
  for i = 1, 2 do
    print("B", i)
    coroutine.yield()
  end
end)

while #s.tasks > 0 do
  s:update()
end

Output:

A 1
B 1
A 2
B 2
A 3

This is a real coroutine scheduler:

  • No threads
  • No async/await
  • No callbacks
  • Extremely cheap (~few bytes each)

2. Coroutine-Based Timers (Game Loop Style)

Time-based coroutine control is the foundation of animations, cutscenes, tweening, AI behavior, and simulation scripting.

2.1 A Wait Function

local function wait(sec)
  local start = os.clock()
  while os.clock() - start < sec do
    coroutine.yield()
  end
end

2.2 Coroutine Timer Example

local function npc_behavior()
  print("NPC: Idle...")
  wait(0.5)

  print("NPC: Walk...")
  wait(1)

  print("NPC: Wait...")
  wait(0.3)
end

local co = coroutine.create(npc_behavior)

while coroutine.status(co) ~= "dead" do
  coroutine.resume(co)
end

Used in:

  • AI ticking
  • Tween and animation timelines
  • Game scripting logic

3. Finite State Machines (FSM) in Lua

State machines are essential for:

  • NPC AI
  • UI flow
  • Boss phases
  • Gameplay systems
  • Networking states

Lua makes FSM construction clean and concise.

3.1 Minimal State Machine

local FSM = {}
FSM.__index = FSM

function FSM.new(initial)
  return setmetatable({state = initial}, FSM)
end

function FSM:transition(new)
  print("STATE:", self.state, "->", new)
  self.state = new
end

-- demo
local f = FSM.new("idle")
f:transition("walk")
f:transition("attack")

3.2 FSM with State Logic Table

local fsm = {
  state = "idle",

  states = {
    idle = function(self)
      print("NPC is idle")
      self.state = "walk"
    end,
    walk = function(self)
      print("NPC is walking")
      self.state = "attack"
    end,
    attack = function(self)
      print("NPC attacks!")
      self.state = "dead"
    end,
  }
}

while fsm.state ~= "dead" do
  fsm.states[fsm.state](fsm)
end

3.3 Coroutine + FSM Hybrid (Industry Standard)

Most professional game engines use a coroutine-driven FSM hybrid.

local AI = {}
AI.__index = AI

function AI.new()
  return setmetatable({
    state = "idle"
  }, AI)
end

function AI:run()
  while true do
    if self.state == "idle" then
      print("Idle...")
      coroutine.yield()
      self.state = "walk"

    elseif self.state == "walk" then
      print("Walking...")
      coroutine.yield()
      self.state = "attack"

    elseif self.state == "attack" then
      print("Attacking...")
      coroutine.yield()
      self.state = "done"
      return
    end
  end
end

local co = coroutine.create(AI.new():run)
while coroutine.status(co) ~= "dead" do
  coroutine.resume(co)
end

This mirrors real AI scripting in:

  • Defold
  • Godot Lua plugins
  • Custom C/C++ engines
  • Roblox (similar coroutine model)

4. Embedded DSLs in Lua

(Domain-Specific Languages)

Lua is often used to build mini-languages because its table syntax is extremely flexible.

4.1 Config DSL

local config = {
  title = "My Game",
  window = {width = 800, height = 600},
  controls = {
    jump = "space",
    fire = "mouse1"
  }
}

Perfect for read-friendly config or asset definitions.

4.2 Animation Timeline DSL

timeline = {
  {wait = 1},
  {move = {x = 100, y = 200}, duration = 0.5},
  {play = "attack"},
  {wait = 0.3},
  {play = "idle"}
}

The engine interprets the DSL:

for _, step in ipairs(timeline) do
  if step.wait then
    wait(step.wait)
  elseif step.move then
    print("move to", step.move.x, step.move.y)
  elseif step.play then
    print("play animation", step.play)
  end
end

4.3 Quest/Action Script DSL

script = {
  talk "NPC_1",
  wait 1,
  move "player", to(10,20),
  play "npc_wave",
  wait 0.5,
  talk "NPC_1"
}

Implemented using Lua’s callable tables and sugar:

function talk(who) return {action="talk", who=who} end
function wait(t)  return {action="wait", time=t} end
function move(who, pos) return {action="move", who=who, pos=pos} end

Lua’s flexibility makes it ideal for high-level design.

5. Data-Driven Game Architecture With Lua

Modern game engines often use a C/C++ core + Lua scripting layer.

Lua excels at:

  • Gameplay scripting
  • Animation/FX scripting
  • AI logic
  • Event systems
  • UI scripting
  • Configuration tables
  • Hot-reload logic

5.1 Architecture Diagram (Common Pattern)

[C/C++ Engine Core]
    | 
    | exposes API
    ↓
[Lua Runtime]
    |
    | loads scripts and data tables
    ↓
[Game Logic: AI, Quests, UI, Entities]

Lua scripts remain hot-swappable, enabling rapid iteration without recompiling the engine.

6. Entity Scripting Pattern (Game Dev Standard)

local Entity = {}
Entity.__index = Entity

function Entity.new(id)
  return setmetatable({
    id = id,
    components = {}
  }, Entity)
end

function Entity:add(name, comp)
  self.components[name] = comp
end

function Entity:update(dt)
  for _, comp in pairs(self.components) do
    if comp.update then comp.update(comp, dt) end
  end
end

Usage:

local e = Entity.new(1)

e:add("move", {
  x = 0, y = 0,
  update = function(self, dt)
    self.x = self.x + 10 * dt
  end
})

e:update(0.16)
print(e.components.move.x)

Lua is perfect for data + logic co-location.

7. Event-Driven Lua Architecture

Lua excels at event-driven design.

local bus = {}

function bus.on(event, fn)
  bus[event] = bus[event] or {}
  table.insert(bus[event], fn)
end

function bus.emit(event, ...)
  for _, fn in ipairs(bus[event] or {}) do fn(...) end
end

bus.on("hit", function(dmg) print("hit:", dmg) end)
bus.emit("hit", 20)

A minimal event bus used in:

  • UI events
  • NPC event responses
  • Networking callbacks
  • Gameplay triggers

8. Building a Scripting Sandbox

For tools or modding support, you may want a restricted environment:

local sandboxEnv = {
  print = print,
  math = math,
  pairs = pairs,
}

local function sandbox(code)
  local fn = load(code, "sandbox", "t", sandboxEnv)
  return fn()
end

sandbox("print(math.sqrt(16))")

This is the foundation of safe modding systems.

9. Putting Everything Together

(A Complete Mini Game Script)

local function wait(sec)
  local start = os.clock()
  while os.clock() - start < sec do
    coroutine.yield()
  end
end

local function npc()
  print("NPC: idle")
  wait(0.5)

  print("NPC: walk")
  wait(1)

  print("NPC: attack")
  wait(0.3)

  print("NPC: done")
end

local co = coroutine.create(npc)

while coroutine.status(co) ~= "dead" do
  coroutine.resume(co)
end

This mini script uses:

  • coroutine timing
  • sequential flow
  • event-driven behavior
  • game-style scripting

10. Summary

In this deep dive you learned:

  • Coroutine pipelines & schedulers
  • Time-based scripting
  • FSM & coroutine hybrid AI
  • Lua DSL design patterns
  • Embedded game-scripting architecture
  • Entity/component scripting patterns
  • Event-driven architecture
  • Sandbox and safe execution
  • Complete game-script examples

Lua is deeply flexible.
It can be your AI engine, timeline system, game logic layer, data language, and DSL host—all in one tiny runtime.

Keep Reading

Follow the engineering thread

Get the next practical Birdor note, or browse the archive for related systems, tooling, and architecture work.

Join newsletter Browse articles