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 — MANDATORY when targeting ~70% flow / progressive hints.
• spaced_repetition_scheduler.gd — MANDATORY when scheduling question reappearance (intervals after success/fail).
• student_progress_config.gd — MANDATORY before persisting mastery/XP (ConfigFile profile).
• threaded_scoring_engine.gd — MANDATORY before heavy assessment/grading on school hardware.

Accessibility / Classroom UI

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

Assessment UX

• assessment_pause_handler.gd — Pause world logic while quiz UI stays interactive.
• 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

Architecture Decision Tree

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

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.