Game Replay Script Engine

Project roadmap

1. 01

   Define the replay format

   ~2h

   Document the replay format in the README: JSON Lines, one event per line, each with t (milliseconds from the match start), type (move, shoot, hit, pickup, death, round_end) and fields specific to each type, such as the player id, position, target and damage. Write a generator script that produces realistic sample replays of a few thousand events. Done when: the README describes every event type and sample replays are in samples/.

2. 02

   Parse and validate events

   ~2h

   Write a parser, using lua-cjson (installed through LuaRocks), that reads a replay line by line and validates each event: a known type, the required fields for that type, the right value types, and timestamps that never go backwards. Collect invalid lines with their line number and reason instead of stopping, and reject a replay when more than 1% of its lines are invalid. Done when: a replay with a few broken lines parses and lists the problems.

3. 03

   Build the event engine

   ~2.5h

   Write an engine that loads stats scripts and feeds them every event in order through handlers such as on_event(event, state) and on_finish(state). The engine keeps a match state object (players, positions, alive or dead, the current round) that scripts can read but not change directly. Processing the same replay always gives the same result. Done when: a simple script counting events per type gives correct totals on a sample replay.

4. 04

   Sandbox the stats scripts

   ~2.5h

   Load each script with load and a restricted environment table containing only safe functions (math, string, table and a few engine helpers), with no io, os, require or debug. Limit each script's run time with debug.sethook and an instruction counter, stopping scripts that run too long, and catch errors with pcall so one failing script doesn't stop the others. Done when: a script that calls os.exit or loops forever is stopped with a clear error, while the other scripts still produce results.

5. 05

   Write the standard stats scripts

   ~2.5h

   Write stats scripts for: accuracy per player (hits divided by shots), damage dealt and taken per round, kills and deaths, average time alive per round, and a position heatmap on a 20×20 grid. Each script returns a table of results. Combine all results into one JSON report. Done when: running the standard scripts on a sample replay produces a complete, correct report.

6. 06

   Visualize replays with LÖVE

   ~2.5h

   Create a LÖVE (love2d) app that loads a replay and plays it back: players as colored circles moving over time, shots as short lines, deaths as markers, with play, pause, 2x speed and a timeline slider. Reuse the same parser and state code as the engine. Done when: running love viewer/ samples/match1.jsonl plays the match back smoothly.

7. 07

   Serve stats with OpenResty and test

   ~2.5h

   Add an OpenResty location, POST /replays/stats, that reads the request body (up to 10 MB), runs the engine with the standard scripts, and returns the report as JSON, or 400 with the validation problems. Write busted tests for the parser, the engine, the sandbox limits and each stats script, using small replays built in the tests. Done when: curl returns stats for a sample replay, and busted passes.

Resources

• DocsLua 5.1 reference (DevDocs), used by LuaJIT and OpenResty
• DocsLÖVE (love2d) website and docs
• DocsOpenResty lua-nginx-module
• Docslua-cjson manual
• Docsbusted testing framework