ASAPS Modern - Advanced Stories Authoring and Presentation System

A modern TypeScript implementation of the Advanced Stories Authoring and Presentation System (ASAPS) by Hartmut Koenitz, based on his original ActionScript version (2005-2017) started at Georgia Tech. This modernization brings the powerful ASML (Advanced Stories Markup Language, also created by Hartmut Koenitz) XML-based narrative system to the web with enhanced features, a visual story builder, and AI-assisted content generation.

📖 Documentation

For a comprehensive guide to using ASAPS Modern, including conceptual foundations, interface walkthrough, and beat reference, see the User Guide.

The User Guide covers:

• Conceptual Framework: Understanding interactive narratives and ASAPS philosophy
• Interface Overview: Workspace layout, graph editor, inspector panels, and visual editor
• Beat Types Reference: Complete documentation of all beat types (24+ including AI-runtime beats)
• Rich Characters: Mood, sentiments, emotions, traits, goals, variants, and dossier policies
• Choice Effects & Conditions: Multi-row effect bundles, affect-aware operators, requirements, baselines, and templates
• Story Analysis & Debug: Reachability, path trees, backward analyzer, soft-lock warnings, pop-out debug window
• Preview Mode: Testing stories with path-based presets, state simulation, and live flowchart trace
• Translation & Voice: Multi-language authoring, AI translation, cloud + local TTS/STT
• AI Integration: Story generation, runtime AI beats, conversation steering, MCP server
• Tips & Best Practices: Workflow recommendations for efficient story creation

⚠️ Development Status

Current release: v0.9.119 — this is a beta. Core functionality works and new features arrive frequently. v0.9.119 keeps your large sound files: in the desktop app, a sound of 5 MB or more (a WAV of about half a minute) played while you worked but was gone after reopening the project, and never reached your collaborators through git. It is now stored like any other file, and if storing a file ever fails, ASAPS tells you. Sounds that already disappeared need to be added once more.

v0.9.118 made the inventory work on screen: items given or taken during play now appear and disappear in the inventory panel, with pictures you can choose on Inventory beats and effects, and the items listed on a character are theirs from the start. In a Dialog Tree each line can change how the speaker looks (an angry or sad picture), and with Message history turned on players can reread every conversation they have had, like chats in a messenger. Pulling with Git no longer fails because of the editing-lock file, and your own fonts work on Windows and in the Preview Window and exports.

v0.9.117 let a conversation react to what the player did before: a line where another character speaks next can now have conditions (a bystander steps in only if the player stood up for someone earlier) and effects (the story remembers what the player witnessed). Use the new Conditions & effects button on the line's connector in the Dialog Tree editor. The Visual Editor and the Preview Window also use the canvas size from Project Settings now, so a 16:9 project is laid out on a 16:9 stage, and speakers in the editor no longer share colours.

v0.9.116 let a group scene play out before the player answers: a Dialog Tree has a new setting, Players can skip ahead (Inspector → Show Advanced Options). Turn it off and the lines other characters say in a row play at reading pace, with no Continue button, until it is the player's turn. In chat layouts the typing indicator now also shows before each next speaker, not only after the player's answer.

v0.9.115 let players pick their character by picture: a Choose Your Character beat could show its options as portrait cards — with names, or pictures only — instead of text buttons (Inspector → Show options as). Each card used the character's portrait, and any option could use a different picture. The Preview Window also fit fixed-layout projects into phone and tablet presets instead of cropping them.

v0.9.114 let you show an asterisk: put a backslash before a formatting character (5 \* 3 shows "5 * 3" instead of starting italics), mark words with ==highlight==, and choice buttons showed bold and italic too. Roles reached the remaining places: a Condition Check can branch on who plays a role, Dialog Tree lines can be spoken by a role, hand-written stories get the role checks in Debug → Story Warnings, and renaming a role updates every beat that uses it.

v0.9.113 let one story be played by different people: set up a role in Project Settings → Roles ("the player", "the confidant"), and write each scene once for it — the role as speaker or AI partner, ${@confidant.name} and ${@confidant.they} in text. A new Choose Your Character beat lets the player pick who to be, with a short description under each name; a choice can also decide who fills a role later, or a role can be drawn at random. Each character keeps their own counters and feelings. Preview as shows a scene as any of the candidates while you write, and the template The Last Ferry shows it all in nine beats. Condition Check beats testing a goal, a variant or a location now work (they always took the false branch), and two older losses are fixed: choosing a theme (and importing a generated story) no longer drops your declared variables, and exported stories now start variables at the values you set in Project Settings.

v0.9.112 let several characters talk before the player answers: in a Dialog Tree, click Then another character speaks under a line, and the next character's line follows by itself after the reading time, with no made-up player reply in between. Story state is more trustworthy too: counter effects add numbers again (two "+2" choices used to make "22"), variables declared true/false or number keep their type and get a true/false picker where they are set or checked, and text variables still hold any text exactly. In the flowchart, copy, paste and delete now take every selected beat, and an AI Conversation always shows its way out in the Inspector.

v0.9.111 let one choice stand apart: in a responsive project, any choice of a Multi Choice beat can be pinned to a corner of the screen on its own (a "Leave" option top-right while the answers stay under the question), and pinned buttons now make room for the text instead of covering it on phones. On Windows, the GitHub setup's link for the GitHub CLI now leads to its installer, which fixes "GitHub CLI not found" for people who had downloaded the zip.

v0.9.110 made AI failures visible: when your AI provider rejects the API key, the Preview tells you instead of letting every AI beat quietly fall back; an Online Content beat whose search fails shows its error message instead of stale text; and an AI dialog tree's System Instructions can finally be edited. Starting the Preview from a beat now asks for the answers the player would have typed, and the Preview no longer hangs on its first launch. For AI conversations, the old "NPC Personality" field is now In this scene: who the NPC is comes from the character you link, the beat says how they behave in this scene.

v0.9.109 fixed Random Target beats: since v0.9.103, Add Branch did nothing — new branches now appear and keep the target you pick.

v0.9.108 fixed two Windows problems: when Windows won't open your browser, the Help menu's Documentation and Report a Bug… entries now show the link to copy instead of doing nothing, and the GitHub setup finds the GitHub CLI wherever its installer put it — click Re-check after installing, no restart needed.

v0.9.107 made location stories say what they are doing: instead of a still screen, players see "Finding your location…", "Placing the points on the map…", and — when no position comes in — "Waiting for GPS…" with a button to continue without it. A slow GPS fix no longer makes a story skip its map scene, and a map without internet says so instead of staying grey. ASAPS Builder now also runs on Linux (beta: AppImage and .deb for 64-bit PCs). Stories exported with the Netlify relay get the same protection against over-cautious AI refusals as the builder (redeploy the relay from a new export). Work toward native mobile apps continues.

v0.9.106 brought the Ink & Brass look to generated stories: AI-generated stories now open in ASAPS's own look instead of a retro theme, and Ink & Brass is a theme you can pick in Project Settings, listed first. AI features got leaner and sturdier: AI beats in a running story think briefly on the newest Claude models (much quicker on Opus 5.5 and Fable), replies that must be data are guaranteed to be valid, repeated requests reuse cached prompts, and the stand-alone players use Claude Sonnet 5. Also: the player's Restart asks inside its menu instead of freezing the page, the story checks explain problems in plain sentences, and a damaged translation file no longer stops a project from opening.

v0.9.105 was a small follow-up to the replay release: the story checks now understand replays (a branch for a returning player is no longer reported unreachable) and variables that only have a default value; chat-style conversations keep their text clear of HUDs in every case; and HUDs in exported fixed-canvas stories hold still while an AI beat is loading.

v0.9.104 was the replay release: an ending's Restart can keep chosen things — a variable, a character's counter, the persona the player picked — while everything else resets, and the built-in ${playthrough} counts the runs; a new Characters reset option lets characters remember the player across a replay, or start over; story variables start at the default value you give them in Project Settings; generated choices gated on a counter now appear; exported stories place their HUDs clear of the text at any window size; the starter templates reset properly when replayed; and the toolbar fits a 13-inch laptop screen.

v0.9.103 was the wiring release: the Co-Designer can change how a story works — choice effects, visibility conditions, entry gates, random branches, new choices, a new version of a beat side by side; restart and fallback targets are real links, and a Restart without a target is flagged; the review, the flowchart and path simulation read links the same way and understand character feelings, so "Start as if…" presets exist for every beat; a character's HUD appears when the character does; quoted speech is spoken in the character's voice; dialog-tree buttons in the Visual Editor reorder by drag, with a "Show as" state picker; hypertext is readable in every theme. Exported stories fit their HUDs to the real window and fold them into the compact strip on phones in either orientation.

v0.9.102 was the UX-evaluation release: renaming a character keeps the story intact; the builder has no blocking dialogs left — notices, with Undo on reversible deletes; settings split into Project Settings and App Preferences; API keys in the desktop app are encrypted by the operating system instead of sitting in plain text; background images get the same Inspector door as sounds; the character editor opens on portrait and names; and the Export menu is organised as Publish for players and Share for editing, including sharing a GitHub project. Also: Help ▸ Report a Bug….

v0.9.101 shipped Electron 43 in the packaged app: a macOS 27 readiness review found that releases since August had packaged an end-of-life Electron 40 because the packaging pin had not moved with the dependency. macOS 27 Golden Gate itself needs nothing else from the app (universal binary, signed and notarized); a non-blocking CI job now smoke-tests each release on GitHub's macOS 27 runner image.

v0.9.100 moved OpenAI to GPT-6 Astra as the default model and runs OpenAI tool turns (the Ideator's web search) through the Responses API — Chat Completions refuses function tools with a reasoning effort on GPT-5.6 and has none on Astra — with per-model effort mapping so a global setting never 400s. The packaged app's built-in proxy gains the Brave search route and Responses-API routing. In the responsive Visual Editor, props and characters render on the slot stage again, text, inputs and buttons stack in front of them by default, and the elements panel's reorder arrows work; long variable values in the Preview Window debug panel are readable in full.

v0.9.99 fixed a Preview Window crash on generated stories whose characters carry a meter with a minimal frame definition — the shape the generation guidance asks for. Frames are now completed wherever they are read (renderer, import pipeline, Character Editor), so a mood-driven meter renders on desktop and folds into the compact strip on phones instead of taking the preview down.

v0.9.98 was the provenance release: a project now carries its own record of AI involvement — an AI edits ledger with every proposal from the generator review, Ask AI and the Co-Designer and what the author decided, accepted and declined alike (AI ▸ AI changes) — and the conversations that belong to it, the Ideator session that produced it and every Co-Designer session about it, travel with it through folders, zips and version control. Also: all Dependabot alerts cleared, multi-line question fields, and a generation rule that sibling variants of one story moment each introduce their characters.

v0.9.97 was the review release: a generated story keeps its original with the project and arrives with typed findings and one-click, undoable fix proposals in the import banner — a typo'd link re-pointed, a counter threshold clamped into reach, an orphaned scene linked — and "Ask AI" for the rest, whose answers are checked by code on a simulated copy and shown as before → after before anything applies. Automatic AI self-repair is gone. Generation escalates once on a capped output instead of truncating twice, Opus 5 gets a 64K floor, and a saved Max Tokens that silently capped every budget fix is migrated away. One import path serves the generator, the Ideator and MCP injection; beats drag out of and between clusters with undo; cluster resize is zoom-correct; the proxy runtime transport streams; feeling gates on choices; voice input off by default on generated conversations.

v0.9.96 was the phone release: in-story AI answers in seconds instead of minutes (no more double generation, no silent thinking-budget burn, streaming everywhere, a per-turn branching cap, and a separate model setting for in-story AI); a blind seven-story bake-off settled the authoring-model question (Opus 5 won both rounds — the verdict is in the User Guide and inline in AI settings) and its AI-length stories flushed out a family of layout bugs, all fixed; dialog trees work on phones; and screen HUDs fold into a tap-to-expand strip on phone-sized stages instead of covering a third of the screen. Also: effectsOncePerChoice (re-readable but once-scored evidence), conditional choices finally documented, Field App P0 chassis, image-anchored background animation, Find & Change, and zero open advisories.

v0.9.95 was the verification release: dialog trees open up on the flowchart with their choice logic visible on the edges, clustered beats behave exactly like free beats (one rendering path), multi-language exports shrank from 170 MB to ~40 MB with translated inventories, and version control speaks plain language — "Track versions" sets up local-only history in one click, saves a First version immediately, and never shows a git error to an author who chose to keep history on their own machine. The flowchart remembers your zoom per project; cluster maps render on cold start; menu Undo finally undoes the story.

v0.9.94 changed where projects live. On desktop, new projects are folders of ordinary files in ~/Documents/ASAPS Projects/ — one file per beat, readable, git-able, backed up by Time Machine like everything else — created silently on the first named save, with a one-click "Move library to disk" for existing projects and safety rails for synced folders (atomic writes, external-change warnings). Project exports are now double-clickable .asaps files (no more zip-viewer hijacking or Safari auto-extraction), every import gap is closed (unzipped folders, bare project.json, recovered debug dumps, duplicate-name handling), and the web build finally asks the browser to protect its storage — with backup badges for work that exists only in one browser.

v0.9.93 made text formatting a real contract (markdown-lite everywhere prose renders, with a formatting bar and translation-safe markers) and gave multi-phase Dialog Trees their depth on the flowchart.

v0.9.91 fixed macOS auto-update and stopped AI-generated and injected stories failing silently: broken links are shown in a banner and marked ⚠ in the graph, and the same validation runs on every import path.

v0.9.90 made HUDs and the stage aware of each other: screen-docked meter, inventory and mood frames now appear in the Visual Editor, so what you arrange is what plays; beat text is laid out clear of them instead of underneath; device-size presets scale to fit rather than cropping the corners the HUDs sit in; and an exported story keeps its HUDs aligned with the stage at any window size and flows them around the page's own language panel. On phone-landscape, choices wrap into two columns and content steps around a corner HUD rather than being pushed off the screen. Two new authoring warnings — a counter shown twice on one beat, and a HUD stack too tall for a small screen — flag what the runtime cannot fix for you.

v0.9.89 before it added counter binding: a counter can be a display rather than a mechanic. Bind one to a character's sentiment, emotion or mood and it becomes a read-only window onto that state, so a simple trust bar can front a full affect model instead of competing with it. Bipolar meters grow outward from zero, optional word ladders replace raw numbers, and HUD meter frames name the character they belong to. Existing counters are untouched.

v0.9.88 was a security release with no feature changes: the desktop runtime moved to Electron 43, external links became scheme-validated before being handed to the operating system, and the build toolchain moved to vite 8 — open dependency alerts dropping from 39 to 9.

macOS users on v0.9.85 or earlier: your installed (unsigned) build cannot auto-update across the signing boundary — download v0.9.86 once manually; auto-update works from then on. Windows auto-updates normally.

For what shipped when, see:

• VERSION_HISTORY.md — feature matrix and per-version highlights (the one-line-per-feature summary that used to live here)
• Progress.md — detailed, narrative release notes with the why behind each change
• GitHub Releases — pre-built desktop installers for macOS, Windows and (beta) Linux with auto-update support

🎯 Features

This is a high-level overview, grouped by theme. For per-version details see VERSION_HISTORY.md; for the why behind each change see Progress.md.

Story Authoring

• Visual Story Builder: Drag-and-drop graph editor for the story structure, plus a per-beat Visual Editor for in-beat layout (positioned text, dialogs, hotspots, props, characters, meters)
• HUD-Faithful Editing (new in v0.9.90): Screen-docked meter, inventory and mood frames are drawn in the Visual Editor in both layout modes, packed exactly as the runtime packs them, with beat text laid out clear of them. Two authoring warnings flag what the runtime cannot fix: a counter shown twice on one beat (HUD frame and placed meter), and a HUD stack too tall for a small screen
• 27+ Beat Types: Visible, invisible, AI-runtime, and experimental camera/AR beats (full catalog below)
• Project Browser (redesigned in v0.9.64): One welcome surface for "where do I go next?". Four create paths (Empty / Build from a prompt / Co-write with AI / Import), compact project cards with beat-count and character-count badges, drag-drop import, a Continue banner for the last session. In Electron, the Browser opens as a dedicated window at app launch; web build keeps the in-editor modal
• Real-time Preview Window: Independent window with state-injection presets, InputText pre-fills, and a live red trace painted back onto the flowchart. Device-size presets (desktop / tablet / phone, either orientation) scale the stage to fit rather than cropping it (fixed in v0.9.90)
• Undo/Redo Everywhere: Full command history including beat operations, character editor, global settings, and visual editor moves/resizes — with a clickable history panel
• Asset Manager: Project-level library with per-element pickers for images, audio, video, and fonts; automatic missing-asset detection and relocation tools
• Backward Compatible: Full support for legacy ASML story files (automatic migration of deprecated beat types and attributes)

Rich Characters & Affect

• 2D Mood Model: Russell's circumplex (valence × arousal) with editable initial mood, runtime nudges, and an optional on-stage HUD
• Sentiments: Directed emotional memories — characters feel <emotion> toward other entities with strength clamped to [-1, 1]
• Counter Binding (v0.9.89): A counter can display affect instead of storing a value — bind it to a sentiment, emotion level or mood and it becomes a read-only meter. Bipolar meters grow outward from zero (distrust reads as distrust, not "less trust"); optional word ladders replace numbers (wary → trusting); derived counters can be read in conditions but never assigned. HUD meter frames name the character they belong to
• Emotion Nodes: Per-character runtime intensity for each emotion, decaying per beat. Author-editable emotion palette (default Ekman 6 + pride/shame/interest)
• Personality Traits: Static Big Five trait bag per character that modulates emotion deltas. 10 psychology-grounded archetype presets (narcissist, anxious-introvert, conscientious-leader, free-spirit, recluse, hothead, peacekeeper, stoic, trickster, balanced)
• Goals + GAMYGDALA: Authored goals with optional satisfaction predicates; runtime auto-fires pride/joy on met and shame/sadness on failed, scaled by goal priority and trait modulation
• Character Variants: One Character can carry multiple persona overlays (e.g., introvert/extrovert) — same id, same beats, only the affect/portrait/displayName slice swaps
• Dossier Policies: Per-character reAnchor (rebuild from structured state every turn — no drift) or reflection (accumulate per-turn reflections so the character grows) — controls how AI-runtime beats see the character

Choice Effects & Conditions

• Multi-Row Effect Bundles: Each choice (and the standalone Update Affect beat) accepts an ordered list of Effects covering counters, variables, inventory, mood nudges, emotion fires, sentiment changes, reflections, goal-status flips, variant switches, and affect-state bookmarks
• Affect-Aware Conditions: ConditionBeat and per-beat Requirements now support six new operators alongside the classic ones (mood, emotion, sentiment, trait, goal, characterVariant)
• State Requirements: First-class requires annotations on beats with fallback redirects, AND/OR combine modes, and analyzer integration that surfaces unsatisfiable gates
• Baseline-Relative Comparisons: "Compared to" switch on mood/emotion/sentiment conditions — literal threshold, delta-from-initial (story-start), or delta-from-named-bookmark — so authoring "X has improved" is a primitive
• Affect Bookmarks: bookmarkAffectState Effect snapshots affect under an author-named handle; conditions reference the bookmark for delta-vs-bookmark comparisons
• Templates: 8 effect templates (Empathetic — full support, Pushy/dismissive, Boundary respecting, etc.) and 28 condition templates across mood/emotion/sentiment/trait/goal/variant — pick one to seed every field at once
• Live Summary: Plain-language synopsis under each effect bundle: "Alex feels happier; joy spikes; trust toward the player grows (+0.40)"

Story Analysis & Debug

• Reachability Analyzer: Find unreachable beats (with requires and condition awareness)
• Path Tree Analyzer: Collapsed tree over simulated paths, hub detection, scope-aware additive state composition, state-aware conditional branches
• Backward Analyzer: From any beat, trace back the decision sequence that gets you there; sticky decision-path panel
• Story Warnings: Soft-lock detection (keypad codes never set, ungated puzzles, unfulfillable requires, paths violating requires)
• Hub Visit Log: Interactive cards for hub nodes — pick options + items across multiple visits, see accumulated state per visit
• Pop-out Debug Window: Story Debug Tools open in a separate browser window (drag to second monitor while editing)
• Live Trace: Beats visited during preview painted live on the main flowchart in red, with a thicker pulsing border on the currently-executing beat

AI-Assisted Authoring

• Complete Story Generation: Author entire interactive stories from prompts, both inside the builder and via MCP server. Output respects translation languages, declares requires annotations, and follows project conventions
• AI-Runtime Beats: Seven AI beat types that call an LLM at playback time — aiInfoText, aiDurScreen, aiCondition, aiSummary, aiDialogTree, aiConversation, onlineContent (web fetch into beat content)
• AI Conversation: Real-time free-form chat with NPCs steered by author-defined trigger/action rules; supports both text and voice input; auto-exit transitions to other beats based on conversation state
• AI Prefetching: Background generation starts while the player reads the previous beat, hiding LLM latency
• Multiple Providers: OpenAI, Anthropic Claude (with extended-thinking budget controls), Kimi K2.5, plus any OpenAI-compatible endpoint
• MCP Server: Both stdio (for Claude Desktop / Claude Code) and HTTP variants. Lets AI assistants create, read, and modify stories programmatically

Translation & Voice

• Multi-Language Authoring: Manage parallel translations of every authored string — beat content, choice text, characters, items, EndScreen credits — with staleness detection when source content changes
• AI Translation: One-click full-story translation, or selective per-string translation with provider choice
• VCS-Aware Persistence: Translations survive push/pull and round-trip through git cleanly
• Text-to-Speech: Cloud providers (OpenAI, ElevenLabs) plus Web Speech API (browser-native) plus self-hosted (mlx-audio Kokoro for fully offline). Per-speaker voice routing, streaming audio, embedded in HTML exports with language-aware switching
• Speech-to-Text: Web Speech API, whisper.cpp, Vosk, or OpenAI Whisper for AI Conversation voice input
• Language-Aware AI: AI beats generate content in the active translation language with translated preview UI

XR & Location-Based Storytelling

• QR Scan, Web View, AR Scene (experimental, v0.9.64): Three new beats that pull authoring into camera / embed / AR territory. QR Scan opens the device camera, decodes a QR code, and either saves the string to a variable or — when the payload is an asaps:// URI — routes the story directly. The inspector ships a printable-QR generator for any beat. Web View embeds a live external page via iframe / Electron <webview>. AR Scene does image-marker tracking via MindAR; anchors attached to the marker route via the same asaps:// parser. All three are flagged experimental on the palette — built end-to-end but not hardware-verified
• asaps:// URI scheme (v0.9.64): A four-verb URI scheme for "do this in the story" — asaps://beat/<id> (jump), asaps://variable/<n>/<v> (set), asaps://inventory/{add|remove}/<item>, asaps://event/<n>. Lets QR codes and AR anchors drive the story without scripting. Schema validator recurses into nested itemSchema so dangling refs in anchor onTap values lint at authoring time
• GpsLocationBeat & IndoorLocationBeat: Both are multi-location beats — like MovementChoice on a map / floor plan. Each location has its own next-beat target and Effects bundle (counters, mood, sentiment, bookmarks, the full ChoiceEffectsEditor range). The first location the player crosses wins
• Visual Editors for both XR beats: drag markers to reposition, click empty map / floor to add a new location, "Fit all" button for overview, selection sync between Visual Editor and Properties tab
• Per-beat floor plans: each indoor beat carries its own room/space — floor plan asset + dimensions in metres. Different beats can show different rooms or scales. Locations carry their own (x, y); the same beacon UUID can appear at different positions on different beats
• Three new Conditions: gpsProximity (within N metres of a target), indoorProximity (within N metres of a beacon), permissionGranted (sensor permission state) — synchronously evaluable from cached sensor reads, available in ConditionBeat, choice requirements, and MovementChoice gates
• Directional Sound: Sounds gain optional spatialPosition — geographic mode (lat/lng with bearing recomputed live) or azimuth-only (fixed compass direction). Routes through Web Audio HRTF panning + linear distance falloff. As the player walks, audio rotates and attenuates
• Location & XR Settings: Project-level origin coordinates, default proximity radius, on-permission-denied policy (skip / fallback), mock location for desktop authoring, optional indoor venue floor plan + beacon UUID registry (with Generate button for testing)
• MockSensorPanel: Desktop-authoring stand-in for real GPS / orientation / Bluetooth hardware. Walk N/S/E/W in 5m steps, simulate compass + tilt, slide beacon distances per project beacon, drives the runtime state for testing without a phone
• SensorService Abstraction: WebSensorService (production — navigator.geolocation, DeviceOrientationEvent, Bluetooth Web API) and MockSensorService (authoring) selected automatically by capability detection. HTML exports get the same XR support as the in-app preview

Collaboration & Distribution

• Git VCS Integration: Full Git inside the app — commit, push, pull, branch, merge, clone, history. Force-push option for rejection recovery; advisory beat-level editing locks for collaboration
• HTML Export: Standalone playable HTML with splash screen, counter HUD, inventory icons, scrollable credits page, embedded TTS, language switcher. HUDs stay anchored to the stage at any window size and flow around the page's own language panel (fixed in v0.9.90)
• Desktop Apps: Pre-built macOS Universal (Intel + Apple Silicon), Windows and (beta) Linux builds via GitHub Releases, with auto-update support
• ASML XML Format: Standard format for interchange and version control — see ASML File Format below
• Session Logging: Exportable play-session traces (beat path, choices, AI outputs, branch decisions) from both the Preview Window and HTML exports

📥 Releases

Pre-built desktop applications are available for macOS, Windows and (in beta) Linux on the GitHub Releases page.

Each release includes:

• macOS: Universal binary (.dmg) supporting both Intel and Apple Silicon
• Windows: Installer (.exe) and portable version
• Linux (beta, 64-bit x86): an AppImage and a .deb package

Installing on Linux. On Ubuntu, Debian and similar, the .deb is the simplest: sudo apt install ./ASAPS-Builder-<version>-amd64.deb installs it with everything it needs and adds it to the applications menu (start it from there or with asaps-builder). The AppImage runs on most other distributions without installing: make it executable (chmod +x ASAPS-Builder-<version>-x86_64.AppImage) and start it. It is also the only Linux build that updates itself. On Ubuntu 24.04 and later the AppImage may refuse to start because the system restricts the sandbox it uses; start it with --no-sandbox or use the .deb instead. Your API keys are stored encrypted when the desktop provides a keyring (GNOME Keyring, KWallet); without one they are stored unencrypted and the log says so.

Download the latest release to get started without building from source.

🚀 Quick Start

Prerequisites

• Node.js 20+ (22+ recommended for Electron desktop builds)
• npm 9+

Installation

# Clone the repository
git clone https://github.com/sumo961/ASAPS_New.git
cd ASAPS_New

# Install dependencies (automatically builds core packages)
npm install

# Start the development server
npm run dev

The builder will open at http://localhost:5173

Note: The npm install command automatically builds the required @asaps/core and @asaps/renderer packages. This may take a minute on first install.

Troubleshooting

Missing packages error (Cannot find package '@asaps/core' or Failed to resolve entry for package "@asaps/core"):

npm run build:deps
npm run dev

This manually builds the core dependencies, then starts the dev server.

Windows Users: The project fully supports Windows. If you encounter build issues after a fresh clone:

npm run build:deps
npm run dev

For a complete reset:

# PowerShell
Remove-Item -Recurse -Force node_modules
npm install
npm run dev

📦 Project Structure

asaps-modern/
├── packages/
│   ├── core/          # Story engine, beat system, ASML XML, analyzers
│   ├── builder/       # React-based visual story builder (the main app)
│   ├── renderer/      # Rendering engines (Canvas + React)
│   ├── player/        # Standalone player runtime
│   └── player-web/    # Browser bundle of the player (for HTML exports)
├── apps/
│   └── builder-desktop/  # Electron wrapper for the builder
├── mcp-server-desktop/  # MCP server (stdio) for Claude Desktop / Claude Code
├── beat-definitions/  # JSON schema for all beat types (single source of truth)
└── docs/              # User Guide and reference documentation

🎮 Usage

Creating a Story

1. Start with the Title Screen: Every story begins with a title screen beat
2. Add Beats: Drag beat types from the palette onto the canvas
3. Connect Beats: Draw connections between beats to create story flow
4. Configure Properties: Select beats to edit their properties in the inspector
5. Test Your Story: Use the preview mode to play through your narrative
6. Export: Save your story as an ASML file

Beat Types

Visible Beats (player-facing)

• Title Screen: Opening screen with title and author
• Info Text: Display text with continue button (supports rich-text formatting and text variations)
• Dialog Tree: Branching conversations with recursive __self__ targets, NPC auto-exit, per-choice visited tracking, and per-choice Effect bundles
• Movement Choice: Location-based navigation between beats
• Pick Prop: Interactive object selection
• Hyper Text: Clickable hyperlinked text with multiple targets per word
• Input Text: User text input with validation, autofocus, and value-leak protection
• Keypad: Numeric/phone/PIN entry with code validation and fail-target redirects
• 360° Panorama: Equirectangular or cylindrical projection with placeable hotspots, zoom controls, and per-element overrides
• Video Beat: Video playback with optional controls and skip button
• Duration Screen: Timed display screen
• End Screen: Story conclusion with optional scrollable credits page and granular reset (variables / inventory / timers independently)

Logic Beats (invisible)

• Set Variable: Modify story variables and counters (with ${variable} interpolation in text)
• Condition Beat: Conditional branching with classic operators (counter, variable, inventory, visitedBeat, fictionalTime, timer) plus six affect-aware operators (mood, emotion, sentiment, trait, goal, characterVariant). Baseline-relative comparisons supported.
• Random Target: Randomly select next beat
• Set Timer: Named timers with timeout targets and HUD display options (countdown, fictional time, narrative text)
• Add/Remove Inventory: Manage character inventories with quantity support
• Update Affect: Apply a multi-row Effect bundle (mood / emotion / sentiment / reflection / goal / variant / bookmark) as a standalone graph node — same editor as choice effects, including templates and live summary

AI-Powered Beats (runtime LLM calls)

• AI Info Text: Dynamically generated text content from a prompt + story context
• AI Duration Screen: Timed dynamic display with generated content
• AI Dialog Tree: LLM-generated branching dialog with author-defined NPC routing plans, exit reasons, and personalization
• AI Conversation: Real-time free-form chat with steering rules (triggers + actions) and text/voice input
• AI Condition: LLM classifies recent state/dialog into one of N author-defined categories and branches accordingly
• AI Summary: Generates a story retrospective from accumulated state and choice history (used for tier-specific endings)
• Online Content: Fetches web content into beat text (for live data, dynamic context, or web-search-enriched generation)

🔄 Importing Legacy Stories

The system fully supports legacy ASML files with automatic migration:

// Legacy conversationChoice beats are automatically converted to dialogTree
// SWFBeat (Flash) content is converted to videoBeat
// All deprecated attributes are handled gracefully

🛠️ Development

Available Scripts

# Development
npm run dev              # Start builder dev server
npm run dev:all         # Start all packages in dev mode

# Building
npm run build           # Build all packages
npm run build:core      # Build core package only
npm run build:builder   # Build builder only

# Testing
npm run test            # Run all tests
npm run lint            # Lint all packages
npm run format          # Format code with Prettier

# Utilities
npm run clean           # Clean all build artifacts

Creating Custom Beat Types

1. Create a new beat class extending Beat:

import { Beat } from '@asaps/core';

export class CustomBeat extends Beat {
  protected async performAction(
    context: StoryContext,
    renderer: IRenderer
  ): Promise<string | null> {
    // Your beat logic here
    return this.getNextBeat(context);
  }
}

1. Register it in the BeatTypeRegistry:

registry.registerBeatType('customBeat', CustomBeat);

1. Add beat definition to beat-definitions/core-beats.json

📖 ASML File Format

ASML (Advanced Stories Markup Language) is an XML-based format for defining interactive narratives:

<?xml version="1.0" encoding="UTF-8"?>
<story title="Story Title" author="Author Name">
  <settings>
    <!-- Configuration -->
  </settings>
  <environment>
    <!-- Props and backgrounds -->
  </environment>
  <characters>
    <!-- Character definitions -->
  </characters>
  <plot>
    <beat>
      <id id="0" name="Beat Name" />
      <function kind="beatType" />
      <connection target="1" />
    </beat>
    <!-- More beats -->
  </plot>
</story>

🎨 Architecture

Modular monorepo (npm workspaces) with the runtime engine, builder UI, and renderers cleanly separated. The builder imports from compiled dist/ folders of the other packages — see CLAUDE.md for the rebuild rules.

Core Package (@asaps/core)

• Beat System: Template method pattern; beats extend a base Beat class with performAction, getParameters, updateParameters
• Story Engine: Event-driven progression with StoryContext holding mood/sentiments/emotions/traits/goals/variants/reflections plus baselines and bookmarks
• Analyzers: Reachability, PathTree, BackwardAnalyzer, ConstraintPathAnalyzer, StoryWarnings (soft-lock detection)
• XML Processing: ASML parsing and generation, with auto-migration for legacy beat shapes
• Translation: Per-string translation tracking with staleness detection
• Persistence: Save/load with full state round-trip including affect baselines and bookmarks

Builder Package (@asaps/builder)

• React 18 + TypeScript: Modern strict-typed UI
• ReactFlow: Graph visualization for the story canvas
• Zustand: State management with command-pattern undo/redo
• Tailwind CSS: Styling
• Vite: Build tooling with HMR

Renderer Package (@asaps/renderer)

• ReactRenderer: Primary in-app renderer (used by Preview Window and HTML exports)
• WebRenderer: Canvas-based renderer (legacy path, still functional)
• BaseRenderer: Shared rendering logic

Desktop App (apps/builder-desktop)

• Electron 40: Chromium 144, Node 24, supported until June 2026
• electron-builder: Universal macOS DMG (Intel + Apple Silicon), Windows installer and (beta) Linux AppImage/.deb with auto-update via GitHub Releases

🤖 AI Integration

ASAPS Modern integrates LLMs at three levels: as a co-author (generating story structures and translations), as a runtime engine (powering AI beats during playback), and as an external client (driving the app via MCP).

Co-Authoring (build-time)

• Complete Story Generation: Author entire stories from prompts, both inside the builder and via MCP server. Output respects the active translation language, declares requires annotations to avoid soft-locks, and follows project conventions (default beat types, restart edges, cluster organization)
• Dialog Tree Generation: Generate branching conversations from a scene description and character context
• Beat Suggestions: Mid-story AI assistance to extend or rewrite a section
• Beat Creator: Natural-language beat creation via a small command palette
• AI Translation: One-click full-story translation, or selective per-string translation
• Verification Checklist: AI generation prompts include a structural-integrity / reachability / connection-rules checklist so generated stories don't dead-end

Runtime AI Beats (play-time)

Seven beat types call an LLM at playback. They share the same provider configuration, support AI prefetching (background generation while the player reads the previous beat — hides latency), and integrate with the character dossier system so generated content sees structured character state:

• aiInfoText, aiDurScreen — dynamically generated text/timed displays
• aiCondition — LLM-judged classification + branching
• aiDialogTree — generated branching dialogs with author routing plans
• aiConversation — real-time free-form chat with author-defined steering rules and exit transitions
• aiSummary — story retrospective generation for tier-specific endings
• onlineContent — web fetch into beat content

Provider Support

• OpenAI (with web search enable for grounded generation)
• Anthropic Claude with extended-thinking budget controls (minimal…xhigh) and Max Tokens visibility
• Kimi K2.5 (OpenAI-compatible, with reasoning model handling and 10-minute proxy timeouts)
• Any other OpenAI-compatible endpoint

Voice (TTS / STT)

• Cloud TTS: OpenAI, ElevenLabs — streaming audio with per-speaker voice routing
• Browser TTS: Web Speech API for zero-config setup
• Local TTS: Self-hosted mlx-audio (Kokoro) for fully offline stories, no cloud dependency
• Cloud STT: OpenAI Whisper (for aiConversation voice input)
• Local STT: whisper.cpp, Vosk, or Web Speech API
• HTML export embedding: TTS works in standalone HTML exports with language-aware voice switching

MCP Server

mcp-server-desktop/ connects Claude Desktop or Claude Code to a running ASAPS Builder over stdio. It needs no API key: the assistant you are already talking to does the thinking, and the server supplies it with the live beat schema and injects the result into the editor.

The tools it exposes:

• asaps_get_beat_schema — the complete, live beat schema, read from the running Builder rather than a copy, so it is never out of date
• asaps_get_affect_guide / asaps_get_example_story / asaps_get_themes — the authoring guidance and a worked example to structure a story correctly
• asaps_inject_story — push a complete story into the Builder, where it appears immediately in the visual editor
• asaps_check_connection — confirm the Builder API is reachable

Prerequisite: the Builder API server must be running — cd packages/builder && STORAGE_TYPE=filesystem npm run api:start (port 3001).

Configure it in your assistant's MCP settings pointing at mcp-server-desktop/dist/index.js. Setup details live in mcp-server-desktop/README.md.

A second server (mcp-server/) previously carried its own Anthropic API key and its own copy of the generation prompts. It was retired in favour of the above: it required the same running Builder, duplicated prompts that drifted silently out of date, and needed a key to do what Claude Desktop already does. For editing a story that is already open, use the in-app Co-Designer (AI menu → Design with Co-Designer).

📋 Version History

See VERSION_HISTORY.md for the per-version feature matrix, highlight summaries, and older bullet-style release notes. See Progress.md for the detailed, narrative release notes covering recent releases.

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

Free for non-commercial use - personal projects, research, education, and non-profit organizations.

Commercial use requires a separate license - contact for commercial licensing inquiries.

🙏 Acknowledgments

• Advanced Stories Group at Georgia Tech
• Dr. Janet Murray for supervision and guidance of the initial project
• All the students using the original ASAPS 2005-2017
• The COST Action 18230 and the ARDIN community for continued inspiration
• Made with the help of Claude and Kimi

📞 Support

For questions and support:

• Open an issue for bug reports

---

Built with ❤️ for interactive storytelling