AI Game Platform

// Frozen engine contract  every engine is exactly this:
interface GameProps<T> {
  content: T           // typed per-engine content
  onComplete: (result: unknown) => void  // raw result, never score
}

// Registry: engine → Zod schema. Single source of truth.
const ENGINE_SCHEMAS = {
  "layout-match": LayoutMatchSchema,
  "code-assembler": CodeAssemblerSchema,
  "memory-match": MemoryMatchSchema,
  "match-connect": MatchConnectSchema,
  // ... 15 more engines
} as const;

// AI emits inner content only  server wraps it:
const inner = await generateContent(prompt)
const validated = ENGINE_SCHEMAS[engine].parse(inner)
const envelope = makeEnvelope(engine, validated)

// Universal envelope  all but 3 fields optional:
interface GameEnvelope {
  schemaVersion: string        // "2.0"  gates migrations
  engine: Engine               // discriminator
  content: EngineContent       // per-engine AI payload

  // Cross-cutting (shared, optional, forward-compatible):
  meta?: { title?; prompt?; objective?; instructions? }
  levels?: Level[]
  rewards?: { xp?; coins?; achievements?: string[] }
  timer?: { seconds: number }
  assets?: { id: string; kind: string; src: string }[]
  audio?: { music?; sfx?: Record<string, string> }
  accessibility?: { reducedMotion?; highContrast?; captions? }
  localization?: { language: string; strings?: ... }
  ext?: Record<string, unknown> // experimental features
}

// AI never emits the envelope  it emits inner content only.
// Server wraps it deterministically:
const envelope = makeEnvelope(engine, content, { rewards: { xp: 10 } })

// Shared schemas package  consumed by both apps:
// packages/schemas/src/engine.ts
export const ENGINE_SCHEMAS = {
  "code-assembler": CodeAssemblerSchema,
  // ...
} as const

// Backend seed script  validate before insert:
import { ENGINE_SCHEMAS } from "@eduplay/schemas"
try {
  const content = ENGINE_SCHEMAS["code-assembler"].parse(aiOutput)
  await db.collection("gameContents").insertOne({ engine, content })
} catch (err) {
  // ZodError with exact field-level issues
  await retryGenerate(prompt, err.issues)  // re-prompt with errors
}

// Frontend renderer  validate before render:
import { ENGINE_SCHEMAS } from "@eduplay/schemas"
try {
  const content = ENGINE_SCHEMAS[engine].parse(raw.content)
  return <CodeAssembler content={content} onComplete={...} />
} catch {
  return <ErrorState message="Content validation failed" />
}

// Client submits raw result only  never a score:
fetch("/api/score", {
  method: "POST",
  body: JSON.stringify({
    playId: "abc123",
    result: ["l3", "l1", "l2"]  // player's line order
  })
})

// Server re-derives everything:
export function scoreResult(
  engine: Engine,
  content: unknown,  // re-validated from stored GameSession
  result: unknown,   // raw client result
): ScoreOutcome {
  const validated = ENGINE_SCHEMAS[engine].parse(content)
  const correct = deriveCorrectness(engine, validated, result)
  return {
    valid: true,
    correct,
    score: correct ? computeXp(engine, validated) : 0,
    userAnswer: formatResult(engine, result),
    correctAnswer: formatCorrectAnswer(engine, validated),
  }
}