How sycrus/math-heroes works
Project Type and Purpose
• This is a Unity‐based augmented-reality (AR) learning app (“Math Heroes”) built on top of the Vuforia AR SDK.
• Purpose: enable tangible, physical math exercises by detecting printed targets (planes, objects) through the device camera, then augmenting them with 3D models, equations, weights, and interactive logic.
High-Level Architectural Components
a. Hardware Layer
• Mobile device (iOS/Android) with camera, accelerometer, gyroscope
b. Unity Engine (Core Runtime)
• Rendering, physics, input, lifecycle management
c. Vuforia AR SDK Plugin
• Camera feed acquisition → image target detection → pose estimation
• Comes under Assets/Plugins and Assets/StreamingAssets/Vuforia
d. Scene & Asset Layer
• Assets/Scenes/MathHeroes.unity
• 3D Models (Assets/Models), Materials, Shaders (Assets/Vuforia/Shaders)
• Prefabs (Assets/Prefabs): numeric and weight objects
e. Resource & Configuration
• VuforiaConfiguration.asset (Assets/Resources)
• math_objects dataset (Assets/StreamingAssets/Vuforia)
f. Logic & Controllers
• Trackable event handlers (Assets/Vuforia/Scripts)
• Custom MonoBehaviour scripts (Assets/Scripts/Controllers & CollidersTriggers)
• EquationDisplay, TrackableList
g. Physics & Interaction
• Unity Physics (Asset PhysicsMaterials, colliders/triggers)
• WeightController, ZeroPairController, etc.
h. UI & Feedback
• On-screen equation text, rotation controls, visual highlights
Component Interactions and Data Flow
1. Device Camera → Unity’s ARCamera object (in scene)
2. ARCamera forwards video frames → Vuforia Plugin
3. Vuforia detects ImageTargets → raises OnTrackableFound/Lost events
4. DefaultTrackableEventHandler (Vuforia) → invokes custom controllers
5. Custom Controllers (EquationController, WeightController, etc.)
– Instantiate or update Prefabs (numbers, weights)
– Update UI via EquationDisplay
– Trigger physics simulations (add/remove weight objects)
6. Unity Physics Engine → resolves collisions/triggers → feedback loops back to scripts
7. Render pipeline → draws augmented 3D models blended with camera feed
Architectural Patterns & Principles
• Component-Based Architecture (Unity’s GameObject + MonoBehaviour)
• Event-Driven Design (trackable found/lost, trigger enter/exit)
• Separation of Concerns:
• Vuforia handles CV and pose estimation
• Unity core handles rendering & physics
• Custom scripts handle game logic
Technologies & Key Libraries
• Unity 2018+ (ProjectSettings, Packages/manifest.json)
• Vuforia Engine (Assets/Plugins, Assets/StreamingAssets)
• C# MonoBehaviour scripts
• Unity Physics & Cinemachine (implicit via Unity engine)
• Standard Unity UI system