Map

The Map object represents the current map. Provides access to entities such as mobs, NPCs, drops, portals, and map terrain data.

#Functions

#Validation & Basic Info

#map:is_valid() -> boolean

Available on GMS and CWGMSCW

Validates the object exists in the game world. Always call this first.

#map:get_id() -> number

Available on GMS and CWGMSCW

Returns the map ID.

#map:is_town() -> boolean

Available on GMS and CWGMSCW

Returns true if the map is a town (safe zone).

#map:get_burning_stage() -> number | nil

Available on GMS and CWGMSCW

Returns the burning XP stage (0-10) or nil if unavailable.

#Drops & Portals

#Drop Object Structure

#map:get_drops() -> table<drop>

Available on GMS and CWGMSCW

Returns all drops available to the player (shared and personal).

The list is already filtered to drops you may loot, so own_type tells you why one is yours rather than whether it is — use it to skip free-for-all drops you would rather leave, or to take only your personal ones. source_id matches mob:get_unique_id(), so you can confirm a specific kill produced a drop before walking over to it.

#Portal Object Structure

#map:get_portals() -> table<portal>

Available on GMS and CWGMSCW

Returns all portals on the map.

#Entities

#map:get_mobs() -> table<Mob>

Available on GMS and CWGMSCW

Returns all mobs on the map. See Mob.

#map:get_bosses() -> table<Mob>

Available on GMS and CWGMSCW

Returns all boss mobs on the map. See Mob.

#map:get_mob_count() -> number

Available on GMS and CWGMSCW

Returns the number of alive mobs. More efficient than iterating get_mobs().

#map:get_npcs() -> table<NPC>

Available on GMS and CWGMSCW

Returns all NPCs on the map. See NPC.

#Reactor Object Structure

Reactors (interactive map objects — switches, boxes, gathering nodes) currently in the field. Each entry is a plain table — not a bound object, so it has no methods.

#map:get_reactors() -> table<reactor>

Available on GMS and CWGMSCW

Returns all reactors currently in the field.

#map:interact_reactor(id: number) -> boolean

Available on GMS and CWGMSCW

Interacts with the reactor whose runtime id is given, as the interaction key does, such as the Afterlands' Solar Pulley. In GMS, a reactor that reacts to being clicked, such as the objects that summon the Root Abyss bosses, is clicked instead. The character must be close to it, and some quest objects only respond to the character they belong to. A reactor that reacts only to being touched, to a key press or to chat may not respond. Quest objects that are NPCs are talked to with npc:talk().

Returns: true when the interaction was sent. false when no reactor with that id is in the field, or when a reactor that is clicked can't be clicked yet: your character is dead or stands outside the area it can be clicked from. To see whether it worked, read the reactor again a moment later: its state changes (with previous_state set) or it disappears when the game accepts; it drops back or stays put when the game refuses.

local map = core.object_manager.get_current_map()
for _, r in ipairs(map:get_reactors()) do
    if r.template_id == 8659064 then
        map:interact_reactor(r.id)
    end
end

#map:get_clock() -> number | nil

Available on GMS and CWGMSCW

Returns the seconds left on the map's countdown clock, or nil when the map has none.

#Rune Object Structure

The active runestone on the field. Maps only ever have one rune at a time, so this is a single plain table (or nil) rather than a list — not a bound object, so it has no methods.

#map:get_rune() -> rune?

Available on GMSGMS

Returns the active rune on the map, or nil if there is none.

#Key Prompt Object Structure

Your character's timed key prompt, as in Tengu's fight in Mushroom Shrine. A plain table (or nil), not a bound object.

#map:get_key_prompt() -> key_prompt?

Available on GMSGMS

Returns your character's timed key prompt on this map, or nil when none is pending.

The prompt that starts an attack is armed first (open is false, step is 0). It appears partway through the monster's attack, but only if at that moment you are within 400 pixels of it, left or right, and able to move. A prompt takes the first of its five keys you press: the expected key passes it, any of the other four fails it, and so does running out of time. on_key_prompt reports each change.

#Player Object Structure

Other players (remote characters) currently in the field. Each entry is a plain table — not a bound object, so it has no methods.

#map:get_players() -> table<player>

Available on GMS and CWGMSCW

Returns all other players currently in the field. Excludes your own character — see Local Player.

#Terrain Data

#Bounds Object Structure

#map:get_bounds() -> bounds?

Available on GMS and CWGMSCW

Returns the map's boundary rectangle, or nil if the map's terrain isn't loaded yet (during a map transition, for example).

These are the same bounds that core.input.teleport_safe clamps against, so a position inside this rect is guaranteed not to be clamped.

center is the rect's midpoint — the position Kami teleports to when no mobs are alive. Note this is the boundary midpoint, which includes empty airspace: on tall maps it can sit well above the floor. Cross-reference map:get_footholds() if you need a point that's actually standing on ground.

local map = core.object_manager.get_current_map()
local bounds = map and map:get_bounds()
if bounds then
    core.log(`map spans ${bounds.width} x ${bounds.height}`)
    core.input.teleport_safe(bounds.center.x, bounds.center.y, 0, 0)
end

#Foothold Object Structure

#map:get_footholds() -> table<foothold>

Available on GMS and CWGMSCW

Returns all footholds (platforms) on the map.

#Ladder Object Structure

#map:get_ladders() -> table<ladder>

Available on GMS and CWGMSCW

Returns all ladders and ropes on the map.

#Example

-- Map and mob monitoring
function on_tick(stage)
    if stage ~= core.stage.FIELD then return end

    local map = core.object_manager.get_current_map()
    if not map or not map:is_valid() then return end

    -- Check map type
    if map:is_town() then
        core.log("In town - safe zone")
        return
    end

    -- Check burning field
    local burning = map:get_burning_stage()
    if burning and burning > 0 then
        core.log("Burning field stage: " .. burning)
    end

    -- Monitor mob count
    local mob_count = map:get_mob_count()
    if mob_count < 5 then
        core.log_warning("Low mob count: " .. mob_count)
    end

    -- List reactors in the field
    for _, reactor in ipairs(map:get_reactors()) do
        core.log(string.format(
            "reactor %d (%s) state=%d at (%d, %d)",
            reactor.template_id, reactor.name, reactor.state,
            reactor.position.x, reactor.position.y))
    end

    -- Check for a solvable rune
    local rune = map:get_rune()
    if rune and rune.solvable then
        core.log(string.format(
            "solvable rune at (%d, %d)",
            rune.position.x, rune.position.y))
    end
end