外观
item_actions API
模块说明
text
Explicit one-packet item actions; no timing, automatic firing, or hit claims.
Use a shared ActionControl around the complete selection/use/release sequence.
Intents are prepared before IO and remain available after cancellation. The Host
revalidates current native inventory references immediately before writing.held_item_ref
python
def held_item_ref(snapshot, slot)SDK 说明：
text
Copy one known window-0 slot's native reference; never invent air.ActionAttempt
python
@dataclass
class ActionAttemptSDK 说明：
text
Caller must persist intent before IO; repr omits potentially private data.字段（包含继承字段）：
ActionAttempt.intent
python
intent: OperationIntent = field(repr=False)数据类字段；声明于 item_actions.ActionAttempt。
ActionAttempt.operation_id
python
operation_id: str = None数据类字段；声明于 item_actions.ActionAttempt。
ActionAttempt.receipt
python
receipt: dict = field(default=None, repr=False)数据类字段；声明于 item_actions.ActionAttempt。
ActionAttempt.started
python
started: bool = False数据类字段；声明于 item_actions.ActionAttempt。
ItemActions
python
class ItemActionsSDK 说明：
text
Prepare explicit selection/attack/use/release with caller-owned keys.
No hidden slot selection, ticks, delay, movement, cleanup, or retry. For item
use the caller supplies an environment-validated sequence and fresh inventory
references at each step. release() is a separate protocol action, not a
required crossbow firing step. Dispatch success never implies a hit.ItemActions.__init__
python
def __init__(self, operations)ItemActions.select
python
def select(self, snapshot, slot, *, entity_runtime_id, idempotency_key, deadline)ItemActions.attack
python
def attack(
self,
snapshot,
slot,
*,
target_runtime_id,
position,
clicked_position,
idempotency_key,
deadline,
)ItemActions.use_air
python
def use_air(
self,
snapshot,
slot,
*,
trigger_type,
block_position,
block_face,
position,
clicked_position,
block_runtime_id,
client_prediction,
idempotency_key,
deadline,
)ItemActions.interact_entity
python
def interact_entity(
self,
snapshot,
slot,
*,
target_runtime_id,
position,
clicked_position,
idempotency_key,
deadline,
)SDK 说明：
text
Explicit interaction packet; use a fresh target observation, never guess IDs.
Like attack(), this does not establish target existence or server effects.
The Host fences held inventory references immediately before sending.ItemActions.use_block
python
def use_block(
self,
snapshot,
slot,
*,
trigger_type,
block_position,
block_face,
position,
clicked_position,
block_runtime_id,
client_prediction,
idempotency_key,
deadline,
)SDK 说明：
text
Click one explicitly observed block; no synthetic block runtime ID.ItemActions.release
python
def release(self, snapshot, slot, *, head_position, idempotency_key, deadline)ItemActions.dispatch
python
async def dispatch(self, attempt, *, timeout=10, on_admitted=None, poll_interval=0.05)SDK 说明：
text
Send at most once per attempt; failed/unknown stops a normal sequence.
Cancellation or transport loss keeps started=True and original intent/ID.
Reconcile through operations.get; this method never submits it again.
The optional on_admitted callback can durably save the admission ID before
waiting. Callback failure does not cancel the already admitted action.
poll_interval uses Operations.wait finite-positive seconds; the default
remains 50 ms and never extends the remaining timeout.
Persist operation_id after return/error when available. Caller owns the
shared control lock and durable journaling before invoking this method.ItemActions.operations
python
self.operations公开实例属性，在 __init__ 中设置。
equipment_matches
python
def equipment_matches(
event,
*,
entity_runtime_id,
slot,
stack_network_id,
after_sequence,
)SDK 说明：
text
Predicate for a fresh independent OriginalPackets JSON MobEquipment event.
Open a current independent stream before sending, record its applied sequence,
and pass only its ordered events. The stream supplies epoch/overflow fences.
A match shows reported selection, never damage, ammo use or exclusive control.
It does not prove causation when other controllers can select concurrently.wait_equipment
python
async def wait_equipment(
stream,
*,
entity_runtime_id,
slot,
stack_network_id,
after_sequence,
timeout = 5,
)SDK 说明：
text
Consume one caller-owned ordered stream until selection tuple is observed.
Use a freshly opened independent observer and known applied cursor. Do not
share concurrent stream readers. Unrelated events are consumed; capture them
in the caller's poll wrapper if needed. Timeout/fault never triggers a send.
Close the stream in the caller's finally block, including on cancellation.