# 🎮 NEV Educational Game Design Document
**Date:** March 22, 2026  
**Target Audience:** NEV major undergraduates/vocational students/industry trainees  
**Research Alignment:** Hybrid physics-ML models, multi-agent coordination, battery diagnostics  

---

## 📋 Executive Summary

This document presents **5 gamified learning modules** designed to reinforce critical NEV competencies through interactive simulation. Each module connects directly to research findings from Papers #1 & #2 (March 2026 collection) and integrates with existing curriculum structures.

**Design Philosophy:** Hands-on learning > passive lectures. Students learn by doing—making decisions, seeing consequences, receiving feedback in real-time.

---

## 🎯 Game Concept #1: "Hybrid Model Builder" (Primary Recommendation)

### Target Learning Objectives
- Understand hybrid physics-ML architecture principles
- Learn when to use physics baselines vs. residual correction
- Grasp driver behavior profile impacts (eco/normal/aggressive)
- Practice tuning model accuracy (target: <1% MAPE error)

### Gameplay Mechanics
**Type:** Interactive simulator + puzzle optimization challenge

**Core Loop:**
```
1. Receive trip scenario (route, elevation, traffic conditions)
2. Build prediction pipeline: choose physics parameters + configure NN residual learner
3. Run simulation with 3 different driver profiles (eco/normal/aggressive)
4. See actual energy consumption vs. predicted SoC trajectory
5. Analyze residuals → adjust NN inputs/hyperparameters
6. Re-run until achieving target accuracy (<1% MAPE)
7. Compete on leaderboard for fastest convergence
```

### Complexity & Time
- **Beginner Mode:** Pre-configured physics baseline, focus on residual learner training
  - Completion: ~15 minutes
- **Intermediate Mode:** Must select optimal vehicle parameters (mass, drag coefficient, etc.)
  - Completion: ~25 minutes
- **Advanced Mode:** Real-time online adaptation—model must update weights during operation as traffic/weather changes
  - Completion: ~40 minutes

### Platform
- **Primary:** Web app (Python + Streamlit or React + TensorFlow.js)
- **Classroom Projector:** Teacher demo mode showing class-wide progress
- **Mobile Companion:** Quick practice quizzes between sessions

### Integration Points
- **Curriculum Week:** Week 8-10 (Battery Management Systems module)
- **Prerequisites:** Basic calculus, introductory neural networks
- **Learning Outcomes Aligned With:** KLSTM/KAN paper discussions from Mar 21 collection
- **Lab Assignment:** Complete Beginner mode before coming to lab; use session time for Advanced mode debugging

---

### Step-by-Step Gameplay Flow

#### Phase 1: Setup (3 min)
- Select vehicle specifications (Tesla Model 3 / NIO ET7 / BYD Han — different aerodynamic profiles)
- Choose route: Mountain highway / Urban stop-and-go / Suburban arterial
- Set initial SoC (e.g., 80%)
- Pick weather condition (clear / rainy / extreme cold)

#### Phase 2: Physics Baseline Tuning (5 min)
Student configures:
- Rolling resistance coefficient C_r
- Drag coefficient C_d (user sees impact of adding side mirrors, lowering suspension)
- Regenerative braking efficiency η_regen
- Vehicle mass m (including payload passenger count)

**Visual Feedback:** Real-time plot showing physics-only prediction vs. historical ground truth data. Initial error typically 5-8% MAPE.

#### Phase 3: Residual Learner Training (7 min)
User trains simple feedforward NN:
- Input layer: Trip features (distance, avg velocity, traffic density, elevation change)
- Hidden layer: Configure neurons (3-8 options, see accuracy tradeoffs)
- Train ONLY on residuals ε = E_actual - E_physics

**Interactive Debugging:** Click on specific trip segments where large residuals occur; NN suggests likely causes ("high variance in speed suggests aggressive driver pattern")

#### Phase 4: Driver Behavior Profile Testing (10 min)
Simulation runs same route with 3 driver profiles:
- **Eco:** Gentle accel, early regen, cruise optimization
- **Normal:** Balanced approach
- **Aggressive:** Rapid accel, late braking, high aux load

Student observes: Aggressive driving can cause **up to 79% higher energy consumption**—visualized as diverging SoC trajectories.

#### Phase 5: Optimization Challenge (10+ min)
Randomly generated scenarios (daily changing):
- Scenario A: Steep mountain descent with heavy regenerative opportunities
- Scenario B: Highway tailwind reducing drag by 15%
- Scenario C: Urban congestion with frequent stops

**Scoring:** 
- Base score: Accuracy (MAPE inverted; 0.8% error = 100 points, 5% error = 60 points)
- Bonus: Speed of convergence (first 5 attempts get multiplier)
- Penalty: Oversimplified physics model (-10 points per omitted force term)
- Top 10 students displayed on classroom leaderboard

---

### Scoring & Ranking System

#### Individual Score Breakdown
| Metric | Weight | Description |
|--------|--------|-------------|
| **Accuracy Achievement** | 50% | How close final model is to ground truth |
| **Efficiency** | 25% | Number of training iterations needed |
| **Parameter Reasonableness** | 15% | Did you pick physically realistic values? (e.g., C_d shouldn't be 0.01) |
| **Cross-Profile Generalization** | 10% | Does your model work across all 3 driver profiles? |

#### Leaderboard Tiers
- **Novice Modeler:** 40-60 points average
- **Competent Practitioner:** 61-75 points
- **Expert Architect:** 76-89 points
- **Hybrid Master:** 90+ points (can achieve <0.9% MAPE consistently)

#### Classroom Gamification
- Weekly "Challenge Map": 5 randomized scenarios, class averages updated in real-time
- Badge system: "Drag Coefficient Detective", "Regen Recycling Champion", "Outlier Hunter"
- Team mode: 2-3 students collaborate—one handles physics, one handles NN, one validates

---

### Feedback Mechanisms

#### Real-Time Visual Feedback
1. **Energy Trajectory Plot:** Animated line chart showing predicted vs. actual SoC over distance
2. **Residual Heatmap:** Color-coded trip map highlighting where predictions fail most severely
3. **Driver Profile Comparison:** Split-screen view comparing eco vs. aggressive behaviors
4. **Parameter Sensitivity Slider:** Slide to see how ±10% parameter change affects accuracy

#### Post-Simulation Report Card
After each scenario completes:
```
✅ Scenario: Urban Arterial (Rainy Conditions)
⚠️ Final MAPE: 1.2% (Target: <1.0%)

🔧 Areas for Improvement:
  • Residual spikes near traffic lights → Add "stop frequency" as NN input feature
  • Over-predicted energy during downhill → Check grade resistance equation
  • Aggressive profile deviation too large → Retrain with more aggressive samples

💡 Pro Tip:
  Your C_d value (0.24) matches Tesla Model 3 specs! But in rain, effective drag increases due to water film. Consider weather-based correction factor.

📊 Performance vs. Class Average:
  • Accuracy: 15% above class mean
  • Training Speed: Slower than 60% of peers (try reducing hidden layers to 4)
```

#### AI Tutor Dialogues
Optional voice/chatbot assistant provides:
- Hints when stuck (>2 min on same step)
- Explanations of physical principles (e.g., "Aerodynamic drag scales with v², not v—watch your calculations!")
- Industry context links ("This exact methodology is used at BYD for their BMS calibration")

---

### Curriculum Integration

#### Module Sequence
```
Week 1-4: Foundations
  → Lecture: Battery fundamentals, SoC/SOH definitions
  → Lab: Manual energy calculation exercises
  
Week 5-7: Machine Learning Basics
  → Lecture: Neural network architectures, regression vs. classification
  → Lab: Simple linear regression on battery discharge data
  
Week 8: Hybrid Model Introduction ⭐
  → Lecture: Why pure ML fails; why physics alone insufficient
  → GAME: "Hybrid Model Builder" Beginner mode assigned as homework
  
Week 9-10: Advanced Applications
  → In-lab session: Students bring optimized models
  → Extension project: Integrate thermal management effects (future work direction)
```

#### Assessment Alignment
- **Quiz Questions:** After playing game, quiz covers key concepts
  - Example: "Why does combining physics baseline with NN residual reduce data requirements?"
- **Lab Reports:** Submit optimized model configs + interpretation of failure modes
- **Final Exam:** Case study problem similar to game scenarios but with novel conditions

---

## 🎯 Game Concept #2: "Traffic Flow Coordinator"

### Target Learning Objectives
- Understand CAV-bus lane coordination challenges
- Practice predictive flow modeling
- Balance bus priority vs. general traffic efficiency
- Experience multi-agent system complexity

### Gameplay Mechanics
**Type:** Real-time strategy simulation + optimization puzzle

**Premise:** You're the traffic control center manager for a mixed-traffic corridor with dedicated bus lanes. Simultaneously manage:
- CAVs requesting lane changes
- Bus schedule adherence (must maintain timetable)
- Human-driven vehicles (unpredictable, follow fixed routes)
- Traffic signal timing (optional integration)

### Complexity & Time
- **Beginner:** Static bus schedules, no weather disruption
  - Time: ~20 minutes
- **Intermediate:** Dynamic disruptions (accidents, construction, weather)
  - Time: ~35 minutes
- **Advanced:** Multi-corridor network with V2I communication constraints (packet loss, latency)
  - Time: ~50 minutes

### Key Mechanics
1. **Predictive Display:** See next 60 seconds of traffic flow projected forward
2. **Lane Change Requests:** CAVs send requests; approve/deny based on utility function
3. **Bus Protection Mode:** Automatically restrict CAV access within safety margin of bus arrival
4. **Utility Maximization:** Maximize total throughput while maintaining ≥95% bus on-time rate

### Scoring
- **+10 points** per successful CAV lane change that saves ≥5 seconds
- **-20 points** per bus delay >30 seconds
- **-5 points** per excessive lane change oscillation (penalize instability)
- **+25 bonus** for completing scenario with zero bus violations

---

## 🎯 Game Concept #3: "SOH Diagnostician"

### Target Learning Objectives
- Master battery state-of-health estimation techniques
- Interpret degradation patterns
- Identify common fault signatures
- Apply LLM-assisted diagnostic reasoning (BatteryAgent concept)

### Gameplay Mechanics
**Type:** Mystery diagnosis game + virtual multimeter interface

**Setup:** Virtual battery pack (100 kWh NMC pack) with hidden degradation mechanism:
- Option A: Uniform capacity fade (aging)
- Option B: Cell imbalance (manufacturing defect)
- Option C: Thermal runaway precursor (dangerous!)
- Option D: Charging protocol mismatch (user error)
- Option E: Mixed mechanisms (championship mode)

**Tools Available:**
- Cycle counter
- Impedance spectroscopy analyzer
- Infrared camera (thermal imaging)
- Voltage distribution map across cells
- Historical charge/discharge curves

**Gameplay:** Make measurements → form hypothesis → test intervention → see outcome

### Difficulty Levels
- **Apprentice:** Single degradation type, clear symptoms
- **Journeyman:** Two simultaneous issues, subtle correlations
- **Master:** Hidden fault requires creative diagnosis strategies

---

## 🎯 Game Concept #4: "Charging Station Optimizer"

### Target Learning Objectives
- Understand V2G coordination principles
- Optimize charging infrastructure utilization
- Manage grid load constraints
- Balance fleet profitability with user satisfaction

### Gameplay Mechanics
**Type:** Resource management simulator

**Scenario:** You run an EV charging depot with 20 chargers serving autonomous ride-sharing fleet. Constraints:
- Grid power cap: 500 kW (surcharge if exceeded)
- Electricity pricing: Dynamic (peak/off-peak rates vary hourly)
- User expectations: Vehicles must depart fully charged by pickup time
- Revenue model: $0.25/kWh charging fee + $2/min idle penalty avoidance

### Gameplay Loop
1. Morning briefing: See incoming reservation schedule, forecast weather (HVAC load impact)
2. Plan: Assign vehicles to chargers, set charging rates
3. Execute: Watch real-time deployment—vehicles arrive earlier/later than scheduled
4. Adapt: Respond to emergencies (vehicle breakdown, grid spike event)
5. Debrief: P&L statement showing profit vs. alternative strategies

---

## 🎯 Game Concept #5: "Fault Diagnosis Branching Tree"

### Target Learning Objectives
- Learn systematic troubleshooting methodology
- Recognize symptom-clue relationships
- Practice risk assessment (when to pull vehicle from service)
- Build mental model trees for common NEV failures

### Gameplay Mechanics
**Type:** Interactive branching narrative + probability puzzle

**Structure:** Decision tree with 50+ nodes representing diagnosis pathways. Players start with customer complaint:
- "My range dropped 30% overnight"
- "Charging stopped at 80% SOC"
- "BMS warning light flashing red"

At each node, choose diagnostic action:
- Ask customer clarifying questions
- Order specific measurement (voltage, temperature, impedance)
- Run software self-test
- Pull vehicle for inspection

Each choice branches differently based on hidden fault. Wrong path = wasted time/money. Optimal path minimizes total diagnosis cost while correctly identifying root cause.

**Championship Mode:** Randomized fault injection creates infinite replayability

---

## 🏆 Priority Recommendation: "Hybrid Model Builder"

### Rationale for Selection

**Strategic Fit:**
1. ✅ Directly maps to Paper #1's core innovation (physics + residual learning framework)
2. ✅ Reinforces curriculum priorities (SOH estimation, ML architectures)
3. ✅ Scalable difficulty serves multiple student levels
4. ✅ Generates measurable outcomes (MAPE scores) for assessment
5. ✅ Connects theoretical concepts to industry practice

**Pedagogical Strengths:**
- Active learning loop: Try → Fail → Adjust → Succeed
- Immediate visual feedback prevents misconception reinforcement
- Competition element motivates repeated practice (deliberate mastery)
- Bridges gap between abstract equations and practical implementation

**Resource Efficiency:**
- Can be built incrementally: MVP first, then advanced features
- Runs on standard web browsers (no specialized hardware)
- Teacher dashboard requires only basic Python/JS knowledge
- Existing codebase (streamlit example notebooks) can be repurposed

---

## 🛠️ Tech Stack Suggestions

### Minimum Viable Product (MVP)
**Timeline:** 2 weeks to deploy pilot version

| Component | Technology | Justification |
|-----------|------------|---------------|
| Frontend | Streamlit (Python) | Fastest prototyping, native pandas/matplotlib support |
| Physics Engine | Custom NumPy implementation | No external dependencies, transparent equations |
| ML Backend | scikit-learn MLPRegressor | Simple feedforward NN, easy to debug |
| Data Storage | SQLite local DB | Student scores, scenario configs |
| Deployment | Local classroom server (Raspberry Pi) or university cloud | Minimal bandwidth required |

**Estimated Development Effort:**
- Physics engine: 4 hours
- Streamlit UI: 6 hours
- NN training interface: 8 hours
- Scenario generator: 4 hours
- Total: ~22 hours (one person, two sprints)

### Enhanced Production Version
**Timeline:** 4-6 weeks for full feature set

| Component | Technology | Added Value |
|-----------|------------|-------------|
| Frontend | React + TypeScript | Better responsiveness, mobile optimization |
| Visualization | D3.js or Plotly | Interactive charts, tooltips, zoom/pan |
| ML Backend | PyTorch Lightning | More complex architectures (LSTM variants), GPU acceleration |
| Analytics | PostgreSQL + Metabase | Deep analytics, cohort analysis, A/B testing |
| Authentication | OAuth2 (university SSO) | Secure student accounts, progress tracking across semesters |
| Voice/TTS | ElevenLabs sag integration | Audio explanations, character voices for "AI tutor" |

### Advanced VR Simulation
**Timeline:** 3-4 months for Unity/Godot prototype

**Features:**
- Immersive 3D cockpit visualization of energy flows
- Hand-tracking controls to "build" model components
- Collaborative multiplayer mode (students work together remotely)
- AR mobile companion app for field trips to EV manufacturers

**Recommendation:** Pursue only after MVP proves pedagogical effectiveness

---

## 📈 Implementation Roadmap

### Phase 1: Discovery & Validation (Week 1-2)
- [ ] Create wireframes of "Hybrid Model Builder" workflow
- [ ] Survey 10 NEV students on current pain points understanding hybrid models
- [ ] Interview 2 instructors about existing curriculum gaps
- [ ] Draft rubric for measuring learning gains

### Phase 2: MVP Development (Week 3-6)
- [ ] Implement physics baseline calculator with 3 resistance terms
- [ ] Build residual learner training interface (simple NN GUI)
- [ ] Generate 20 randomized trip scenarios with ground truth labels
- [ ] Deploy classroom trial version

### Phase 3: Pilot Study (Week 7-10)
- [ ] Run with 2 course sections (~60 students total)
- [ ] Collect quantitative metrics (pre/post quiz scores, completion rates)
- [ ] Gather qualitative feedback via surveys and focus groups
- [ ] Iterate on UX/UI issues (likely: confusing terminology, unclear success criteria)

### Phase 4: Scale & Polish (Week 11-14)
- [ ] Add Advanced mode (online adaptation, weather variables)
- [ ] Integrate classroom leaderboard system
- [ ] Develop teacher dashboard for monitoring class progress
- [ ] Write accompanying lab manual and assessment bank

### Phase 5: Long-Term Maintenance (Ongoing)
- [ ] Quarterly scenario updates (fresh randomized problems)
- [ ] Annual review aligned with new research papers
- [ ] Expand to other NEV topics (Concept #2-5 implementations)
- [ ] Publish case study on gamified NEV education effectiveness

---

## 🔗 Cross-Reference with Research Papers

### Paper #1 Integration Points
| Game Element | Corresponding Paper Section |
|--------------|----------------------------|
| Vehicle dynamics model | Section 3.1: Force balance equations |
| Driver behavior profiles | Section 3.2: Eco/Normal/Aggressive parameters table |
| Residual learner training | Section 4: Neural network architecture diagram |
| Weather correction factors | Limitations subsection (future work direction) |
| Range anxiety reduction application | Section 5: Practical applications #1 |

### Paper #2 Integration Points
| Game Element | Corresponding Paper Section |
|--------------|----------------------------|
| Bus protection mechanism | Module 2 of control framework |
| Utility function for lane changes | Equation defining U_i |
| Mixed-traffic simulation | Methodology overview: SUMO platform section |
| Predictive flow estimation | Mathematical formulation: segment modeling |

---

## 📝 Assessment & Learning Verification

### Embedded Quizzes
After completing each game phase, pop-up questions verify comprehension:

**Example (post-physics-tuning):**
> *Question:* If you increase rolling resistance coefficient C_r by 0.02 (from 0.01 to 0.03), how much additional traction power is required at constant speed?
> 
> A) No change (rolling resistance negligible at highway speeds)  
> B) Linear increase proportional to vehicle mass × gravity × ΔC_r  
> C) Quadratic increase due to turbulence effects  
> D) Decrease (higher friction improves efficiency)
>
> **Correct Answer:** B  
> **Feedback:** Rolling resistance force F_r = C_r × m × g × cos(θ). Increasing C_r directly increases F_r, requiring proportional extra power to maintain velocity.

### Lab Report Requirements
Students submit structured report containing:
1. Initial MAPE achieved without residual learner (baseline performance)
2. Chosen NN architecture (number of layers, neurons per layer)
3. Most significant residual predictors identified (feature importance analysis)
4. Analysis of one "failure case" scenario where model performed poorly
5. Reflection: What did this exercise teach you about limitations of pure ML vs. physics approaches?

### Final Evaluation Rubric (100 points)
| Criterion | Excellent (90-100) | Good (75-89) | Needs Improvement (<75) |
|-----------|-------------------|--------------|------------------------|
| **Model Accuracy** | Achieves <0.9% MAPE across all 3 profiles | 0.9-1.5% MAPE | >1.5% MAPE |
| **Physical Understanding** | Correctly identifies all parameter sensitivities | Minor errors in parameter impact analysis | Fundamental misconceptions about forces |
| **Troubleshooting Process** | Systematically isolates residual sources | Trial-and-error approach, lucky fixes | Gives up when facing persistent errors |
| **Critical Reflection** | Articulates deep insights about hybrid methodology | Describes what worked without explaining why | Surface-level observations only |

---

## 💡 Additional Inspiration & Related Concepts

### Existing Educational Games to Study
1. **EVE Online (corporate simulation):** Complex resource management mechanics applicable to Charging Station Optimizer
2. **Kerbal Space Program:** Physics-first learning philosophy; students struggle → succeed → deeply internalize orbital mechanics
3. **Foldit (citizen science protein folding):** Gamifies scientific discovery; players optimize molecular structures without knowing underlying math
4. **Factorio (automation factory optimization):** Teaches system thinking through iterative improvement loops

### Adjacent Topics for Future Game Expansion
- **Thermal management simulator:** Coolant flow optimization, battery pack heat dissipation puzzles
- **Power electronics designer:** SiC inverter switching sequence arrangement (soldering mini-game?)
- **Autonomous driving perception fusion:** ADAS sensor selection puzzle (which sensors detect which obstacles in fog/rain?)
- **Battery swap station operator:** Logistics optimization matching vehicles to available swap slots
- **Range anxiety counselor (LLM roleplay):** Chat-based game practicing natural language explanations for passengers

---

## 📊 Expected Learning Outcomes

After completing the "Hybrid Model Builder" suite:

### Knowledge Domains
- Students can explain why hybrid physics-ML approaches outperform pure ML in EV contexts
- Students understand the four resistance force terms and their mathematical formulations
- Students can interpret residual patterns to diagnose specific failure modes (aggressive driving, weather effects, terrain mis-modeling)

### Skill Domains
- Ability to build and tune simple neural networks using scikit-learn/PyTorch
- Competence in configuring vehicle parameters from manufacturer specifications
- Proficiency in interpreting MAPE/RMSE metrics for model evaluation
- Experience with scenario-based stress testing (different driver profiles, conditions)

### Attitude Domains
- Appreciation for interpretability and physical consistency in engineering solutions
- Confidence in applying ML methods to domain-specific problems
- Curiosity about ongoing research directions (online adaptation, thermal coupling)

---

## ✍️ Appendix: Quick Start Code Snippet

For developers implementing MVP:

```python
import streamlit as st
import numpy as np
from sklearn.neural_network import MLPRegressor

# 1. Define physics baseline function
def physics_baseline(distance_km, avg_velocity_kmh, vehicle_params):
    """Calculate energy consumption using force balance equations"""
    g = 9.81
    m = vehicle_params['mass_kg']
    C_d = vehicle_params['drag_coefficient']
    A = vehicle_params['frontal_area_m2']
    C_r = vehicle_params['rolling_resistance']
    
    # Aerodynamic drag force: F_a = 0.5 * ρ * C_d * A * v²
    rho = 1.225  # air density kg/m³
    F_a = 0.5 * rho * C_d * A * (avg_velocity_kmh/3.6)**2
    
    # Rolling resistance: F_r = C_r * m * g
    F_r = C_r * m * g
    
    # Total tractive force (neglecting grade/inertia for simplicity)
    F_total = F_a + F_r
    
    # Energy = Force × Distance (convert km to m)
    energy_kWh = (F_total * distance_km * 1000) / (vehicle_params['drivetrain_efficiency'] * 3.6e6)
    
    return energy_kWh

# 2. Streamlit UI skeleton
st.title("🔋 Hybrid Model Builder")
st.sidebar.header("Vehicle Parameters")
m = st.sidebar.slider("Mass (kg)", 1200, 2500, 1800)
C_d = st.sidebar.slider("Drag Coefficient", 0.15, 0.40, 0.24, 0.01)

distance = st.number_input("Trip Distance (km)", 1.0, 200.0, 50.0)
velocity = st.number_input("Avg Velocity (km/h)", 20.0, 120.0, 60.0)

if st.button("Run Physics Simulation"):
    energy_pred = physics_baseline(distance, velocity, {'mass_kg': m, 'drag_coefficient': C_d})
    st.metric("Predicted Energy Consumption", f"{energy_pred:.2f} kWh")

# 3. Add residual learner training interface (separate page/tab)
```

---

**Document Status:** ✅ Complete  
**Next Actions:** Share with LessonPlanner team for curriculum alignment verification, begin Phase 1 discovery tasks  
**Version:** 1.0 (March 22, 2026)