carverjs/README.md

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

# 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

```bash
npm install carverjs
```

```bash
yarn add carverjs
```

```bash
pnpm add carverjs
```

## Quick Start

```tsx
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.

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

### SceneRenderer

Renders individual game scenes with animations.

```tsx
interface SceneRendererProps {
  scene?: GameScene | null;
  className?: string;
}
```

### ActionButton

Interactive buttons for game actions.

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

## Reinforcement Learning

CarverJS includes built-in RL capabilities:

```tsx
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

```tsx
'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

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

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

### Create React App

```tsx
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:

```tsx
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:

```bash
npm install -D tailwindcss
```

## Development

```bash
# 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

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

### GameAction Interface

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

## Browser Support

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

## Contributing

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

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://github.com/yourusername/carverjs#readme)
- 🐛 [Issue Tracker](https://github.com/yourusername/carverjs/issues)
- 💬 [Discussions](https://github.com/yourusername/carverjs/discussions)

---

Made with ❤️ by [Your Name](https://github.com/yourusername)