Client & Player

The client and player APIs give access to the local game session, HUD info, player state, and actions.

Guards

player and client are always available as objects, but many methods return nil or false when not in a game. Use player.is_present before reading player state:

return unless player.is_present

---

client

Info

client.get_version      # => String  e.g. "1.21.4"
client.get_username     # => String  current session name
client.get_fps          # => Integer current frame rate
client.get_ping         # => Integer ping to server in ms
client.get_server_address  # => String or nil
client.is_in_game       # => Boolean  player and world both present
client.is_screen_open   # => Boolean  a GUI screen is open
client.now              # => Integer  System.currentTimeMillis

Chat & clipboard

client.message("Hello")          # info message in chat (prefixed [Scripts])
client.warn("Something odd")     # same, styled as warning
client.error("Something broke")  # same, styled as error

client.send_chat("/say hi")      # sends a chat message as the player
client.copy_to_clipboard("text") # copies text to system clipboard

Actions

client.do_attack    # triggers the attack action
client.do_item_use  # triggers the use-item action

Randomness

client.random_int(1, 10)      # => Integer in [1, 10]
client.random_float(0.0, 1.0) # => Float in [0.0, 1.0]

---

player

Presence

player.is_present  # => Boolean — check this before anything else

Identity

player.get_id           # => Integer  entity ID
player.get_name         # => String
player.get_display_name # => String  formatted display name

Health & hunger

player.get_health      # => Float
player.get_max_health  # => Float
player.get_absorption  # => Float  absorption hearts
player.get_hunger      # => Integer 0–20
player.has_status_effect("speed")  # => Boolean
player.get_hurt_time   # => Integer  frames since last hit (0 = not hurt)
player.get_fall_distance  # => Float

Position & rotation

player.get_x     # => Float
player.get_y     # => Float
player.get_z     # => Float
player.get_yaw   # => Float
player.get_pitch # => Float

player.get_velocity_x  # => Float
player.get_velocity_y  # => Float
player.get_velocity_z  # => Float

Movement flags

player.is_on_ground    # => Boolean
player.is_sprinting    # => Boolean
player.is_sneaking     # => Boolean
player.is_using_item   # => Boolean
player.is_in_water     # => Boolean
player.is_in_cobweb    # => Boolean

Combat

player.is_holding_weapon  # => Boolean
player.can_crit           # => Boolean
player.get_attack_cooldown           # => Float 0.0–1.0  (base_time defaults to 0.5)
player.get_attack_cooldown(0.0)      # Float, custom base_time

Actions

player.jump
player.swing
player.set_sprinting(true)
player.set_yaw(90.0)
player.set_pitch(-30.0)
player.set_rotation(90.0, -30.0)  # yaw, pitch
player.send_chat("/say hi")

---

rotation

The rotation API provides helpers for aim assistance, including calculating rotations to entities and positions.

Rotation calculations

rotation.get_rotation_to(entity)          # => {yaw, pitch, x, y, z} to target an entity
rotation.get_rotation_to(block)           # block hit / block-pos table with x,y,z
rotation.get_rotation_to(x, y, z)         # exact world position

rotation.get_rotation_to_entity(entity)   # explicit alias
rotation.get_rotation_to_entity(entity, "Head")
rotation.get_rotation_to_entity(entity, "Body", 50.0)  # multipoint accuracy (0-100)
rotation.get_rotation_to_block(block)
rotation.get_rotation_to_block(x, y, z)

rotation.get_to_entity(entity)            # legacy alias
rotation.get_to_entity(entity, "Head")
rotation.get_to_entity(entity, "Body", 50.0)
rotation.get_to_position(x, y, z)
rotation.get_to_block(block)
rotation.get_to_block(x, y, z)

All rotation methods return a table with yaw, pitch, x, y, and z keys.

Angle difference helpers

rotation.get_angle_diff(entity)     # => {yaw, pitch, total} angle difference from current rotation
rotation.get_yaw_diff(entity)       # => Float yaw difference in degrees (-180 to 180)
rotation.get_pitch_diff(entity)     # => Float pitch difference in degrees
rotation.get_abs_angle_diff(entity) # => Float combined Euclidean angle difference
rotation.apply_gcd(current, target) # => Float snapped to the client's mouse GCD step

rotation.apply_gcd(current, target) is useful before player.set_yaw, player.set_pitch, or player.set_rotation if you want your scripted rotations to look like native client input.

Distance

rotation.get_distance_to(entity)  # => Float distance to entity in blocks

---

Example — session HUD

script = {
  name: "Session HUD",
  description: "Shows username, health, and ping.",
  category: "RENDER",

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

    white  = render.color(255, 255, 255, 255)
    yellow = render.color(255, 220, 50, 255)

    render.text("#{player.get_name}  HP #{player.get_health.round(1)}", 8, 8, white, true)
    render.text("Ping: #{client.get_ping} ms", 8, 20, yellow, true)
  end
}

Example — auto-sprint

script = {
  name: "Auto Sprint",
  description: "Keeps sprinting while moving forward.",
  category: "MISC",

  on_tick: lambda do |_event|
    return unless player.is_present
    return if player.is_sprinting
    return unless input.is_forward_pressed

    player.set_sprinting(true)
  end
}

Example — aim assist

script = {
  name: "Aim Assist",
  description: "Smoothly aims at the nearest player.",
  category: "COMBAT",
  max_range: 5.0,
  smoothing: 3.0,

  on_tick: lambda do |_event|
    return unless player.is_present

    target = nil
    min_dist = 100.0

    world.get_players.each do |p|
      next if p.is_player == false
      next if p.get_name == player.get_name
      next if friends.is_friend(p.get_name)

      dist = rotation.get_distance_to(p)
      if dist and dist < min_dist
        min_dist = dist
        target = p
      end
    end

    return unless target

    rot = rotation.get_rotation_to_entity(target, "Head")
    if rot
      current_yaw = player.get_yaw
      current_pitch = player.get_pitch

      yaw_diff = rot.yaw - current_yaw
      yaw_diff = yaw_diff - 360.0 if yaw_diff > 180.0
      yaw_diff = yaw_diff + 360.0 if yaw_diff < -180.0

      pitch_diff = rot.pitch - current_pitch

      smoothing = 3.0
      new_yaw = current_yaw + (yaw_diff / smoothing)
      new_pitch = current_pitch + (pitch_diff / smoothing)

      player.set_rotation(new_yaw, new_pitch)
    end
  end
}

Related Reference

• Available APIs
• Event Callbacks