React Text Game

A powerful, reactive text-based game engine for React applications. Build interactive narrative experiences with TypeScript, featuring state management, multiple passage types, and a comprehensive save system.

Why React Text Game?

Building interactive narrative experiences shouldn't require reinventing the wheel. React Text Game provides a production-ready game engine that handles the complexity of state management, save systems, and UI components—so you can focus on crafting your story.

• Zero boilerplate - Start building immediately with factory functions and pre-built components
• Production-ready - Built-in save system with IndexedDB persistence and encrypted exports
• Author-friendly - Write passages in Markdown (MDX) or programmatically with TypeScript
• Fully customizable - Use our UI components or build your own with the core engine
• Type-safe - Catch errors at compile time with comprehensive TypeScript support
• Modern React - Built for React 18+ with hooks and reactive state management

Whether you're building a visual novel, interactive fiction, or educational narrative experience, React Text Game provides the foundation to ship faster.

Features

• Reactive State Management - Built on Valtio for automatic UI updates
• Multiple Passage Types - Story passages, Interactive Maps, and custom Widget passages
• Comprehensive Save System - IndexedDB persistence with encrypted export/import
• Themeable UI Components - Tailwind CSS v4 with semantic color tokens
• Type-Safe - Full TypeScript support with detailed JSDoc documentation
• Factory-Based Entities - Plain-object factories with optional class-based escape hatches
• React Integration - Built-in hooks and React 19 support
• Modular Architecture - Use core engine independently or with UI components

Packages

This monorepo contains three publishable packages:

@react-text-game/core

The core game engine providing:

• Game orchestration and entity registry
• Reactive state management (Valtio)
• JSONPath-based storage system
• Story and Interactive Map passages
• Save/load system with auto-save
• React hooks for game integration

Core Package Documentation

@react-text-game/ui

UI components library featuring:

• Pre-built game components (GameProvider, MainMenu, PassageController)
• Story and Interactive Map renderers
• Save/Load modals with slot management
• Tailwind CSS v4 semantic theming
• Dark mode support

UI Package Documentation

@react-text-game/mdx

MDX integration package enabling:

• Author-friendly Markdown syntax for game passages
• Seamless React component integration in narratives
• Type-safe custom components with full TypeScript support
• Vite plugin for optimized build pipeline
• Automatic metadata and story structure extraction
• Runtime-evaluated dynamic variables

MDX Package Documentation

Quick Start

Installation

# Install core and UI packages
bun add @react-text-game/core @react-text-game/ui

# Optional: Add MDX support for Markdown-based passages
bun add @react-text-game/mdx @mdx-js/mdx @mdx-js/react

# Or use npm/yarn/pnpm
npm install @react-text-game/core @react-text-game/ui
npm install @react-text-game/mdx @mdx-js/mdx @mdx-js/react

Basic Example

import { Game, createEntity, newStory } from '@react-text-game/core';
import { GameProvider, PassageController } from '@react-text-game/ui';
import '@react-text-game/ui/styles';

// Initialize the game
await Game.init({
  gameId: 'my-game',
  gameTitle: 'My Adventure'
});

// Create a game entity (factory-first approach)
const player = createEntity('player', {
  name: 'Hero',
  stats: {
    health: 100,
    mana: 50,
  },
  inventory: [] as string[],
});

// Create a story passage
const intro = newStory('intro', () => [
  {
    type: 'header',
    content: 'Welcome to the Game',
    props: { level: 1 }
  },
  {
    type: 'text',
    content: `Hello, ${player.name}!`
  },
  {
    type: 'actions',
    content: [
      {
        label: 'Start Adventure',
        action: () => Game.jumpTo('chapter-1')
      }
    ]
  }
]);

// React component
function App() {
  return (
    <GameProvider game={Game}>
      <PassageController />
    </GameProvider>
  );
}

// Start the game
Game.jumpTo(intro);

Prefer class-based entities? Extend BaseGameObject directly—the factory and class APIs work side by side.

Documentation

• Full Documentation - Comprehensive guides and tutorials (Docusaurus site)
• API Reference - Auto-generated TypeDoc API documentation
• Example Game - Complete game implementation example

Development

This is a Turborepo monorepo using Bun as the package manager.

Prerequisites

• Bun 1.2.23 or later
• Node.js 18 or later

Setup

# Install dependencies
bun install

# Run all packages in watch mode
bun run dev

# Build all packages
bun run build

# Type checking
bun run check-types

# Linting
bun run lint

# Code formatting
bun run format

Turborepo Filtering

Target specific packages or apps:

# Run dev for specific app
bun run dev --filter=example-game

# Build only the core package
bun run build --filter=@react-text-game/core

# Build both packages
bun run build --filter='@react-text-game/*'

Repository Structure

react-text-game/
├── packages/
│   ├── core/          # @react-text-game/core - Game engine
│   ├── ui/            # @react-text-game/ui - UI components
│   └── mdx/           # @react-text-game/mdx - MDX integration
├── apps/
│   ├── docs/          # Docusaurus documentation site
│   ├── example-game/  # Example game implementation
│   ├── core-test-app/ # Core package testing
│   └── ui-test-app/   # UI components testing
└── turbo.json         # Turborepo configuration

Note: The apps/ directory contains examples, tests, and documentation. The main deliverables are the packages in packages/.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository and create a new branch for your feature or bugfix
2. Install dependencies with bun install
3. Follow existing patterns - Use factory functions, semantic colors in UI, and TypeScript types
4. Test your changes in the test apps (apps/core-test-app or apps/ui-test-app)
5. Ensure code quality:
   • Run bun run lint to check for linting issues
   • Run bun run check-types to verify TypeScript types
   • Run bun run format to format code with Prettier
6. Create a changeset if you're modifying a package:
   • Run bun run changeset and follow the prompts
   • This helps with version management and changelog generation
7. Submit a pull request with a clear description of your changes

Please ensure all checks pass before submitting your PR. If you're adding new features, consider updating the documentation in apps/docs.

License

MIT (c) laruss

Links

• NPM Packages:
  • @react-text-game/core
  • @react-text-game/ui
  • @react-text-game/mdx
• Repository: GitHub
• Issues: Report bugs and request features on GitHub Issues