Skip to main content

Getting Started

This guide will help you set up React Text Game in your project.

Installation​

React Text Game consists of two packages: the core engine (@react-text-game/core) and the UI components (@react-text-game/ui).

Core Package Only​

If you want to build your own UI, you can install just the core package:

# Bun
bun add @react-text-game/core

# npm
npm install @react-text-game/core

# yarn
yarn add @react-text-game/core

# pnpm
pnpm add @react-text-game/core

Core + UI Packages​

For a complete solution with ready-to-use React components:

# Bun
bun add @react-text-game/core @react-text-game/ui

# npm
npm install @react-text-game/core @react-text-game/ui

# yarn
yarn add @react-text-game/core @react-text-game/ui

# pnpm
pnpm add @react-text-game/core @react-text-game/ui

UI Package Setup​

If you're using the UI package, you need to configure Tailwind CSS:

1. Install Tailwind CSS​

Follow the official Tailwind installation guide for your stack.

2. Import UI Styles​

Import the UI styles in your global CSS file (e.g., src/index.css or src/main.css):

@import "@react-text-game/ui/styles";

/* Optional: Override theme colors */
@theme {
  --color-primary-500: oklch(0.65 0.25 265);
}

Basic Setup​

Using Core Package Only​

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

// IMPORTANT: Initialize the game first
await Game.init({
  gameName: 'My Text Adventure',
  isDevMode: true,
});

// Create game entities
const player = createEntity('player', {
  name: 'Hero',
  health: 100,
});

// Create story passages
const intro = newStory('intro', () => [
  {
    type: 'header',
    content: 'Welcome!',
    props: { level: 1 }
  },
  {
    type: 'text',
    content: 'Your adventure begins...'
  },
]);

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

Using Core + UI Packages​

The UI package provides a complete game interface with minimal setup:

// src/App.tsx
import { GameProvider, PassageController } from '@react-text-game/ui';

export function App() {
  return (
    <GameProvider options={{ gameName: 'My Text Adventure', isDevMode: true }}>
      <PassageController />
    </GameProvider>
  );
}

Then define your game entities and passages:

// src/game/entities.ts
import { createEntity } from '@react-text-game/core';

export const player = createEntity('player', {
  name: 'Hero',
  health: 100,
  inventory: [] as string[],
});
// src/game/passages.ts
import { newStory, Game } from '@react-text-game/core';
import { player } from './entities';

export const intro = newStory('intro', () => [
  {
    type: 'header',
    content: 'Welcome to the Game',
    props: { level: 1 }
  },
  {
    type: 'text',
    content: `Hello, ${player.name}! Your health is ${player.health}.`
  },
  {
    type: 'actions',
    content: [
      {
        label: 'Start Adventure',
        action: () => Game.jumpTo('chapter1'),
        color: 'primary'
      }
    ]
  }
]);

Project Structure​

Here's a recommended project structure:

src/
├── game/
│   ├── entities/          # Game entities (player, inventory, etc.)
│   │   ├── player.ts
│   │   ├── inventory.ts
│   │   └── index.ts
│   ├── passages/          # Game passages (story screens)
│   │   ├── intro.ts
│   │   ├── chapter1.ts
│   │   └── index.ts
│   └── index.ts           # Game initialization
├── App.tsx                # Main app component
└── main.tsx               # Entry point

Next Steps​

Now that you have the basics set up, learn more about:

  • Core Concepts - Understand entities, passages, and state management
  • Core API - Complete API reference for the core package
  • UI API - Complete API reference for the UI package

Example Projects​

Check out the example projects in the repository:

Troubleshooting​

Game Not Initializing​

Make sure you call Game.init() before creating any entities or passages:

// ❌ Wrong
const player = createEntity('player', { name: 'Hero' });
await Game.init();

// ✅ Correct
await Game.init();
const player = createEntity('player', { name: 'Hero' });

UI Components Not Styled​

Ensure you've imported the UI styles in your global CSS:

@import "@react-text-game/ui/styles";

And that Tailwind CSS is properly configured for your project.

TypeScript Errors​

Make sure you have TypeScript 5+ installed (5.9+ recommended):

bun add -d typescript@latest

Need Help?​