A World represents a game server/world with information about its properties, population, and requirements.

world:number() -> number

Returns the world number (e.g., 301, 302, 303).

Returns:

• number: The world number

Example:

local current = worlds.current()
if current then
    logger:info("Current world: " .. current:number())
end

---

world:id() -> number

Alias for number(). Returns the world ID.

Returns:

• number: The world number

---

world:population() -> number

Returns the current player population on this world.

Returns:

• number: The number of players

Example:

local worlds_list = worlds:all()
for _, world in ipairs(worlds_list) do
    if world:population() < 500 then
        logger:info("Low pop world: " .. world:number() .. " (" .. world:population() .. " players)")
    end
end

---

world:text_color() -> number

Returns the text color for display (RGB value).

Returns:

• number: The RGB color value

---

world:world_type() -> string

Returns the world type as a string.

Returns:

• string: One of: "members" or "free"

Example:

local world = worlds.current()
if world and world:world_type() == "members" then
    logger:info("On a members world")
end

---

world:type() -> string

Alias for world_type(). Returns the world type as a string.

Returns:

• string: World type

---

world:specialty() -> string

Returns the world's specialty/activity type.

Returns:

• string: The specialty string value. Use worlds.Specialty enum constants for comparison:
  • worlds.Specialty.NONE - Regular world
  • worlds.Specialty.PVP_WORLD - PVP world
  • worlds.Specialty.HIGH_RISK - High risk world
  • worlds.Specialty.DEADMAN_MODE - Deadman Mode
  • worlds.Specialty.LEAGUES - Leagues world
  • worlds.Specialty.TOURNAMENT - Tournament world
  • worlds.Specialty.SKILL_TOTAL - Skill total requirement
  • worlds.Specialty.BETA - Beta world
  • worlds.Specialty.SPEED_RUNNING - Speed running world
  • worlds.Specialty.QUEST_SPEED_RUNNING - Quest speed running
  • worlds.Specialty.FRESH_START - Fresh Start world
  • worlds.Specialty.LMS_CASUAL - LMS Casual
  • worlds.Specialty.LMS_COMPETITIVE - LMS Competitive
  • worlds.Specialty.PVP_ARENA - PvP Arena
  • worlds.Specialty.TRADE - Trade world
  • worlds.Specialty.FORESTRY - Forestry
  • worlds.Specialty.CASTLE_WARS - Castle Wars
  • worlds.Specialty.CLAN_RECRUITMENT - Clan Recruitment
  • worlds.Specialty.TEMPOROSS - Tempoross
  • worlds.Specialty.BLAST_FURNACE - Blast Furnace
  • worlds.Specialty.ZEAH_RUNECRAFTING - Zeah Runecrafting
  • worlds.Specialty.YAMA - Yama
  • worlds.Specialty.SOUL_WARS - Soul Wars
  • worlds.Specialty.BRIMHAVEN_AGILITY - Brimhaven Agility
  • worlds.Specialty.TOMBS_OF_AMASCUT - Tombs of Amascut
  • worlds.Specialty.ROLE_PLAYING - Role-playing
  • worlds.Specialty.BARBARIAN_ASSAULT - Barbarian Assault
  • worlds.Specialty.WINTERTODT - Wintertodt
  • worlds.Specialty.BOUNTY_HUNTER - Bounty Hunter World
  • worlds.Specialty.GUARDIANS_OF_THE_RIFT - Guardians of the Rift
  • worlds.Specialty.GROUP_PVM - Group PvM
  • worlds.Specialty.HOUSE_PARTY - House Party, Gilded Altar

Example:

local world = worlds.current()
if world then
    local spec = world:specialty()
    if spec ~= worlds.Specialty.NONE then
        logger:info("Special world type: " .. spec)
    end
end

---

world:server() -> string

Returns the server location.

Returns:

• string: One of:
  • "runescape" - General RuneScape server
  • "us" - United States
  • "uk" - United Kingdom
  • "au" - Australia
  • "de" - Germany
  • "unknown" - Unknown location

Example:

local world = worlds.current()
if world then
    logger:info("Server location: " .. world:server())
end

---

world:min_total_level() -> number

Returns the minimum total level requirement for this world.

Returns:

• number: The minimum total level, or -1 if no requirement

Example:

local world = worlds:find_first({
    world_type = "members",
    min_total_level_greater_than = 1500
})

if world then
    logger:info("Found skill world: " .. world:number() .. " (requires " .. world:min_total_level() .. " total)")
end

---

world:is_valid() -> boolean

Checks if this is a valid world (number > 0).

Returns:

• boolean: True if valid

---

world:is_members() -> boolean

Checks if this is a members world.

Returns:

• boolean: True if members world

Example:

local world = worlds.current()
if world and world:is_members() then
    logger:info("Members content available")
end

---

world:is_free() -> boolean

Checks if this is a free-to-play world.

Returns:

• boolean: True if F2P world

---

world:is_pvp() -> boolean

Checks if this is a PVP world.

Returns:

• boolean: True if PVP world

Example:

local world = worlds.current()
if world and world:is_pvp() then
    logger:warn("WARNING: On a PVP world!")
end

---

world:has_skill_requirement() -> boolean

Checks if this world has a skill total requirement.

Returns:

• boolean: True if there's a skill requirement

---

world:name() -> string

Returns the world name (e.g., "World 301").

Returns:

• string: The world name

Example:

local world = worlds.current()
if world then
    logger:info("Connected to: " .. world:name())
end

---

local function find_low_pop_world(max_population)
    local all_worlds = worlds:all()
    local candidates = {}
    
    for _, world in ipairs(all_worlds) do
        if world:is_members() and world:population() < max_population then
            if world:specialty() == worlds.Specialty.NONE then  -- Regular world only
                table.insert(candidates, world)
            end
        end
    end
    
    -- Sort by population
    table.sort(candidates, function(a, b)
        return a:population() < b:population()
    end)
    
    return candidates[1]
end

local quiet_world = find_low_pop_world(300)
if quiet_world then
    logger:info("Found quiet world: " .. quiet_world:number() .. " (" .. quiet_world:population() .. " players)")
end

---

local function hop_to_best_world()
    local all_worlds = worlds:all()
    local best = nil
    local best_score = -1
    
    for _, world in ipairs(all_worlds) do
        if world:is_members() and world:specialty() == worlds.Specialty.NONE then
            -- Score based on low population
            local score = 2000 - world:population()
            
            -- Prefer US servers
            if world:server() == "us" then
                score = score + 500
            end
            
            -- Avoid skill requirement worlds
            if world:has_skill_requirement() then
                score = score - 1000
            end
            
            if score > best_score then
                best = world
                best_score = score
            end
        end
    end
    
    if best then
        logger:info("Hopping to world " .. best:number())
        worlds.hop(best:number())
        return true
    end
    
    return false
end

---

local function is_safe_world(world)
    if world:is_pvp() then
        return false, "PVP world"
    end
    
    if world:specialty() == worlds.Specialty.HIGH_RISK then
        return false, "High risk world"
    end
    
    if world:specialty() == worlds.Specialty.DEADMAN_MODE then
        return false, "Deadman mode"
    end
    
    return true, "Safe world"
end

local current = worlds.current()
if current then
    local safe, reason = is_safe_world(current)
    if not safe then
        logger:warn("Unsafe world: " .. reason)
    end
end

---

local function find_skill_world(min_level)
    local all_worlds = worlds:all()
    
    for _, world in ipairs(all_worlds) do
        if world:has_skill_requirement() then
            if world:min_total_level() >= min_level then
                logger:info("Found skill world " .. world:number() .. " (requires " .. world:min_total_level() .. ")")
                return world
            end
        end
    end
    
    return nil
end

local high_level_world = find_skill_world(2000)

---

local function find_regional_world(region)
    local all_worlds = worlds:all()
    local regional = {}
    
    for _, world in ipairs(all_worlds) do
        if world:server() == region and world:is_members() then
            if world:specialty() == worlds.Specialty.NONE then
                table.insert(regional, world)
            end
        end
    end
    
    -- Sort by population
    table.sort(regional, function(a, b)
        return a:population() < b:population()
    end)
    
    return regional
end

-- Find US servers
local us_worlds = find_regional_world("us")
logger:info("Found " .. #us_worlds .. " US worlds")

---

local function display_world_info(world)
    logger:info("===== World Info =====")
    logger:info("Number: " .. world:number())
    logger:info("Name: " .. world:name())
    logger:info("Population: " .. world:population())
    logger:info("Type: " .. world:world_type())
    logger:info("Specialty: " .. world:specialty())
    logger:info("Server: " .. world:server())
    
    if world:has_skill_requirement() then
        logger:info("Skill requirement: " .. world:min_total_level())
    end
    
    logger:info("Members: " .. tostring(world:is_members()))
    logger:info("PVP: " .. tostring(world:is_pvp()))
    logger:info("======================")
end

local current = worlds.current()
if current then
    display_world_info(current)
end

---

local function is_too_crowded(world, max_pop)
    return world:population() > max_pop
end

local function hop_if_crowded(threshold)
    local current = worlds.current()
    if not current then return false end
    
    if is_too_crowded(current, threshold) then
        logger:info("World too crowded (" .. current:population() .. " players)")
        
        -- Find less crowded alternative
        local all_worlds = worlds:all()
        for _, world in ipairs(all_worlds) do
            if not is_too_crowded(world, threshold) then
                if world:is_members() and world:specialty() == worlds.Specialty.NONE then
                    logger:info("Hopping to world " .. world:number())
                    worlds.hop(world:number())
                    return true
                end
            end
        end
    end
    
    return false
end

hop_if_crowded(800)  -- Hop if more than 800 players

---

Worlds are typically accessed through the worlds API module:

-- Get current world
local current = worlds.current()

-- Get all worlds
local all_worlds = worlds:all()

-- Find worlds by filters
local members_worlds = worlds:find({
    world_type = "members"
})

-- Find first matching world
local pvp_world = worlds:find_first({
    specialty = worlds.Specialty.PVP_WORLD
})

• Worlds API documentation for finding and hopping between worlds