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

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
Keep learners in flow (~70%)	Windowed success ratio + hint branch	adaptive_difficulty_adjuster.gd
Long-term retention	Interval queue (success → longer delay; fail → sooner)	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
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 — 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.