sporel/sporel-lib-core.composition
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial: composition v0.1.0 — template + tag-index + instantiation

Browse Source 
Phase-A.1 implementation per
sporel-meta/docs/superpowers/specs/2026-06-09-phase-A-...
Template-Only-Subset; slots/container/quality/condition produce
loud-errors with explicit re-entry-phase hints. Position-Format
revised to two flat scalar properties (position.x, position.y) per
engine reality: no PROPERTY_TABLE exists.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Axel Meyer
2026-06-09 13:28:52 +00:00
commit b6a16df6f0
4 changed files with 538 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

349
init.lua Normal file
View File

@@ -0,0 +1,349 @@
-- =====================================================================
-- lib-core.composition v0.1.0 — Template + Instantiation + Tag-Index
-- See: meta/docs/superpowers/specs/2026-06-09-phase-A-inactive-entities-...
--
-- v0.1.0 Template-Only-Subset:
-- - composition.define_template{id, properties, tags} — registers a
-- template; auto-declares all properties as inert via
-- domain.contribute. Nested tables (e.g. position = {x, y}) are
-- flattened to dotted keys (position.x, position.y).
-- - composition.create{template, properties} — instantiates an
-- engine.entity, applies template-defaults + per-instance overrides
-- via set_property. Registers entity in template-index + tag-index.
-- - composition.list_by_template(id) -> {entity, ...}
-- - composition.list_by_tag(tag) -> {entity, ...}
-- - composition.destroy(entity) — removes from indices + destroys
-- engine.entity.
--
-- DEFERRED (loud-error if attempted in v0.1):
-- - slots → Phase D Trigger (Composite Items with Sub-Items)
-- - container → Phase B Trigger (Items + Inventory)
-- - quality → Phase J Trigger (Damage / Wear)
-- - condition → Phase J Trigger (Damage / Wear)
-- - parent: → Template-Inheritance, no consumer yet
-- - composite-property values (e.g. position = {x, y} as single
-- property) — engine PROPERTY_TABLE doesn't exist; nested-tables
-- are auto-flattened to dotted scalar keys.
-- =====================================================================
local M = {}
-- ---------- internal state ----------
-- template_id (string) → template-record:
-- { id, properties_flat (key → default-value), tags (set) }
local templates = {}
-- template_id (string) → list of engine.entity handles
local index_by_template = {}
-- tag (string) → list of engine.entity handles
local index_by_tag = {}
-- weak reverse-lookup: entity → { template, tags } (for destroy())
-- Lua-tables can't key on userdata reliably across GC, so we store
-- by stable entity-id derived from get_property("id"). engine assigns id.
-- For v0.1 we keep the parallel structure simpler: each entity records
-- its own template + tags in a Lua-side table keyed by a per-entity
-- monotonic registration-id we issue in create().
local entity_meta = {} -- reg_id → { template_id, tags, handle }
local next_reg_id = 1
-- ---------- internal helpers ----------
local function is_array(t)
if type(t) ~= "table" then return false end
local n = 0
for k, _ in pairs(t) do
if type(k) ~= "number" then return false end
n = n + 1
end
return n == #t
end
-- Flatten nested-table property-values into dotted scalar keys.
-- Input: { position = {x=144, y=200}, text = "Hi" }
-- Output: { ["position.x"] = 144, ["position.y"] = 200, text = "Hi" }
-- Arrays inside properties (e.g. tags) are NOT flattened; they belong
-- in `tags`, not `properties`. Reject arrays here loudly.
local function flatten_props(t, prefix, out)
out = out or {}
for k, v in pairs(t) do
if type(k) ~= "string" then
error(string.format(
"composition: property keys must be strings, got %s",
type(k)))
end
local key = prefix and (prefix .. "." .. k) or k
if type(v) == "table" then
if is_array(v) then
error(string.format(
"composition: property '%s' is an array; arrays in " ..
"properties are not supported (use tags=... at " ..
"template-level for tag-lists)", key))
end
flatten_props(v, key, out)
elseif type(v) == "number" or type(v) == "string" or type(v) == "boolean" then
out[key] = v
elseif v == nil then
-- nil default means "declared but no default" — skip
else
error(string.format(
"composition: property '%s' has unsupported value-type '%s' " ..
"(supported: number, string, boolean, or nested table for flattening)",
key, type(v)))
end
end
return out
end
-- Infer the engine property-type from a default-value.
local function infer_type(v)
local t = type(v)
if t == "number" then return "number" end
if t == "string" then return "string" end
if t == "boolean" then return "boolean" end
error("composition: cannot infer property type from value of type " .. t)
end
-- Set the engine property using the auto-detected setter (engine handles
-- typed writes via set_property based on Lua type).
local function set_prop(entity, key, value)
entity:set_property(key, value)
end
-- Declare a property via domain.contribute if not already declared.
-- Type is inferred from the default-value. inert=true so subsequent
-- set_property writes are accepted (per engine §11 inert-write rule).
local declared = {} -- "key" → true, idempotent across multiple templates
local function declare_inert(key, default_value)
if declared[key] then return end
domain.contribute("property", {
id = key,
type = infer_type(default_value),
inert = true,
})
declared[key] = true
end
-- ---------- public API ----------
function M.define_template(def)
if type(def) ~= "table" then
error("composition.define_template: expected table, got " .. type(def))
end
if type(def.id) ~= "string" or def.id == "" then
error("composition.define_template: 'id' must be a non-empty string")
end
if templates[def.id] then
error(string.format(
"composition.define_template: template '%s' already defined",
def.id))
end
-- Phase B/D/J reject — explicit Loud-Error pointing to re-entry phase.
if def.slots ~= nil then
error(string.format(
"composition.define_template '%s': 'slots' block is Phase-D " ..
"trigger (Composite Items with Sub-Items); not supported in v0.1",
def.id))
end
if def.container ~= nil then
error(string.format(
"composition.define_template '%s': 'container' block is " ..
"Phase-B trigger (Items + Inventory); not supported in v0.1",
def.id))
end
if def.quality ~= nil or def.condition ~= nil then
error(string.format(
"composition.define_template '%s': 'quality' / 'condition' " ..
"are Phase-J triggers (Damage / Wear); not supported in v0.1",
def.id))
end
if def.parent ~= nil then
error(string.format(
"composition.define_template '%s': 'parent:' inheritance has " ..
"no consumer in v0.1; declare inline until a real use-case appears",
def.id))
end
-- Properties block (optional but recommended).
local props_in = def.properties or {}
if type(props_in) ~= "table" then
error(string.format(
"composition.define_template '%s': 'properties' must be a table",
def.id))
end
local props_flat = flatten_props(props_in)
-- Tags block (optional list of strings).
local tags_set = {}
if def.tags ~= nil then
if type(def.tags) ~= "table" or not is_array(def.tags) then
error(string.format(
"composition.define_template '%s': 'tags' must be an array " ..
"of strings",
def.id))
end
for _, tag in ipairs(def.tags) do
if type(tag) ~= "string" or tag == "" then
error(string.format(
"composition.define_template '%s': tag entries must be " ..
"non-empty strings",
def.id))
end
tags_set[tag] = true
end
end
-- Declare each property as inert via domain.contribute. Type inferred
-- from default-value. nil-defaults skipped (no inference possible).
for key, val in pairs(props_flat) do
declare_inert(key, val)
end
templates[def.id] = {
id = def.id,
props_flat = props_flat,
tags = tags_set,
}
index_by_template[def.id] = index_by_template[def.id] or {}
end
function M.create(spec)
if type(spec) ~= "table" then
error("composition.create: expected table, got " .. type(spec))
end
if type(spec.template) ~= "string" or spec.template == "" then
error("composition.create: 'template' must be a non-empty string")
end
local tpl = templates[spec.template]
if not tpl then
error(string.format(
"composition.create: unknown template '%s' (was define_template " ..
"called?)",
spec.template))
end
-- Build flat merged property-bag: template-defaults overridden by
-- per-instance properties. Nested-tables in overrides are flattened
-- too. Override-flatten happens AFTER template-flatten, so nested
-- overrides naturally land on dotted keys.
local overrides_flat = {}
if spec.properties ~= nil then
if type(spec.properties) ~= "table" then
error("composition.create: 'properties' must be a table")
end
overrides_flat = flatten_props(spec.properties)
end
-- Any override-key that wasn't declared via define_template gets
-- declared on-the-fly with type inferred from the override value.
-- This lets per-instance properties live without forcing the template
-- to enumerate every possible override.
for key, val in pairs(overrides_flat) do
if templates[spec.template].props_flat[key] == nil then
declare_inert(key, val)
end
end
-- Spawn engine entity.
local entity = entity.create()
-- Apply template defaults first.
for key, val in pairs(tpl.props_flat) do
local final = overrides_flat[key]
if final == nil then final = val end
set_prop(entity, key, final)
end
-- Apply override-only properties (those not in template defaults).
for key, val in pairs(overrides_flat) do
if tpl.props_flat[key] == nil then
set_prop(entity, key, val)
end
end
-- Register in indices + meta.
local reg_id = next_reg_id
next_reg_id = next_reg_id + 1
entity_meta[reg_id] = { template_id = tpl.id, tags = tpl.tags, handle = entity }
table.insert(index_by_template[tpl.id], entity)
for tag, _ in pairs(tpl.tags) do
index_by_tag[tag] = index_by_tag[tag] or {}
table.insert(index_by_tag[tag], entity)
end
-- Stash reg_id on the entity via a reserved property so destroy()
-- can find the meta-record. We use a composition-internal key.
declare_inert("composition.reg_id", 0)
set_prop(entity, "composition.reg_id", reg_id)
return entity
end
function M.list_by_template(id)
if type(id) ~= "string" then
error("composition.list_by_template: 'id' must be a string")
end
local list = index_by_template[id]
if not list then return {} end
-- Return a shallow copy so callers can't mutate our index.
local out = {}
for i, e in ipairs(list) do out[i] = e end
return out
end
function M.list_by_tag(tag)
if type(tag) ~= "string" then
error("composition.list_by_tag: 'tag' must be a string")
end
local list = index_by_tag[tag]
if not list then return {} end
local out = {}
for i, e in ipairs(list) do out[i] = e end
return out
end
-- Remove entity from indices + destroy engine-side. Idempotent.
local function remove_from_list(list, entity)
if not list then return end
for i, e in ipairs(list) do
if e == entity then
table.remove(list, i)
return
end
end
end
function M.destroy(target_entity)
if not target_entity then return end
local reg_id = target_entity:get_property("composition.reg_id")
if not reg_id or reg_id == 0 then
-- Not composition-created or already destroyed.
entity.destroy(target_entity)
return
end
local meta = entity_meta[reg_id]
if meta then
remove_from_list(index_by_template[meta.template_id], target_entity)
for tag, _ in pairs(meta.tags) do
remove_from_list(index_by_tag[tag], target_entity)
end
entity_meta[reg_id] = nil
end
entity.destroy(target_entity)
end
-- ---------- introspection (debug/testing) ----------
-- Returns the set of declared template-ids (for tests + debug).
function M.list_templates()
local out = {}
for id, _ in pairs(templates) do
table.insert(out, id)
end
return out
end
return M