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 GameModel } from 'carverjs';

const gameModel: GameModel = {
  id: 'quick-start-demo',
  name: 'Forest Adventure',
  initialScene: 'clearing',
  config: {
    gridSize: 32,
    animationSpeed: 300,
    debugMode: false
  },
  scenes: [
    {
      id: 'clearing',
      name: 'Forest Clearing',
      width: 10,
      height: 10,
      player: {
        startPosition: { x: 2, y: 2 },
        color: '#4CAF50',
        health: 3
      },
      entities: [],
      objectives: [
        {
          id: 'reach-grove',
          type: 'reach',
          reward: 50,
          description: 'Reach the glowing grove to continue your adventure.'
        }
      ],
      transitions: [
        {
          targetScene: 'grove',
          trigger: () => true,
          animation: 'fade',
          duration: 300
        }
      ]
    },
    {
      id: 'grove',
      name: 'Ancient Grove',
      width: 10,
      height: 10,
      player: {
        startPosition: { x: 5, y: 5 },
        color: '#4CAF50',
        health: 3
      },
      entities: [],
      objectives: [
        {
          id: 'complete-journey',
          type: 'reach',
          reward: 100,
          description: 'Explore the grove to finish the demo.'
        }
      ]
    }
  ]
};

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: GameModel;
  mode?: 'solo' | 'vsAgent';
  onAction?: (sceneId: string, action: GameAction) => void;
}

SceneRenderer

Renders individual game scenes with animations.

interface SceneRendererProps {
  scene?: GameScene | null;
  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 {
  GameModel,
  GameScene,
  NarrativeScene,
  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