Lua v4 World Evidence
World evidence is implemented in the source foundation with focused tests. It is not an accepted public or AI-runnable promise until a named distributed build passes controlled live acceptance. It returns immutable snapshots captured on the client thread, acquires no control resources, never loads chunks, and checks world generation before and after capture. A changed generation fails the observation instead of returning mixed-world evidence.
Exact block observations
hexis.world.blocks.observe requires world.blocks.read and accepts:
local snapshot = hexis.world.blocks.observe({
positions = {
{x = 10, y = 64, z = 20},
{x = 11, y = 64, z = 20},
},
})
positions contains 1 through 128 exact integer coordinates. Results preserve
request order:
{
world_generation = 7,
observed_tick = 1804,
complete = false,
observations = {
{position = {x = 10, y = 64, z = 20}, loaded = true, block_id = "minecraft:air"},
{position = {x = 11, y = 64, z = 20}, loaded = false},
},
}
An unloaded position omits block_id; loaded air is explicitly
minecraft:air. complete is false when any requested position was not
resident.
Bounded block search
hexis.world.blocks.find also requires world.blocks.read:
local blocks = hexis.world.blocks.find({
center = {x = 10, y = 64, z = 20},
radius = 15,
selector = {
block_ids = {"minecraft:spruce_log"},
},
limit = 32,
})
center is optional and defaults to the player's position. An explicit center
uses exact integer coordinates and must be within 32 blocks of the player.
radius is from 1 through 15. The required selector contains 1 through 8 exact
namespaced block IDs. limit is from 1 through 32. Search uses resident chunks
only and sorts matches by distance, then x, y, and z.
{
world_generation = 7,
observed_tick = 1804,
complete = true,
truncated = false,
matches = {
{
position = {x = 10, y = 64, z = 20},
block_id = "minecraft:spruce_log",
distance = 3.25,
},
},
}
complete reports whether resident data covered the requested search;
truncated reports whether more matches existed beyond the limit.
Bounded entity search
hexis.world.entities.find requires world.entities.read. Its selector is
mandatory. The area is either a radius from 0.5 through 128 blocks or an
axis-aligned box whose width, height, and depth are each at most 128 blocks.
local entities = hexis.world.entities.find({
area = {kind = "radius", radius = 24},
selector = {
type_ids = {"minecraft:enderman"},
exclude_self = true,
tablist_only = false,
},
limit = 32,
})
type_ids contains 1 through 8 exact namespaced entity IDs. exclude_self and
tablist_only are optional; tablist_only is valid only for player entities.
limit is from 1 through 32. A box uses
{kind = "box", min = {x, y, z}, max = {x, y, z}}.
{
world_generation = 7,
observed_tick = 1804,
matched_count = 1,
truncated = false,
entities = {
{
ref = {id = entity_uuid, world_generation = 7},
type_id = "minecraft:enderman",
name = "Zealot",
position = {x = 10.5, y = 64, z = 20.5},
distance = 12.25,
alive = true,
sneaking = false,
health = 13000,
max_health = 13000,
labels = {"Zealot"},
labels_contain_self_name = false,
carried_block_id = "minecraft:end_portal_frame",
},
},
}
The result holds at most 32 entities. Names and labels are at most 128
characters, with at most four labels. Health fields are optional when the
client does not have that evidence. labels_contain_self_name is always a
boolean. It is true when any associated label contains the local display name
or game-profile name as a case-insensitive substring. This remains heuristic
evidence, not proof that a boss belongs to the local player.
carried_block_id is optional and appears only when an observed Enderman is
carrying a block; its value is the exact namespaced block ID. Entity references
are evidence for a later action, not a live Minecraft object or proof the
entity still exists.
Crosshair observation
hexis.world.crosshair.observe({}) requires world.crosshair.read. It reports
the client's actual hitResult as an exact block, entity, or miss variant. All
variants contain world_generation, observed_tick, and kind.
-- Block hit
{
world_generation = 7,
observed_tick = 1804,
kind = "block",
hit_position = {x = 10.4, y = 64.8, z = 20.0},
distance = 3.25,
block = {
position = {x = 10, y = 64, z = 20},
block_id = "minecraft:spruce_log",
face = "north",
},
}
-- Entity hit
{
world_generation = 7,
observed_tick = 1804,
kind = "entity",
hit_position = {x = 10.4, y = 65.2, z = 20.0},
distance = 3.25,
entity = {
ref = {id = entity_uuid, world_generation = 7},
type_id = "minecraft:enderman",
name = "Zealot",
position = {x = 10.5, y = 64, z = 20.5},
},
}
-- Miss
{world_generation = 7, observed_tick = 1804, kind = "miss"}
Block faces use canonical direction strings. The host does not raycast again,
accept an arbitrary ray length, choose a nearby replacement, or infer a target.
The crosshair entity DTO contains exactly ref, type_id, name, and
position; it does not expose labels, health, alive state, or other nearby-
entity search fields.
Its source binding exists, but the docs keep it non-executable until
distributed-build acceptance exists.
Interaction handoff
An entity interaction target is
{kind = "entity", ref = {id = entity_uuid, world_generation = generation}}.
The action revalidates that reference. A stale generation returns
world_changed before acquiring controls; an entity absent from the current
generation returns target_lost. Interaction never substitutes another entity.