Troubleshooting and FAQ

Troubleshooting & FAQ

Turn on warnings first

EntityDiagnostics.WarningHandler = m => Console.WriteLine($"[template] {m}");

A template property that matches no component member (typo, or a field instead of a property) is reported here instead of silently dropped.

Common errors

Symptom	Cause / fix
Component values stay default	The member is a field, or misspelled. Use a settable property; check the warning handler.
Unknown component type exception	The class lacks [Component], or its name/Name does not match the template key.
TemplateAlreadyExistsException	Two templates share a name (names are case-insensitive). Loading is additive.
AggregateException from folder load	One or more files failed; inner exceptions list each file. Repository is unchanged.
FailedToParseException: Cyclic template reference	$ref/$merge-ref chain loops.
InvalidCastException naming a script type	Call EntityScripting.Register() before spawning.
FormatException / OverflowException on spawn	Value does not fit the member type (e.g. 2.5 into int).
Parent's field disappeared in child	Inheritance replaces whole components; repeat every field you need.
Global component ignored on later spawn	Global components are first-write-wins.
Works in Editor, fails in IL2CPP build	Code stripping: see Unity Guide.

FAQ

Can I unload a template? No. Load into a fresh repository/factory and drop the old one.

YAML or JSON? Either; author in YAML, ship JSON if load time matters.

Is it thread-safe? Repository reads and script objects are; a ScriptHost is not. Iterators are single-threaded.

Where are the benchmarks? benchmarks/ and the README.

Something missing? Open an issue.