@fortune-kit/headless

Headless game engines — framework-agnostic logic for wheel, quiz, and more.

Installation

pnpm add @fortune-kit/headless

Exports

// Main entry
import { useWheel, useQuiz } from '@fortune-kit/headless'

// Subpath imports
import { useWheel } from '@fortune-kit/headless/wheel'
import { useQuiz } from '@fortune-kit/headless/quiz'

// Types
import type {
  WheelSegment,
  WheelState,
  WheelOptions,
  UseWheelReturn,
  QuizQuestion,
  QuizOption,
  QuizAnswer,
  QuizState,
  QuizOptions,
  UseQuizReturn
} from '@fortune-kit/headless'

useWheel

Signature

function useWheel(options: WheelOptions): UseWheelReturn

Options

interface WheelOptions {
  segments: WheelSegment[]
  spinDuration?: number      // Default: 4000ms
  minRotations?: number      // Default: 3
  maxRotations?: number      // Default: 5
  onSpinStart?: () => void
  onSpinEnd?: (result: WheelSegment) => void
}

interface WheelSegment {
  id: string
  label: string
  value: number | string
  weight?: number  // Default: 1
  color?: string
}

Returns

interface UseWheelReturn {
  state: Ref<WheelState>
  spin: (targetIndex?: number) => Promise<WheelSegment>
  reset: () => void
  isSpinning: ComputedRef<boolean>
  result: ComputedRef<WheelSegment | null>
  segmentAngle: ComputedRef<number>
}

interface WheelState {
  segments: WheelSegment[]
  isSpinning: boolean
  currentRotation: number
  result: WheelSegment | null
}

useQuiz

Signature

function useQuiz(options: QuizOptions): UseQuizReturn

Options

interface QuizOptions {
  questions: QuizQuestion[]
  shuffleQuestions?: boolean  // Default: false
  shuffleOptions?: boolean    // Default: false
  onAnswer?: (answer: QuizAnswer) => void
  onComplete?: (answers: QuizAnswer[], score: number) => void
}

interface QuizQuestion {
  id: string
  text: string
  options: QuizOption[]
  correctOptionId?: string
  timeLimit?: number
  points?: number
}

interface QuizOption {
  id: string
  text: string
  isCorrect?: boolean
}

Returns

interface UseQuizReturn {
  state: Ref<QuizState>
  currentQuestion: ComputedRef<QuizQuestion | null>
  progress: ComputedRef<number>
  score: ComputedRef<number>
  isComplete: ComputedRef<boolean>
  answer: (optionId: string) => QuizAnswer
  next: () => void
  previous: () => void
  goTo: (index: number) => void
  reset: () => void
}

interface QuizAnswer {
  questionId: string
  optionId: string
  timeSpent: number
  isCorrect: boolean
}