ember-edu 0.2.0

Lightweight educational simulation library for AI-generated visual lessons

ember

ember is a small educational simulation library.

The main goal is simple: an AI or teacher should be able to make a clear visual simulation without writing hundreds of lines. The code should focus on the idea, not on drawing everything manually.

It is useful for:

• explaining science and maths concepts
• making small interactive lessons
• generating GIF/PNG style visual explanations
• testing how LLMs can create better teaching simulations

This is not a game engine in the big sense and it is not a console emulator. It is a lightweight sandbox for educational visuals.

What Is Inside

• A C11 core library in src/ and include/
• Python bindings in python/ember/
• A high-level education API in python/ember/edu.py
• Example simulations in examples/ and games/
• Plain text mission files in missions/
• Documentation in docs/

The most important API for AI-generated lessons is ember.edu.

Example Gallery

These previews are regenerated into docs/gallery/ so changes in the visual library are visible in the README. The small examples show the target style: AI writes one clear mechanism in roughly 40-50 lines instead of making a large custom app.

Regenerate the gallery after visual/library changes:

make gallery

Concept	Source	Render
Fajan's rule	examples/fajan_sim_test.py - 47 lines
Faraday's law	examples/faraday_sim_test.py - 62 lines
Hybridisation	examples/hybridisation_sim.py - 64 lines
Heart function	games/heart_sim.py - richer demo
Transformer attention	games/transformer_sim.py - richer demo

Run Examples

From the repo root:

PYTHONPATH=python python3 examples/hybridisation_sim.py
PYTHONPATH=python python3 games/heart_sim.py
PYTHONPATH=python python3 games/transformer_sim.py

Many examples also add the local python/ path themselves, so they can be run directly with python3.

Build And Test

make all
make test
make python-test

Run the default C mission:

make run

This writes frames into build/.

For AI Agents

Before generating a simulation, read the prompt contract:

import ember
print(ember.prompt)

The same guide is available here:

docs/AI_SIMULATION_GUIDE.md

Important rules for AI-generated simulations:

• Ask what exact mechanism the user wants to understand.
• Websearch for factual topics unless the user provides source material.
• Show one clear cause and effect.
• Prefer concrete scenes over abstract variable animation.
• Keep the code small.
• Use only existing public APIs.
• Do not edit the library unless the user asks for library work.

For most visual lessons, use Lesson plus Sketch:

from ember.edu import Lesson, Sketch

def draw(canvas, state):
    canvas.text("main idea", 0, -0.8)

lesson = Lesson("My Lesson", theme="neon")
lesson.show_hud = False
lesson.state.params["_time"] = 0.0
lesson.rate("_time", lambda s: 1.0)
lesson.show(Sketch(draw, "one-line visual legend"))
lesson.explain("One sentence takeaway.")
lesson.run()

Useful Docs

• docs/AI_SIMULATION_GUIDE.md: system prompt for AI agents
• docs/EDU_LIBRARY.md: high-level education API
• docs/GRAPHICS_API.md: lower-level graphics helpers
• docs/PYTHON_BINDINGS.md: Python API
• docs/MISSION_FORMAT.md: text mission format
• docs/CAR_PHYSICS.md: car physics lesson

Project Layout

include/          C public headers
src/              C implementation
python/ember/     Python package
examples/         small concept examples
games/            richer interactive lessons
missions/         text mission files
docs/             documentation
tests/            C and Python tests

Notes

The project is still evolving. The important direction is to make the library more general and easier for smaller models also. If a generated sim needs too much drawing code, that is a sign the library needs a better primitive.