Scenario Compiler Ixperium

Bidirectional converter between custom DSL (.scenario / .room) and React Flow JSON.

.scenario + .room  ──import──>  .json   (import → React Flow JSON)
.scenario + .room  <──export──  .json   (export → DSL files)

Prerequisites

• Zig 0.16.0 — or Docker.

Build

zig build

Binary at zig-out/bin/scenario_compiler_ixperium.

Usage

import — DSL → JSON (into React Flow app)

Parse .scenario file (auto-detects matching .room) and write React Flow JSON.

# specify output path
scenario_compiler_ixperium import data/sample.scenario out/sample.json

# output to directory (filename derived from scenario name)
scenario_compiler_ixperium import data/sample.scenario out/

# no output arg — writes <name>.json to cwd
scenario_compiler_ixperium import data/sample.scenario

export — JSON → DSL (from React Flow app)

Parse React Flow JSON and write .scenario + .room files.

# write to specific directory
scenario_compiler_ixperium export data/sample.json out/

# default output dir is cwd
scenario_compiler_ixperium export data/sample.json

Using zig build run

Pass args after --:

zig build run -- import data/sample.scenario
zig build run -- export data/sample.json out/

Docker

Build image

docker build -t scenario-compiler .

Run (vanilla Docker)

# import (DSL → JSON)
docker run --rm -v ./data:/data scenario-compiler import /data/sample.scenario

# export (JSON → DSL)
docker run --rm -v ./data:/data scenario-compiler export /data/sample.json

Run (docker-compose)

docker-compose.yml mounts ./data as /data and sets working dir there.

# import (DSL → JSON)
docker compose run --rm app import sample.scenario

# export (JSON → DSL)
docker compose run --rm app export sample.json

Data format

.scenario — scenario logic

Defines clients, actors, triggers, actions, delays, and a flow graph:

scenario "<name>" {
  room: "<room-id>"

  client <id> { label, age, hearing, mobility, vision }
  actor  <id> { client, position }

  trigger <id> { device, on }
  action  <id> { service, target, message }
  delay   <id> { duration }

  flow {
    trigger -> action
    action -> [action_a, action_b]   // parallel
  }
}

.room — room layout

Defines walls, openings, zones, and devices with positions:

room "<name>" {
  dimensions: [w, h]
  wall   <id> { from, to }
  opening <id> { wall, from, to }
  zone   <id> { from, to }
  device <id> { entity_id, position, type, radius }
}

Data files

• data/ — mounted by docker-compose, contains sample .scenario, .room, and .json
• src/examples/ — copies of samples baked into the Docker image at /data