CodeQuest

Learn by questing. CodeQuest is an open-source educational RPG: walk a village, talk to teachers, solve puzzles, and defeat a concept boss — all driven by JSON content packs on top of a reusable harness.

Built on RPGJS v5 (standalone).

Play the Japanese village demo

https://codequest.exams.live/ — live Go Basics quest on a Japanese-styled Gopher Village.

This public repo ships Pipoya starter maps so you can develop immediately. The hosted demo uses a separately licensed graphics pack that is not redistributed here. Screenshots below are from that live build.

Title	Placement quiz

How to play

Control	Action
Arrow keys	Move your character
Space or Enter	Talk / interact (when a prompt appears at the bottom of the screen)

What to do

1. Click New Quest on the title screen.
2. Answer the Elder’s placement quiz (sets easy / medium / hard — same answers always give the same quest).
3. Follow the Objectives list in the top-left corner.
4. Walk up to villagers who have a ! above their head — those are teachers or quest NPCs. Stand next to them until you see a bottom prompt like Space / Enter Talk — …, then press Space or Enter.
5. Complete each lesson puzzle in order, then enter the cave and defeat the boss.
6. Refresh the page and choose Continue to resume from your browser save.

Tip: if nothing happens when you press Space, you may not be close enough — keep walking until the interaction prompt appears.

Want that look (or any other art) in your own clone? See Use your own graphics pack.

Why CodeQuest?

Content packs, not forks	New topics are JSON + maps + a thin module — not a new game engine.
Deterministic	Same quiz answers → same difficulty → same puzzles and boss. No gameplay RNG.
Shared world	Settlements and routes live in one atlas; packs bind into districts.
Ready demos	Ship with Go Basics and Generative AI vs Agentic AI.
Bring your own art	Swap spritesheets and Tiled maps; keep licensed vendor zips local.

Quick start

npm install
npm run dev

Open http://localhost:5173. Controls match the How to play section above (arrows to move; Space/Enter to talk to ! NPCs).

1. Take the placement quiz (sets easy / medium / hard).
2. Explore Gopher Village, talk to the Elder, then complete lessons in order.
3. Enter Nil Cave and defeat NilPointer.
4. Refresh and choose Continue to restore your local save.

Second demo pack (AI)

npm run dev:agentic
# then open http://localhost:5173/?pack=agentic-vs-genai&newGame=1

Hub: Prompt Plaza. Boss: RunawayAgent in the Cave of Misuse.

How to pick a pack	Example
npm script	npm run dev:agentic
Environment	CODEQUEST_PACK=agentic-vs-genai and VITE_CODEQUEST_PACK=agentic-vs-genai
URL	?pack=agentic-vs-genai
Default	go-basics

Default art in this repo

Title → Placement quiz → Village lessons → Cave boss → Quest complete

Maps use the RPGJS starter Pipoya tilesets. Characters use the starter hero / female sheets plus OpenGameArt animal sprites (see docs/assets-licenses.md). To replace them with your own pack: docs/custom-graphics.md.

Architecture

packages/world/                 Shared atlas (settlements, routes, districts)
packages/content/
  schema.ts                     Zod pack + manifest schemas
  packs/<id>/pack.json          Pedagogy, copy, maps, weather
  packs/<id>/manifest.json      Event ids + coordinates
  templates/                    Skeleton pack + checklist

src/modules/codequest-core/     Reusable harness (HUD, puzzles, boss, weather)
src/modules/codequest-world/    Overworld route warps
src/modules/go-basics/          Go district on Gopher Hamlet
src/modules/agentic-vs-genai/   GenAI / agentic district
src/gui/                        Vue overlays
src/tiled/                      Tiled maps (Pipoya BaseChip)

Create your own topic

npm run topic:new -- python-basics
# edit pack.json + manifest.json, place events, register the module
npm run harness:check -- python-basics
node scripts/run-with-pack.mjs python-basics npm run dev

Guides:

• docs/create-a-game.md — step-by-step
• docs/custom-graphics.md — your own tiles / characters
• docs/pack-schema.md — schema reference
• packages/content/templates/checklist.md

Tooling

Command	Purpose
npm run harness:check -- <pack>	Schema, maps, manifest, world bind, no-RNG
npm run validate:pack -- <pack>	Zod-only pack validation
npm run maps:generate	Regenerate settlements + shared routes
npm run maps:audit	Walkability / event-anchor audit
npm test	Product contracts
npm run quality:check	Assets + maps + tests + harness + build
npm run smoke:demo	Playwright path (dev server must be running)

Reproducibility

Placement answers determine tier; tier selects authored puzzles and bosses. See docs/reproducibility.md.

License

• Code: MIT
• Art in this repo: Pipoya (via RPGJS starter) and OpenGameArt LPC fauna — see docs/assets-licenses.md
• Demo screenshots (docs/screenshots/): captured from the hosted Japanese village build at codequest.exams.live; the underlying licensed tilesets are not included in this repository
• Pedagogical source for agentic-vs-genai: IBM Think — Agentic AI vs generative AI

Contributing

Issues and PRs welcome. Keep packs deterministic (no Math.random in gameplay paths), document new art licenses under docs/assets-licenses.md, and run npm run quality:check before opening a PR.

Optional GitHub Actions: copy .github/workflow-examples/quality.yml to .github/workflows/quality.yml if you want CI on push/PR.