1.4.5 • Published 4 months ago

lior-game v1.4.5

Weekly downloads
-
License
-
Repository
-
Last release
4 months ago

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

  1. 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>
  );
}
  1. 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:

  1. Define a game state interface
  2. Create a context provider for your game state
  3. 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

  1. Clear Instructions: Provide clear game descriptions in the desc prop
  2. Timely Feedback: Send messages at key interaction points
  3. Progressive Guidance: Break down complex actions into simple steps
  4. Error Handling: Provide helpful messages when users make mistakes
  5. 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;
}>;

License

MIT © Lior Learning Inc

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

Development

To run the development server, run npm run dev.

To build the package, run npm run build.

To push the package to npm, run npm publish.

1.4.5

4 months ago

1.4.4

4 months ago

1.4.3

4 months ago

1.4.2

5 months ago

1.4.1

5 months ago

1.4.0

5 months ago

1.3.9

5 months ago

1.3.8

5 months ago

1.3.7

5 months ago

1.3.6

5 months ago

1.3.5

5 months ago

1.3.4

6 months ago

1.3.3

6 months ago

1.3.2

6 months ago

1.3.1

6 months ago

1.3.0

6 months ago

1.2.10

6 months ago

1.2.9

6 months ago

1.2.8

6 months ago

1.2.7

6 months ago

1.2.6

6 months ago

1.2.5

6 months ago

1.2.4

6 months ago

1.2.3

6 months ago

1.2.2

6 months ago

1.2.1

6 months ago

1.2.0

6 months ago

1.1.13

6 months ago

1.1.12

6 months ago

1.1.11

6 months ago

1.1.10

6 months ago

1.1.9

6 months ago

1.1.8

6 months ago

1.1.7

6 months ago

1.1.6

6 months ago

1.1.5

6 months ago

1.1.4

6 months ago

1.1.3

7 months ago

1.1.2

7 months ago

1.1.1

7 months ago

1.1.0

7 months ago

1.0.14

7 months ago

1.0.13

7 months ago

1.0.12

7 months ago

1.0.11

7 months ago

1.0.10

7 months ago

1.0.9

7 months ago

1.0.8

7 months ago

1.0.7

7 months ago

1.0.6

7 months ago

1.0.5

7 months ago

1.0.4

7 months ago

1.0.3

7 months ago

1.0.2

7 months ago

1.0.1

7 months ago

1.0.0

7 months ago

0.1.0

7 months ago