builtin map - boyism80/fb GitHub Wiki

Built-in Functions Documentation (Map)

This document describes functions available to map type objects.

model

model()

  • Description:
    Returns the map model (fb.model.map) that this map is based on.
  • Parameters:
    • None
  • Return Value:
    • fb.model.map: Map model object
  • Example: 
    -- This is a real usage example from game scripts
local map_model = current_map:model()
me:message("Map: " .. map_model:name())

width

width()

  • Description:
    Returns the width of the map in tiles.
  • Parameters:
    • None
  • Return Value:
    • number: Map width
  • Example: 
    -- This is a real usage example from game scripts
local map_width = current_map:width()
me:message("Map width: " .. map_width)

height

height()

  • Description:
    Returns the height of the map in tiles.
  • Parameters:
    • None
  • Return Value:
    • number: Map height
  • Example: 
    -- This is a real usage example from game scripts
local map_height = current_map:height()
me:message("Map height: " .. map_height)

area

area()

  • Description:
    Returns the width and height of the map.
  • Parameters:
    • None
  • Return Value:
    • number, number: Width and height of the map
  • Example: 
    -- This is a real usage example from game scripts
local w, h = me:map():area()
me:message("Map size: " .. w .. "x" .. h)

objects

objects([type:OBJECT_TYPE])

  • Description:
    Returns a table containing all objects on the map, optionally filtered by type.
  • Parameters:
    • [type:OBJECT_TYPE]: Optional. The type of objects to return (e.g., OBJECT_TYPE_MOB, OBJECT_TYPE_ITEM). If omitted, all objects are returned.
  • Return Value:
    • table: A table of fb.game.object instances.
  • Example: 
    -- This is a real usage example from game scripts
-- Get all mobs on the current map
local mobs = me:map():objects(OBJECT_TYPE_MOB)
me:message("Found " .. #mobs .. " mobs on the map.")

-- Get all items on the map
local items = me:map():objects(OBJECT_TYPE_ITEM)
for _, item in ipairs(items) do
  me:message("Found item: " .. item:name())
end

nears

nears(position:table[, type:OBJECT_TYPE])

  • Description:
    Returns objects near the specified position on the map.
  • Parameters:
    • position:table: Position table with {x, y} coordinates
    • [type:OBJECT_TYPE]: Optional. The type of objects to return (e.g., OBJECT_TYPE_CHARACTER, OBJECT_TYPE_MOB). If omitted, all objects are returned.
  • Return Value:
    • table: Table containing nearby objects
  • Example: 
    -- This is a real usage example from game scripts
local position = {10, 20}
local nearby_objects = map:nears(position)  -- Get all nearby objects
for i, obj in ipairs(nearby_objects) do
    me:message("Found object: " .. obj:name())
end

-- Get only characters near position
local nearby_chars = map:nears(position, OBJECT_TYPE_CHARACTER)

movable

movable(object:fb.game.object, position)

  • Description:
    Checks if the specified object can move to the given position on the map.
  • Parameters:
    • object:fb.game.object: Object to check movement for
    • position: Target position (table {x, y}, x/y coordinates, or object reference)
  • Return Value:
    • boolean: True if movement is possible, false otherwise
  • Example: 
    -- This is a real usage example from game scripts
if current_map:movable(me, {150, 200}) then
    me:message("Can move to that position")
else
    me:message("Cannot move there")
end

door

door(position)

  • Description:
    Gets the door at the specified position.
  • Parameters:
    • position: Position to check (table {x, y} or x, y coordinates)
  • Return Value:
    • fb.game.door|nil: Door object or nil if none exists
  • Example: 
    -- This is a real usage example from game scripts
local door = current_map:door({100, 100})
if door then
    me:message("Found a door")
end

doors

doors()

  • Description:
    Returns a table containing all doors on the map.
  • Parameters:
    • None
  • Return Value:
    • table: Table containing all doors
  • Example: 
    -- This is a real usage example from game scripts
for _, door in pairs(current_map:doors()) do
    me:message("Door found on map")
end

contains

contains(object:fb.game.object)

  • Description:
    Checks if the specified object is on this map.
  • Parameters:
    • object:fb.game.object: Object to check
  • Return Value:
    • boolean: True if object is on this map, false otherwise
  • Example: 
    -- This is a real usage example from game scripts
if current_map:contains(target) then
    me:message("Target is on this map")
end

belows

belows(position)

  • Description:
    Returns objects that are below/under the specified position.
  • Parameters:
    • position: Position to check (table {x, y} or x, y coordinates)
  • Return Value:
    • table: Table containing objects below the position
  • Example: 
    -- This is a real usage example from game scripts
local below_objects = current_map:belows({100, 100})
for _, obj in pairs(below_objects) do
    me:message("Object below: " .. obj:name())
end

tile

tile(position)

  • Description:
    Returns the tile information at the specified position.
  • Parameters:
    • position: Position to check (table {x, y} or x, y coordinates)
  • Return Value:
    • number: Tile type/ID
  • Example: 
    -- This is a real usage example from game scripts
local tile_type = current_map:tile({100, 100})
me:message("Tile type: " .. tile_type)

at

at(x:number, y:number[, object_type:OBJECT_TYPE])

  • Description:
    Returns the first object at the specified position of the given type.
  • Parameters:
    • x:number: X coordinate
    • y:number: Y coordinate
    • [object_type:OBJECT_TYPE]: Object type filter (default: OBJECT_TYPE_UNKNOWN)
  • Return Value:
    • fb.game.object|nil: Object at the position or nil if none found
  • Example: 
    -- This is a real usage example from game scripts
local obj = map:at(10, 20)  -- Get any object at position (10, 20)
if obj then
    me:message("Found object: " .. obj:name())
end

-- Get only character at specific position
local character = map:at(15, 25, OBJECT_TYPE_CHARACTER)
if character then
    me:message("Character found: " .. character:name())
end