Selectors & Values

Selectors choose entities or blocks for later work. Values provide runtime numbers for conditions and actions that accept object-form numeric sources.

Selectors are used by action on, condition selection tests, pheno:at block selection, block action on, item action on, and value sources such as pheno:count.

Shared Selector Forms

Entity and block selectors both understand spatial shorthand before they look for a typed selector.

Form	Description
"here"	The current focus block. For entity selection, this means living entities in that block-sized region, excluding the current focus entity.
"above" / "below"	The block above or below the focus block.
"in_front" / "front"	The neighboring block in the current entity’s facing direction. Requires an entity focus.
"behind" / "back"	The neighboring block behind the current entity. Requires an entity focus.
"left" / "right"	The neighboring block to the side of the current entity. Requires an entity focus.
"looking_at" / "aim"	The block the current entity is looking at, up to 6 blocks away. Requires an entity focus and a block hit.
{ "offset": [x, y, z] }	A block offset from the current focus block.
{ "at": [x, y, z] }	An absolute block position.
{ "radius": r }	A spherical region around here, with radius r.
{ "radius": [x, y, z] }	A box region around here, with independent half-extents.
{ "radius": ..., "around": ... }	A region centered around another place form.
[ ... ]	Union of multiple selectors. Duplicates are removed for entity and block selectors.

For entity regions, optional where, limit, and order fields can filter and sort results:

Field	Description
where	Optional entity condition applied to each candidate.
limit	Optional maximum result count. 0 or missing means no cap.
order	any, nearest/closest, farthest/furthest, or random. Defaults to any.

For block regions, optional where and limit fields can filter positions:

Field	Description
where	Optional block condition applied to each block position.
limit	Optional maximum result count. 0 or missing means no cap. Block enumeration has an internal cap of 8192 positions.

Entity Selectors

Entity selector strings can also name a role:

Role Names	Result
self, each, it	Current focus entity.
origin, bearer, actor	Original power bearer.
attacker, target, other, victim, counterpart	Contextual counterpart, when one exists.
owner	Owner of an ownable current entity.
vehicle	Living vehicle the current entity is riding.
passenger	First living passenger of the current entity.

Typed entity selectors:

Type	Fields	Description
pheno:command	selector	Uses vanilla command selector syntax such as @e[type=minecraft:zombie,distance=..8]. Parsed once at load; returns only living entities. Requires a server-side entity focus.
pheno:ray	ray fields	Selects the first living entity hit by a ray, or all hits when pierce: true. Entities behind the first block collision are not selected.
pheno:collection	collection	Selects live entity members from a collection on the focus entity. Gone or unloaded members are skipped.
pheno:village	where, limit, order	Selects living entities inside the current MCA village bounds. The focus entity is excluded. Server-side only.
pheno:reservation	none	Selects the living entities reserved by the current action execution. Returns nothing outside a reservation-aware host.

Block Selectors

Block selectors use the shared spatial forms above. Typed block selectors:

Type	Fields	Description
pheno:ray	ray fields	Selects the first block hit by a ray. Returns no positions if the ray reaches its end without hitting a block.
pheno:collection	collection	Selects stored block positions from a collection on the focus entity. Entries that no longer decode are skipped.
pheno:connected	condition, limit	Flood-selects face-connected blocks from the focus position. Without condition, it follows the focus block’s type or the enclosing host’s default block membership. limit defaults to 256 and is capped at 8192.
pheno:column	direction, distance, where, limit	Selects an ordered straight run away from the focused block. direction accepts a Minecraft direction and defaults to down. distance is required to remain between 1 and 64. The optional block condition where filters the run, and limit stops after that many matches.

Ray Fields

pheno:ray is used by both entity and block selectors, and by pheno:beam.

Field	Description
distance	Maximum ray distance. Defaults to 6, unless toward is used; then the default distance is the distance to the target.
pierce	Entity selector only. When false, returns the nearest entity hit; when true, returns all entity hits before the first block. Defaults to false.
direction	Optional [x, y, z] vector. If omitted, the ray uses the actor’s look direction. Invalid arrays fall back to [0, 0, 1].
space	world or local. With local, direction means x right, y up, z forward relative to the actor. Defaults to world.
toward	Optional role name. Aims the ray at that role’s first resolved entity. If distance is omitted or 0, the ray length becomes the distance to that target.

Ray origins are the current entity’s eye position. Entity hits are pickable, alive living entities other than the current focus.

Item Selectors

Item selectors are used by item action on fields. Empty stacks are skipped.

Form	Description
"held", "main_hand", "mainhand", "hand"	Main-hand stack.
"off_hand", "offhand"	Off-hand stack.
"head", "helmet"	Head slot.
"chest", "chestplate"	Chest slot.
"legs", "leggings"	Legs slot.
"feet", "boots"	Feet slot.
"inventory"	All non-empty player inventory stacks. Returns nothing for non-player holders.
{ "slot": "..." }	Slot object form using the same slot names.
{ "where": { ... } }	Player inventory stacks filtered by an item condition.
[ ... ]	Concatenates multiple item selectors.

Collections As Selectors

pheno:collection resolves differently by selector domain:

Domain	Selected Members
Entity selector	Live entity members stored in the focus entity’s collection.
Block selector	Block positions stored in the focus entity’s collection.

Collections can also store item ids and literal keys, but those do not select live targets. They are read through collection conditions and collection actions instead.

Values

Numeric fields that accept values can be either a JSON number or a typed value object.

Form	Description
4	Constant numeric value.
{ "type": "pheno:count", "on": ... }	Counts selected entities and returns the count. on is an entity selector.
{ "type": "pheno:if", "condition": {...}, "then": ..., "else": ... }	Chooses one of two values using a block condition at the focused block. Both branches are required.
{ "type": "pheno:bond_count", "kind": "townstead:marriage", "active": true }	Counts the focus entity’s bonds of one kind. active defaults to true.
{ "type": "pheno:bond_max", "kind": "townstead:marriage" }	Reads the bond kind’s max_active; an unlimited kind returns a practically unbounded value.
{ "type": "pheno:game_time" }	Current world game time in ticks.
{ "type": "pheno:air_temperature", "felt": false }	The air temperature in °C at the focus, with rooms, ground and nearby heat. With "felt": true on a villager, it is what the villager feels after clothing, wetness and work. Without a temperature mod, it is the vanilla biome temperature in °C.
{ "type": "pheno:climate", "field": "humidity" }	One part of the climate at the focus: mean (the day’s mean in °C), seasonal, diurnal, phase (0 to 1 from the start of spring, 0 without a season mod), swing, humidity, diurnal_range or depth (blocks of terrain overhead). Zone fields are 0 for a biome without a zone. Without a temperature mod, mean is the vanilla biome temperature in °C, and seasonal and diurnal are 0.
{ "type": "pheno:event_damage", "scale": 0.2, "max": 2, "default": 0 }	The damage of the event a trigger is answering (when_hurt, when_attack, when_death_prevented, or a ward’s on_absorb), times scale, capped at max. Outside such an event, or after a pheno:delay, it is default. Use it for lifesteal: heal a fifth of each hit.
{ "type": "pheno:block_data", "key": "progress", "default": 0 }	Numeric persistent data on the focused block entity.
{ "type": "pheno:arithmetic", "operation": "add", "values": [...] }	Combines values with add, subtract, multiply, divide, min, or max.
{ "type": "pheno:provider", "provider": "examplemod:holy_ground", "default": 0 }	The current reading of a provider that a supported mod registers. When the provider has no reading, the value is default, which defaults to 0. Some providers report about a place. During hazard avoidance, Townstead asks those providers about the block it tests.

pheno:count currently counts entity selectors. For block counts, use condition/action logic that operates in a block selector context rather than the numeric value source.

Values resolve against the current focus. In a block action, pheno:block_data reads the block being acted on, including after an on or offset wrapper has moved that focus. A missing block entity or key returns default, which itself defaults to 0.

Arithmetic requires at least one value and evaluates from left to right. Division by zero leaves the accumulated result unchanged. This is deliberate: a malformed denominator does not turn the remainder of a block procedure into infinity or NaN.