ReignsAgent

ReignsAgent

English | 简体中文

ReignsAgent is a modular authoring, validation, and publishing stack for Reigns-like card narratives. It combines a creator workbench, a deterministic headless runtime, simulation-based diagnostics, content import/export tooling, and a deployable player build path.

The project is built for two primary audiences: creators who need a practical workspace for narrative card production, and AI-assisted workflows that need clear contracts for drafting, repairing, validating, and shipping content without crossing runtime boundaries.

Contents

• Start Here: Choose And Use A Client
• Learn The Product Through Onboarding
• Capabilities
• Design Boundaries
• Developer Quick Start
• Creator Workflow
• Architecture
• Content Model
• AI-Assisted Workflows
• Build Output
• Creator Distribution
• Package Examples
• Repository Layout
• CI And Verification
• Acknowledgements
• License

Start Here: Choose And Use A Client

ReignsAgent has two kinds of application. Creator is the authoring workspace used to make, inspect, test, and publish projects. Player is the deliberately smaller application that runs one published project and exposes only the left/right game experience. A Player build cannot edit its own content, run reviews, or connect to an AI endpoint.

Most release users should download a portable desktop Creator ZIP. The other clients exist for zero-install browser use, a system-Node workflow, development, and deployment-specific needs.

The Creator overview is the hand-off point between project setup, card editing, review, preview, and release. The screenshots in this guide use the bundled Open Court sample and the Famicom skin; content and appearance are project/client choices.

Launch A Release Build

The Releases page contains five Creator archives plus SHA256SUMS.txt:

Do not run the application from inside the ZIP. Extract it into a writable directory first so the portable ReignsAgentData workspace can be created beside it. Desktop archives are unsigned: Windows SmartScreen, macOS Gatekeeper, or Linux desktop policy may ask you to confirm the first launch. The current release has no installer, automatic updater, code signing, or notarization.

Verify the downloaded archive before extraction:

# macOS/Linux, from the directory containing the ZIP and SHA256SUMS.txt
sha256sum -c SHA256SUMS.txt --ignore-missing

# Windows PowerShell: compare the result with the matching SHA256SUMS.txt line
Get-FileHash .\ReignsAgent-win32-x64-0.1.0.zip -Algorithm SHA256

The desktop Creator starts its shared local server automatically and opens /workbench inside the application window. The Node Creator prints its loopback address, normally http://127.0.0.1:4321/workbench, and opens that address in the default browser. Closing the desktop window stops its server; stop the Node Creator with Ctrl+C.

Learn The Product Through Onboarding

The onboarding guide is a 12-step, localized walkthrough of the actual Creator rather than a separate tutorial project. Its first screen explains the Reigns-style loop with an interactive left/right dilemma; the remaining spotlight steps move through the live workspace:

The guide starts automatically only on the first ordinary /workbench visit for the current client. An explicit deep link such as /workbench/content wins over onboarding so shared links remain deterministic. Completion is stored in guarded client-local storage: Finish, Skip, or Esc suppresses the next automatic launch, while unavailable or throwing localStorage falls back safely and does not block Creator startup.

Use the on-screen arrows, Left/Right, or Space to move between steps; Esc exits. The introductory card remains interactive, while later targets are highlighted without triggering editor, AI, Review, or Build actions. When the guide changes panels it restores the panel from which the tour began when closed, and it never changes projects or shared settings. Open Settings → Guidance → Replay onboarding guide at any time to start again immediately.

Create Or Open Your First Project

Use the Project menu in the top bar to choose one of these starting points:

1. New from sample clones the bundled Open Court sample into an editable project. This is the recommended first run because it demonstrates branching requirements, story groups, localized content, custom gauge labels, art bindings, endings, and a player-ready deck.
2. New blank project creates an empty project for original work.
3. Import project in Content imports a project/content bundle from a local file. The Hosted PWA also exposes workspace and active-project ZIP import/export under Settings → Browser Persistence.
4. Selecting an existing project switches the active workspace. Deletion is project-scoped and requires confirmation.

The bundled sample itself is immutable; New from sample creates an ordinary editable copy. The title shown in the top bar and releases comes from content.json.metadata.title, while author, description, links, version, localization, and gauge presentation remain project-authored metadata.

Complete One Creator Workflow

The numbered rail is ordered as a practical production loop. You can move freely between panels, but a first project is easiest to understand in this order.

1. Author Cards In Content

Open Content to import a bundle, search and filter the deck, add or select a card, and edit the dilemma text. Every playable card has exactly one left choice and one right choice. Choice effects can change the four gauge slots and set author-owned tags or variables; requirements decide when a card is eligible. Use the author summary above the fields to inspect the current gate and both outcomes before changing low-level values.

Save actions validate the edited shape before it becomes the current project state. A card marked player-ready satisfies the Player contract; invalid cards remain visible to the author but block a release. Use assets relative to the project, and confirm art bindings in Preview rather than relying on a file name alone.

2. Inspect Narrative Structure In Story

Open Story after the first branch exists. The graph projects card-to-card possibilities from requirements and effects; its summary distinguishes reachable, unreachable, and isolated cards. Story groups can label chapters, themes, arcs, or endings without adding built-in gameplay systems. Click a graph node to return to its card, filter by a story group to isolate a thread, and rename tags carefully because they connect authored state across multiple cards.

Graph reachability is structural. It tells you whether a path can exist, not how often a player will see it. Review adds simulation evidence: run it after meaningful content changes, then inspect coverage, pacing, endings, dead paths, gauge pressure, and story-group health. Review findings are diagnostics, not automatic edits; return to Content or Story to make deliberate changes and rerun the review.

3. Use AI Assist As An Optional Proposal Layer

AI Assist is an optional Creator-side collaboration layer, not an autonomous author and not part of the game runtime. Turning on the AI control exposes contextual actions around the current Overview, card, Story selection, or Review finding. Without an endpoint it can still assemble and preview a local request plan; with a configured endpoint it executes that plan and returns proposals for inspection.

Text endpoint configuration lives under **Settings → A