2D-first game engine for MoonBit inspired by Ebiten

game-engine

wgpu

webgl

moonbit

Download zip

Author

mizchi

Version

0.6.0

License

Apache-2.0

Repository

github.com/mizchi/kagura

Last updated

15 days ago

Downloads

Dependencies

#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.

#Features

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

#Architecture

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

#Platform Support

Target	Backend	Status
Web (all OS)	WebGPU	Supported
Native macOS	wgpu-native + Metal + GLFW	Supported
Native Linux	wgpu-native + Vulkan + GLFW	Supported (CI: check + test + build)
Native Windows	wgpu-native + D3D12/Vulkan + GLFW	Partial (CI: check + build workaround; runtime validation pending)
WASM Guest	Shared-memory binary protocol	Supported (MoonBit / Rust / Zig)

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.

#Quick Start

#Prerequisites

MoonBit
Node.js 24+
pnpm
just

#Run in Browser

pnpm install
just dev flappy_bird

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

#Development CLI

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.

#Publish the playground

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.

#Native

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).

#Examples

Example	Description
runtime_smoke	Minimal JS smoke test
runtime_smoke_native	Minimal native smoke test (non-visual)
native_triangle	Native backend triangle demo
flappy_bird	2D game loop with input handling
survivor	Multi-entity game with weapons/UI
arena3d	3D arena prototype (experimental)

Each example is an independent MoonBit module. Run with:

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

#Documentation

#For Users

#For Contributors

#Verification

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

#Updating release versions

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.

#Dependencies

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

#License

Apache-2.0

kagura

#kagura

#Features

#Architecture

#Platform Support

#Quick Start

#Prerequisites

#Run in Browser

#Development CLI

#Publish the playground

#Native

#Examples

#Documentation

#For Users

#For Contributors

#Verification

#Updating release versions

#Dependencies

#License

#EngineTermination

#FixedStepConfig

#FixedStepState

#RenderPassDesc

#RunOptions

#StepResult

#WindowOptions

#default_fixed_step_config

#initial_fixed_step_state

#new_fixed_step_config

#plan_fixed_updates

#run_loop

#step_result_alpha

#step_result_next_state

#step_result_updates

Source Files

EngineTermination

FixedStepConfig

FixedStepState

RenderPassDesc

RunOptions

StepResult

WindowOptions

default_fixed_step_config

initial_fixed_step_state

new_fixed_step_config

plan_fixed_updates

run_loop

step_result_alpha

step_result_next_state

step_result_updates