LessonPlay

Give it a chemistry chapter. Get a playable lab.

LessonPlay is an AI-assisted chemistry-game studio for teachers and educational creators. Hand it a chapter, a textbook activity, or a single concept, and it plans an interactive lab that teaches it — then builds and publishes that lab from the same conversation.

Every game is one of two lab surfaces, and neither is a quiz:

• ExperimentLab — a discovery bench. The learner applies tools to unknown samples, watches what happens, records readings, and reasons out which category each sample belongs to. Concept names stay hidden until after a correct call, so the discovery comes before the vocabulary.
• ChemQuest Lab — a guided investigation. A staged lab procedure where each step is a real choice of material and tool, ending in an evidence-backed conclusion.

Games are only published if the engine can prove they are winnable — a game the validator cannot solve is refused, not shipped.

The product application lives in my-app/. Its README covers product capabilities, architecture, setup, limitations, and the portfolio launch plan.

Repository layout

my-app/       LessonPlay Next.js product
packages/     Shared Learn Loop engine and lab UI
games/        Minimal chemistry-lab reference template
.agents/      Chemistry game-design and implementation skills

Run LessonPlay

cd my-app
cp .env.example .env
pnpm install
pnpm db:migrate
pnpm dev

See my-app/.env.example for required services and placeholders.

Verify

Shared engine and chemistry starter:

npm install
npm test
npm run typecheck
npm run build

Product application:

cd my-app
pnpm install
pnpm test
pnpm build

How a game gets made

The agent runs one sequential job: plan the lab, then build it from that plan.

1. Plan. From a chapter or concept, it picks a single atomic idea and decides which lab surface fits — a discovery bench or a guided investigation — then stops for your approval.
2. Build. It authors the game as data, not hand-written UI: an ExperimentDefinition of samples, tools, and rules, or a set of ChemQuest missions. The shared viewport renders it.
3. Gate. Publication runs the matching validator, which solves the game to prove it is winnable and rejects anything railed, brute-forceable, or leaking the answer in its own observation text.

Skills under .agents/skills/ define the pedagogy and the authoring contracts. The planner deliberately never names engine ids, so a plan cannot over-promise a capability the engine lacks — an over-ambitious plan simply fails the build-time gate.

The only checked-in game folder is games/chemistry-lab-bench/, a minimal consumer of @learn-loop/core. Generated games are published artifacts rather than repository source.

Status

LessonPlay is an actively developed project, released publicly as a portfolio and research project. There is no hosted public instance yet — run it locally with the steps above. Expect the agent pipeline and game archetypes to keep moving.

Contributing

Contributions are welcome. CONTRIBUTING.md covers setup, the checks to run, and the conventions this repository follows — in particular that generated games are not committed, and that runtime skills must stay byte-identical across their three locations. Participation is governed by our Code of Conduct.

For security issues, follow SECURITY.md rather than opening a public issue.

License

Licensed under the Apache License 2.0.

The product application began from Vercel's Apache-2.0-licensed v0 clone example. Earlier revisions also carried one-button game-design skills and a GA balance harness adapted from abagames/claude-one-button-game-creation, removed when the product narrowed to chemistry. See NOTICE for full attribution.