World & Entities

The world API gives access to the current dimension and its entities. The targeting API reads the player’s crosshair result and fires raycasts.

Guards

Always check world.is_present before reading world state:

return unless world.is_present

`world`

State

world.is_present       # => Boolean
world.get_dimension    # => String  e.g. "minecraft:overworld"
world.get_time         # => Integer  world tick time
world.is_raining       # => Boolean
world.get_player_count # => Integer
world.get_entity_count # => Integer

Fetching entities

world.get_players   # => Array of entity objects (players only)
world.get_entities  # => Array of entity objects (all entities)
world.get_entity(id)  # => entity object or nil

Entity Object

Every entity object returned by world.get_players, world.get_entities, world.get_entity, or targeting has the following.

Fields (direct access, no call needed)

Field	Type	Description
`id`	Integer	Entity ID
`name`	String	Name string
`display_name`	String	Formatted display name
`type`	String	Entity type identifier
`x`, `y`, `z`	Float	Current position
`eye_y`	Float	Eye-level Y
`last_x`, `last_y`, `last_z`	Float	Previous tick position
`yaw`, `pitch`	Float	Rotation
`width`, `height`	Float	Hitbox dimensions
`alive`	Boolean	`true` if not dead
`removed`	Boolean	`true` if removed from world
`invisible`	Boolean
`player`	Boolean	`true` if this is a player entity

Methods

entity.get_id           # => Integer
entity.get_uuid         # => String
entity.get_name         # => String
entity.get_display_name # => String
entity.get_type         # => String
entity.get_x            # => Float
entity.get_y            # => Float
entity.get_z            # => Float
entity.get_eye_y        # => Float
entity.get_last_x       # => Float  (previous tick)
entity.get_last_y       # => Float
entity.get_last_z       # => Float
entity.get_yaw          # => Float
entity.get_pitch        # => Float
entity.get_width        # => Float  hitbox width
entity.get_height       # => Float  hitbox height
entity.get_distance     # => Float  distance from local player; -1 if no local player
entity.get_health       # => Float or nil  (nil for non-living entities)
entity.get_max_health   # => Float or nil
entity.get_hurt_time    # => Integer or nil  frames since last hit

entity.is_player        # => Boolean
entity.is_living        # => Boolean
entity.is_hostile       # => Boolean
entity.is_passive       # => Boolean
entity.is_alive         # => Boolean
entity.is_removed       # => Boolean
entity.is_attackable    # => Boolean
entity.is_invisible     # => Boolean
entity.is_friend        # => Boolean  (Epitaph friends list)
entity.is_teammate      # => Boolean  (Teams feature)
entity.is_bot           # => Boolean  (AntiBot feature)

Iterating safely

Always guard for nil, dead, and removed entities:

world.get_players.each do |entity|
  next if entity.nil?
  next unless entity.alive
  next if entity.removed
  # ...
end

`targeting`

These methods check mc().crosshairTarget directly. None of them take arguments.

targeting.get_type   # => "entity", "block", or "miss"
targeting.is_entity  # => Boolean
targeting.is_block   # => Boolean
targeting.is_miss    # => Boolean
targeting.get_entity # => entity object or nil
targeting.get_block  # => block hit object or nil

targeting.get returns the full hit result table:

hit = targeting.get
# hit.type       => "entity", "block", or "miss"
# hit.is_entity  => Boolean
# hit.is_block   => Boolean
# hit.is_miss    => Boolean
# hit.x, hit.y, hit.z  => Float  exact hit position
# hit.entity     => entity object (when is_entity)
# hit.entity_id  => Integer       (when is_entity)
# hit.block      => block hit object (when is_block)

Block hit object

block = targeting.get_block
# block.x, block.y, block.z   => Integer  block position
# block.side                   => String   face name: "up", "down", "north", "south", "east", "west"
# block.hit_x, block.hit_y, block.hit_z  => Float  exact cursor position on the face

Raycasts

# reach: Float distance
# yaw, pitch: optional Float overrides (default: player's current rotation)
targeting.raycast(reach)                  # => hit result or nil
targeting.raycast(reach, yaw, pitch)      # => hit result or nil
targeting.raycast_through_walls(reach)    # => hit result or nil
targeting.raycast_through_walls(reach, yaw, pitch)

Example — entity list HUD

script = {
  name: "Nearby Players",
  description: "Lists nearby players on screen.",
  category: "RENDER",

  on_load: lambda do
    mod.register_double_setting("Max Distance", 32.0, 1.0, 128.0, 1.0)
  end,

  on_render_2d: lambda do |event|
    return unless player.is_present && world.is_present

    max_dist = mod.get_setting_value("Max Distance") || 32.0
    self_id  = player.get_id
    white    = render.color(255, 255, 255, 255)
    y        = 8

    world.get_players.each do |entity|
      next if entity.nil? || !entity.alive || entity.removed
      next if entity.id == self_id
      next if entity.get_distance > max_dist

      render.text("#{entity.name}  #{entity.get_distance.round(1)}m", 8, y, white, true)
      y += 10
    end
  end
}

Example — block targeting

script = {
  name: "Block Info",
  description: "Shows targeted block coords in chat on key press.",
  category: "MISC",

  on_key: lambda do |event|
    return unless event.pressed
    return unless targeting.is_block

    block = targeting.get_block
    client.message("Block at #{block.x}, #{block.y}, #{block.z}  side: #{block.side}")
  end
}