feat: add template_of getter + bump to v0.3.0

Add composition.template_of(entity) -> string|nil, returning the
template-id this entity was created from. Returns nil for
non-composition-managed entities (e.g. raw entity.create() handles)
and loud-errors on nil arg. Enables crafting and inventory consumers
to recover the template-id without round-tripping through tags.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Axel Meyer
2026-06-14 11:57:29 +02:00
parent ccc4bb5643
commit b2a6d5c170
3 changed files with 51 additions and 5 deletions

View File

@@ -5,7 +5,7 @@ property defaults; `create` spawns an `engine.entity` with template
defaults + per-instance overrides; entities are indexed by template-id
and tag for cheap reverse-lookup.
**Version:** 0.2.0
**Version:** 0.3.0
**Lib-ID:** lib-core.composition
**Requires:** (none — uses engine `entity.*`, `domain.contribute` only)
**Tags:** composition, entity, template, tag-index
@@ -21,15 +21,16 @@ graph LR
```
<!-- topology:end -->
## Scope (v0.2.0)
## Scope (v0.3.0)
Template-Only-Subset + set_tag + container declaration.
Template-Only-Subset + set_tag + container declaration + template-id reverse-lookup.
**Supported:**
- `define_template{id, properties, tags}`
- `define_template{..., container={kind="list"}}` — v0.2: `kind="list"` accepted
- `create{template, properties}`
- `list_by_template(id)`, `list_by_tag(tag)`
- `template_of(entity)` — v0.3: read back the template-id an entity was created from
- `destroy(entity)`
- `set_tag(entity, tag, present)` — v0.2: runtime tag add/remove
- `get_container(entity)` — v0.2: read back the container block from entity's template
@@ -151,6 +152,28 @@ end
declared `tag` in its `tags` array. Used by `lib-core.render`
`draw_entities{tag="..."}` (see A.2). Empty list if tag has no entities.
### `composition.template_of(entity)`
**Syntax:** `composition.template_of(entity) -> string or nil`
**Example:**
```lua
local sign = composition.create{ template = "sign" }
local tpl_id = composition.template_of(sign)
-- tpl_id == "sign"
local raw = entity.create()
local none = composition.template_of(raw)
-- none == nil (raw entities are not composition-managed)
```
**Description:** Returns the template-id this entity was created from,
or `nil` if the entity is not composition-managed (e.g. a raw
`entity.create()` handle, or an entity whose composition meta-record
has already been cleared via `destroy`). Loud-Error if `entity` is `nil`.
Used by crafting / inventory / recipe code that needs to recover the
template-id without round-tripping through tags.
### `composition.set_tag(entity, tag, present)`
**Syntax:** `composition.set_tag(entity, tag: string, present: boolean) -> void`