Biwa is a TypeScript visual novel framework built around Ink, React and Bun. Its name is inspired by the Japanese biwa: an instrument traditionally tied to storytelling, performance and memory.
The project includes:
framework/: engine, React components, save/load, audio, minigames and docs.manager/: CLI commands fornew,dev,doctor,build,preview,assetsandlist.games/mi-novela/: richer demo game.games/smoke-fixture/: tiny fixture used by CI.
bun install
bun manager/cli.ts new my-novel "My Novel"
bun manager/cli.ts doctor my-novel
bun manager/cli.ts dev my-novelOpen the dev server URL printed by the CLI.
bun run check # tests + typecheck
bun run coverage # coverage report for framework + manager
bun run e2e # browser smoke against the built smoke fixture
bun manager/cli.ts doctor mi-novela
bun manager/cli.ts doctor mi-novela --json
bun manager/cli.ts assets character-atlas mi-novela kai
bun manager/cli.ts build mi-novela
bun manager/cli.ts build mi-novela --mode static
bun manager/cli.ts preview mi-novela --build
bun run verify # CI-style check against smoke-fixtureProduction builds are static ESM packages:
bun manager/cli.ts build mi-novela
bun manager/cli.ts preview mi-novelaOutput is written to dist/mi-novela/ with a post-build smoke check and manifest.json size report.
See framework/docs/distribution.md.
- First game guide
- GameEngine API
- Diagnostics
- Player features
- Aseprite atlas JSON
- Ink tag guide
- Project structure
- Customizing components
- Agent skills guide
- Distribution
- Packaging roadmap
| Area | Status |
|---|---|
| Ink story runtime | Stable baseline |
| Unified tag parser | Implemented |
| Data pipeline | Recursive indexes, doctor validation, build conversion |
| Save/load | Story, variables, visual scene, characters, audio, locale, thumbnails, playtime and delete |
| Player reading features | Backlog, auto/skip, settings, preferences and configurable input map |
| Audio | Extracted runtime manager, persisted master/bgm/ambience/sfx/voice volumes |
| UI customization | Typed app and stage component overrides |
| Distribution | Static ESM build with import map and smoke checks |
| Portal/embedded packaging | Planned |
| Browser E2E smoke | Implemented |
Before opening a PR, run:
bun run verifyThis executes tests, typecheck, doctor, a production build of the lightweight fixture and Playwright browser smoke.