godot-genre-educational

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: godot-genre-educational
description: "Expert blueprint for educational games including gamification loops (learn/apply/feedback/adapt), progress tracking (student profiles, mastery %), adaptive difficulty (target 70% success rate), spaced repetition, curriculum trees (prerequisite system), and visual feedback (confetti, XP bars). Use for learning apps, training simulations, or edutainment. Trigger keywords: educational_game, gamification, adaptive_difficulty, spaced_repetition, student_profile, curriculum_tree, mastery_tracking."
---

## 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_localizatio