Amalie Engine

A TypeScript quiz game engine with Liveblocks real-time sync, React hooks for Next.js apps, configurable scoring systems, and power-up support.

Features

- 🎮 Complete Game Engine - State machine handling lobby, playing, revealing, and finished phases
- ⚡ Liveblocks Realtime - Built-in real-time multiplayer with automatic reconnection
- 🎯 Multiple Question Types - Multiple choice, text input, and numeric/estimation questions
- 🏆 Flexible Scoring - Time bonuses, streak multipliers, difficulty modifiers, and golf-style estimation scoring
- 💪 Power-ups - Built-in power-ups like double points, 50/50, extra time, and shields
- 🔌 React Hooks - useQuizHost and useQuizPlayer hooks for easy integration
- 📱 QR Code Component - Easy player joining with QR codes
- 🔄 Reconnection Support - Player identity persistence and automatic reconnection
- 📦 Lightweight - Minimal dependencies, tree-shakeable exports
- 🤖 AI-Ready - Includes AI_INSTRUCTIONS.md for AI-assisted development

Installation

``bash
npm install amalie-engine @liveblocks/client @liveblocks/react


or

`bash
npm install qrcode.react
`

Quick Start

$3

1. Sign up at liveblocks.io
2. Create a project and get your public API key (starts with pk_)
3. Add it to your .env.local:

`
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY=pk_...
`

$3

`tsx
'use client'

import { useState, useMemo } from 'react'
import { QuizProvider, useQuizHost, generateRoomCode } from 'amalie-engine'
import type { Question, Presence, QuizGameConfig } from 'amalie-engine'

const LIVEBLOCKS_KEY = process.env.NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY!

const questions: Question[] = [
{
id: '1',
category: 'Science',
text: 'What is the chemical symbol for gold?',
answerType: 'multiple-choice',
options: ['Ag', 'Au', 'Fe', 'Cu'],
correctOptionIndex: 1,
},
// ... more questions
]

const config: QuizGameConfig = {
scoring: {
basePoints: 100,
timeBonus: { enabled: true, maxBonus: 50, decayPerSecond: 5 },
},
questionTimeLimit: 20,
}

function HostGame() {
const {
gameState,
currentQuestion,
players,
scoreboard,
roomCode,
startGame,
nextQuestion,
revealAnswer,
isConnected,
} = useQuizHost({ config, questions })

if (gameState === 'lobby') {
return (


return (
publicApiKey={LIVEBLOCKS_KEY}
roomCode={roomCode}
initialPresence={initialPresence}
>


)
}
`

$3

`tsx
'use client'

import { useState, useMemo } from 'react'
import { QuizProvider, useQuizPlayer, generatePlayerId } from 'amalie-engine'
import type { Presence } from 'amalie-engine'

const LIVEBLOCKS_KEY = process.env.NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY!

function PlayerGame({ playerName }: { playerName: string }) {
const { gameState, currentQuestion, myScore, hasAnswered, submitAnswer, isConnected } =
useQuizPlayer({ playerName })

if (gameState === 'lobby') {
return

return (
publicApiKey={LIVEBLOCKS_KEY}
roomCode={params.code}
initialPresence={initialPresence}
>


)
}
`

Question Types

$3

`typescript
const question: Question = {
id: 'mc-1',
category: 'Geography',
text: 'What is the capital of France?',
answerType: 'multiple-choice',
options: ['London', 'Paris', 'Berlin', 'Madrid'],
correctOptionIndex: 1,
difficulty: 'easy',
}
`

$3

`typescript
const question: Question = {
id: 'text-1',
category: 'Geography',
text: 'Name the largest country by area',
answerType: 'text',
correctText: 'Russia',
acceptedAnswers: ['Russia', 'Russian Federation'],
caseSensitive: false,
}
`

$3

`typescript
const question: Question = {
id: 'est-1',
category: 'History',
text: 'In what year did World War II end?',
answerType: 'numeric',
correctNumber: 1945,
lowerBound: 1900,
upperBound: 2000,
}
`

Scoring Configuration

`typescript
const config: QuizGameConfig = {
scoring: {
basePoints: 100,
timeBonus: {
enabled: true,
maxBonus: 50,
decayPerSecond: 5,
},
streakBonus: {
enabled: true,
multiplierPerStreak: 0.1,
maxMultiplier: 2,
},
difficultyMultipliers: {
easy: 1,
medium: 1.5,
hard: 2,
},
},
}
`

Round Behavior

`typescript
const config: QuizGameConfig = {
questionsPerGame: 10,
questionTimeLimit: 20,
autoAdvanceOnAllAnswered: true, // Auto-reveal when all answered
}
`

$3

`tsx
const {
allPlayersAnswered, // true when all connected players have answered
endRound, // Force end current round
revealAnswer, // Reveal the answer
} = useQuizHost(options)
`

Power-ups

`typescript
import {
DOUBLE_POINTS,
FIFTY_FIFTY,
EXTRA_TIME,
SKIP_QUESTION,
SHIELD,
STEAL_POINTS,
} from 'amalie-engine'

const config: QuizGameConfig = {
powerups: [DOUBLE_POINTS, FIFTY_FIFTY, SHIELD],
}
`

API Reference

$3

Wraps your quiz components and establishes the Liveblocks connection.

`tsx
publicApiKey="pk_..." // Your Liveblocks public key
roomCode="ABC123" // The quiz room code
initialPresence={{
// User's presence data
playerId: 'player-1',
playerName: 'Alice',
isHost: false,
joinedAt: Date.now(),
}}
>
{children}

`

$3

Host-side hook for managing a quiz game.

Options:

- config - Game configuration
- questions - Array of questions or QuestionProvider
- baseUrl - Base URL for join links (optional)
- onGameEnd - Callback when game ends
- onRematch - Callback before rematch

Returns:

- gameState - Current game phase ('lobby' | 'playing' | 'revealing' | 'finished')
- currentQuestion - Current question state
- players - List of players
- scoreboard - Current scoreboard
- answers - Current round's answers
- allPlayersAnswered - Whether all connected players have answered
- roomCode - Room code
- startGame() - Start the game
- nextQuestion() - Show next question
- revealAnswer() - Reveal the answer
- endRound() - Force end current round
- endGame() - End the game
- rematch() - Start a rematch
- kickPlayer(id) - Remove a player
- isConnected - Connection status
- error - Connection error if any

$3

Player-side hook for playing in a quiz game.

Options:

- playerName - Player's display name

Returns:

- gameState - Current game phase
- currentQuestion - Current question (without answers)
- myScore - Player's current score
- myRank - Player's current rank
- hasAnswered - Whether player has answered
- answerRejected - Whether answer was rejected
- questionTimeRemaining - Time remaining in ms
- submitAnswer(answer) - Submit an answer
- activatePowerup(id) - Use a power-up
- isConnected - Connection status
- isReconnecting - Whether reconnecting
- connectionError - Connection error if any
- reconnect() - Manual reconnect

$3

#### RoomQRCode

QR code component for player joining.

`tsx

`

Question Providers

$3

`typescript
import { createArrayProvider } from 'amalie-engine'

const provider = createArrayProvider(questions)
const filtered = await provider.getQuestions({
categories: ['Science'],
count: 10,
shuffle: true,
})
`

$3

`typescript
import { createJsonUrlProvider } from 'amalie-engine'

const provider = createJsonUrlProvider('https://api.example.com/questions.json')
`

$3

`typescript
import { createSupabaseProvider } from 'amalie-engine'

const provider = createSupabaseProvider(supabaseClient, {
tableName: 'quiz_questions',
})
`

Migration from v0.1.x (Supabase Realtime)

If you're migrating from the Supabase-based version:

1. Dependencies: Replace @supabase/supabase-js with @liveblocks/client and @liveblocks/react

2. Environment: Replace NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY with NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY

3. Provider: The QuizProvider now takes different props:

`tsx
// Before (v0.1.x)
{children}

// After (v0.2.x)
publicApiKey={liveblocksKey}
roomCode={roomCode}
initialPresence={presence}
>
{children}

`

4. Hooks: Remove supabaseClient from hook options:

`tsx
// Before
useQuizHost({ supabaseClient, config, questions })
useQuizPlayer({ supabaseClient, roomCode, playerName })

// After
useQuizHost({ config, questions })
useQuizPlayer({ playerName })
`

5. Room code: Now passed to QuizProvider` instead of hooks

License

MIT