跳转至

levilamina::entity · 实体

实体：所有用 ActorUniqueID 指定的东西，玩家也包括在内。

id 是身份，不是指针

一个 Entity 只存一个 i64。宿主每次调用都重新查一遍活动实体表，所以 Entity 值可以跨刻保存：实体死掉以后，调用返回 Err，不会跳进已经释放的内存。代价是每次调用一次查找，所以热路径要自己缓存结果。

玩家要经过这里才能用实体的能力

Player::as_entity() 经 player_resolve 取得 id。反过来不成立：一个实体 id 不一定是玩家，也没有槽位能把 id 解析回选择器。

Entity

Rust
1
pub struct Entity(/* private */);

一个实体。ActorUniqueID 的零开销包装。

  • 实现的 trait：Debug、Clone、Copy、PartialEq、Eq、Hash、PartialOrd、Ord、Display

Entity::from_id

Rust
1
pub fn from_id(id: i64) -> Entity
  • 参数：
    • id : i64
  • 返回值类型：Entity

Entity::id

Rust
1
pub fn id(&self) -> i64
  • 返回值类型：i64

Entity::list

Rust
1
pub fn list(dim: Option<i32>) -> Vec<ActorEntry>

列出活着的实体。dim 为 None 时覆盖所有维度。

这个槽位没有失败位，世界没就绪时什么都不报告，所以表为空，既可能是这个维度里没有实体，也可能是世界还没起来；调用方用 Host::gaming_status() 区分两者。

Entity::exists

Rust
1
pub fn exists(&self) -> bool

这个 id 是否仍然指向一个活着的实体。

判断依据是能不能读到类型名：每个能解析到的实体都有类型名，解析不到的会让 actor_get_str 返回 false。

Entity::snapshot

Rust
1
pub fn snapshot(&self) -> Result<NbtValue>

Entity::num

Rust
1
pub fn num(&self, prop: i32) -> Result<f64>

读取一个 PIER_APROP_* 数值属性。

  • 参数：
    • prop : i32
  • 返回值类型：Result<f64>
  • 对应槽位：actor_get_num

Entity::text

Rust
1
pub fn text(&self, prop: i32) -> Result<String>

读取一个 PIER_ASTR_* 字符串属性。

  • 参数：
    • prop : i32
  • 返回值类型：Result<String>
  • 对应槽位：actor_get_str

Entity::pos

Rust
1
pub fn pos(&self) -> Result<PositionF64>

位置，取自 Actor::getPosition。玩家的脚下坐标见 Entity::feet_pos。

  • 返回值类型：Result<PositionF64>
  • 对应槽位：actor_get_num

Entity::feet_pos

Rust
1
pub fn feet_pos(&self) -> Result<PositionF64>
  • 返回值类型：Result<PositionF64>
  • 对应槽位：actor_get_num

Entity::head_pos

Rust
1
pub fn head_pos(&self) -> Result<PositionF64>
  • 返回值类型：Result<PositionF64>
  • 对应槽位：actor_get_num

Entity::velocity

Rust
1
pub fn velocity(&self) -> Result<PositionF64>
  • 返回值类型：Result<PositionF64>
  • 对应槽位：actor_get_num

Entity::view_vector

Rust
1
pub fn view_vector(&self) -> Result<PositionF64>

视线方向的单位向量。

  • 返回值类型：Result<PositionF64>
  • 对应槽位：actor_get_num

Entity::rotation

Rust
1
pub fn rotation(&self) -> Result<(f64, f64)>

(pitch, yaw)，即俯仰角和偏航角。

  • 返回值类型：Result<(f64, f64)>
  • 对应槽位：actor_get_num

Entity::act

Rust
1
pub fn act(&self, action: i32, sarg: &str, a: f64, b: f64, c: f64) -> Result<String>

执行一个 PIER_AACT_* 动作，返回它的输出；大多数动作的输出是空字符串。

  • 参数：
    • action : i32
    • sarg : &str
    • a : f64
    • b : f64
    • c : f64
  • 返回值类型：Result<String>
  • 对应槽位：actor_action

Entity::kill

Rust
1
pub fn kill(&self) -> Result<()>

Entity::despawn

Rust
1
pub fn despawn(&self) -> Result<()>

Entity::clear_effects

Rust
1
pub fn clear_effects(&self) -> Result<()>

Entity::stop_fire

Rust
1
pub fn stop_fire(&self) -> Result<()>

Entity::remove_all_passengers

Rust
1
pub fn remove_all_passengers(&self) -> Result<()>

Entity::heal

Rust
1
pub fn heal(&self, amount: f64) -> Result<()>
  • 参数：
    • amount : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::hurt

Rust
1
pub fn hurt(&self, amount: f64) -> Result<()>
  • 参数：
    • amount : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::burn

Rust
1
pub fn burn(&self, damage: f64) -> Result<()>
  • 参数：
    • damage : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_on_fire

Rust
1
pub fn set_on_fire(&self, seconds: i32) -> Result<()>
  • 参数：
    • seconds : i32
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::teleport

Rust
1
pub fn teleport(&self, x: f64, y: f64, z: f64) -> Result<()>

在同一个维度内传送到别处。

Entity::teleport_to

Rust
1
pub fn teleport_to(&self, dim: i32, x: f64, y: f64, z: f64) -> Result<()>

传送到指定的维度。id 为 3 及以上的自定义维度也走这里。

  • 参数：
    • dim : i32
    • x : f64
    • y : f64
    • z : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_rotation

Rust
1
pub fn set_rotation(&self, pitch: f64, yaw: f64) -> Result<()>
  • 参数：
    • pitch : f64
    • yaw : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_velocity

Rust
1
pub fn set_velocity(&self, x: f64, y: f64, z: f64) -> Result<()>
  • 参数：
    • x : f64
    • y : f64
    • z : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::apply_impulse

Rust
1
pub fn apply_impulse(&self, x: f64, y: f64, z: f64) -> Result<()>
  • 参数：
    • x : f64
    • y : f64
    • z : f64
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_name_tag

Rust
1
pub fn set_name_tag(&self, name: &str) -> Result<()>
  • 参数：
    • name : &str
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_name_tag_visible

Rust
1
pub fn set_name_tag_visible(&self, on: bool) -> Result<()>
  • 参数：
    • on : bool
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_score_tag

Rust
1
pub fn set_score_tag(&self, text: &str) -> Result<()>
  • 参数：
    • text : &str
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::add_tag

Rust
1
pub fn add_tag(&self, tag: &str) -> Result<bool>
  • 参数：
    • tag : &str
  • 返回值类型：Result<bool>
  • 对应槽位：actor_action

Entity::remove_tag

Rust
1
pub fn remove_tag(&self, tag: &str) -> Result<bool>
  • 参数：
    • tag : &str
  • 返回值类型：Result<bool>
  • 对应槽位：actor_action

Entity::has_tag

Rust
1
pub fn has_tag(&self, tag: &str) -> Result<bool>
  • 参数：
    • tag : &str
  • 返回值类型：Result<bool>
  • 对应槽位：actor_action

Entity::add_effect

Rust
1
2
3
4
5
6
7
pub fn add_effect(
        &self,
        effect: &str,
        ticks: i32,
        amplifier: i32,
        visible: bool,
    ) -> Result<()>

添加一个状态效果。

  • 参数：
    • effect : &str
    • ticks : i32
    • amplifier : i32
    • visible : bool
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::remove_effect

Rust
1
pub fn remove_effect(&self, effect: &str) -> Result<()>
  • 参数：
    • effect : &str
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::attribute

Rust
1
pub fn attribute(&self, name: &str) -> Result<f64>

读取一个属性的当前值，属性名的写法和 minecraft:health 一样。

  • 参数：
    • name : &str
  • 返回值类型：Result<f64>
  • 对应槽位：actor_action

Entity::set_variant

Rust
1
pub fn set_variant(&self, v: i32) -> Result<()>
  • 参数：
    • v : i32
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_mark_variant

Rust
1
pub fn set_mark_variant(&self, v: i32) -> Result<()>
  • 参数：
    • v : i32
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_persistent

Rust
1
pub fn set_persistent(&self) -> Result<()>

Entity::set_invisible

Rust
1
pub fn set_invisible(&self, on: bool) -> Result<()>
  • 参数：
    • on : bool
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_sneaking

Rust
1
pub fn set_sneaking(&self, on: bool) -> Result<()>
  • 参数：
    • on : bool
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_skin_id

Rust
1
pub fn set_skin_id(&self, id: i32) -> Result<()>
  • 参数：
    • id : i32
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_strength

Rust
1
pub fn set_strength(&self, v: i32) -> Result<()>
  • 参数：
    • v : i32
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_target

Rust
1
pub fn set_target(&self, target: Entity) -> Result<()>
  • 参数：
    • target : Entity
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_owner

Rust
1
pub fn set_owner(&self, owner: Entity) -> Result<()>
  • 参数：
    • owner : Entity
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::set_leash_holder

Rust
1
pub fn set_leash_holder(&self, holder: Entity) -> Result<()>
  • 参数：
    • holder : Entity
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::execute_event

Rust
1
pub fn execute_event(&self, event: &str) -> Result<()>
  • 参数：
    • event : &str
  • 返回值类型：Result<()>
  • 对应槽位：actor_action

Entity::type_name

Rust
1
pub fn type_name(&self) -> Result<String>

Entity::name_tag

Rust
1
pub fn name_tag(&self) -> Result<String>

显示在头顶上的名字。

Entity::score_tag

Rust
1
pub fn score_tag(&self) -> Result<String>

名字下方的那一行。

Entity::filtered_name

Rust
1
pub fn filtered_name(&self) -> Result<String>

经过脏话过滤以后的名字。

Entity::dimension

Rust
1
pub fn dimension(&self) -> Result<i32>

Entity::health

Rust
1
pub fn health(&self) -> Result<f64>

Entity::max_health

Rust
1
pub fn max_health(&self) -> Result<f64>

Entity::speed

Rust
1
pub fn speed(&self) -> Result<f64>

当前的移动速度，单位是方块每刻。

Entity::fall_distance

Rust
1
pub fn fall_distance(&self) -> Result<f64>

这一次下落已经落了多少格，着地时用来计算摔落伤害。

Entity::scale

Rust
1
pub fn scale(&self) -> Result<f64>

体型缩放，1.0 是原始大小。

Entity::variant

Rust
1
pub fn variant(&self) -> Result<i32>

variant 数据值，含义随实体种类而不同。

Entity::mark_variant

Rust
1
pub fn mark_variant(&self) -> Result<i32>

mark_variant 数据值，编号和 Entity::variant 是两套。

Entity::death_time

Rust
1
pub fn death_time(&self) -> Result<i32>

死亡动画已经播放了多少刻。

Entity::is_alive

Rust
1
pub fn is_alive(&self) -> Result<bool>

Entity::is_on_ground

Rust
1
pub fn is_on_ground(&self) -> Result<bool>

Entity::is_in_water

Rust
1
pub fn is_in_water(&self) -> Result<bool>

Entity::is_in_lava

Rust
1
pub fn is_in_lava(&self) -> Result<bool>

Entity::is_on_fire

Rust
1
pub fn is_on_fire(&self) -> Result<bool>

Entity::is_invisible

Rust
1
pub fn is_invisible(&self) -> Result<bool>

Entity::is_sneaking

Rust
1
pub fn is_sneaking(&self) -> Result<bool>

Entity::is_baby

Rust
1
pub fn is_baby(&self) -> Result<bool>

Entity::is_riding

Rust
1
pub fn is_riding(&self) -> Result<bool>

Entity::is_tame

Rust
1
pub fn is_tame(&self) -> Result<bool>

Entity::is_persistent

Rust
1
pub fn is_persistent(&self) -> Result<bool>

不会因为离玩家太远而被清除。

Entity::is_leashed

Rust
1
pub fn is_leashed(&self) -> Result<bool>

Entity::is_invulnerable

Rust
1
pub fn is_invulnerable(&self) -> Result<bool>

Entity::is_frozen

Rust
1
pub fn is_frozen(&self) -> Result<bool>

Entity::is_in_love

Rust
1
pub fn is_in_love(&self) -> Result<bool>

处在繁殖状态。

Entity::is_in_rain

Rust
1
pub fn is_in_rain(&self) -> Result<bool>

Entity::is_in_snow

Rust
1
pub fn is_in_snow(&self) -> Result<bool>

Entity::is_in_thunderstorm

Rust
1
pub fn is_in_thunderstorm(&self) -> Result<bool>

Entity::has_totem

Rust
1
pub fn has_totem(&self) -> Result<bool>

主手或副手拿着不死图腾。

Entity::has_passenger

Rust
1
pub fn has_passenger(&self) -> Result<bool>

Entity::vehicle

Rust
1
pub fn vehicle(&self) -> Result<Option<Entity>>

正在骑乘的载具。什么都没骑时返回 Ok(None)，只有缺少槽位才是 Err。

Entity::first_passenger

Rust
1
pub fn first_passenger(&self) -> Result<Option<Entity>>

Entity::owner

Rust
1
pub fn owner(&self) -> Result<Option<Entity>>

Entity::target

Rust
1
pub fn target(&self) -> Result<Option<Entity>>

Entity::distance_to

Rust
1
pub fn distance_to(&self, other: Entity) -> Result<f64>

两个实体之间的距离。跨维度时宿主返回失败。

  • 参数：
    • other : Entity
  • 返回值类型：Result<f64>
  • 对应槽位：actor_distance_to

Entity::aabb

Rust
1
pub fn aabb(&self) -> Result<Aabb>

碰撞箱。

Entity::clone_at

Rust
1
pub fn clone_at(&self, dim: i32, x: f64, y: f64, z: f64) -> Result<Entity>

在指定的位置复制出一个。

  • 参数：
    • dim : i32
    • x : f64
    • y : f64
    • z : f64
  • 返回值类型：Result<Entity>
  • 对应槽位：actor_clone

Entity::equipped_item

Rust
1
pub fn equipped_item(&self, slot: EquipSlot) -> Result<ItemStack>

Entity::set_equipped_item

Rust
1
pub fn set_equipped_item(&self, slot: EquipSlot, item: &ItemStack) -> Result<()>

Entity::effects

Rust
1
pub fn effects(&self) -> Result<Vec<Effect>>

身上的全部状态效果。

Entity::status_flag

Rust
1
pub fn status_flag(&self, flag_index: i32) -> Result<bool>

读取 ActorFlags 的一位。

在 ABI 上，这个槽位把「实体不在了」和「这一位为 false」合成了同一个 false，这正是契约 §5.2 反对的形状。这个签名已经发布，所以这里只是如实写明。需要区分两者时，先调用 Entity::exists。

Entity::set_status_flag

Rust
1
pub fn set_status_flag(&self, flag_index: i32, value: bool) -> Result<()>
  • 参数：
    • flag_index : i32
    • value : bool
  • 返回值类型：Result<()>
  • 对应槽位：actor_set_status_flag

Entity::trace_ray

Rust
1
2
3
4
5
6
pub fn trace_ray(
        self,
        max_dist: f32,
        include_actors: bool,
        include_blocks: bool,
    ) -> Result<RayHit>

沿着这个实体的视线发射一条射线，以精确坐标报告命中点。

  • 参数：
    • max_dist : f32
    • include_actors : bool
    • include_blocks : bool
  • 返回值类型：Result<RayHit>
  • 对应槽位：actor_trace_ray

Entity::trace_ray_blocks

Rust
1
2
3
4
5
6
pub fn trace_ray_blocks(
        self,
        max_dist: f32,
        include_actors: bool,
        include_blocks: bool,
    ) -> Result<RayHit>

同上，但以方块格报告命中点，并带上命中的面。

两个槽位都保留，因为它们回答的问题不同：放方块需要格子坐标和面，画粒子需要精确坐标，而把后者向下取整当作前者，在方块边界上会差一格。

  • 参数：
    • max_dist : f32
    • include_actors : bool
    • include_blocks : bool
  • 返回值类型：Result<RayHit>
  • 对应槽位：edit_trace_ray

Effect

Rust
1
2
3
4
5
6
pub struct Effect {
    pub id: String,
    pub ticks: i32,
    pub amplifier: i32,
    pub visible: bool,
}

一个状态效果。

  • 实现的 trait：Debug、Clone、PartialEq、Eq

Aabb

Rust
1
2
3
4
pub struct Aabb {
    pub min: PositionF64,
    pub max: PositionF64,
}

实体的轴对齐碰撞箱。

  • 实现的 trait：Debug、Clone、Copy、PartialEq

ActorEntry

Rust
1
2
3
4
pub struct ActorEntry {
    pub id: i64,
    pub type_name: String,
}

list_actors 报告的一项。

  • 实现的 trait：Debug、Clone、PartialEq、Eq