@mindmodel/game

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:

• Used standalone for testing and development
• Easily integrated into larger full-stack applications
• Customized through simple configuration
• 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

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

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

Usage

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:

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:

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)

• Digit Span
  • Assesses working memory capacity
  • Forward and backward digit recall
• N-Back
  • Tests working memory and cognitive flexibility
  • Progressive difficulty (1-back to 3-back)
• Stroop Task
  • Measures attention and response inhibition
  • Color-word interference paradigm
• Card Sorting
  • Measures cognitive flexibility and rule learning
  • Dynamic rule switching
• 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

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

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

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

4. styles.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

export { Game } from './game';
export type { GameProps, GameResults } from './types';
export { gameConfig } from './config';

Performance Requirements

Each game must implement performance tracking:

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

• Create a new folder in src/games/
• Copy the basic structure from an existing game
• Implement the game logic using jsPsych
• Add the game to the dashboard in TestDashboard.tsx
• 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