Components

Components

Declaring

[Component]                       // name = "Position"
public struct Position { public int X { get; set; } public int Y { get; set; } }

[Component(Name = "hp")]          // template key: hp
public class Health { public int Max { get; set; } public int Current { get; set; } }

Rules:

• Members are populated through settable properties (any visibility). Fields are not populated and are reported through EntityDiagnostics.
• Names match case-insensitively.
• Unknown component types throw with template + member context.

Global components

[Component(IsGlobal = true)] shares one instance per World (stored as DefaultEcs single-component). It is first write wins: the first spawn sets it, later spawns link to it and a warning is raised if their values differ.

Single-value components

Implement IValueComponent<T> when a component is just a primitive or string.

Value conversion

Scalars in templates convert to the member type in this order:

1. already assignable
2. a registered parser for the member type
3. enums (case-insensitive name or number)
4. primitives, string, decimal (invariant culture)
5. Guid, TimeSpan, DateTime, DateTimeOffset, Uri, Version from strings

Out-of-range numbers throw OverflowException; 2.5 into an int throws FormatException (2.0 is fine).

Custom parsers

TemplateValueParsers.Register(static s => Color.FromHex(s));   // thread-safe

Parsers run on every spawn, so cache inside the parser when the result is immutable.

Dice

Dice members are parsed from strings ("2d6+3", "4d6k3", "d%").

var d = Dice.Parse("2d6+3");
d.Roll();                    // thread-local random
d.Roll(new Random(seed));    // reproducible
Dice.TryParse(text, out d);  // no exceptions

See the README for the full syntax table.

Unity / AOT note

On older IL2CPP and NativeAOT, register each component type once at startup: AotComponentRegistry.Register<Health>();. See the Unity Guide.