2D-first game engine for MoonBit inspired by Ebiten

game-engine

wgpu

webgl

moonbit

moon add mizchi/kagura@0.4.0

Download zip

Author

mizchi

Version

0.4.0

License

Apache-2.0

Repository

github.com/mizchi/kagura

Last updated

2 months ago

Downloads

Dependencies

README

#kagura

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

日本語

#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
|-- mizchi/kagura             Thin public facade over core/engine contracts
|-- mizchi/kagura_core        Core contracts, math, camera, mesh, input utilities
|-- mizchi/kagura_engine      Rendering/runtime infrastructure
|   |-- platform/, gfx/        Platform, graphics, native/web backends
|   |-- runtime/, asset/       Runtime loop, assets, audio, text, UI
|   `-- gltf/, renderer*/      glTF loading and 2D/3D renderer facades
|-- mizchi/kagura_physics     Reusable physics, collision, and pathfinding
|-- mizchi/kagura_game        Gameplay-oriented packages
|   |-- scene/                 Declarative 2D Scene API
|   `-- ai/, ecs/, tilemap2d/  Game systems and helpers
`-- mizchi/kagura_js_runtime  JS-only WebGPU runtime helpers

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

#Native

bash scripts/setup-wgpu-native.sh

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

# 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
action_rpg	Action RPG prototype
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

#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

#
EngineTermination

source

using @mizchi/kagura_core { type EngineTermination }

#
FixedStepConfig

source

using @mizchi/kagura_core { type FixedStepConfig }

Fixed-step simulation contract. Ebiten refs:

internal/clock/clock.go
internal/ui/context.go (updateFrameImpl / update count handling)

#
FixedStepState

source

using @mizchi/kagura_core { type FixedStepState }

Scheduler state carried between frames. Ebiten refs:

internal/ui/context.go (tick progression and frame accumulator semantics)

#
RenderPassDesc

source

using @mizchi/gfx { type RenderPassDesc }

What GraphicsDriver.begin does before any draw calls of a pass.

clear_enabled=false keeps the previous framebuffer contents (useful for additive overlays). present=true swaps buffers at end; set false for offscreen render-to-texture passes.

#
RunOptions

source

using @mizchi/kagura_core { type RunOptions }

#
StepResult

source

using @mizchi/kagura_core { type StepResult }

Planned updates for one rendered frame. Ebiten refs:

run.go (Update / Draw separation)
internal/ui/context.go (skip / interpolation flow)

#
WindowOptions

source

using @mizchi/kagura_engine/platform { type WindowOptions }

#
default_fixed_step_config

source

fn default_fixed_step_config() -> @mizchi/kagura_core.FixedStepConfig
FixedStepConfig

#
initial_fixed_step_state

source

fn initial_fixed_step_state() -> @mizchi/kagura_core.FixedStepState
FixedStepState

#
new_fixed_step_config

source

fn new_fixed_step_config(tps : Int, max_updates_per_frame : Int) -> @mizchi/kagura_core.FixedStepConfig
FixedStepConfig

#
plan_fixed_updates

source

fn plan_fixed_updates(state : @mizchi/kagura_core.FixedStepState
FixedStepState, elapsed_ms : Double, config : @mizchi/kagura_core.FixedStepConfig
FixedStepConfig) -> @mizchi/kagura_core.StepResult
StepResult

#
run_loop

source

fn[G : @mizchi/kagura_core.Game
Game, P : @mizchi/kagura_engine/platform.PlatformDriver
PlatformDriver, R : @mizchi/gfx.GraphicsDriver
GraphicsDriver] run_loop(game : G, platform : P, graphics : R, options : @mizchi/kagura_core.RunOptions
RunOptions) -> Unit raise

#
step_result_alpha

source

fn step_result_alpha(result : @mizchi/kagura_core.StepResult
StepResult) -> Double

#
step_result_next_state

source

fn step_result_next_state(result : @mizchi/kagura_core.StepResult
StepResult) -> @mizchi/kagura_core.FixedStepState
FixedStepState

#
step_result_updates

source

fn step_result_updates(result : @mizchi/kagura_core.StepResult
StepResult) -> Int

Source Files

lib.mbt

Site source Report issue Packages Build queue Skills Statistics

kagura

#kagura

#Features

#Architecture

#Platform Support

#Quick Start

#Prerequisites

#Run in Browser

#Native

#Examples

#Documentation

#For Users

#For Contributors

#Verification

#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