npm package: @mindmodel/game
Description: A collection of cognitive assessment games built with React, designed for easy integration into research applications.
Latest version: 0.1.13

# Cognitive Games

A collection of cognitive assessment games built with React, designed for easy integration into research applications.

## Project Goal
Create a modular, well-documented set of cognitive assessment games that can be:
1. Used standalone for testing and development
2. Easily integrated into larger full-stack applications
3. Customized through simple configuration
4. Extended with new games following the established pattern

## Tech Stack
- React 18 with TypeScript
- Material-UI for UI components
- Custom game logic implementation
- React Router for navigation

## Quick Start

```bash
# Install from npm
npm install @cognitive-games/core

# Or using yarn
yarn add @cognitive-games/core
```

## Usage
```typescript
import { DigitSpan, NBack, StroopTask } from '@cognitive-games/core';

function App() {
  const handleGameComplete = (results) => {
    console.log('Game Results:', results);
  };

  return (
    <DigitSpan 
      onComplete={handleGameComplete}
      config={{
        trials: 10,
        difficulty: 'medium'
      }}
    />
  );
}
```

## Available Games
Each game can be imported individually:
```typescript
import { DigitSpan } from '@cognitive-games/core/games/digit-span';
import { NBack } from '@cognitive-games/core/games/n-back';
import { StroopTask } from '@cognitive-games/core/games/stroop';
import { CardSorting } from '@cognitive-games/core/games/card-sorting';
import { GoNoGo } from '@cognitive-games/core/games/go-no-go';
```

## Common Props
All games share these base props:
```typescript
interface CommonGameProps {
  onComplete: (results: GameResults) => void;  // Required
  config?: Partial<GameConfig>;                // Optional
  theme?: ThemeConfig;                         // Optional
  onError?: (error: Error) => void;           // Optional
  language?: string;                          // Optional, defaults to 'en'
}
```

## Project Setup
- React 18 with TypeScript
- Material-UI for UI components
- Custom game logic implementation

## Games
### **Core Games (Main Assessment)**
1. **Digit Span** 
   - Assesses working memory capacity
   - Forward and backward digit recall
2. **N-Back** 
   - Tests working memory and cognitive flexibility
   - Progressive difficulty (1-back to 3-back)
3. **Stroop Task** 
   - Measures attention and response inhibition
   - Color-word interference paradigm
4. **Card Sorting**
   - Measures cognitive flexibility and rule learning
   - Dynamic rule switching
5. **Go/No-Go**
   - Tests response inhibition and attention
   - Rapid stimulus discrimination

## Project Structure
```
cognitive-games/
├── src/
│   ├── components/                   # Shared components
│   │   ├── countdown.tsx            # Timer component
│   │   ├── endScreen.tsx           # Game completion screen
│   │   ├── loading.tsx             # Loading indicator
│   │   ├── startScreen.tsx         # Game start screen
│   │   └
│   │
│   ├── games/                      # Game implementations
│   │   ├── cardSorting/
│   │   │   ├── game.tsx            # Main game component
│   │   │   ├── config.tsx          # Game configuration
│   │   │   ├── styles.tsx          # Game-specific styles
│   │   │   └── index.ts            # Game exports
│   │   └── ... (other games)
│   │
│   ├── pages/                      # Page components
│   │   └── TestDashboard.tsx       # Game selection dashboard
│   │
│   │
│   └── App.tsx                     # Main application component
```

## Game Implementation Pattern
Each game follows a consistent structure with 5 required files:

### 1. `game.tsx`
```typescript
import React from 'react';
import { GameProps, GameState } from './types';
import { gameConfig } from './config';

export const Game: React.FC<GameProps> = ({ onComplete }) => {
  // Core game logic
  const [gameState, setGameState] = useState<GameState>({
    isActive: false,
    currentTrial: 0,
    score: 0,
    responses: []
  });

  // Required functions
  const startGame = () => { /* ... */ };
  const nextTrial = () => { /* ... */ };
  const handleResponse = (response: any) => { /* ... */ };
  const endGame = () => { /* ... */ };
  const handleCountdownComplete = () => { /* ... */ };

  return (
    <div className="game-container">
      {/* Game UI */}
    </div>
  );
};
```

### 2. `types.ts`
```typescript
export interface GameProps {
  onComplete: (results: GameResults) => void;
  config?: Partial<GameConfig>;
}

export interface GameState {
  isActive: boolean;
  currentTrial: number;
  score: number;
  responses: GameResponse[];
}

export interface GameResults {
  accuracy: number;
  averageResponseTime: number;
  totalTime: number;
  responses: GameResponse[];
}
```

### 3. `config.ts`
```typescript
export const gameConfig = {
  trials: 20,
  trialDuration: 3000,
  interTrialInterval: 1000,
  countdownDuration: 3,
  minimumResponseTime: 200,
  // Game-specific settings
};
```

### 4. `styles.css`
```css
.game-container {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 2rem;
}

.game-stimulus {
  font-size: 2rem;
  margin: 2rem 0;
}

.game-controls {
  display: flex;
  gap: 1rem;
}
```

### 5. `index.ts`
```typescript
export { Game } from './game';
export type { GameProps, GameResults } from './types';
export { gameConfig } from './config';
```

## Performance Requirements
Each game must implement performance tracking:

```typescript
interface GameMetrics {
  accuracy: number;        // Percentage of correct responses
  responseTime: number;    // Average response time in ms
  totalTime: number;      // Total game duration
  trialHistory: Trial[];  // Complete trial data
}
```

## Adding a New Game
1. Create a new folder in `src/games/`
2. Copy the basic structure from an existing game
3. Implement the game logic using jsPsych
4. Add the game to the dashboard in `TestDashboard.tsx`
5. Add routing in `App.tsx`

## Dependencies
- React >=16.8.0 (peer dependency)
- @mui/material >=5.0.0 (peer dependency)
- TypeScript >=4.5.0 (for type definitions)

## Browser Support
- Chrome (last 2 versions)
- Firefox (last 2 versions)
- Safari (last 2 versions)
- Edge (last 2 versions)

## Development Notes
- Material-UI for consistent theming
- Modular game structure for easy maintenance
- Shared components for common UI elements