MathSmith | 数锻
Updated: 18 hours ago
Solo Developer
MathSmith is a bilingual educational math game built in Godot. Instead of evaluating only the final answer, the project turns the reasoning between a question and its solution into the playable experience.
I designed MathSmith as a portfolio project exploring the intersection of technical design, educational game design, data-driven systems, adaptive learning, learning analytics, and content-authoring tools.
PROJECT LINKS
PROJECT INFORMATION
Role: Solo Developer · Technical Designer
Project Type: Passion Project
Engine: Godot 4.7.1
Languages: English · Simplified Chinese
Content: 12 Levels · 90 Authored Questions
Development: 10 Active Development Days
Core Focus: Systems Design · Educational Gameplay · Data-Driven Design · Adaptive Learning · Learning Analytics · Teacher Tools · UI/UX
Development Approach: AI-Assisted Development · Human-Directed Design, Validation & Playtesting
PROJECT OVERVIEW
Most math exercises ask a question, accept an answer, and determine whether that answer is correct. I wanted to explore a different question:
What if the reasoning process itself became the gameplay?
MathSmith turns intermediate mathematical reasoning into a sequence of player interactions. Players choose learning content, reconstruct solution processes, receive progressive feedback, earn scores and stars, review mistakes, practice weak skills adaptively, and replay content through multiple modes.
Choose Content → Rebuild the Process → Receive Feedback → Earn Score & Stars → Review Mistakes → Practice Adaptively → Replay
The project was designed around several principles:
Make intermediate mathematical reasoning playable.
Present readable, school-appropriate solution processes.
Reuse one content source across multiple gameplay modes.
Connect feedback, progression, review, analytics, and replay into one learning loop.
Keep mathematical and learning logic deterministic and testable.
MY ROLE
I designed and developed MathSmith independently, covering:
Educational Game Technical Design
Designing the systems connecting mathematical content, gameplay, progression, feedback, analytics, adaptation, and authoring.
Gameplay & System Design
Creating the three primary interaction models, scoring, stars, hints, replay modes, mistake review, progression, and supporting systems.
Mathematical Content Architecture
Building a structured pipeline that converts authored mathematical expressions into human-readable solution processes.
UI/UX Design & Implementation
Designing and implementing the bilingual interface, reusable components, navigation, cards, popups, gameplay states, and responsive presentation.
Data-Driven Tool Development
Creating CSV import, validation, preview, editing, and export workflows so new learning content can be authored without changing gameplay code.
Learning Analytics & Adaptive Practice
Building telemetry, player history, skill mastery, behavior-pattern detection, weak-skill recommendations, and weighted adaptive selection.
Production & Validation
Defining milestone scope, manually playtesting the project, validating mathematical output, and iterating on system architecture.
AI-assisted development was used to accelerate implementation and iteration. Feature direction, educational rules, milestone scope, manual playtesting, validation, and final design decisions remained human-directed.
THREE CORE GAMEPLAY SYSTEMS
MathSmith uses three interactions built on the same underlying mathematical content.
1 · Step Ordering
Players receive complete solution steps and drag them into the correct order. Instead of asking only “What is the answer?”, the interaction asks players to understand the sequence of transformations that produces it.
2 · Multiple-Choice Ordering
Players identify the correct next step from deterministic distractors. This turns mathematical progression into a decision-making problem while keeping incorrect options controlled and reproducible.
3 · Fill in the Process
Players complete missing values inside a generated solution process. This shifts attention from ordering toward understanding the transformations occurring inside individual steps.
All three modes share the same expressions, generated solution steps, Skill Tags, scoring, Hint, and feedback systems.
PROGRESSIVE LEARNING LOOP
I wanted incorrect answers to become part of the learning process rather than simply producing an error state. MathSmith therefore uses progressive error feedback.
First incorrect attempt: generic retry feedback
Second incorrect attempt: directional feedback
Third and later attempts: contextual rule explanation
This gives players an opportunity to self-correct before the system reveals increasingly explicit guidance. Player-requested Hints remain a separate, limited resource.
The broader progression system includes:
Scores · 1–3 Star Ratings · Best-Star Level Cards · Limited Hints · Completion/Failure States · Versioned Local Save
Mistakes can also be stored in the Mistake Book, including the answer, explanation, original Level, Skill Tags, and complete correct solution process.
REPLAY MODES
MathSmith extends authored curriculum content through several replay systems.
Mistake Practice randomly selects previously saved mistakes.
Zen Mode provides three minutes of mixed practice.
Survival Mode gives the player three lives with no time limit.
Rather than requiring separate question sets, these modes reuse the same structured content and learning systems.
LEARNING ANALYTICS & ADAPTIVE PRACTICE
One of the largest technical-design expansions was turning player interaction into structured learning data.
MathSmith records information including:
First-Action Time · Total Solve Time · Drag/Reorder/Selection/Input Events · Check & Hint Usage · Incorrect Attempts · Completion Outcome · Question History · Skill Mastery
These records feed rule-based behavior patterns, weak-skill recommendations, and weighted adaptive question selection. Skill Mastery grows progressively rather than immediately producing high percentages from very small samples, preventing a new player's first few correct answers from creating misleading mastery scores. Importantly, the analytics and adaptive-learning systems are deterministic rather than runtime generative AI.
TEACHER CONTENT PIPELINE
A major goal of MathSmith was separating learning content from gameplay implementation.
Teachers and content designers can create playable material without editing gameplay code.
Author → Validate → Preview → Play → Revise → Export
The CSV Course Workspace supports separate Level and Question data, validation errors and warnings, safe importing, replacement, and course preview.
I also built MathSmith Studio, a visual authoring environment that allows users to:
Create & Edit Courses, Levels and Questions · Duplicate & Reorder Content · Normalize Expressions · Validate Content · Preview Generated Solutions · Preview Questions & Levels · Export Validated CSV
Core Curriculum, Imported Course, and Studio Course maintain independent content and player records.
GUIDED SMART TUTOR
The final milestone introduced a contextual Tutor that connects MathSmith's existing deterministic systems through a floating, option-based interface.
The Tutor can read the current:
Course · Level · Question · Score · Mistakes · History · Skill Mastery
It can then provide contextual explanations and navigation actions appropriate to the player's current state. The Tutor is available across Home, Lobby, gameplay, summaries, the Mistake Book, and different Course sources, while avoiding revealing answers before the appropriate learning state. Rather than replacing MathSmith's learning systems, the Tutor acts as an interface over validated structured information. Mathematical validation, adaptive weighting, saving, and progression remain deterministic systems underneath it.
MATHEMATICAL CONTENT PIPELINE
A central technical challenge was creating solution processes that could support several gameplay modes from the same authored expression.
Authored Expression
↓
ExpressionParser
↓
StepGenerator
↓
Human-Readable Solution Process
↓
Step Ordering · Multiple-Choice Ordering · Fill in the Process
The generator supports strategies including make-ten, place-value decomposition, regrouping, partial products, division decomposition, parentheses, precedence, and multi-step reduction.
KEY DESIGN FINDING
Mathematically Correct Is Not Always Pedagogically Useful
This became one of the most important lessons from the project. Early versions could generate mathematically valid solutions that still felt wrong as teaching material. Some contained unnatural decomposition, redundant transformations, excessive mental arithmetic, or large reasoning jumps.
So I changed the design target. Instead of asking:
“Can the system generate enough steps?”
I began asking:
“What is the minimum number of meaningful, readable steps needed to explain this solution?”
That led to a recurring development loop:
Plan → Build → Playtest → Observe → Classify → Fix Systemically → Validate
Rather than manually patching individual questions, I treated recurring bad outputs as system-level design problems and improved the underlying rules.
TECHNICAL ARCHITECTURE
MathSmith follows several architectural principles:
Content Is the Source of Truth: Gameplay reads structured content rather than embedding question logic into individual scenes.
Content and Presentation Are Separated: The same learning content can support different interfaces and gameplay modes.
Mathematical Logic and UI Are Separated: Generation and validation do not depend on presentation.
Shared Systems Support Multiple Gameplay Modes: Step Ordering, Multiple-Choice Ordering, and Fill in the Process reuse common mathematical and learning infrastructure.
Save Data Is Versioned: Player data can be migrated as the project evolves.
Course Sources Are Isolated: Core, imported, and Studio-authored courses maintain separate data.
Mathematical Feedback Is Deterministic: Correctness and learning rules remain predictable and testable.
M1–M7 DEVELOPMENT
MathSmith was developed through seven vertical milestones, with each milestone preserving a complete playable flow.
M1 — Core Prototype
JSON content · Step Ordering · Drag-and-Drop · Check · Hint · Level Progression
M2 — Structure & UI
Home · Lobby · Level Cards · Multi-Level Flow · Unified UI · Icons · SFX
M3 — Gameplay Expansion
Multiple-Choice Ordering · Fill in the Process · Progressive Feedback · Search · Filters
M4 — Learning Loop
Scores · Stars · Limited Hints · Save · Localization · Mistake Book · Zen · Survival
M5 — Learning Analytics
Telemetry · History · Skill Mastery · Behavior Patterns · Recommendations · Adaptation
M6 — Content Authoring
Teacher Login · CSV Import · Validation · Preview · Visual Editing · Export
M7 — Smart Tutor & Polish
Contextual Tutor · Course-Aware Guidance · Localization · UI Polish · Splash Screen
RESULT
Across 10 active development days spread over three weeks, MathSmith grew from a Step Ordering prototype into a bilingual educational game containing 12 Levels and 90 authored Questions, three core gameplay interactions, progression and replay systems, learning analytics, adaptive practice, teacher-facing content-authoring tools, and a contextual Tutor.
More importantly, the project became an exploration of a technical-design problem I care about:
How can one structured content source support gameplay, pedagogy, analytics, adaptation, authoring, and player guidance without turning those systems into isolated features?
MathSmith is my answer to that question.
Comments