Template Reference

Template Reference

A template file is a YAML or JSON mapping (.yaml / .json, extension case-insensitive). The template's name is the file name without its last extension (boss.final.yaml → boss.final) when loaded from a folder.

Top-level keys

Key	Meaning
Components	Map of component name → map of member values
Tags	List of string tags (queryable, inherited)
Inherits	List of template names to inherit from
any other key	An embedded child template (see below)

Tags: [enemy, melee]
Inherits: [base-fighter]
Components:
  Health:
    Max: 20
sword:                  # embedded child template named "sword"
  Components:
    Damage:
      Value: "1d6"

Inheritance

• A template can inherit from several templates; components and tags are merged.
• The inheriting template wins. Overriding a component replaces the whole component, not individual fields.
• Inheritance is resolved once per template and cached.
• Cycles throw with the template name in the message.

Embedded entities

Any key that is not Components, Tags or Inherits defines a child template. When the parent is spawned, children are spawned too and linked with Entity.SetAsParentOf. Use entity.GetChildrenWithTags("x") to find them.

Wolf:
  Components:
    Speed: { Value: 10 }

OrcRider:
  Components:
    Mount: { Type: "Wolf" }
  Wolf: {}     # embeds the Wolf template as a child

Splitting across files: $ref and $merge-ref

Paths are relative to the referencing file's directory.

# orc.yaml
Tags: [orc]
Rider:                       # an embedded child template...
  $ref: wolf.yaml            # ...that embeds wolf.yaml (as a child named after the file)
  $merge-ref: stats.yaml     # ...and merges stats.yaml's components/tags/inherits into "Rider"

$ref / $merge-ref can appear at the top level of a file or inside any embedded template.

• $ref – embeds the referenced file as a child template of the template it appears in.
• $merge-ref – merges the referenced file into the template it appears in; existing values are not overridden.
• Reference loops throw a FailedToParseException ("Cyclic template reference").
• Any other $-prefixed meta-property is an error.

Loading

repository.LoadTemplate("one-file.yaml");
repository.LoadTemplate("name", yamlString);
repository.LoadTemplateFolder("folder");
await repository.LoadTemplateFolderAsync("folder", ct);

• Loading is additive; duplicate names throw TemplateAlreadyExistsException.
• Folder loads are atomic: if any file fails, an AggregateException (one inner exception per file) is thrown and the repository is unchanged.

YAML vs JSON

Author in YAML (comments, readability); ship JSON or a packed file for faster loading. The same loader reads both.