Tyrant Stage Designer

Stage design software for IDPA and USPSA match directors.

Draw a stage by clicking and dragging. The software knows which sport you picked, checks your layout against that sport's current rulebook as you work, and prints a clean stage diagram and written briefing for the squad.

It runs entirely on your own computer. No account, no cloud, no internet needed to use it.

A printed stage sheet: docs/example-stage-sheet.pdf

Every target, prop and marking, in both rulesets:

Most stages get designed on graph paper or in a drawing program that has no idea what a fault line is. The rulebook lives in a separate PDF, so the round-count limits, steel percentages, non-threat ratios and distance caps get checked by memory — or at the safety briefing, which is too late.

Tyrant puts the rules inside the drawing. Place a target too far downrange for a scenario stage and it tells you, cites the rule, and tells you the distance.

Stage designer — the main tool. Pick IDPA or USPSA, pick the stage type, and get a palette containing only the targets and props that ruleset actually permits. Click to place, drag to position, set the required shots per target. Distances, round counts and steel percentages update as you work.

Every item carries its own colour and a small upright pictogram of what the thing looks like from the front — a popper is a popper, a barrel is a barrel — so a bay can be read at a glance without checking back against the palette. The footprint underneath stays geometrically true and rotates with the item; the pictogram stays upright, because a rotated silhouette stops being recognisable.

Live rule checking — every check cites the rule it came from. Red means fix it, amber means look at it, blue is a reminder about something the software cannot measure from a diagram.

Printed stage sheet — diagram, written briefing, target table with distances, and any outstanding rule problems, on one page. Print it or save it as a PDF from the browser's print dialog.

Gun checker — separate tool. Pick a division, enter weight, barrel length, capacity, magazine length, optic and compensator, plus bullet weight and velocity. It calculates power factor and tells you what is legal and what is not, with rule citations. Covers all IDPA and USPSA handgun divisions.

Rulebook watcher — a scheduled job re-checks the IDPA and USPSA sites, keeps local copies of the rulebooks current, and tells you in plain English which rule lines changed. It never edits the rule data on its own; changed wording gets queued for a human to read.

• Node.js 18 or newer (setup and rule updates only — the app itself needs none)
• curl
• python3 (only for ./start.sh; you can also just open the HTML file)
• poppler-utils for pdftotext (optional — enables rulebook change diffing)

On Debian or Ubuntu:

sudo apt install nodejs curl python3 poppler-utils

git clone https://github.com/nolanselby/tyrant-stage-designer.git
cd tyrant-stage-designer
./setup.sh

setup.sh downloads the current IDPA and USPSA rulebooks from the associations' own sites into rulebooks/, builds the app's data bundle and runs the test suite.

To also install the daily rule-update check:

./setup.sh --with-cron

./start.sh

That serves the app on http://localhost:8777 and opens your browser. You can also skip it entirely and open app/index.html directly — the app is plain HTML and JavaScript with no build step.

1. Pick the sport. Everything downstream follows that rulebook.
2. Name the stage, choose the stage type, set your bay size.
3. Work down the left column — it is numbered in the order a stage gets built. Drag an item onto the bay to place it exactly where you want, or click it to drop it in the middle. Hold Alt while dragging for fine positioning.
4. Step 1 is Positions & Markings for a reason: fault lines and the start position are what distances and several rule checks measure from, so lay them out before the targets go up.
5. Select an item and drag any of its four corner handles to resize it. Hold Shift to keep its proportions. Set required shots on each target in the Selected panel.
6. Check the Stage Info tab. It arrives pre-filled with the wording most stages use; edit whatever does not fit.
7. Watch the Rule Check tab and fix what it flags. Anything already fine, and the reminders a diagram cannot measure, stay folded away.
8. Save — if you cleared a required field, a short list says what is still outstanding.
9. Print / PDF.

Stages save to your browser's local storage. Use Open → Export to write a .tyrant.json file you can back up or send to someone else.

Both sports revise their rules. scripts/check-rules.js fetches every document listed in data/sources.json, hashes it, and compares against the last run.

When something changes it archives the old copy, saves the new one, extracts the text, and prints the specific rule lines that were added or removed:

[idpa-rulebook] IDPA Rulebook
    archived previous copy → rulebooks/_archive/2026-IDPA-Rulebook-2.2026-08-06T23-40-13.pdf
    saved rulebooks/idpa/2026-IDPA-Rulebook-2.pdf (1827 KB)
    ! CONTENT CHANGED
      lines added: 2, removed: 2
      + 6.5.11   No string of fire may require more than 18 rounds.
      - 6.5.11   No string of fire may require more than 16 rounds.

It then rebuilds the app data and re-runs the self-tests. If a change affects a ruleset it adds an entry to a review queue and writes RULE-STATUS.txt in the project root — one file to glance at.

It deliberately does not rewrite the rule data by itself. A changed sentence needs a person to read it and decide what it means. Silently auto-updating a legality check is worse than being told to go look.

Commands:

node scripts/check-rules.js             # check now
node scripts/check-rules.js --dry-run   # report only, change nothing
node scripts/check-rules.js --force     # re-download everything
./scripts/install-cron.sh               # install the scheduled checks
./scripts/install-cron.sh --show        # see what is scheduled
./scripts/install-cron.sh --uninstall   # remove them

The cron schedule installed is: daily at 03:15, a forced full re-download Mondays at 03:45, and once fifteen minutes after boot in case the machine was off.

When the watcher flags a change:

1. Read the diff in logs/ and the archived rulebook in rulebooks/_archive/.
2. Edit the affected file in data/rulesets/ — idpa.json or uspsa.json.
3. Run node scripts/selftest.js. If a limit moved, a test will disagree with it; update the test to match the new rule.
4. Run node scripts/build-data.js.
5. Clear the entry from pendingReview in .state/sources-state.json.

Everything the app knows about a sport lives in that one JSON file: targets and their dimensions, legal props, stage types, round-count and distance limits, division equipment specs, and the briefing fields. Nothing is hard-coded in the UI, so a rule change is a data edit.

app/                   the application — open index.html and it runs
  index.html
  css/styles.css
  js/core.js           units, geometry, stage document, undo, storage
  js/validate.js       the rule engine
  js/designer.js       canvas rendering and direct manipulation
  js/gunchecker.js     division legality checks
  js/print.js          the printable stage sheet
  js/app.js            screens and wiring
  js/data-bundle.js    generated from data/rulesets
data/
  rulesets/idpa.json   everything the app knows about IDPA
  rulesets/uspsa.json  everything the app knows about USPSA
  sources.json         documents the watcher monitors
scripts/
  build-data.js        rulesets -> app data bundle
  check-rules.js       the rulebook watcher
  selftest.js          203 assertions over the rule engine and gun checker
  install-cron.sh      scheduled checks
rulebooks/             local rulebook copies (not in version control)
logs/                  rule-check history

node scripts/selftest.js

Runs the real rule engine against deliberately legal and deliberately illegal stages — 20-round IDPA strings, 50% steel, too many non-threats, targets past the scenario distance cap, USPSA courses that mix USPSA and IPSC targets, metal plates at Level III, poppers inside the 23 ft minimum — and asserts the checker calls each one correctly. It also verifies every constraint in the rule data has a working implementation, so adding a rule without implementing it fails the build.

The rule engine checks what a plan view can measure: round counts, steel percentages, target ratios, distances, movement, prop requirements, division equipment specs and briefing completeness.

It cannot see. Anything depending on what a competitor can view from a position is estimated by grouping targets to the nearest shooting position, and the app says so where it does this. Safe angles of fire, backstops, berms and shoot-through risk need eyes on the bay.

The Match Director remains responsible for the stage.

GNU Affero General Public License v3.0.

You may use, study, modify and share this software. If you run a modified version as a network service, you must offer your users the source of your modified version. Commercial licences are available from the copyright holder for anyone who wants to build on this without the AGPL's terms.

This project is not affiliated with or endorsed by IDPA or USPSA, and does not redistribute their copyrighted rulebooks. See NOTICE.md.