Aetheria Classroom RPG
Theory → Art → Commerce: directed architecture for an educational RPG
Related Live Sites
Aetheria Classroom RPG Concept Sketch
The Full Pipeline
Aetheria is the project that proves the system works — and honestly reveals where it doesn't. It traveled the complete I→II→III path: from gamification theory to game design to revenue product. I directed the comprehensive post-mortem below because honest reflection on what failed teaches more than polished success stories.[1]
The Theory (ORGAN-I)
Not shallow "add points and badges" gamification. Structural gamification Using game design principles like meaningful choice, progression systems, and narrative framing to reshape an activity, rather than just adding points and badges — using game design principles to reshape learning:[2] Deterding's framework distinguishes between surface-level gamification (points, badges, leaderboards) and deeper gameful design that draws on game design's capacity to create intrinsically motivated engagement.
- Meaningful choices over reward schedules (Deterding's gameful design)
- Recursive pedagogy — learning is recursive; Level 3 quests require applying Level 2 knowledge in new contexts
- Narrative as motivation — academic mastery genuinely advances the plot, not as arbitrary overlay
The Game Design (ORGAN-II)
Character system: Four stats — Insight, Craft, Valor, Empathy — mapping to learning modalities, all growable.[3] Schell's lens-based approach to game design informed the stat system — each stat functions as a lens through which students engage with material, ensuring every learner finds a growth path. Quest design: Teachers create quests from assignment templates. A reading assignment becomes a "Library Expedition." The RPG framing provides structure that helps teachers design better assignments.[4] Koster's central thesis — that fun is the brain's response to mastering patterns — guided quest structure so that each quest teaches a recognizable pattern before layering complexity. World building: Procedurally generated from curriculum — a chemistry unit generates a world where alchemical principles govern reality.[5] Murray's concept of the procedural author — designing systems that generate narrative rather than scripting it directly — is the exact principle behind curriculum-driven world generation.
Technical Architecture
Aetheria is a React 19 single-page application built with TypeScript 5.9 (strict mode), Vite, and Tailwind CSS. The architecture follows a context-provider architecture A React pattern where application state is organized into distinct context objects, each managing one domain, and made available to the component tree through provider wrappers with three primary React contexts — GameStateContext for realm/quest/submission state, FirebaseContext for authentication and persistence, and ThemeContext for the theming engine — ensuring clear separation of concernsA design principle where each module addresses a single aspect of functionality, so changes to one concern do not require changes to unrelated parts of the system across the game loop, infrastructure, and presentation layers.[13] The context-provider pattern mirrors Gamma's Strategy pattern: game state mutations flow through typed action functions that enforce domain invariants before updating state, preventing the kind of implicit coupling that plagues educational software built on ad-hoc state management.
| Layer | Technology | Rationale |
|---|---|---|
| UI Framework | React 19 | Concurrent rendering for smooth quest map interactions |
| Language | TypeScript 5.9 (strict) | 30+ domain interfaces across five type layers |
| 3D Rendering | Three.js + React Three Fiber | Constellation maps, themed geometries per skin |
| Backend | Firebase (Auth, Firestore, Storage) | Zero-ops persistence for classroom-scale data |
| AI Evaluation | LLM integration + DOMPurify | Instant feedback with XSS-safe output rendering |
| Resilience | Circuit breaker, rate limiter, retry | Graceful degradation when AI service is unavailable |
The domain model defines over 30 TypeScript interfaces organized into five layers: core game types (Realm, Quest, Submission, Artifact, KnowledgeCrystal), educator extensions (Syllabus, RubricData, ReportConfig), personalization types (ThematicVariant, ThreeWayVote, ParentAccount), standards alignment (LearningStandardRef, StandardMastery), and system types (Notification, AIConsentState). Quest types include standard, boss, redemption, learning, challenge, and essay, each with distinct XP values and prerequisite chains. The quest status machine follows: locked → available → in_progress → completed | failed.[14] Evans's domain-driven design Eric Evans's approach where the software's core structure directly models the business domain, with shared language between developers and domain experts driving architecture decisions principle that the domain model should be the backbone of the codebase — not an afterthought imposed by framework constraints — drove the decision to define all game mechanics as typed interfaces before writing a single React component.
// Character stat system — four growth dimensions
interface CharacterStats {
insight: number; // analytical, reading, research
craft: number; // making, building, creating
valor: number; // presentation, debate, leadership
empathy: number; // collaboration, peer review, mentorship
}
interface StudentCharacter {
id: string;
name: string;
stats: CharacterStats;
level: number;
questLog: QuestEntry[];
narrative: NarrativeState;
}
// Quest system — teachers author from templates
type QuestDifficulty = 'apprentice' | 'journeyman' | 'master';
interface QuestTemplate {
id: string;
assignmentType: 'reading' | 'writing' | 'project' | 'exam';
narrativeFrame: string; // "Library Expedition", "Forge Trial"
statWeights: Partial<CharacterStats>; // which stats grow
difficulty: QuestDifficulty;
prerequisites: string[]; // quest IDs for recursive depth
}
interface QuestEntry {
templateId: string;
status: 'available' | 'active' | 'completed' | 'failed';
startedAt?: Date;
completedAt?: Date;
xpAwarded: number;
narrativeOutcome?: string; // procedurally generated
}
// World generation — curriculum drives reality
interface WorldConfig {
subject: string; // "chemistry", "literature"
unit: string; // "organic compounds", "modernism"
generativeRules: WorldRule[]; // curriculum → world mechanics
aestheticTheme: string; // "alchemical", "mythological"
}
interface WorldRule {
curriculumConcept: string;
worldMechanic: string; // how concept manifests in-world
interactionType: 'explore' | 'solve' | 'craft' | 'negotiate';
}Game Mechanics in Depth
The XP and level progression system uses an eight-tier curve (Novice through Legend) where each tier requires progressively more effort. The calculateLevel() function maps cumulative XP to level thresholds, and getLevelTitle() returns a role-appropriate title depending on whether the user is a student or teacher. Level-ups trigger sound effects and toast notifications, maintaining the feedback loop that sustains engagement.[7] The progression curve was calibrated to Csikszentmihalyi's flow channel The narrow zone between boredom and anxiety where challenge matches skill level, producing a state of deep, intrinsically motivated engagement : too-easy thresholds produce boredom, too-steep thresholds produce anxiety, and the sweet spot keeps students in the productive zone where challenge matches skill.
Artifact scarcity drives quality. High-scoring submissions generate artifacts with procedurally generated names and rarity tiers (common, rare, epic, legendary). The generateArtifactName() function combines theme-specific prefixes and suffixes with concept words extracted from the quest name — a legendary artifact from a rhetoric quest in fantasy mode might be "Enchanted Tome of Rhetoric," while the same achievement in cyberpunk mode produces "Quantum Core of Rhetoric." Knowledge Crystals are separate collectibles tied to quest completions that students can "attune" to demonstrate mastery retention.
Theming transforms identity. Four complete skins remap every user-facing label: teacher becomes Game Master (fantasy), Admin (cyberpunk), Lord (royal court), or Teacher (glass classroom). Students become Adventurers, Operatives, Vassals, or Students. Each theme specifies a Three.js geometry for the constellation visualization — octahedron, icosahedron, dodecahedron, or sphere — creating a complete alternative reality for the classroom experience.[3]
Classroom Integration and Standards Alignment
Aetheria ships with a four-year English Literature curriculum and three complete standards frameworks: CCSS ELA Grades 9-10, CCSS ELA Grades 11-12, and AP Literature organized by College Board Big Ideas (Character, Setting, Structure, Narration, Figurative Language, Argumentation, Interpretation). Every quest can be tagged with specific standards via QuestStandardAlignment, specifying coverage level (full, partial, introduced). Student mastery is tracked per standard across five levels (not-started through mastered), with evidence references linking mastery assessments to specific submissions.
The educator dashboard provides teachers with feedback snippets organized by category (grammar, thesis, evidence, organization, clarity, citations, analysis, mechanics, positive), structured rubric management with weighted criteria, syllabus upload via Firebase Storage, a student sample library for calibration, and configurable report generation (transcript, mastery, progress) exportable as PDF, CSV, or JSON. The three-way voting system allows teachers, students, and parents to collaboratively shape personalized learning paths — a mechanism ensuring personalization is collaborative rather than algorithmically imposed.[11] Self-determination theory's three needs — autonomy, competence, and relatedness — map directly to the voting system: students gain autonomy through vote participation, competence through mastery tracking, and relatedness through the parent-student-teacher collaboration loop.
Testing and Quality Infrastructure
The testing infrastructure uses Vitest with React Testing Library and jsdom. Test coverage spans hooks (use-ai-consent, use-dialogs, use-feedback-snippets, use-navigation-items, use-parent-linking, use-player-stats, use-reduced-motion), library utilities (api-retry, circuit-breaker, game-utils, network, rate-limiter, sandbox-mode, sanitize, schemas, utils), and core type validation. Six CI workflows run on every push: CI pipeline, CodeQL static analysis, dependency review, deployment, video generation, and stale issue management. The circuit breaker A resilience pattern that monitors for failures and temporarily stops calling a degraded service, preventing cascading failures across the system pattern prevents cascading failures from degraded LLM API calls, the rate limiter throttles AI evaluation requests to manage cost, and DOMPurify sanitizes all AI-generated content before rendering.[15] Nygard's stability patterns — particularly the circuit breakerA resilience pattern that monitors for failures and temporarily stops calling a degraded service, preventing cascading failures across the system and bulkhead — informed the resilience layer: educational software that fails during a classroom session loses trust permanently, so graceful degradation is not optional but architecturally mandated.
// Circuit breaker states for AI evaluation service
type CircuitState = 'closed' | 'open' | 'half-open';
interface CircuitBreakerConfig {
failureThreshold: number; // failures before opening (default: 5)
resetTimeout: number; // ms before half-open attempt (default: 30000)
monitorWindow: number; // ms window for failure counting
}
// Usage: wraps every LLM evaluation call
const evaluationBreaker = createCircuitBreaker({
failureThreshold: 5,
resetTimeout: 30_000, // 30s before retry
monitorWindow: 60_000, // 1-minute sliding window
});
// When open: returns cached feedback or graceful fallback
// When half-open: allows single probe request
// When closed: normal operation with failure countingMetrics
| Metric | Value | Assessment |
|---|---|---|
| Pilot classrooms | 47 | Below target (100) |
| Teacher retention (month 2) | 68% | Acceptable |
| Teacher retention (month 6) | 41% | Below target (60%) |
| Student engagement increase | +23% | Strong |
| NPS (teachers) | 42 | Good but not great |
| Core features implemented | 13/13 | Complete prototype |
| Production readiness | 35% | Active hardening |
| Innovation score | 9/10 | Per 9-dimensional analysis |
What Worked
Student engagement: +23% assignment completion. Narrative integration was the key — students cared about quest outcomes because the stories were connected to their actual learning.[6] Gee's research demonstrates that well-designed game environments create "situated meaning" — players learn because the context makes abstract concepts tangible and consequential, exactly what we observed in assignment completion data.[7] The engagement increase aligns with Csikszentmihalyi's flow theory: the quest structure balanced challenge and skill, keeping students in the productive zone between boredom and anxiety.
The governance pipeline caught quality issues early. At the I→II transition, we verified the theoretical framework. At II→III, we verified the game design was teacher-ready. Without these gates, we would have shipped too early.[8] Ostrom's work on institutional governance informed the gate structure — her design principles for managing shared resources translate directly to managing shared creative infrastructure, where premature release degrades the commons.
What Failed
Onboarding complexity. 2-3 hours of setup. Teachers don't have that time.[9] Brooks's observation that conceptual integrity demands one mind (or a very small team) shaping the user experience proved prescient — we had built a system that reflected our own understanding rather than meeting teachers where they were. Free tier didn't demonstrate value. Without the narrative engine, it looked like every other gamification tool.[10] Christensen's framework reveals our pricing failure — the free tier stripped away the disruptive innovation (narrative integration) and left only sustaining features that incumbents already offered better. Wrong sales direction. Bottom-up (individual teachers) when value was clearest at school level.[11] Self-determination theory explains the adoption gap: individual teachers lacked institutional autonomy to adopt a tool that required cross-classroom coordination, undermining the competence and relatedness needs that drive sustained engagement.
Market Context
Aetheria occupies a specific niche within the $8B+ EdTech gamification market. Classcraft, the most direct competitor, focuses on behavior management (HP loss for disruptions, XP for good behavior) rather than curriculum-aligned assessment — its game mechanics reward compliance, not mastery. Kahoot excels at synchronous formative assessment but provides no persistent progression or narrative continuity between sessions. Duolingo's streak mechanics and adaptive difficulty are well-studied, but Aetheria targets teacher-directed curriculum rather than algorithmic content sequencing, preserving instructor autonomy. Google Classroom and Canvas handle assignment distribution but treat gamification as an afterthought. Gimkit and Blooket optimize for short-burst entertainment rather than the sustained academic rigor that secondary and post-secondary education demands.
Aetheria's differentiation is the combination of deep RPG mechanics, AI-powered evaluation, multi-stakeholder personalization (teacher + student + parent voting), and rigorous standards alignment in a single platform — capabilities that existing products offer only in isolation. The sandbox mode with pre-populated demo data enables risk-free exploration without touching real classroom state, addressing the evaluation barrier that prevents teachers from trialing new tools during active semesters.
Why Include a Failure?
The I→II→III pipeline worked as governance — it caught problems, preserved decisions, and enabled this post-mortem. The product needs iteration, but the system that produced it is sound. That's what governance as creative infrastructure looks like in practice: not preventing failure, but making failure legible and recoverable.[12] Papert's constructionism holds that the best learning happens through building things that fail and then understanding why — Aetheria itself became an instance of the pedagogy it tried to teach, and this post-mortem is the assignment. Within a system of 116 repositories across 8 organs, Aetheria demonstrates that the governance model produces accountable outcomes even when the product itself requires further iteration.
References
- Ries, Eric. The Lean Startup. Crown Business, 2011.
- Deterding, Sebastian et al.. From Game Design Elements to Gamefulness: Defining Gamification. Proceedings of MindTrek 2011, ACM, 2011.
- Schell, Jesse. The Art of Game Design: A Book of Lenses. CRC Press, 2008.
- Koster, Raph. A Theory of Fun for Game Design. Paraglyph Press, 2004.
- Murray, Janet. Hamlet on the Holodeck: The Future of Narrative in Cyberspace. MIT Press, 1997.
- Gee, James Paul. What Video Games Have to Teach Us About Learning and Literacy. Palgrave Macmillan, 2003.
- Csikszentmihalyi, Mihaly. Flow: The Psychology of Optimal Experience. Harper & Row, 1990.
- Ostrom, Elinor. Governing the Commons: The Evolution of Institutions for Collective Action. Cambridge University Press, 1990.
- Brooks, Frederick P.. The Mythical Man-Month: Essays on Software Engineering. Addison-Wesley, 1975.
- Christensen, Clayton M.. The Innovator's Dilemma: When New Technologies Cause Great Firms to Fail. Harvard Business Review Press, 1997.
- Deci, Edward L. and Ryan, Richard M.. Self-Determination Theory: A Macrotheory of Human Motivation, Development, and Health. Canadian Psychology, 49(3), 2008.
- Papert, Seymour. Mindstorms: Children, Computers, and Powerful Ideas. Basic Books, 1980.
- Gamma, Erich et al.. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 1995.
- Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003.
- Nygard, Michael T.. Release It! Design and Deploy Production-Ready Software. Pragmatic Bookshelf, 2007.