Replay NDJSON execution logs

The replay panel turns a captured run of your tree into a step-through debug session. Each tick replays onto the canvas as a colored overlay so you can see exactly which nodes were RUNNING, SUCCESS, or FAILURE in real time.

NDJSON format

The replay panel expects one JSON object per line, in this order (the panel groups events by tick):

{"type":"tree","root":{...}}
{"type":"tick_begin","tick":1}
{"type":"transition","tick":1,"nid":0,"to":"RUNNING"}
{"type":"transition","tick":1,"nid":1,"to":"SUCCESS"}
{"type":"tick_end","tick":1,"result":"SUCCESS"}
{"type":"tick_begin","tick":2}
{"type":"transition","tick":2,"nid":0,"to":"RUNNING"}
{"type":"tick_end","tick":2,"result":"RUNNING"}

Field reference

How to capture a run

The editor doesn't generate the log itself — it consumes logs produced by whatever behavior-tree engine you run in production (or in a test harness). Two common ways to get a log:

Option A: instrument a BehaviorTree.CPP runner

In your C++ code, hook the tree's tick callbacks and write JSON lines to a file:

// Pseudocode — adapt to your BTCPP version
BehaviorTree::Tree tree;
tree.tickWhile([&](const Tree& t) {
  int tick = t.tickCount();
  std::cout << R"({{"type":"tick_begin","tick":{}}})" << tick << "}\n";
  for (auto node : t.nodesInExecutionOrder()) {
    std::cout << R"({{"type":"transition","tick":{}})" << tick
              << R"(,"nid":)" << node->id()
              << R"(,"to":")" << to_string(node->status()) << "\"}\n";
  }
  std::cout << R"({{"type":"tick_end","tick":{}})" << tick
            << R"(,"result":")" << to_string(t.rootNode()->status()) << "\"}\n";
  return true;
});

Option B: stream via WebSocket

Use the editor's built-in WebSocket viewer to receive ticks live. See Live monitor via WebSocket.

Loading the log

1. Click the 📊 Replay button in the header. The right drawer slides open.
2. Under Load log, click Choose file and select your .jsonl.
3. Or click Load example to load the bundled sample run.

Once loaded, the tree is drawn automatically and the playback controls activate.

Playback controls

Reading the visualization

Each node on the canvas is overlaid with a status color:

• ▢ Gray — IDLE / not ticked yet this run.
• ▣ Blue — RUNNING (animates briefly when a node enters this state).
• ▣ Green — SUCCESS (terminal).
• ▣ Red — FAILURE (terminal).

When a node transitions to RUNNING / SUCCESS / FAILURE, the editor briefly flashes its border to draw your eye. The status bar at the top of the replay panel shows the current tick number and final result.

Sharing logs

The .jsonl log is a plain text file. Send it via Slack, email, or commit it to your repo. Recipients can open it in the same editor and see exactly what you saw — no out-of-band screenshots needed.

← Import & export WebSocket live monitor →

Last updated: 2026-07-09