Worlds API

World/server information and world hopping:

Functions

current

worlds:current() -> World?

Get current world information:

Returns:

• World? - Current world, or nil

Example:

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

---

is_current_world_members

worlds:is_current_world_members() -> boolean

Check if the current world is a members world:

Returns:

• boolean - True if current world is members

---

all

worlds:all() -> table

Get all worlds:

Returns:

• table - Array of World objects

---

members_only

worlds:members_only() -> table

Get all members-only worlds:

Returns:

• table - Array of members World objects

---

free_only

worlds:free_only() -> table

Get all free-to-play worlds:

Returns:

• table - Array of free-to-play World objects

---

pvp_only

worlds:pvp_only() -> table

Get all PVP worlds:

Returns:

• table - Array of PVP World objects

---

with_skill_requirement

worlds:with_skill_requirement() -> table

Get all worlds that have a skill total requirement:

Returns:

• table - Array of World objects with skill requirements

---

find_by_number

worlds:find_by_number(number: number) -> World?

Find a world by its number (e.g. 301, 302):

Parameters:

Parameter	Type	Required	Description
number	number	Yes	World number to find

Returns:

• World? - Matching world, or nil

Example:

local world = worlds:find_by_number(301)
if world then
    logger:info("Found world: " .. world:name())
end

---

lowest_population

worlds:lowest_population(members_only: boolean?) -> World?

Find the world with the lowest population:

Parameters:

Parameter	Type	Required	Description
members_only	boolean	No	If true, only search members worlds: If false, only search F2P worlds: If nil, search all worlds

Returns:

• World? - World with lowest population, or nil

Example:

local quiet_world = worlds:lowest_population(true)  -- Lowest pop members world
if quiet_world then
    quiet_world:hop()
end

---

highest_population

worlds:highest_population(members_only: boolean?) -> World?

Find the world with the highest population:

Parameters:

Parameter	Type	Required	Description
members_only	boolean	No	If true, only search members worlds: If false, only search F2P worlds: If nil, search all worlds

Returns:

• World? - World with highest population, or nil

---

opened

worlds:opened() -> boolean

Check if the world list interface is open:

Returns:

• boolean - True if world list is open

---

open

worlds:open() -> boolean

Open the world list interface:

Returns:

• boolean - True if successfully opened

---

scroll_to

worlds:scroll_to(world_id: number) -> boolean

Scroll the world list to make a specific world visible:

Parameters:

Parameter	Type	Required	Description
world_id	number	Yes	World number to scroll to

Returns:

• boolean - True if scroll was successful

---

hop_to

worlds:hop_to(world_id: number) -> boolean

Hop to a specific world by its ID:

Parameters:

Parameter	Type	Required	Description
world_id	number	Yes	World number to hop to

Returns:

• boolean - True if successful

Example:

if worlds:hop_to(301) then
    logger:info("Successfully hopped to World 301")
else
    logger:warn("Failed to hop to World 301")
end

---

World Object Methods

World objects returned by the Worlds API have the following methods:

hop

world:hop() -> boolean

Hop to this world: This is a convenience method that calls worlds:hop_to(world:number()):

Returns:

• boolean - True if successful

Example:

local world = worlds:find_by_number(301)
if world then
    world:hop()  -- Hop to this world
end

is_current

world:is_current() -> boolean

Check if this is the current world the player is logged into:

Returns:

• boolean - True if this is the current world

Example:

local world = worlds:find_by_number(301)
if world and world:is_current() then
    logger:info("Already on World 301")
end

For a complete list of World object methods, see the methods listed above:

---

Common Patterns

Find Low Population World

-- Using the built-in method (recommended)
local quiet = worlds:lowest_population(true)  -- Lowest pop members world
if quiet then
    quiet:hop()
end

-- Or manually iterate
local function find_quiet_world()
    local worlds_list = worlds:members_only()
    
    local best = nil
    local best_pop = 999999
    
    for _, world in ipairs(worlds_list) do
        if world:population() < best_pop then
            best = world
            best_pop = world:population()
        end
    end
    
    return best
end

local quiet = find_quiet_world()
if quiet then
    quiet:hop()
end

---

World Safety Check

local function is_safe_world(world)
    if world:is_pvp() then
        return false
    end
    
    return true
end

-- Find a safe, quiet members world
local safe_worlds = worlds:members_only()
for _, world in ipairs(safe_worlds) do
    if is_safe_world(world) and world:population() < 200 then
        world:hop()
        break
    end
end

---

Hop to World with Retry

local function hop_to_world_with_retry(world_id, max_attempts)
    max_attempts = max_attempts or 3
    
    for i = 1, max_attempts do
        if worlds:hop_to(world_id) then
            return true
        end
        
        if i < max_attempts then
            wait:time(1000)  -- Wait 1 second before retry
        end
    end
    
    return false
end

if hop_to_world_with_retry(301, 3) then
    logger:info("Successfully hopped to World 301")
else
    logger:error("Failed to hop to World 301 after 3 attempts")
end

---

Specialty Enum

The worlds.Specialty enum provides constants for world specialty/activity types. Use these constants when comparing or filtering worlds by specialty:

-- Check if world is a regular world
if world:specialty() == worlds.Specialty.NONE then
    logger:info("Regular world")
end

-- Find PvP worlds
local pvp_worlds = worlds:find_all({
    specialty = worlds.Specialty.PVP_WORLD
})

-- Available constants:
-- worlds.Specialty.NONE
-- worlds.Specialty.PVP_WORLD
-- worlds.Specialty.HIGH_RISK
-- worlds.Specialty.DEADMAN_MODE
-- worlds.Specialty.LEAGUES
-- worlds.Specialty.TOURNAMENT
-- worlds.Specialty.SKILL_TOTAL
-- worlds.Specialty.BETA
-- worlds.Specialty.SPEED_RUNNING
-- worlds.Specialty.QUEST_SPEED_RUNNING
-- worlds.Specialty.FRESH_START
-- worlds.Specialty.LMS_CASUAL
-- worlds.Specialty.LMS_COMPETITIVE
-- worlds.Specialty.PVP_ARENA
-- worlds.Specialty.TRADE
-- worlds.Specialty.FORESTRY
-- worlds.Specialty.CASTLE_WARS
-- worlds.Specialty.CLAN_RECRUITMENT
-- worlds.Specialty.TEMPOROSS
-- worlds.Specialty.BLAST_FURNACE
-- worlds.Specialty.ZEAH_RUNECRAFTING
-- worlds.Specialty.YAMA
-- worlds.Specialty.SOUL_WARS
-- worlds.Specialty.BRIMHAVEN_AGILITY
-- worlds.Specialty.TOMBS_OF_AMASCUT
-- worlds.Specialty.ROLE_PLAYING
-- worlds.Specialty.BARBARIAN_ASSAULT
-- worlds.Specialty.WINTERTODT
-- worlds.Specialty.BOUNTY_HUNTER
-- worlds.Specialty.GUARDIANS_OF_THE_RIFT
-- worlds.Specialty.GROUP_PVM
-- worlds.Specialty.HOUSE_PARTY

---

Related APIs

• Game API - Game client state: