golem-engine

README

Golem Engine lets you build server-authoritative multiplayer backends in Go, and generate type-safe clients for multiple languages and engines from one shared protocol. It's a full tick-based engine with physics, navigation, and interest management, designed to support worlds with high player and entity density.

Website · Documentation · Changelog

Features

• Authoritative by default. The server runs the simulation and owns state; per-session ownership lets a client drive its own entity.
• Schema-driven codegen. Define entities, commands, and events in YAML; generate server scaffolding, entities.proto, and typed clients with zero boilerplate.
• Multi-stack clients. One protocol shared across Go (Ebiten), JavaScript/TypeScript (Phaser), and C# (Unity).
• Built for density. A fixed tick loop and compact binary deltas keep hundreds of players and thousands of entities in sync.
• Interest management. Field-of-interest sends each player only what they are meant to see.
• Physics & navigation. Both sit behind interfaces with swappable backends, so you can trade speed for depth as your game grows.
• Batteries included. World snapshots, map/tile serving for 2D games, and other helpers that cut plumbing.
• Modern networking. WebSocket and WebTransport (HTTP/3) with reliable/ordered datagram delivery modes over UDP.

Repository layout

Path	Role
cmd/golem-bake/	Codegen CLI: runs golem-bake from a consumer project root.
schema/	golem.yaml plus entity, command, event, and world YAML loading and template data.
codegen/	Bake, embedded templates, and integration targets (go-server, go-client, js-client, phaser, ebiten, csharp-client, unity).
golem/	Runtime loop: Server, tick/delta hooks, world data, and networking.
golem/registry/	Thread-safe entity registry and the Entity interface.
golem/world/	Thread-safe store for static world data.
golem/collision/, golem/nav/	Physics and navigation, with swappable backends (nested Go modules).
golem-go-client/	Native Go client runtime.
golem-ebiten/	Ebiten client lifecycle and generated bridge helpers.
golem-js/	JS/TS runtime, published to npm as golem-engine.
golem-phaser/	Phaser 4 helper package built on golem-engine.
golem-unity/	Unity client package.

Note: golem/collision/ and golem/nav/ (and their backends) are nested Go modules resolved by a local go.work during development. Consumers building outside a workspace need published versions of these modules.

Quick start

Install the CLI

go install github.com/demiurgos-hub/golem-engine/cmd/golem-bake@latest

Describe your project

Add a golem.yaml at your project root:

entity_schema: schemas/entities/
command_schema: schemas/commands/
world_schema: schemas/world/
event_schema: schemas/events/
types_schema: schemas/types/

simulation:
  dimensions: 2

proto:
  package: game
  go_package: example.com/game/pb
  out: gen/pb

integrations:
  go-server:
    out: gen/server
    package: server
  js-client:
    out: web/src/gen

Define an entity (for example schemas/entities/player.yaml):

entity: Player
vars:
  health: { type: int32, tag: 1 }
  inventory: { type: list<Item>, tag: 2 }
  equipment: { type: dict<string, Item>, tag: 3 }

Entity, command, and event schemas may set an optional root tag to pin their field in the generated EntityUpdate, ClientMessage, or ServerEvent oneof. Declarations without it keep their legacy sequential assignment; use an explicit tag when adding a schema without renumbering an already shipped wire contract. Entity tags reserve a consecutive state/delta pair, and all explicit tags must be legal, non-overlapping protobuf field numbers.

Generate

Run the CLI from your project root:

golem-bake

This emits the entities.proto reference, server scaffolding, and typed clients for every integration you enabled. See Minimal server wiring for how to stand up the Server and tick loop.

Client packages

Stack	Package	Install
JavaScript / TypeScript	golem-engine	npm install golem-engine
Phaser 4	golem-phaser	npm install golem-phaser
Go / Ebiten	golem-ebiten	go get github.com/demiurgos-hub/golem-engine/golem-ebiten
Unity (C#)	io.demiurgos.golemengine	via Unity Package Manager

Generated client classes import these runtimes and share one binary protocol with the server.

Documentation

Full documentation lives at golemengine.dev/docs, including:

• Configuration & schema — golem.yaml, entity/command/world/event schemas, custom types & collections.
• Server & simulation — game loop, creation/destruction, authority, interest management, snapshots, profiling.
• Physics — backends & wiring, colliders, contacts & events, overlap/cast queries, 3D collision.
• Navigation — backends & wiring, map sources, NavAgent.
• Clients & networking — channels & transports, state updates, client commands, and per-stack integration guides.

Building & testing

# Root Go module
go test ./...

# JS runtime
cd golem-js && npm test

# Phaser package
cd golem-phaser && npm test

The nested modules under golem/collision/ and golem/nav/ are developed with a local go.work. Do not commit go.work or go.work.sum. The npm package dist/ directories are generated by npm run build and npm prepack; do not hand-edit or commit them.

Status

Golem Engine is at v0.3.0. Public APIs and generated output may still change between releases; see CHANGELOG.md for details.

Contributing

Contributions are welcome. Please keep changes scoped to the subsystem you are editing and follow the existing local patterns before introducing new abstractions. Run the relevant tests above before opening a pull request.

License

Licensed under the Apache License 2.0.

---

Golem Engine is developed and maintained by Demiurgos B.V.

Website · contact@demiurgos.io