Authoring API

Namespace GodotECS.Authoring. Editor-side nodes that describe entities, the baker that converts them to EntityScene, and runtime spawning helpers. See Authoring workflow for the big picture.

Baker

public static class Baker
{
    public static EntityScene BakeSubtree(Node root);
    public static int BakeSubtreeInto(World world, Node root);
}

• BakeSubtree(Node root) — bakes the subtree into a throwaway World and returns EntityScene.FromWorld(tmp). Throws ArgumentNullException on null root. Cold path; allocations allowed.
• BakeSubtreeInto(World world, Node root) — bakes into an existing world (e.g. World.Preview), returns the number of entities created. Throws ArgumentNullException on null world or root.
• Traversal is pre-order (parent before children) so Parent references resolve. Only EcsAuthoring3D / EcsAuthoring2D nodes emit entities; other nodes are transparent containers. Dispatch is by is checks — no runtime reflection.

EcsAuthoring3D

public partial class EcsAuthoring3D : Node3D
{
    [Export] public Mesh Mesh;
    [Export] public Material MaterialOverride;
    [Export] public bool IsStatic;
    [Export] public float Radius = 0.5f;
    [Export] public int Health = 100;
    [Export] public int MaxHealth = 100;
    [Export] public Godot.Vector3 Velocity;
    [Export] public Godot.Color Tint = Colors.White;

    public EntityScene Baked { get; private set; }
    public Entity Bake(World world);
    public EntityScene BakeScene();
    internal static Entity BakeInto(World world, EcsAuthoring3D node, Entity parent);
}

• Bake(World world) — bakes this node (no children) into world as a root entity (parent = Entity.Null). Throws ArgumentNullException on null world.
• BakeScene() — bakes into a throwaway world, caches the result on Baked, returns it.
• BakeInto(World, EcsAuthoring3D, Entity) — core routine used by Baker: creates the entity and writes LocalTransform (from GlobalTransform; uniform scale = basis-scale average, 1 when non-positive; identity quaternion fallback), Velocity, Health (Max raised to Value if lower), PhysicsStaticTag + PhysicsRadius when IsStatic else PhysicsVelocity + PhysicsRadius (radius clamped to 0.5 when ≤ 0.01), PhysicsLayer.Default, shared RenderMeshRef { GroupId = 0 } (resolved later at sync), RenderColor, and Parent when parent is not null.

EcsAuthoring2D

public partial class EcsAuthoring2D : Node2D
{
    [Export] public Texture2D Texture;
    [Export] public Godot.Vector2 Size = new Godot.Vector2(16.0f, 16.0f);
    [Export] public Godot.Color Modulate = Colors.White;
    [Export] public int Health = 100;
    [Export] public Godot.Vector2 Velocity2D;

    public EntityScene Baked { get; private set; }
    public Entity Bake(World world);
    public EntityScene BakeScene();
    internal static Entity BakeInto(World world, EcsAuthoring2D node, Entity parent);
}

• Bake(World world) / BakeScene() / Baked — same contract as the 3D variant.
• BakeInto(World, EcsAuthoring2D, Entity) — writes LocalTransform (GlobalPosition → XZ-less Vector3(x, y, 0), Z-axis quaternion from GlobalRotation, averaged GlobalScale), Velocity (from Velocity2D), Health (Max = Value), shared SpriteRef { AtlasGroupId = 0 } (resolved later at sync), SpriteSize, RenderColor, and Parent when applicable.

EntitySceneInstance

public partial class EntitySceneInstance : Node
{
    [Export] public EntityScene Scene;
    [Export] public int Count = 1;
    [Export] public float SpawnRadius = 5.0f;
    [Export] public float StreamDistance = 100.0f;

    public Entity Spawn(World world, Godot.Vector3 pos);
    public Entity SpawnDefault(Godot.Vector3 pos);
    public Entity[] SpawnAll(World world, Godot.Vector3 origin);
}

• Spawn(World world, Vector3 pos) — instantiates Scene once at pos via Scene.Instantiate(world, pos). Returns Entity.Null for null world (throws ArgumentNullException), null scene, or empty Data.
• SpawnDefault(Vector3 pos) — Spawn(World.Default, pos).
• SpawnAll(World world, Vector3 origin) — instantiates Count copies (negative → 0). When the scene is missing/empty, or when StreamDistance > 0 and origin.Length() > StreamDistance, returns an all-Null array without spawning. Otherwise copy i is placed at origin plus ring offset (cos(a) * SpawnRadius, 0, sin(a) * SpawnRadius) with a = (i / n) * TAU (no offset when n == 1 or SpawnRadius <= 0).

StaticBake

public static class StaticBake
{
    public static StaticCollider[] BakeFromStatics(Node root);
}

Walks the subtree and returns world-space static colliders (GodotECS.Physics.StaticCollider { Kind, Center, HalfExtents, Radius, Height, Layer }). Returns an empty array for null root. Sources: CollisionShape3D under a StaticBody3D (BoxShape3D → Box, SphereShape3D → Sphere, CapsuleShape3D → Capsule; skips disabled shapes, shapes without a StaticBody3D ancestor, and shapes flagged with _baked_disabled meta; copies the body's CollisionLayer), GridMap used cells (one Box per cell, CellSize * 0.5 half extents, grid's layer), and TileMap layer-0 used cells (flat Box, TileSize * 0.5 × 0.5 depth scaled by TileMap scale, layer 1; skipped without a TileSet or layers).