Unity scribe

When Unity prefabs and ScriptableObjects are where your team already defines game content, duplicating those definitions in server YAML creates drift. Golem Scribe exports the server-facing parts of that content from Unity while the Go server remains authoritative. Entity components become schemas, ScriptableObjects become typed catalogs, and marked prefab colliders become collision footprints.

Export an entity schema

Declare the network shape on a MonoBehaviour, then add that component to one prefab:

using GolemEngine.Unity;
using UnityEngine;

[GolemEntity("Monster")]
public sealed class MonsterAuthoring : MonoBehaviour
{
    [GolemVar(1)] public int Health;
    [GolemVar(2, GolemSync.Once)] public string Kind;
}

Create one GolemPrefabRegistry asset, open Golem > Settings…, and set Project Root to the directory containing golem.yaml. Run Golem > Scribe > Export All. Scribe writes the entity YAML under the configured entity_schema directory, registers the prefab as Monster, and runs golem-bake when auto-bake is enabled.

The explicit entity name is stable protocol identity. It becomes the YAML entity name, the generated SyncedMonster suffix, and the prefab registry key. Each [GolemVar] tag is a user tag and must remain stable. Public fields and private [SerializeField] fields are supported.

Scribe accepts int, uint, long, ulong, float, double, bool, and string. Set Global or Persistent on [GolemEntity] when the corresponding entity-schema behavior is needed:

[GolemEntity("WorldClock", Global = true, Persistent = false)]
public sealed class WorldClockAuthoring : MonoBehaviour
{
    [GolemVar(1)] public long Tick;
}

Prefab field values do not become Go defaults. The fields declare schema names, types, tags, and sync modes only. Initialize spawned entities in Go, or keep reusable gameplay definitions in a Scribe catalog.

Author a ScriptableObject catalog

Use catalogs for shared definitions such as monsters, items, abilities, or building types:

using GolemEngine.Unity;
using UnityEngine;

[CreateAssetMenu(menuName = "Game/Monster Definition")]
[GolemCatalog("Id")]
public sealed class MonsterDefinition : ScriptableObject
{
    [GolemField(1)] public string Id;
    [GolemField(2)] public int Health;
    [GolemField(3)] public float MoveSpeed;
    [GolemAssetRef(4)] public GameObject Prefab;
}

Create normal MonsterDefinition assets in Unity. Scribe exports:

A custom type under the configured types_schema directory.
A catalog world schema under world_schema.
catalogs/monster_definition.golem.yaml, containing one row per asset.

Catalog tags are direct Protobuf field numbers. They do not use the entity-field offset. [GolemAssetRef] writes the referenced asset’s 32-character Unity GUID as an opaque string; it does not copy the Unity asset into the server.

After bake, load and store the catalog during server startup:

definitions, err := synced.LoadMonsterDefinitionData(
    "catalogs/monster_definition.golem.yaml",
)
if err != nil {
    log.Fatal(err)
}

srv.World.Set(definitions)

Stored catalog data is included in the initial world snapshot. If it changes while the server is running, store the replacement and call srv.PushWorldData("MonsterDefinition"). See World schemas for the world-data lifecycle.

Export collision footprints

Some prefabs matter to server collision without being replicated entities. A wall streamed independently by the client and server is a common example. Add one GolemFootprint component to the prefab root, choose the included Unity layers, and optionally set an alias such as stone_wall.

Scribe writes matching collider geometry to footprints.golem.yaml. Load it once, then place and remove the footprint alongside your world-streaming logic:

import "github.com/demiurgos-hub/golem-engine/golem/footprint"

footprints, err := footprint.Load("footprints.golem.yaml")
if err != nil {
    log.Fatal(err)
}

wall, ok := footprints.LookupAlias("stone_wall")
if !ok {
    log.Fatal("missing stone_wall footprint")
}

placer := &footprint.Placer2D{
    Backend: backend,
    Resolve: footprint.LayersResolver(layers),
}

handle, err := placer.Place(wall, footprint.Transform2D{
    X:               40,
    Y:               12,
    Scale:           1,
    RotationDegrees: 90,
})
if err != nil {
    log.Fatal(err)
}

// When the streaming region unloads:
handle.Remove()

layers is a configured CollisionLayers value whose names match the Unity layer names exported with each collider. The placer allocates negative collision-only IDs, so the wall does not enter the entity registry or consume replication bandwidth. Those negative IDs can still appear in contact callbacks.

For 3D geometry, use Placer3D and Transform3D. A 3D project supplies a LayerResolver that returns the layer and mask for each exported Unity layer name.

Supported geometry

Scribe exports enabled colliders on included layers, including colliders beneath inactive child GameObjects. Disabled collider components are skipped.

2D footprints support CircleCollider2D and BoxCollider2D.
3D footprints support SphereCollider and BoxCollider.
Boxes must remain axis-aligned after quarter-turn rotation.
Circles require uniform XY scale; spheres require uniform XYZ scale.
Runtime placement accepts positive uniform scale and exact quarter turns. In 3D, rotation is yaw around Unity’s Y axis.

Unsupported colliders or transforms on included layers fail that prefab’s export rather than producing incomplete geometry. Scribe exports collision footprints only; it does not export scenes or navigation data.

Generated artifact ownership

Scribe output is generated but committed. scribe.golem.yaml records which source owns each generated file, allowing deletion and rename cleanup without touching handwritten YAML.

Do not edit files carrying the Generated by Golem Scribe marker. Change the Unity source and export again. If a handwritten file already occupies a path Scribe needs, export fails instead of overwriting it.

Auto-export coalesces prefab, ScriptableObject, and script changes. Auto-bake runs only when entity, custom-type, or world-schema bytes change. Catalog data-only edits and footprint edits do not run golem-bake.

Validate locally and in CI

Use Golem > Scribe > Validate for a side-effect-free check. It reports missing, stale, orphaned, and manually changed generated files, along with invalid names, tags, GUIDs, aliases, registry entries, and footprint geometry.

Use Golem > Validate Setup when you also want the normal project-root, codegen, registry, and scene-helper checks.

For CI, run Unity in batch mode with the Scribe entry point:

Unity -batchmode \
  -projectPath Unity \
  -executeMethod GolemEngine.Unity.Editor.GolemScribeCI.ExportAllAndValidate \
  -logFile -

The command exits nonzero when sources or committed artifacts are invalid, or when Export All had to change generated files. An automatic repair during CI does not count as success; run Export All locally and commit the result.