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
Resourcescripts (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_UPDATEfor complex character input support (e.g., East Asian). - NEVER ignore
mouse_filteron overlays; strictly set toPASSto 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
- 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
- Chocolate-Covered Broccoli — mechanic must be the learning.
- Punishing Failure — Try Again / hint, never Game Over for wrong answers.
- 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_modeso 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.
