kagura

A 2D-first (with future 3D) game engine for MoonBit, inspired by Ebiten.

日本語

Playground · Play ASHEN REALMS — a low-poly action RPG with hunter, mage, archer and summoner builds.

Kagura Studio is a work in progress. Features and workflows are incomplete and may change.

• Contract-first architecture -- API contracts are defined before implementations, keeping the codebase modular and replaceable
• Ebiten-inspired design -- Fixed timestep updates, draw command batching, offscreen compositing, and backend abstraction
• Cross-platform -- Desktop via wgpu-native, browser via WebGPU
• Pure MoonBit -- No CGo, no FFI beyond the graphics backend boundary

moon.work
|-- core/                    Calculations: geometry, physics, terrain, input state
|-- platform/                Shared window/input/surface contracts
|-- platform_web/            Browser adapters and runtime_hooks/
|-- platform_native/         Native hooks, gfx_wgpu_native/, capture/
|-- engine/                  Rendering, assets, application/runtime, scene, HUD
|-- game/                    Rules, progression, ECS, inventory, input bindings
`-- editor/                  Authoring and inspection tools

JS builds (browser) work on any OS. Native builds support macOS and Linux. Windows native build uses a repo-side workaround for the upstream -lm issue, but runtime validation is still limited.

• MoonBit
• Node.js 24+
• pnpm
• just

pnpm install
just dev flappy_bird

Builds and serves at http://localhost:8080. Browser demos currently require WebGPU (Chrome 113+, Edge 113+).

Install the CLI from this checkout, then scaffold a standalone Web game:

moon install ./cmd/kagura
kagura new my-game --web
cd my-game
pnpm install
kagura dev
kagura build

kagura new --web uses the current empty directory. The template includes the browser runtime and Vite setup and depends on the published Kagura packages, without local path dependencies.

Starting with 0.6.0, the CLI shares the root mizchi/kagura module and release version. Install it with moon install mizchi/kagura/cmd/kagura@0.6.0.

For examples and Studio in this checkout:

pnpm kagura dev hacknslash_3d --port 8080
pnpm kagura build hacknslash_3d --out-dir output/game
pnpm kagura studio

Run just studio-install once before launching Studio. just kagura ... also works; inside a game directory the project argument can be omitted. Builds are self-contained static sites. See Kagura CLI for options.

kagura capture [url] --output game.png captures the game surface, and kagura profile [url] --out-dir output/profile writes frame statistics and a Chrome CPU profile. Both work with external Kagura projects; install @playwright/test in the calling project. See browser tool setup.

Run just studio-install once to install the Studio build dependencies. just pages builds release bundles, Studio, and relative assets into _site/. Pushing main publishes them to GitHub Pages through .github/workflows/deploy.yml. The repository's Pages source must be GitHub Actions.

After deployment, just pages-test https://mizchi.github.io/kagura/ checks the public gallery, Studio modeling, save selection and summoner gameplay with Playwright. It also accepts a locally served _site/ URL, including a project subdirectory.

Open kawaiko in Studio initializes the modeling workspace directly from a shareable URL.

bash scripts/setup-wgpu-native.sh

# Run with just (recommended -- sets CPATH/LIBRARY_PATH automatically)
just run-native flappy_bird

# Non-visual smoke test (window can appear black)
(cd examples/smoke/runtime_smoke_native && moon run src --target native)

# Visual sanity check
just run-native native_triangle

runtime_smoke_native is intended for internal verification. A black window is expected; success is runtime_smoke_native: ok (real).

Each example is an independent MoonBit module. Run with:

(cd examples/<name> && moon run src --target <js|native>)

• Getting Started
• Tutorials
• API Guide
• Reusable Game Components
• Rendering Performance and Profiling

• Contributing Guide
• Architecture
• Module Boundaries
• Roadmap

just fmt
just check target=js
just test target=js
just check target=native
just test target=native
just check-release
pnpm e2e:smoke

just version 0.6.0 --dry-run  # Preview affected modules and manifests
just version 0.6.0           # Update versions and regenerate Web runtime / CLI
just version 0.6.0 --check   # Fail if any manifest version/reference differs
just check-release
just publish-status         # Inspect packaged modules without uploading

The publication catalog in scripts/release-policy.mjs is shared with just publish. It includes the reusable libraries, platform runtime hooks and CLI. The updater changes their versions and internal dependency references in source manifests, examples, editors and Web scaffolding, preserving external dependencies and consumer project versions. Both moon.mod and moon.mod.json are supported. Use a stable X.Y.Z version; downgrades are rejected.

Version updates regenerate the browser distribution before embedding it in the CLI. If a build fails, fix the error and repeat the same command to finish regeneration. The updater does not commit, tag, push or publish. Review the diff and validation results before running just publish.

Publication stages every module outside the checkout, checks the staged workspace and verifies each archive has its manifest, MoonBit sources and prebuild support. Modules are published in dependency order; an upload failure stops the release. just publish-status performs the same packaging checks.

• mizchi/image -- Image codec (PNG/BMP/JPEG)
• mizchi/font -- Font rendering and shaping
• mizchi/layout -- Layout engine
• mizchi/audio -- Audio system
• mizchi/svg -- SVG rendering

Apache-2.0