lior-game v1.4.5
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 componentButton
: An interactive button with hover statesSuccessAnimation
: 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;
}>;
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
.
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago