manifold:ecs 0.2.0

Contract reference · Payloads · contract.json (crates/manifold-wasm-abi/wit/contract.json)

Contract 0.2.0, track 0.2: open, unreleased. Nothing on track 0.2 is released yet, so any item may still change in place (spec §7.2).

Interface plugin-systems

export · consent silent · sides both · owner contract-foundation · since 0.2.0

Exported by a mod that runs systems (contract foundation spec §6.1). Optional: a mod without systems does not export it, and then imports nothing from resource-bundle either.

Functions

run-system

run-system: func(system-id: u32, bundle: borrow<resource-bundle-handle>) -> result<_, string>

Run the system the host numbered system-id (its index in the declarations’ walk order) for one tick. bundle carries the system’s read and write sets; the host drops it when the call returns. The error is a diagnostic for logs.

Types

resource-bundle-handle (alias)

= ecs/resource-bundle.resource-bundle-handle

Interface resource-bundle

import · consent listed · sides both · owner contract-foundation · since 0.2.0

ResourceBundle capability: per-PluginSystem ECS resource snapshot. Coarse-grained crossing: host serializes the declared read-set before calling run-system, then deserializes the write-set after. Chosen over fine-grained per-entity access because all 8 current PluginSystems use resource-keyed access only (no entity iteration). Entity-snapshot is a v2+ sibling capability for mods that need it.

Resources: resource-bundle-handle.

Functions

[method]resource-bundle-handle.insert-entity-component

[method]resource-bundle-handle.insert-entity-component: func(self: borrow<resource-bundle-handle>, entity: u64, type-id: u64, bytes: list<u8>)

Attach (create) a novel component on an entity. Unlike write-entity-component (which updates an existing component), insert creates the component if absent, creating the entity’s DynComponents bag if it does not yet exist. Authorized by the system’s declared write-components set — inserting a type outside that set causes a host trap (mirrors write-entity-component). The insert is accumulated and applied by the host after run-system; an undeclared or unexposed type is diagnosed and skipped, never applied silently.

• bytes: opaque bytes component-value.

[method]resource-bundle-handle.query-entities

[method]resource-bundle-handle.query-entities: func(self: borrow<resource-bundle-handle>, type-id: u64) -> list<u64>

— Entity-component access (B2-EC) — Resources are global; entity components belong to entities, so these are parameterized by an entity id and paired with a query primitive to enumerate the entities a system may touch. This is the surface that reserves the future no-code rule-VM door: read entity state by id + bytes, never by Rust type. Enumerate the entity ids staged for type-id — the entities carrying that component among the system’s declared component read-set. Entity ids are the u64 Entity::to_bits() form; pass them back to read-entity-component. Returns an empty list if the type was not declared or no staged entity carries it.

[method]resource-bundle-handle.read-entity-component

[method]resource-bundle-handle.read-entity-component: func(self: borrow<resource-bundle-handle>, entity: u64, type-id: u64) -> option<list<u8>>

Read one entity’s component by (entity, type-id). Returns None if the component was not staged for that entity (type not declared, entity absent, or component absent). Bytes are postcard-encoded.

• result: opaque bytes component-value.

[method]resource-bundle-handle.read-resource

[method]resource-bundle-handle.read-resource: func(self: borrow<resource-bundle-handle>, type-id: u64) -> option<list<u8>>

Read a resource from the bundle by its type-id. type-id is the u64 hash of the Rust TypeId (host-computed, stable for a given engine version). Returns None if the resource was not included in the read-set (either not declared in AccessSet or not present in the world). The returned bytes are postcard-encoded.

• result: opaque bytes component-value.

[method]resource-bundle-handle.remove-entity-component

[method]resource-bundle-handle.remove-entity-component: func(self: borrow<resource-bundle-handle>, entity: u64, type-id: u64)

Detach a novel component from an entity. Authorized by the system’s declared write-components set — removing a type outside that set causes a host trap (mirrors write-entity-component). The removal is accumulated and applied by the host after run-system; an undeclared or unexposed type is diagnosed and skipped, never applied silently. A no-op if the entity does not carry the component.

[method]resource-bundle-handle.write-entity-component

[method]resource-bundle-handle.write-entity-component: func(self: borrow<resource-bundle-handle>, entity: u64, type-id: u64, bytes: list<u8>)

Write one entity’s component by (entity, type-id). The bytes must be postcard-encoded. Writing a component type not in the system’s declared write-components set causes a host trap (mirrors write-resource). The write is accumulated and applied to the live world by the host’s entity bridge after run-system returns; an absent entity / read-only or unexposed component is diagnosed and skipped, never applied silently.

• bytes: opaque bytes component-value.

[method]resource-bundle-handle.write-resource

[method]resource-bundle-handle.write-resource: func(self: borrow<resource-bundle-handle>, type-id: u64, bytes: list<u8>)

Write a resource back to the bundle by its type-id. The bytes must be postcard-encoded and decode to the correct type; the host validates this at lift time (decodes and checks type-id against the AccessSet write-set before committing to the world). Writing a type not declared in AccessSet.write_set causes a trap.

• bytes: opaque bytes component-value.

Types

bundle-error (record)

Error returned if a system-id is unknown or the bundle is malformed.

resource-bundle-handle (resource)

Opaque handle passed to run-system. Owns the serialized read_map and write-accumulator for one PluginSystem invocation. WIT resource so the handle is lifetime-tracked by the component model; the host drops it after run-system returns.

resource