🎓 Lesson Engine

AI-generated educational physics lessons powered by Chaos Engine.

What is this?

Lesson Engine is an orchestration layer that:

1. Loads Chaos Engine (a Matter.js physics sandbox) in an iframe
2. Generates lesson configs using OpenAI (GPT-4o-mini)
3. Feeds structured JSON to drive physics-based learning activities
4. Tracks goals and provides feedback

The Vision

Instead of boring worksheets, kids learn math and science through physics simulations:

• "Stack 7 blocks to build a tower" → teaches counting + physics stability
• "Drop rocks on the Moon" → demonstrates gravity differences
• "Help the dinosaur escape!" → adds story context to make it engaging

Quick Start

# Clone the repo
git clone https://github.com/kbo4sho/lesson-engine.git
cd lesson-engine

# Start the server (port 3007)
npm start

# Open http://localhost:3007

Generate a Lesson with AI

# Requires OPENAI_API_KEY in environment
npm run generate

This creates a new lesson JSON in lessons/generated/.

Project Structure

lesson-engine/
├── index.html          # Lesson player UI
├── server.js           # Node server with API endpoints
├── src/
│   ├── generator.js    # OpenAI lesson generation
│   ├── lesson-schema.js # JSON schema validation
│   ├── scorer.js       # Goal tracking
│   └── player.js       # Lesson playback management
├── lessons/
│   ├── examples/       # Hand-crafted example lessons
│   └── generated/      # AI-generated lessons
└── tests/              # Test suite (39 tests)

API Endpoints

Endpoint	Method	Description
/api/lessons	GET	List example lessons
/api/lessons/:id	GET	Get a specific lesson
/api/generate	POST	Generate a new AI lesson
/api/validate	POST	Validate a lesson config

Lesson Schema

Lessons are JSON configs that define:

• Simulation setup: gravity, spawned objects, fixtures
• Goals: count-placed, height-reached, collision-count, etc.
• Narrative: intro, hints, success/failure messages
• Math question: optional follow-up challenge

Example:

{
  "id": "dino-tower",
  "title": "T-Rex Tower Builder",
  "grade": 2,
  "theme": "dinosaurs",
  "narrative": {
    "intro": "Stack blocks to help the T-Rex!",
    "success": "You did it! 🦕"
  },
  "simulation": {
    "gravity": "earth",
    "spawnObjects": [{ "type": "block", "count": 10 }],
    "goals": [{ "type": "height-reached", "y": 150 }]
  },
  "math": {
    "question": "Each block is 40cm. 7 blocks = ?",
    "answer": 280
  }
}

Target User

MVP is built for Leo (7yo, Grade 2):

• Interests: dinosaurs, space, cars, robots, Minecraft
• Lessons are themed around these interests
• Goals are K-2 appropriate (counting, simple math)

Tech Stack

• Plain HTML/JS/CSS – no frameworks
• Node.js – simple HTTP server
• OpenAI API – GPT-4o-mini for lesson generation
• Chaos Engine – Matter.js physics sandbox (via iframe)

Running Tests

npm test

39 tests covering schema validation, example lessons, and scoring logic.

Credits

Part of the Atlas Learn ecosystem – homeschool curriculum tracking meets interactive learning.

---

Built with ❤️ by Clawd