Adding Games to IF Hub

← Back to IF Hub

Overview

IF Hub serves games in-place from their own GitHub Pages deployments. There is no deploy script, no file copying, and no games/ directory. Each game project is a separate repository that owns its own pages, assets, and binaries.

The hub simply references each game by URL. The split-pane player (app.html) loads the game in an iframe pointing directly at the game’s own play.html, fetches source code from the game’s own source.html or story.ni, and loads walkthroughs from the game’s own walkthrough.html.

Architecture

All game repos deploy under johnesco.github.io/*, making everything same-origin. This means iframes, fetch(), and postMessage all work freely between the hub and game pages.

Prerequisites

Before adding a game to IF Hub, the game project must have:

Building the game binary

Use the shared compilation tools:

# Standard compilation (no sound):
python /c/code/ifhub/tools/compile.py game-name

# With native blorb sound (embeds .ogg audio in .gblorb):
python /c/code/ifhub/tools/compile.py game-name --sound

This compiles the source, base64-encodes the binary, generates play.html, and validates the result — all in one command.

Step-by-Step

1. Write the game and first compile

   Place story.ni in projects/mygame/ and compile:

   python /c/code/ifhub/tools/compile.py mygame

   This compiles the source, base64-encodes the binary, generates play.html and walkthrough.html, and validates the result.

2. Create the walkthrough

   Extract walkthrough commands from the game’s source (if it has Test me with “...”) or from a TRANSCRIPT file recorded during play.

   # From Test me in source:
   mkdir -p projects/mygame/tests/inform7
   python /c/code/ifhub/tools/extract_commands.py --from-source \
       projects/mygame/story.ni \
       -o projects/mygame/tests/inform7/walkthrough.txt
   
   # Or from a TRANSCRIPT file (recorded by typing TRANSCRIPT in-game):
   python /c/code/ifhub/tools/extract_commands.py transcript.txt \
       -o projects/mygame/tests/inform7/walkthrough.txt

3. Recompile (with walkthrough)

   Now that walkthrough commands exist, recompiling auto-generates the transcript, annotated guide, and copies everything to the web root:

   python /c/code/ifhub/tools/compile.py mygame

4. Generate landing page and source browser

   python /c/code/ifhub/tools/web/generate_pages.py \
       --title "My Game" \
       --meta "An Interactive Fiction" \
       --description "A brief description of the game." \
       --out projects/mygame

   Generates index.html (landing page with Play/Source/Walkthrough links) and source.html (syntax-highlighted source browser).

5. Register in IF Hub

   python /c/code/ifhub/tools/register_game.py \
       --name mygame \
       --title "My Game" \
       --meta "An Interactive Fiction" \
       --description "A brief description of the game."

   Adds entries to games.json and cards.json automatically. Optional flags: --sound blorb for sound-enabled games.

6. Publish to GitHub Pages

   python /c/code/ifhub/tools/publish.py mygame

   First run: creates a Johnesco/mygame GitHub repo, pushes all files, and enables GitHub Pages via a GitHub Actions workflow (auto-generated if missing). Subsequent runs: commits and pushes to trigger redeployment.

7. Push hub changes

   python /c/code/ifhub/tools/push_hub.py mygame

   Stages games.json and cards.json, commits with a message referencing the game name, and pushes to the hub repo. Skips if no changes.

8. Verify

   Wait for Pages to deploy (~1 minute), then check:

   • johnesco.github.io/mygame/play.html — game loads
   • johnesco.github.io/ifhub/app.html?game=mygame — hub shows game, source, and walkthrough

Registry Files

games.json

Drives the split-pane player (app.html). Each entry defines URL-based fields:

cards.json

Drives the landing page (index.html). Each card groups a game with its versions:

Adding a Walkthrough

The walkthrough viewer is a self-contained HTML page that fetches three data files via relative paths. It supports three modes: Commands (annotated step list), Game Text (full transcript), and Replay (animated playback).

Required files (all in the same directory)

Generating walkthrough files

compile.py handles this automatically. When tests/inform7/walkthrough.txt exists and glulxe.exe is available, it:

1. Runs the walkthrough commands through the interpreter → walkthrough_output.txt
2. Generates the annotated guide via generate-guide.py → walkthrough-guide.txt
3. Copies all three files to the project root for web serving

To create the initial walkthrough commands:

# From "Test me with ..." in story.ni:
python /c/code/ifhub/tools/extract_commands.py --from-source story.ni \
    -o tests/inform7/walkthrough.txt

# From a TRANSCRIPT file (recorded in Parchment, IDE, or any interpreter):
python /c/code/ifhub/tools/extract_commands.py transcript.txt \
    -o tests/inform7/walkthrough.txt

# Then recompile to generate the transcript and guide:
python /c/code/ifhub/tools/compile.py mygame

Local Development

The dev server at tools/dev_server.py maps URL prefixes to local directories, providing production-equivalent URLs without deploying to GitHub Pages:

python tools/dev_server.py [--port 8000]
# /ifhub/*      → site/
# /mygame/*     → projects/mygame/
# Open http://127.0.0.1:8000/ifhub/app.html

The server auto-discovers game projects from the projects/ directory. It binds to 127.0.0.1 (not "") to avoid IPv6 issues on Windows.

Verification Checklist