World Observations and Events
World APIs expose evidence, not live Minecraft objects. Events report changes through the same serialized Lua lane.
Candidate observations
| Capability | Purpose |
|---|---|
world.snapshot | Player, dimension, time, and world-generation summary |
world.blocks | Bounded block query |
world.entities | Bounded entity query |
world.raycast | Engine-executed hit observation |
events.subscribe | Typed scoped event stream |
Cheap snapshots may be synchronous through a bounded client-thread gateway. Queries requiring scanning, indexing, or chunk work return action handles.
Query contract
Every spatial query declares:
- center or region;
- dimension or current-world requirement;
- selector;
- maximum radius/volume and result count;
- ordering;
- freshness requirement;
- optional pack interpretation.
Unknown chunks and unloaded data are reported explicitly. The engine does not silently treat unknown space as air.
Snapshot identity
Entity references contain an opaque stable reference, type ID, position, sanitized attributes, observed tick, and world generation. Block hits contain block position, face, hit point, block state ID, observed tick, and generation.
References are inputs to later actions only after live revalidation. UUIDs, entity IDs, or slot positions alone are not proof that the same target remains.
Events
local subscription = hexis.events.subscribe({
type = "world.entity_changed",
filter = {selector = pack.entities.zealots, radius = 20},
queue = {capacity = 32, overflow = "coalesce"},
}, function(event)
-- Serialized on this script's Lua lane.
end)
Subscriptions belong to a scope. Delivery order is stable per source.
High-frequency events declare an overflow policy: coalesce, drop_oldest, or
disconnect. Terminal lifecycle events are never dropped.
Callbacks cannot run concurrently with the script or each other. Slow callbacks consume the script budget rather than blocking the client thread.
Standard event envelope
Events include type, sequence, observed_tick, world_generation,
source, and typed data. Pack-derived semantic events also identify the pack
and pack version that produced them.
Event streams add QUEUE_OVERFLOW, SUBSCRIPTION_CLOSED, SOURCE_UNAVAILABLE,
and FILTER_INVALID. Queries add REGION_TOO_LARGE, CHUNK_UNAVAILABLE,
RESULT_LIMIT, and REFERENCE_STALE.
Security and privacy
Snapshots expose only allowlisted fields. Diagnostics and AI repair context redact player identifiers, chat content, server tokens, proprietary scoring, and internal indexes unless an explicit trusted capability permits them.
Acceptance tasks
- Bound block/entity query time, volume, and result size.
- Distinguish unloaded/unknown data from empty results.
- Invalidate all references on world generation change.
- Revalidate a block hit or entity before interaction.
- Preserve per-source event ordering on one Lua lane.
- Exercise every overflow policy without client-thread stalls.
- Close subscriptions on scope stop and world unload.
- Verify pack-derived events retain provenance.
- Fuzz selectors and serialized values against the sandbox boundary.
- Measure tick and memory cost under event bursts.