godot-genre-educational

NEVER Do (Expert Anti-Patterns)

Pedagogy & Flow

• NEVER punish failure with a "Game Over"; strictly use "Try Again" or Contextual Hints to ensure a safe, encouraging learning environment.
• NEVER separate learning from gameplay ("Chocolate-covered broccoli"); strictly ensure the mechanic IS the learning (e.g., math-based trajectory calc).
• NEVER use walls of text for instructions; strictly use Show, Don't Tell methods: interactive diagrams, non-verbal tutorials, or 3-second looping GIFs.
• NEVER skip Spaced Repetition logic; strictly ensure successfully answered questions reappear at increasing intervals to verify long-term retention.
• NEVER focus on failure; strictly prominently display Mastery %, XP Bars, and Skill Trees to motivate through visible progress.
• NEVER assume a fixed difficulty; strictly implement Dynamic Scaffolding that adjusts challenge based on the student's mastery level to keep them in the "Zone of Proximal Development".
• NEVER hardcode student stats in UI components; strictly use Resource scripts (StudentProfile) to decouple student data from the presentation layer for persistence and scalability.
• NEVER build custom debug dashboards for performance tracking during development; strictly use Performance.add_custom_monitor() to inject live student metrics into the Godot Editor Debugger.

Technical & Accessibility

• NEVER hardcode text into UI; strictly use Translation Keys (PO files) for internationalization and classroom localized support.
• NEVER force TTS without user consent; strictly provide an in-game toggle and respect OS-level screen reader settings.
• NEVER use absolute pixel positioning; strictly use the Anchoring & Container system for responsive scaling across tablets and classroom laptops.
• NEVER perform heavy data grading on the main thread; strictly use WorkerThreadPool to prevent UI freezes during automated assessments.
• NEVER forget to handle IME updates; strictly monitor NOTIFICATION_OS_IME_UPDATE for complex character input support (e.g., East Asian).
• NEVER ignore mouse_filter on overlays; strictly set to PASS to prevent invisible containers from silently consuming clicks.
• NEVER update static strings in _process(); strictly update labels ONLY on state change events to save mobile/tablet battery.
• NEVER embed sensitive database credentials in exports; strictly use Environment Variables or proxy APIs for student data security.

---

Available Scripts

> MANDATORY: Read the script matching the scenario before implementing. Do not paste quiz/profile tutorials inline.

Pedagogy / Adaptivity

• [adaptive_difficulty_adjuster.gd](scripts/adaptive_difficulty_adjuster.gd) — MANDATORY when targeting ~70% flow / progressive hints.
• [spaced_repetition_scheduler.gd](scripts/spaced_repetition_scheduler.gd) — MANDATORY when scheduling question reappearance (intervals after success/fail).
• [student_progress_config.gd](scripts/student_progress_config.gd) — MANDATORY before persisting mastery/XP (ConfigFile profile).
• [threaded_scoring_engine.gd](scripts/threaded_scoring_engine.gd) — MANDATORY before heavy assessment/grading on school hardware.

Accessibility / Classroom UI

• [tts_manager.gd](scripts/tts_manager.gd) — MANDATORY before DisplayServer TTS (consent toggle first).
• [dynamic_localization.gd](scripts/dynamic_localization.gd) — Runtime locale switch / pluralization.
• [adaptive_ui_anchors.gd](scripts/adaptive_ui_anchors.gd) — Responsive tablet/laptop lesson layouts.
• [focus_navigation_manager.gd](scripts/focus_navigation_manager.gd) — Keyboard/controller focus for classroom navigation.
• [interactive_rich_text.gd](scripts/interactive_rich_text.gd) — Meta-click glossaries / formula prompts.
• [text_reveal_effect.gd](scripts/text_reveal_effect.gd) — Progressive text reveal without walls of text.

Assessment UX

• [assessment_pause_handler.gd](scripts/assessment_pause_handler.gd) — Pause world logic while quiz UI stays interactive.
• [low_processor_optimizer.gd](scripts/low_processor_optimizer.gd) — Battery-friendly idle for ed apps on school devices.

---

Core Loop

1. Learn → 2. Apply → 3. Feedback → 4. Adapt → 5. Master

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. UI | godot-ui-rich-text, godot-ui-theming | Readable text, drag-and-drop answers |

| 2. Data | godot-save-load-systems | Student profiles, progress tracking |

| 3. Logic | godot-state-machine-advanced | Quiz flow (Question → Answer → Result) |

| 4. Juice | godot-particles, godot-tweening | Making learning feel rewarding |

| 5. Meta | godot-scene-management | Navigating between lessons and map |

| 6. Balance | godot-monte-carlo-balancer | Override bands to ~70% flow / mastery |

Architecture Decision Tree

Pick the owner script; keep SKILL free of duplicate StudentProfile / quiz_manager paste-ups.

| Need | Decision | MANDATORY script |

|------|----------|------------------|

| Track mastery / XP / badges | One StudentProfile Resource + ConfigFile I/O | [student_progress_config.gd](scripts/student_progress_config.gd) |

| Keep learners in flow (~70%) | Windowed success ratio + hint branch | [adaptive_difficulty_adjuster.gd](scripts/adaptive_difficulty_adjuster.gd) |

| Long-term retention | Interval queue (success → longer delay; fail → sooner) | [spaced_repetition_scheduler.gd](scripts/spaced_repetition_scheduler.gd) |

| Prerequisite lesson map | Curriculum Resource graph (id + required_topics) — data only, no UI | Peer godot-resource-data-patterns |

| Grade without hitching | Offload scoring | [threaded_scoring_engine.gd](scripts/threaded_scoring_engine.gd) |

| Classroom a11y | TTS + locale + focus + anchors | tts_manager / dynamic_localization / focus_navigation_manager / adaptive_ui_anchors |

| Live debugger metrics | Performance.add_custom_monitor("edu/...") — no custom dashboards | (inline one-liner OK) |

StudentProfile (single shape): @export mastery Dictionary + XP; emit change signals; persist via student_progress_config.gd. Do not redefine the class twice in this skill.

Quiz curtain: state machine owns Question → Answer → Result → Adapt; spaced-repetition + adaptive-difficulty scripts decide what is next — do not inline a full quiz_manager.gd tutorial here.

Juice (Duolingo Effect)

Learning is hard — reward effort: satisfying SFX, particles on correct, Tweened XP bars. Pedagogue first; juice never substitutes for spaced repetition / ZPD scaffolding.

Common Pitfalls

1. Chocolate-Covered Broccoli — mechanic must be the learning.
2. Punishing Failure — Try Again / hint, never Game Over for wrong answers.
3. Wall of Text — show/interact first; use text_reveal_effect / rich-text meta.

Expert knowledge (on demand)

> LLM-ignorance rule: If a general agent would not know it before reading, load the reference — never delete expert deltas.

• [expert-educational-patterns.md](references/expert-educational-patterns.md) — restored baseline pedagogy (architecture, WHY, implementation depth)
• [student_profile.gd](scripts/student_profile.gd)

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Internationalizing games — tr() / locale workflow for classroom multi-language UI without hardcoding strings.
• Localization using gettext — PO/CSV pipeline and plural forms used by runtime locale switching.
• Text-to-speech — DisplayServer TTS voices, speak/stop, and consent-friendly accessibility read-aloud.
• BBCode in RichTextLabel — Colored keywords, formulas, meta links, and custom RichTextEffect reveals for lessons.
• Using Containers — Responsive quiz/layout composition for tablets and classroom laptops.
• Size and anchors — Anchor/offset rules that replace absolute pixel placement across orientations.
• Keyboard/Controller Navigation and Focus — Focus neighbors and grab_focus patterns for keyboard-only classroom navigation.
• Resources — StudentProfile / curriculum node Resources decoupled from presentation.
• Saving games — Persist mastery, XP, and progress without baking credentials into exports.
• Using multiple threads — WorkerThreadPool grading so heavy assessment never freezes the quiz UI.
• Pausing games — Tree pause + process_mode so assessments freeze world logic while UI stays interactive.
• Performance — Custom monitors, low-processor mode, and battery-friendly idle screens for ed apps.

Related Skills

Prerequisites

• godot-project-foundations — Project locale, display, and input map defaults must exist before classroom UI and TTS toggles.
• godot-gdscript-mastery — Typed Resources, signals, and await patterns underpin student profiles and quiz flow.
• godot-ui-containers — Anchors/containers are the non-negotiable layout base for multi-device lesson screens.

Complements

• godot-ui-rich-text — BBCode, meta clicks, and custom effects for glossaries and formula-heavy prompts.
• godot-ui-theming — Readable theme scales and contrast for mixed tablet/laptop classrooms.
• godot-save-load-systems — Durable StudentProfile / mastery persistence beyond ad-hoc ConfigFile snippets.
• godot-tweening — XP bars, confetti timing, and overlay fades that sell the “Duolingo effect.”
• godot-signal-architecture — Mastery-up, hint-revealed, and difficulty-changed events without UI↔logic hardwiring.
• godot-input-handling — Focus actions, drag-and-drop answers, and IME-safe text entry for assessments.

Downstream / consumers

• godot-monte-carlo-balancer — Simulate override bands so adaptive difficulty actually lands near ~70% flow/mastery success.
• godot-state-machine-advanced — Question → Answer → Result → Adapt quiz FSMs once the curtain grows beyond one script.
• godot-scene-management — Lesson map ↔ quiz ↔ results transitions without leaking paused tree state.
• godot-performance-optimization — Escalate when scoring threads, TTS, or rich-text effects still show profiler cost on school hardware.
• godot-particles — Confetti/reward bursts wired to correct-answer juice without blocking pedagogy.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting educational concern.