Lior-game NPM | npm.io

lior-game

lior-game is a React package that transforms any interactive game into a conversation-based learning experience. It adds an AI assistant that guides users through gameplay, providing real-time feedback and instructions in a chat-like interface.

Features

🤖 AI-powered conversational interface
💬 Real-time feedback system
🎮 Game state management
🔄 Seamless integration with existing games
📱 Responsive design
⚡ Built-in UI components

Installation

npm install lior-game
# or
yarn add lior-game
# or
pnpm add lior-game

Quick Start

First, wrap your game component with the necessary providers:

import { LiorGameProvider, useSandboxContext } from 'lior-game';
import { GameStateProvider, useGameState } from './your-game';

function GameWrapper() {
  const { gameState } = useGameState();
  
  return (
    <LiorGameProvider gameState={gameState} desc={gameDescription}>
      <YourGame />
    </LiorGameProvider>
  );
}

Add conversation capabilities to your game component:

function YourGame({ sendAdminMessage }) {
  // Use sendAdminMessage to communicate with the AI assistant
  const handleUserAction = () => {
    sendAdminMessage('agent', 'Great move! Now try...');
  };

  return (
    // Your game UI
  );
}

Core Components

LiorGameProvider

The main provider that sets up the conversational context.

<LiorGameProvider 
  gameState={gameState}  // Your game's current state
  desc={description}     // Game description and rules
>
  {children}
</LiorGameProvider>

useSandboxContext

A hook that provides communication with the AI assistant.

const { sendAdminMessage } = useSandboxContext();

// Send messages from the AI assistant
sendAdminMessage('agent', 'Try clicking the blue button', () => {
  console.log('message sent');
});

Built-in Components

The package includes several pre-styled components:

Card: A styled container component
Button: An interactive button with hover states
SuccessAnimation: A celebration animation for achievements

import { Card, Button, SuccessAnimation } from 'lior-game';

function GameComponent() {
  return (
    <Card>
      <Button onClick={handleAction}>Play</Button>
      {isSuccess && <SuccessAnimation />}
    </Card>
  );
}

Game State Management

To integrate with the conversation system, your game should:

Define a game state interface
Create a context provider for your game state
Create a custom hook to access the game state

Example:

// GameStateProvider
export const GameStateProvider = ({ children }) => {
  const [gameState, setGameState] = useState(initialState);
  
  return (
    <GameStateContext.Provider value={{ gameState, setGameState }}>
      {children}
    </GameStateContext.Provider>
  );
};

// Custom hook
export const useGameState = () => {
  const context = useContext(GameStateContext);
  if (!context) {
    throw new Error('useGameState must be used within GameStateProvider');
  }
  return context;
};

Best Practices

Clear Instructions: Provide clear game descriptions in the desc prop
Timely Feedback: Send messages at key interaction points
Progressive Guidance: Break down complex actions into simple steps
Error Handling: Provide helpful messages when users make mistakes
State Management: Keep game state synchronized with the conversation

Example Implementation

Here's a complete example of how to structure your game:

'use client'

import { Suspense } from 'react';
import { LiorGameProvider, useSandboxContext } from 'lior-game';
import Game, { desc, GameStateProvider, useGameState } from './game/game';

// Wrapper to access context
function LiorGameWrapper() {
  const { sendAdminMessage } = useSandboxContext();
  return <Game sendAdminMessage={sendAdminMessage} />;
}

// Game state wrapper
function GameWrapper() {
  const { gameState } = useGameState();

  return (
    <LiorGameProvider gameState={gameState ?? {}} desc={desc}>
      <LiorGameWrapper />
    </LiorGameProvider>
  );
}

// Page component
export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <GameStateProvider>
        <GameWrapper />
      </GameStateProvider>
    </Suspense>
  );
}

TypeScript Support

The package includes TypeScript definitions out of the box. Define your game state interface and use it with the providers:

interface GameState {
  score: number;
  level: number;
  // ... other state properties
}

const LiorGameProvider: React.FC<{
  gameState: GameState;
  desc: string;
  children: ReactNode;
}>;