RoguelikeToolkit.Entities 5.0.0

RoguelikeTools.Entities

This is a library to allow resolve entity templates for Entity Component System in a similar way Ultimate Adom is doing.

Supports entity template inheritance and creation of entity hierarchies.
It is using the awesome DefaultEcs library to construct the entities.

Features

• YAML and JSON support: Entity templates can be written in human-readable .yaml or .json formats.
• Inheritance: Templates can inherit from one or more base templates, mixing components and tags together.
• Embedded templates: Hierarchies are fully supported, you can embed child entities inside templates.
• Scripts: Components can carry JavaScript (Jint) scripts for data-driven behavior; parsed once, shared, AOT-safe.
• Dice parsing: The system seamlessly creates component variables from standard dice notations (2d6+3).

Quick Start

1. Define Templates

Create a file named templates.yaml in your project containing your entity definitions:

# A base template with generic components
EnemyBase:
  Tags:
    - AI
    - CanMove
  Components:
    Health:
      Max: 10
      Current: 10
    Speed:
      Value: 5

# A concrete template that inherits the EnemyBase
Goblin:
  Inherits:
    - EnemyBase
  Tags:
    - Goblin
  Components:
    Attack:
      Damage: "1d4" # This will automatically be parsed into a Dice object!
    Health:
      Max: 15 # Overrides the EnemyBase's Health Max value

2. Loading Templates & Creating Entities

Load these templates and generate DefaultEcs entities easily:

using DefaultEcs;
using RoguelikeToolkit.Entities.Repository;
using RoguelikeToolkit.Entities.Factory;

var world = new World();
var repository = new EntityTemplateRepository();

// Load the templates
repository.LoadTemplateFolder("path/to/my/templates");

// Initialize the factory
var factory = new EntityFactory(repository, world);

// Create the entity!
if (factory.TryCreate("Goblin", out Entity goblinEntity))
{
    // The goblinEntity now has:
    // - Health component (Max: 15, Current: 0) -- inheritance overrides whole components, not single fields
    // - Speed component (Value: 5)
    // - Attack component (Damage: 1d4)
    // - Tags: "AI", "CanMove", "Goblin"
}

Advanced Examples

Embedded Entities

You can embed child entities into another template. When EntityFactory creates an OrcRider, it also creates the embedded Wolf and automatically assigns it as a child using DefaultEcs.Entity.SetAsParentOf.

Wolf:
  Components:
    Speed:
      Value: 10

OrcRider:
  Components:
    Mount:
      Type: "Wolf"
  # Embeds the 'Wolf' template
  Wolf: {}

Querying Templates

repository.TryGetByName("Goblin", out var template); // O(1), case-insensitive

// Tag index: cost follows the matches, not the repository size.
// Requires ALL tags; an empty query returns every template.
var meleeEnemies = repository.GetByTags("AI", "CanMove");

Spawning at Scale

Inheritance is resolved once per template and cached, so spawning thousands of instances of the same blueprint stays flat:

for (var i = 0; i < 2000; i++)
{
    factory.TryCreate("Goblin", out var goblin);
}

Global components are first-write-wins: the first spawned entity sets the world's shared copy, later spawns link to it. Dice strings ("1d4") share one parse per distinct expression; scripts likewise share one parsed, immutable instance per distinct source.

Scripts

Script-typed component members (EntityScript, EntityComponentScript, EntityInteractionScript, Script, all in RoguelikeToolkit.Entities.Scripting) are populated from template strings:

Components:
  Behavior:
    OnHit: |
      var h = entity.GetComponent(Health);
      h.Current -= damage;
      entity.SetComponent(Health, h);
    Regen: component.Current += amount;

[Component]
public class Behavior
{
    public EntityScript? OnHit { get; set; }
    public EntityComponentScript? Regen { get; set; }
}

// one host per thread / simulation loop; it owns the (single) Jint engine
using var host = new ScriptHost(new ScriptHostOptions { ReferenceTypes = new[] { typeof(Health) } });

var behavior = goblin.Get<Behavior>();
behavior.OnHit!.ExecuteOn(host, ref goblin, ("damage", 4));
behavior.Regen!.TryExecuteOn<Health>(host, goblin, ("amount", 2)); // writes the component back via Entity.Set

• Scripts are immutable and hold no state: each distinct source is parsed once per process and the instance is shared by every entity spawned from the template. Keep state in components.
• Each execution runs in its own function scope (var/function do not leak between scripts, return exits early); bindings (entity, component, source/target, arguments) are cleared afterwards.
• entity.HasComponent/GetComponent/SetComponent/RemoveComponent(Type) take any type exposed via ScriptHostOptions.ReferenceTypes. Value-type components come back as copies: write them back with SetComponent.
• Limits: 500 statements and recursion depth 1024 per execution by default; Timeout and MemoryLimitBytes are opt-in.
• ScriptHost is not thread-safe (neither is a Jint engine); scripts are, and can run on any number of hosts.

Catching Template Typos

A template property that matches no component member (renamed property, field instead of property) warns instead of silently dropping. Hard failures (unknown component type, null value, cycles) throw with template + member context.

using RoguelikeToolkit.Entities;

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

Save / Load

Persist the template name plus dynamic state, then re-spawn and re-apply:

// save
Save("Goblin", entity.Get<Health>().Current, entity.Get<Position>());

// load
factory.TryCreate(savedTemplateName, out var entity);
entity.Set(new Health { Current = savedHp, Max = savedMax });

Modding / Hot-Reload

Loading is additive and folder loads are atomic — on any failure an AggregateException (one inner exception per file) is thrown and the repository is left unchanged:

await repository.LoadTemplateFolderAsync("Mods/Extra", cancellationToken);

There is no unload: hot-reload a mod by loading it into a fresh EntityTemplateRepository + EntityFactory pair and dropping the old one.

Template Format

Author in YAML (comments, readability), ship JSON or a packed single file for spawn-time loading — the same loader reads both (.yaml / .json, case-insensitive). Relative $ref / $merge-ref paths resolve against the referencing file's directory.

Unity / IL2CPP

The netstandard2.1 build has no Reflection.Emit on the load/spawn path, so it runs under IL2CPP. CI publishes a NativeAOT smoke test (stricter than IL2CPP: no JIT, no runtime generic instantiation) to keep it that way.

• Unity 2022.1+: works as is.

• Stricter AOT (NativeAOT, older IL2CPP): register each component type once at startup so its closed generic code exists: AotComponentRegistry.Register<Health>();

• Managed code stripping: component types (and the types of their nested struct/class members) are populated through reflection only. Keep them from being stripped with [Preserve] or a link.xml:

  <linker>
    <assembly fullname="MyGame.Components" preserve="all" />
  </linker>
  

• Scripts: Jint is a pure managed interpreter (no IL emission); arguments are marshalled without dynamic. Script interop reaches your component types by reflection, so they need the same stripping protection as above. Leave ScriptHostOptions.MemoryLimitBytes off on IL2CPP (it polls GC.GetAllocatedBytesForCurrentThread per statement). Jint is pinned to the version RoguelikeToolkit.World.Scripting.Jint uses: a Unity project can only hold one.

Docs

• Usage guide — querying, spawning, pooling, save/load, modding, examples.
• Architecture — internal creation and inheritance flow.
• Integration decisions — why each dependency / perf choice stands.

Benchmarks & Stress Tests

dotnet run --project benchmarks/RoguelikeToolkit.Entities.Benchmarks -c Release
dotnet test Library.sln

Benchmarks (BenchmarkDotNet, allocation + time) catch perf/allocation regressions; the test suite includes stress tests (mass spawn, mass load, concurrent reads). See benchmarks/README.md.

Baseline (Apple M2, macOS Tahoe 26.3.1, .NET 10.0.12, BenchmarkDotNet 0.15.8; spawn rows are per 100-entity batch, resolve rows per single cold resolve + 1 spawn):