golem.yaml

golem.yaml

golem.yaml is the project-level config file that golem-bake reads from your project root. It tells the tool where your schema files live, where to write generated output, and which integrations to produce.

A minimal config that generates a Go server integration, a JavaScript client, a native Go client, and a Unity/C# client:

entity_schema: schemas/entities/   # entity YAML files (default: "schemas/entities/")
command_schema: schemas/commands/  # command YAML files, optional (default: "schemas/commands/")
world_schema: schemas/world/       # world data YAML files, optional (default: "schemas/world/")
types_schema: schemas/types/       # custom type YAML files, optional (default: "schemas/types/")
event_schema: schemas/events/      # server event YAML files, optional (default: "schemas/events/")

simulation:
  dimensions: 2                    # 2 or 3; default: 2

proto:
  package: entities
  go_package: example.com/mygame/internal/entities
  out: gen/entities.proto

integrations:
  go-server:
    out: internal/synced/
    golem_import: golem-engine/golem
  js-client:
    out: client/src/synced/
    golem_import: golem-engine
  go-client:
    out: internal/client/
    package: client
  csharp-client:
    out: UnityProject/Assets/GolemGenerated/
    package: MyGame.GolemGenerated

Top-level keys

entity_schema — directory that golem-bake scans for entity YAML files. Defaults to schemas/entities/. At least one entity file must exist; an empty directory is a bake error.

command_schema — directory for command YAML files. Defaults to schemas/commands/. Optional: if the directory does not exist, bake skips command generation without error.

world_schema — directory for world data YAML files. Defaults to schemas/world/. Optional: if the directory does not exist, bake skips world generation without error.

types_schema — directory for custom type YAML files used in collection fields (list<T>, dict<K,V>). Defaults to schemas/types/. Optional: if the directory does not exist, bake proceeds without custom types. See Custom types & collections.

event_schema — directory for server event YAML files. Defaults to schemas/events/. Optional: if the directory does not exist, bake skips event generation without error. See Event schemas.

simulation block

Choose the position model before baking generated code. Most projects can omit this block and use the default 2D mode. Set dimensions: 3 when the server and clients should replicate height/depth as part of every entity position:

simulation:
  dimensions: 3

In 2D projects, generated entities expose PosX/PosY and SetPosition. In 3D projects, generated entities also replicate PosZ and expose Position3D / SetPosition3D on the Go server integration, plus posZ / PosZ on JS and C# clients.

Interest management uses the same circular XY field of interest in both modes. In a 3D project, FOI radius ignores height until 3D interest shapes are added. The pure-Go 3D collision backend is covered in 3D collision.

proto block

Controls the generated entities.proto reference file.

proto.package — the proto package name written into the .proto file (e.g. entities). This is not the Go package line in generated go-server .go files; that is controlled by package under integrations.go-server (see below).

proto.go_package — the option go_package value in the .proto file (e.g. example.com/mygame/internal/entities). This is the Go import path for the proto package used by the go-server integration.

proto.out — path (relative to project root) where entities.proto is written. The directory is created if it does not exist.

integrations block

Each key under integrations names an integration target: go-server, js-client, go-client, csharp-client, phaser, ebiten, or unity. Use the targets that match the runtimes in your game.

Common keys

out — output directory for generated files (relative to project root). Created if missing.

golem_import — where generated code imports the golem-engine runtime package.

• For go-server: the Go import path of a package that exports the golem API—golem.Server, golem.Entity, etc. Defaults to golem-engine/golem. You can point this at a thin re-export in your own module if needed, but a direct dependency on golem-engine/golem works without any wrapper.
• For js-client: the npm package specifier for GameClient, PbWriter, and PbReader. Defaults to golem-engine.
• For go-client: the Go import path for the native Go client runtime. Defaults to golem-engine/golem-go-client.
• For ebiten: the Go import path for Ebiten helpers. Defaults to golem-engine/golem-ebiten.
• For csharp-client and unity: the C# namespace that contains the Unity runtime types. Defaults to GolemEngine.Unity.

protocol_import — import prefix/path for bridge integrations that live outside the protocol client output. For phaser, use the JavaScript module prefix to the generated js-client files. For ebiten, use the Go import path to the generated go-client package.

go-server

package (optional) - the Go package name at the top of every file this integration emits (for example xxx_synced.go, entities_pb.go, world_pb.go when worlds exist, server.go, golem_helpers.go, and the command/router helpers). Defaults to synced. Use this when your module layout needs a different identifier than synced while keeping the same output directory. This key is unrelated to proto.package (protobuf namespace in entities.proto).

integrations:
  go-server:
    out: internal/generated/
    package: generated   # import as "example.com/mygame/internal/generated"

Emits Go files into the out directory:

• xxx_synced.go per entity type — the SyncedXxx struct, constructor, field getters/setters, and serialization logic.
• entity_manager.go — MarshalEntityRemoved (pass to srv.SetRemovalSerializer) and the internal EntityManager.
• command_router.go — NewCommandRouter and typed OnXxx handler registration. Present when at least one command schema exists.
• world_pb.go — world data structs and LoadXxxData helpers. Present when at least one world schema exists.
• events_pb.go — event structs with Marshal methods and the ServerEvent oneof wrapper. Present when at least one event schema exists.
• shared.go — EventBroadcaster and NewEventBroadcaster with typed BroadcastXxx methods. Present when at least one event schema exists.

js-client

Emits two files in the out directory after a bake-time TypeScript compile:

• client.js — createClient, EntityManager, WorldManager, EventManager, and buildXxxCommand helpers.
• client.d.ts — full TypeScript declarations for everything in client.js.

EventManager and its events_pb.js companion are only emitted when at least one event schema exists.

go-client

Emits native Go client files into the out directory:

• xxx_synced.go per entity type — client-side state holders with typed getters and revision-aware state/delta application.
• entity_manager.go — local entity registry, spawn/update/remove callbacks, compact datagram state handling, and command builders.
• client.go — CreateClient() wired to golem-go-client.
• entities_pb.go — generated protobuf encode/decode types for entities, commands, and ClientPacket.
• world_manager.go and world_pb.go when world schemas exist.
• event_manager.go and events_pb.go when event schemas exist.

Use package to set the generated Go package name:

integrations:
  go-client:
    out: internal/client/
    package: client

csharp-client

Emits C# files into the out directory:

• SyncedXxx.cs per entity type — client-side state with typed properties and revision-aware state/delta application.
• EntityManager.cs — local entity registry, spawn/update/remove callbacks, and command builders.
• EntitiesPb.cs — generated protobuf encode/decode types for entities, commands, and ClientPacket.
• Client.cs — ClientFactory.CreateClient() wired to the Unity runtime transport.
• WorldManager.cs and WorldPb.cs when world schemas exist.
• EventManager.cs and EventsPb.cs when event schemas exist.

Use package to set the generated C# namespace:

integrations:
  csharp-client:
    out: UnityProject/Assets/GolemGenerated/
    package: MyGame.GolemGenerated

unity

Emits optional Unity MonoBehaviour view scaffolds per entity type. Point it at a separate folder from csharp-client, but use the same package namespace so the views can reference generated synced entities:

integrations:
  unity:
    out: UnityProject/Assets/GolemViews/
    package: MyGame.GolemGenerated

ebiten

Emits optional Ebiten view scaffolds per entity type. Point it at a separate folder from go-client, and set protocol_import to the Go import path for the generated go-client package:

integrations:
  go-client:
    out: internal/client/
    package: client
  ebiten:
    out: internal/views/
    package: views
    protocol_import: example.com/mygame/internal/client

Paths

All paths (entity_schema, command_schema, world_schema, types_schema, proto.out, out) are relative to the directory where golem-bake is run (your project root). Absolute paths work but are unusual.

Running golem-bake

Run from your project root—there are no flags:

golem-bake

golem-bake fails with a descriptive error if:

• golem.yaml is missing or malformed.
• No entity schema files are found.
• A field uses an unknown type (not a proto scalar or known custom type).
• A list<T> or dict<K,V> field references a custom type that doesn’t exist in the configured types directory (default schemas/types/).
• Duplicate entity or world type names exist across files.
• An entity-targeted command references an entity_type that doesn’t match any entity schema.
• An entity-targeted event references an entity_type that doesn’t match any entity schema.
• An event declares foi_only: true without specifying entity_type.
• A world schema source references a map file that doesn’t exist.

Generated directories are fully reproducible from your schemas. Commit them to source control so CI doesn’t need to run golem-bake to build—but treat them as read-only. Changes are overwritten on the next bake.