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.

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 — restored baseline pedagogy (architecture, WHY, implementation depth)
• 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.