Docs / moxzi.game / moxzi.game overview

moxzi.game overviewpreview

How a moxzi.game game is put together, what you write, and what the shared player does for you.

moxzi.game is a framework for games whose logic is written in Motoko. You write the game's rules as actors and describe its scenery, controls and sounds in YAML. A shared player, moxzi-player, runs the actors, draws the scene in 3D, plays sound and handles input, windows, touch and saving.

It's a developer preview. It runs on Apple Silicon Macs and arm64 iPhones. See Platforms.

What you write#

Part	Format	Contents
`game.yaml`	YAML	The project: id, title, entry file, simulation rate
`src/*.mo`	Motoko	The simulation. One actor is the entry point; it can create others
`assets/.model.yaml`, `.glb`	YAML, glTF	Shapes and meshes
`assets/*.material.yaml`	YAML	Colours and surface properties
`assets/controls.ui.yaml`	YAML	Buttons, keys, sliders and on-screen text
`assets/*.wav`	WAV	Sound effects
`assets/*.meta.yaml`	YAML	One per asset: its stable id and the name Motoko code uses for it

There's no Rust, C++ or engine code in a game.

How it runs#

The player owns the clock. It calls the entry actor at a fixed rate, set by simulation_hz in game.yaml:

player                                  your entry actor
  │  moxzi_boot(seed)          ───────▶   set up state, create other actors
  │  moxzi_snapshot()          ───────▶   return the whole scene
  │  moxzi_advance(tick)       ───────▶   step the game, return what moved
  │  moxzi_input(command)      ───────▶   a key, button or slider changed
  │  moxzi_lifecycle(suspend)  ───────▶   the app went to the background

The actor holds all game state. The player keeps a copy of the scene only to draw it, and smooths movement between ticks. Because the simulation is ordinary Motoko, it's deterministic: the same seed and the same inputs give the same game, and the whole state can be saved and restored.

Each game actor works like an Internet Computer actor: it processes one message at a time, and a trap rolls back that message. Actors can create other actors and call them with await. Pong's AI opponent is a separate actor.

Tools#

Tool	Does
`moxzi-game`	Checks, builds and validates projects, generates asset bindings, runs games without a window
`moxzi-player`	Plays a built game in a window, with saving and restoring
`moxzi`	The Motoko compiler. `moxzi-game build` uses it

Next steps#

Your first game: build and change the bundled Pong.
Writing a game: a small game from scratch, explaining each part of the actor.