halfstreet/README.md

Halfstreet

A gothic text adventure. Second person, present tense, sparse — never explains.

Style anchors: Le Fanu's Carmilla, Shirley Jackson's The Haunting of Hill House, M.R. James's ghost stories.

Played at halfstreet.io.

Stack

• Astro static site
• TypeScript engine — pure (no DOM, Date, Math.random, or console)
• World content authored in markdown (rooms, items, encounters, endings) under src/world/
• Vitest for tests

Development

npm install
npm test          # engine + world tests
npm run dev       # local dev server
npm run build     # type-check + production build

Make Your Own Game

Halfstreet is currently meant to be forked as a complete Astro app, not consumed as a separate engine package. To make a new story, replace the markdown vault in src/world/ and keep the TypeScript runtime in place.

Start with:

• src/world/game.md for the title, starting room, starting inventory, ending priority, opening art, help text, and end text.
• src/world/parser.md for command vocabulary and aliases.
• src/world/rooms/, src/world/items/, src/world/encounters/, and src/world/endings/ for story content.
• src/world/mechanics/ and src/world/actions/ for configurable rules and interactions.
• src/world/ui.md for page metadata, footer links, and UI feature switches.
• src/world/templates/ for starter files.

Run npm test after changing world files. The loader validates wikilinks, required sections, frontmatter shape, and references between rooms, items, encounters, endings, mechanics, and actions.

Releases

The footer build number comes from Woodpecker's pipeline number and increments on each CI build. The package version is an intentional release label.

Use one of these from a clean worktree when you are ready to cut a release:

npm run release:patch  # fixes, typo corrections, small polish
npm run release:minor  # meaningful playable additions or mechanics
npm run release:major  # disruptive changes after 1.0.0
git push --follow-tags

Each release script updates package.json and package-lock.json, creates a release commit, and tags it.

Layout

• src/engine/ — parser, dispatcher, encounter logic
• src/ui/ — terminal renderer, theme, chips
• src/world/ — Obsidian-friendly authoring vault
• src/pages/index.astro — entry page

Design docs

• docs/superpowers/specs/halfstreet-bible.md — content bible (canonical world)
• docs/superpowers/specs/2026-05-08-mystery-text-adventure-design.md — engine/UI architecture
• docs/superpowers/specs/halfstreet-followon-notes.md — pending engine work before authoring more rooms
• docs/superpowers/specs/2026-05-09-mystery-markdown-migration-design.md — markdown content migration design
• docs/superpowers/plans/2026-05-09-mystery-markdown-migration.md — migration plan that was executed

License

GPL-3.0-or-later. See LICENSE.