Combat API

Access combat stats, health, special attack, and combat state.

Constants

combat.Style

Combat style enum for type-safe style selection.

combat.Style.ACCURATE     -- "ACCURATE"
combat.Style.AGGRESSIVE   -- "AGGRESSIVE"
combat.Style.CONTROLLED   -- "CONTROLLED"
combat.Style.DEFENSIVE    -- "DEFENSIVE"

Example:

-- Use enum for type safety
combat:switch_style(combat.Style.ACCURATE)

-- Check current style
if combat:get_style() == combat.Style.AGGRESSIVE then
    logger:info("Using aggressive style")
end

---

Functions

current_health

combat:current_health() -> number

Gets current HP.

Returns:

• number - Current health points

---

max_health

combat:max_health() -> number

Gets maximum HP (hitpoints level × 10).

Returns:

• number - Maximum health points

---

health_percentage

combat:health_percentage() -> number

Gets health as percentage (0-100).

Returns:

• number - Health percentage

---

is_low_health

combat:is_low_health(threshold: number?) -> boolean

Checks if health is below threshold.

Parameters:

Parameter	Type	Required	Description
threshold	number	No	Threshold percentage (default: 30)

Returns:

• boolean - True if health is low

Example:

if combat:is_low_health(20) then
    logger:warn("Health critical!")
    -- Drink healing potion
end

---

special_attack_percentage

combat:special_attack_percentage() -> number

Gets special attack energy (0-100).

Returns:

• number - Special attack percentage

---

is_special_attack_queued

combat:is_special_attack_queued() -> boolean

Checks if special attack is queued.

Returns:

• boolean - True if queued

---

toggle_special_attack

combat:toggle_special_attack(enable: boolean) -> boolean

Toggles special attack on/off.

Parameters:

Parameter	Type	Required	Description
enable	boolean	Yes	True to enable, false to disable

Returns:

• boolean - True if successful

---

is_auto_retaliate_enabled

combat:is_auto_retaliate_enabled() -> boolean

Checks if auto-retaliate is enabled.

Returns:

• boolean - True if enabled

---

is_in_multi_combat

combat:is_in_multi_combat() -> boolean

Checks if in multi-combat area.

Returns:

• boolean - True if in multi-combat zone

---

is_poisoned

combat:is_poisoned() -> boolean

Checks if player is poisoned.

Returns:

• boolean - True if poisoned

---

is_venomed

combat:is_venomed() -> boolean

Checks if player is venomed (a stronger form of poison).

Returns:

• boolean - True if venomed

Example:

if combat:is_venomed() then
    logger:warn("Player is venomed! Use anti-venom!")
    -- Use anti-venom potion
end

---

is_poison_immune

combat:is_poison_immune() -> boolean

Checks if player has poison immunity.

Returns:

• boolean - True if immune

---

is_teleblocked

combat:is_teleblocked() -> boolean

Checks if player is teleblocked.

Returns:

• boolean - True if teleblocked

---

get_style

combat:get_style() -> string?

Gets current combat style.

Returns:

• string? - One of: "ACCURATE", "AGGRESSIVE", "CONTROLLED", "DEFENSIVE"

Example:

local style = combat:get_style()
if style == combat.Style.AGGRESSIVE then
    logger:info("Currently in aggressive mode")
end

---

switch_style

combat:switch_style(style: string) -> boolean

Switches to a combat style. Accepts both enum values and string literals (case-insensitive).

Parameters:

Parameter	Type	Required	Description
style	string	Yes	Style name (use combat.Style.* constants or string)

Returns:

• boolean - True if successful

Example:

-- Using enum (recommended)
combat:switch_style(combat.Style.ACCURATE)

-- Using string (case-insensitive)
combat:switch_style("defensive")
combat:switch_style("CONTROLLED")

---

wilderness_level

combat:wilderness_level() -> number

Gets wilderness level (-1 if not in wilderness).

Returns:

• number - Wilderness level or -1

---

Common Patterns

Emergency Health Check

local function handle_low_health()
    if combat:is_low_health(15) then
        logger:warn("Critical health: " .. combat:current_health())

        -- Drink potion
        local potion = inventory:find_first({name_contains = "Potion"})
        if potion then
            potion:click()
        else
            -- Log out if no potion
            logger:error("No potions available!")
            return false
        end
    end

    return true
end

---

Combat Monitoring

local function monitor_combat()
    logger:info("=== Combat Stats ===")
    logger:info("HP: " .. combat:current_health() .. "/" .. combat:max_health() .. " (" .. combat:health_percentage() .. "%)")
    logger:info("Special: " .. combat:special_attack_percentage() .. "%")
    logger:info("Poisoned: " .. tostring(combat:is_poisoned()))
    logger:info("Teleblocked: " .. tostring(combat:is_teleblocked()))
    logger:info("Auto-retaliate: " .. tostring(combat:is_auto_retaliate_enabled()))
    logger:info("====================")
end

monitor_combat()

---

Special Attack Management

local function use_special_attack(threshold)
    threshold = threshold or 50

    if combat:special_attack_percentage() >= threshold then
        logger:info("Using special attack!")
        return combat:enable_special_attack()
    end

    return false
end

---

PvP Safety Check

local function check_pvp_safety()
    if combat:is_in_multi_combat() then
        logger:warn("In multi-combat zone!")
    end

    if combat:wilderness_level() > 0 then
        logger:warn("In wilderness level " .. combat:wilderness_level())
    end

    if combat:is_teleblocked() then
        logger:error("Teleblocked! Trapped!")
    end
end

---

Combat Style Tracking

local function ensure_combat_style(desired_style)
    local current = combat:get_style()

    if current == desired_style then
        logger:info("Already using correct style")
        return true
    end

    logger:info("Switching combat style to " .. desired_style)
    return combat:switch_style(desired_style)
end

-- Usage with enum
ensure_combat_style(combat.Style.ACCURATE)

---

Dynamic Style Switching

local function optimize_combat_style()
    local current_hp_percent = combat:health_percentage()

    if current_hp_percent < 50 then
        -- Low health, play defensive
        combat:switch_style(combat.Style.DEFENSIVE)
        logger:info("Switched to defensive (low HP)")
    else
        -- Good health, maximize damage
        combat:switch_style(combat.Style.AGGRESSIVE)
        logger:info("Switched to aggressive (good HP)")
    end
end

---

Related APIs

• Skills API - Skill levels
• Prayer API - Prayer mechanics
• Inventory API - Potion management