Violet

Mob

On this page

The Mob object represents a mob entity in the game world.

Functions

mob:is_valid() -> boolean

Validates the object exists in the game world. Always call this before using other methods.

mob:get_id() -> number | nil

Returns the mob template ID or nil if unavailable.

The template ID identifies the mob species (e.g. every Blue Snail shares the same template ID). To tell two mobs of the same species apart, use mob:get_unique_id().

mob:get_unique_id() -> number | nil

Returns the unique instance ID of this specific spawned mob, or nil if unavailable.

Unlike the template ID, the unique ID is assigned by the server when the mob spawns: every mob in the map has a different one, it stays the same for the mob's whole lifetime, and it is not reused when the mob dies. This makes it the right key for tracking a specific mob across ticks.

lua
-- Lock onto a single mob and keep following that exact instance
local target_uid = nil

local function find_target(map)
    for _, mob in ipairs(map:get_mobs()) do
        if mob and mob:is_valid() then
            local uid = mob:get_unique_id()
            if target_uid == nil then
                target_uid = uid
            end
            if uid == target_uid then
                return mob
            end
        end
    end
    target_uid = nil -- target died or despawned, pick a new one next tick
    return nil
end

mob:get_position() -> table | nil

Returns position as a table with x and y fields, or nil if unavailable.

lua
local pos = mob:get_position()
if pos then
    -- pos.x, pos.y
end

mob:get_name() -> string | nil

Returns the mob name or nil if unavailable.

mob:is_elite() -> boolean | nil

Returns true if the mob belongs to the Elite Monster system — an elite monster or an elite boss — or nil if unavailable.

This is true for every special mob alike: both a trivial elite (e.g. Killer Bee, Failed Subject) and a much stronger boss-type elite (e.g. Odium's Guard). Use mob:is_boss() to tell those apart.

mob:is_boss() -> boolean | nil

Returns true if the mob's template is flagged as a boss — a designated boss-type mob (field boss, mini-boss, or a boss-type elite) that shows the boss HP bar and runs boss mechanics — or nil if unavailable.

This is independent of mob:is_elite(); a mob can be both. On a normal farming map a trivial elite and a stronger boss-type elite are both is_elite(), but only the boss-type one is is_boss() — so this is what distinguishes the tougher target when the map isn't a dedicated boss fight (where map:get_bosses() returns nothing).

lua
-- Prefer a boss-type mob on the map, otherwise fall back to any elite
local function pick_target(map)
    local elite_fallback = nil
    for _, mob in ipairs(map:get_mobs()) do
        if mob and mob:is_valid() then
            if mob:is_boss() then
                return mob            -- strongest: field boss / boss-type elite
            elseif mob:is_elite() and not elite_fallback then
                elite_fallback = mob  -- weaker elite, keep as a backup
            end
        end
    end
    return elite_fallback
end

Example

lua
-- Find closest mob to player
local player = core.object_manager.get_local_player()
local map = core.object_manager.get_current_map()

if player and player:is_valid() and map and map:is_valid() then
    local player_pos = player:get_position()
    local closest_mob = nil
    local closest_dist = math.huge

    for _, mob in ipairs(map:get_mobs()) do
        if mob and mob:is_valid() then
            local mob_pos = mob:get_position()
            if mob_pos then
                local dist = math.sqrt(
                    (mob_pos.x - player_pos.x)^2 +
                    (mob_pos.y - player_pos.y)^2
                )
                if dist < closest_dist then
                    closest_dist = dist
                    closest_mob = mob
                end
            end
        end
    end

    if closest_mob then
        core.log("Closest: " .. (closest_mob:get_name() or "Unknown"))
    end
end