IF Hub Dashboard

← IF Hub

The dashboard is a local web interface for managing IF Hub game projects. It runs on your machine and gives you browser-based access to the full build pipeline — compiling, testing, publishing, and registering games — without touching the command line.

Starting the Dashboard

The dashboard requires Python and Flask. Install Flask once, then launch: 

# Install (one time)
pip install flask

# Launch (opens browser automatically)
python tools/dashboard.py

# Custom port
python tools/dashboard.py --port 8080

The dashboard opens in your default browser. It runs entirely locally — nothing is exposed to the network. Press Ctrl-C in the terminal to stop.

Layout

The interface has two panels:

+--- Sidebar --------+--- Main Panel --------------------+ | IF Hub | | | Dashboard | babel | | | Web player · Compiled · Git repo | | * babel | | | * dracula | Quick Actions | | * feverdream | [Compile] [Build&Test] [Pub Update] | | * sample | | | * zork1 | > Publish New Game | | | > More Tools | | [+ New Game] | | | | Output [Stop][Clear]| | | +----------------------------------+ | | | | === Compiling babel === | | | | | [1/4] Inform 7 -> Inform 6... | | | | +----------------------------------+ | +---------------------+------------------------------------+

Creating a New Game

Click + New Game in the sidebar. The creation panel gives you two options:

  1. Paste source code — enter a game name and paste your Inform 7 source directly into the textarea. The dashboard scaffolds the full project structure (via new_project.py) and writes your source to projects/<name>/story.ni.
  2. Use starter template — enter just the name and leave the textarea empty. The dashboard scaffolds the project with a default starter story.ni, test wrappers, workflow file, and CLAUDE.md.
Name rules: lowercase, alphanumeric, hyphens and underscores allowed. The name becomes the project folder, the GitHub repo name, and the URL slug (johnesco.github.io/<name>/).

After creation, the project appears in the sidebar and is automatically selected. From there, use Publish New Game to compile and deploy it.

Quick Actions

Three buttons for common tasks on the selected project:

Button What it does
Compile Runs compile.py — compiles story.ni to a Glulx binary, sets up the web player, and generates walkthrough files if a walkthrough exists. Auto-detects sound.
Build & Test Runs the pipeline with compile + test stages — compiles and then runs walkthroughs and regtests.
Publish Update Commits and pushes changes to the game’s GitHub Pages repo. Prompts for a commit message. Only available for projects with a git repo.

Publishing a New Game

The Publish New Game section (click to expand) handles the full flow from source code to a live game on GitHub Pages. Fill in the form fields and click the gold button.

Field Purpose
Title Display name (pre-filled from the folder name)
Subtitle Tagline shown below the title (default: “An Interactive Fiction”)
Description Card description on the IF Hub landing page
Sound Check if the game has Sounds/*.ogg files for blorb packaging

The pipeline runs these steps automatically:

  1. Extract walkthrough

    If story.ni contains Test me with "...", the commands are extracted to tests/inform7/walkthrough.txt. Nested sub-tests (test first / test second) are expanded recursively.

  2. Compile

    Inform 7 → Inform 6 → Glulx binary. Sets up the Parchment web player with play.html and walkthrough pages. If a walkthrough exists, the transcript and annotated guide are generated automatically.

  3. Generate pages

    Creates index.html (landing page) and source.html (syntax-highlighted source browser) from templates, using the title, subtitle, and description you entered.

  4. Register in hub

    Adds entries to games.json (game registry) and cards.json (landing page cards) so the IF Hub knows about the game.

  5. Publish

    Creates the GitHub repo (if first time), pushes all files, and enables GitHub Pages. The game becomes playable at johnesco.github.io/<name>/play.html.

  6. Push hub

    Commits and pushes the updated games.json and cards.json to the IF Hub repo so the live hub immediately sees the new game.

More Tools

The More Tools section (click to expand) provides individual access to each pipeline step. These use the same title, subtitle, and description from the Publish New Game form.

Button Script What it does
Extract Walkthrough extract_commands.py Extracts commands from Test me in source
Generate Pages generate_pages.py Creates index.html + source.html
Register in Hub register_game.py Adds entries to games.json + cards.json
Run Walkthrough run_walkthrough.py Plays through the game with deterministic RNG seed
Run Regtests run_tests.py Runs regression test suite
Unregister from Hub unregister_game.py Removes the game from games.json + cards.json and pushes to GitHub. The game’s standalone Pages site remains live — this only hides it from IF Hub.
Run Walkthrough and Run Regtests are only enabled for projects that have the corresponding test scripts in their tests/ directory.

Output Terminal

The bottom panel streams live output from running commands. It shows the exact same output you would see in the terminal.

When a command finishes, the status indicator next to “Output” shows Done or Failed (exit code N), and the project list refreshes to reflect any status changes.

Status Indicators

Each project in the sidebar shows a colored dot indicating its build state:

Dot Meaning What it means
Green Live Registered in IF Hub — game appears in the hub dropdown and landing page
Yellow Ready play.html exists (compiled and web-ready) but not yet registered in the hub
Red Uncompiled Only story.ni — needs to be compiled before it can be played or published

Below the dot, small tags show project capabilities: sound, versioned, Test me, walkthrough, regtest.

Architecture

The dashboard is a single Python file (tools/dashboard.py) that runs a Flask web server on localhost. It serves an inline HTML page and exposes a JSON API:

Endpoint Method Purpose
/ GET Serves the dashboard HTML page
/api/projects GET Returns all projects with metadata (sound, versions, status)
/api/create POST Scaffolds a new project via new_project.py, optionally with custom source
/api/run POST Starts a task — returns a job ID
/api/stream/<id> GET Server-Sent Events stream of live command output
/api/stop/<id> POST Terminates a running job

Commands run as Python subprocesses. Output is streamed to the browser via SSE (Server-Sent Events) — each line is sent as a JSON event as soon as the subprocess writes it. The dashboard delegates to the same scripts that the CLI tools use: compile.py, publish.py, register_game.py, etc.

No external access. The dashboard binds to 127.0.0.1 only. It is a development tool, not a production server.

IF Hub · Adding games · Source on GitHub