CarverJS

A React library for AI-generated interactive games with built-in reinforcement learning support.

Features

🎮 Interactive game scene rendering
🤖 Built-in RL agents (Q-learning)
⚛️ React components with TypeScript
🎨 Tailwind CSS styling support
📱 Framework agnostic (Next.js, CRA, Remix, etc.)
🎬 Smooth animations with Framer Motion
📚 Storybook component documentation

Installation

npm install carverjs

yarn add carverjs

pnpm add carverjs

Quick Start

import { GamePlayer, type GameScene } from 'carverjs';

const gameModel: GameScene[] = [
  {
    id: 'start',
    title: 'Welcome to the Adventure',
    description: 'You find yourself at a crossroads...',
    actions: [
      { label: 'Go left', nextId: 'forest' },
      { label: 'Go right', nextId: 'cave' }
    ]
  },
  {
    id: 'forest',
    title: 'The Dark Forest',
    description: 'Ancient trees surround you...',
    actions: [
      { label: 'Return to start', nextId: 'start' }
    ]
  }
];

function App() {
  return (
    <div className="container mx-auto p-4">
      <GamePlayer gameModel={gameModel} />
    </div>
  );
}

Components

GamePlayer

The main component for rendering interactive game scenes.

interface GamePlayerProps {
  gameModel: GameScene[];
  mode?: 'solo' | 'vsAgent';
  onAction?: (sceneId: string, action: GameAction) => void;
}

SceneRenderer

Renders individual game scenes with animations.

interface SceneRendererProps {
  scene: GameScene;
  className?: string;
}

ActionButton

Interactive buttons for game actions.

interface ActionButtonProps {
  action: GameAction;
  onClick: () => void;
  disabled?: boolean;
}

Reinforcement Learning

CarverJS includes built-in RL capabilities:

import { GameEnv, QLearningAgent } from 'carverjs';

// Create environment
const env = new GameEnv(gameModel);

// Create and train agent
const agent = new QLearningAgent({
  learningRate: 0.1,
  explorationRate: 0.9,
  discountFactor: 0.95
});

// Training loop
for (let episode = 0; episode < 1000; episode++) {
  const state = env.reset();
  
  while (!env.isDone()) {
    const action = agent.chooseAction(state);
    const { nextState, reward, done } = env.step(action);
    agent.learn(state, action, reward, nextState);
    state = nextState;
  }
}

Framework Examples

Next.js App Router

'use client';

import { GamePlayer } from 'carverjs';
import { gameModel } from './game-data';

export default function GamePage() {
  return (
    <main className="container mx-auto py-8">
      <GamePlayer gameModel={gameModel} />
    </main>
  );
}

Next.js Pages Router

import { GamePlayer } from 'carverjs';
import { gameModel } from '../data/game-model';

export default function Game() {
  return <GamePlayer gameModel={gameModel} />;
}

Create React App

import { GamePlayer } from 'carverjs';
import './App.css';

function App() {
  return (
    <div className="App">
      <GamePlayer gameModel={gameModel} />
    </div>
  );
}

TypeScript Support

CarverJS is written in TypeScript and includes full type definitions:

import type { 
  GameScene, 
  GameAction, 
  GamePlayerProps,
  AgentStats 
} from 'carverjs';

Styling

CarverJS components are styled with Tailwind CSS. Make sure Tailwind is installed in your project:

npm install -D tailwindcss

Development

# Clone the repository
git clone https://github.com/yourusername/carverjs.git
cd carverjs

# Install dependencies
npm install

# Start development server
npm run dev

# Run Storybook
npm run storybook

# Build library
npm run build

# Run tests
npm test

API Reference

GameScene Interface

interface GameScene {
  id: string;
  title: string;
  description: string;
  image?: string;
  animation?: 'fadeIn' | 'slideLeft' | 'zoomIn';
  actions: GameAction[];
}

GameAction Interface

interface GameAction {
  label: string;
  nextId: string;
  effect?: string;
}

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

Made with ❤️ by Your Name