builtin object - boyism80/fb GitHub Wiki

Built-in Functions Documentation (Object)

This document describes functions available to object type objects (base class for all game objects).

• model
• id
• name
• sound
• position
• front_position
• direction
• chat
• buff
• isbuff
• unbuff
• buffs
• effect
• map
• mkitem
• sight_in
• nears
• front
• is
• thread
• ptr
• near
• hidden
• __tostring
• destroy

---

model

model()

• Description:
  Returns the model object that this game object is based on.
• Parameters:
  • None
• Return Value:
  • fb.model.object: Model object
• Example:

  -- This is a real usage example from game scripts
  local model = me:model()
  me:message("Object model: " .. model:name())
  

---

id

id()

• Description:
  Returns the unique sequence ID of the object.
• Parameters:
  • None
• Return Value:
  • number: Object sequence ID
• Example:

  -- This is a real usage example from game scripts
  local obj_id = me:id()
  me:message("Object ID: " .. obj_id)
  

---

name

name()

• Description:
  Returns the name of the object.
• Parameters:
  • None
• Return Value:
  • string: Object name
• Example:

  -- This is a real usage example from game scripts
  local obj_name = me:name()
  me:message("Object name: " .. obj_name)
  

---

sound

sound(sound_type:SOUND)

• Description:
  Plays a sound effect for the object.
• Parameters:
  • sound_type:SOUND: Sound type to play (SOUND_* enum values)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:sound(SOUND_PICKUP)
  

---

position

Provides functionality to get or set the object's position.

position()

• Description:
  Returns the current position of the object as x, y coordinates.
• Parameters:
  • None
• Return Value:
  • number, number: X and Y coordinates
• Example:

  -- This is a real usage example from game scripts
  local x, y = me:position()
  me:message("Position: " .. x .. ", " .. y)
  

position(x:number, y:number)

• Description:
  Sets the object's position to the specified coordinates.
• Parameters:
  • x:number: X coordinate
  • y:number: Y coordinate
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:position(100, 150)
  

position(table)

• Description:
  Sets the object's position using a table containing x, y coordinates.
• Parameters:
  • table: Table with x, y coordinates as {x, y}
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:position({100, 150})
  

---

front_position

front_position()

• Description:
  Returns the position in front of the object based on its current direction.
• Parameters:
  • None
• Return Value:
  • number, number: X and Y coordinates of front position
• Example:

  -- This is a real usage example from game scripts
  local front_x, front_y = me:front_position()
  me:message("Front position: " .. front_x .. ", " .. front_y)
  

---

direction

Provides functionality to get or set the object's facing direction.

direction()

• Description:
  Returns the current facing direction of the object.
• Parameters:
  • None
• Return Value:
  • number: Direction value (0-7)
• Example:

  -- This is a real usage example from game scripts
  local dir = me:direction()
  me:message("Facing direction: " .. dir)
  

direction(value:number)

• Description:
  Sets the object's facing direction.
• Parameters:
  • value:number: Direction value (0-7)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:direction(2)  -- Face south
  

---

chat

chat(message:string[, type:CHAT_TYPE][, decorate:boolean])

• Description:
  Makes the object display a chat message.
• Parameters:
  • message:string: Message to display
  • [type:CHAT_TYPE]: Chat type (default: CHAT_TYPE_NORMAL)
  • [decorate:boolean]: Whether to decorate the message (default: true)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  npc:chat("Welcome to our shop!")
  npc:chat("Important announcement", CHAT_TYPE_SHOUT)
  

---

buff

buff(spell_name_or_model:string|fb.model.spell[, seconds:number][, caster:fb.game.object])

• Description:
  Applies a buff to the object using spell name or model.
• Parameters:
  • spell_name_or_model:string|fb.model.spell: Spell name (string) or spell model object
  • [seconds:number]: Duration of the buff in seconds
  • [caster:fb.game.object]: Object that cast the buff
• Return Value:
  • fb.game.buff|nil: Buff object if successfully applied, nil if failed
• Example:

  -- This is a real usage example from game scripts
  local buff = me:buff("무장", 300)  -- Apply armor buff for 5 minutes
  if buff then
      me:message("Armor buff applied")
  end
  

---

isbuff

isbuff(spell_name_or_model)

• Description:
  Checks if the object has a specific buff.
• Parameters:
  • spell_name_or_model: Spell name (string) or spell model object
• Return Value:
  • boolean: True if the buff exists, false otherwise
• Example:

  -- This is a real usage example from game scripts
  if me:isbuff("무장") then
      me:message("You are armored")
  end
  

---

unbuff

unbuff(buff_or_spell)

• Description:
  Removes a buff from the object.
• Parameters:
  • buff_or_spell: Buff object or spell name/model to remove
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:unbuff("무장")  -- Remove armor buff
  

---

buffs

buffs()

• Description:
  Returns a table containing all buffs on the object.
• Parameters:
  • None
• Return Value:
  • table: Table with buff objects
• Example:

  -- This is a real usage example from game scripts
  for _, buff in pairs(me:buffs()) do
      me:message("Buff: " .. buff:model():name())
  end
  

---

effect

effect(effect_type:number)

• Description:
  Displays a visual effect on the object.
• Parameters:
  • effect_type:number: Effect type to display
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:effect(115)  -- Display effect #115
  

---

map

Provides functionality to get or set the object's map.

map()

• Description:
  Returns the map that the object is currently on.
• Parameters:
  • None
• Return Value:
  • fb.game.map: Map object
• Example:

  -- This is a real usage example from game scripts
  local current_map = me:map()
  me:message("Current map: " .. current_map:model():name())
  

map(map, position)

• Description:
  Moves the object to a different map at the specified position.
• Parameters:
  • map: Target map object or map name
  • position: Target position (x, y coordinates or table)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local target_map = context:name2map("국내성")
  me:map(target_map, {100, 100})
  

---

mkitem

mkitem(name:string, count:number)

• Description:
  Creates an item at the object's current position on the map.
• Parameters:
  • name:string: Name of the item to create
  • count:number: Number of items to create (default: 1)
• Return Value:
  • fb.game.item|nil: Created item object or nil if failed
• Example:

  -- This is a real usage example from game scripts
  local item = me:mkitem("도토리", 5)
  if item then
      me:message("Created 5 red potions on the ground")
  end
  

---

sight_in

sight_in(target:fb.game.object)

• Description:
  Checks if the target object is within sight range.
• Parameters:
  • target:fb.game.object: Target object to check
• Return Value:
  • boolean: True if target is in sight, false otherwise
• Example:

  -- This is a real usage example from game scripts
  if me:sight_in(target) then
      me:message("Target is visible")
  end
  

---

nears

nears([range:number][, object_type:OBJECT_TYPE])

• Description:
  Returns a table of nearby objects within the specified range and of the specified type.
• Parameters:
  • [range:number]: Search range
  • [object_type:OBJECT_TYPE]: Object type filter (OBJECT_TYPE_* enum values)
• Return Value:
  • table: Table containing nearby objects
• Example:

  -- This is a real usage example from game scripts
  for _, obj in pairs(me:nears(5, OBJECT_TYPE_CHARACTER)) do
      me:message("Nearby character: " .. obj:name())
  end
  

---

front

front()

• Description:
  Returns the object that is directly in front of this object.
• Parameters:
  • None
• Return Value:
  • fb.game.object|nil: Object in front or nil if none
• Example:

  -- This is a real usage example from game scripts
  local front_obj = me:front()
  if front_obj then
      me:message("Object in front: " .. front_obj:name())
  end
  

---

is

is(object_type:OBJECT_TYPE)

• Description:
  Checks if the object is of the specified type.
• Parameters:
  • object_type:OBJECT_TYPE: Object type to check (OBJECT_TYPE_* enum values)
• Return Value:
  • boolean: True if object is of the specified type, false otherwise
• Example:

  -- This is a real usage example from game scripts
  if me:is(OBJECT_TYPE_CHARACTER) then
      me:message("This is a character")
  end
  

---

thread

thread()

• Description:
  Returns the active Lua thread for this object.
• Parameters:
  • None
• Return Value:
  • thread|nil: Active thread object or nil if none
• Example:

  -- This is a real usage example from game scripts
  local active_thread = me:thread()
  if active_thread then
      me:message("Object has an active thread")
  end
  

---

ptr

ptr()

• Description:
  Returns the memory pointer address of the object (for debugging purposes).
• Parameters:
  • None
• Return Value:
  • number: Memory pointer address
• Example:

  -- This is a real usage example from game scripts
  local pointer = me:ptr()
  me:message("Object pointer: " .. pointer)
  

---

near

near(target:fb.game.object)

• Description:
  Checks if the target object is near this object.
• Parameters:
  • target:fb.game.object: Target object to check
• Return Value:
  • boolean: True if target is near, false otherwise
• Example:

  -- This is a real usage example from game scripts
  if me:near(target) then
      me:message("Target is nearby")
  end
  

---

hidden

Provides functionality to get or set the object's hidden state.

hidden()

• Description:
  Returns whether the object is hidden.
• Parameters:
  • None
• Return Value:
  • boolean: True if hidden, false otherwise
• Example:

  -- This is a real usage example from game scripts
  if me:hidden() then
      me:message("You are hidden")
  end
  

hidden(value:boolean)

• Description:
  Sets the object's hidden state.
• Parameters:
  • value:boolean: True to hide, false to show
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:hidden(true)  -- Hide the object
  

---

__tostring

__tostring()

• Description:
  Returns the string representation of the object, which is its name. This allows the object to be used directly in functions like print() or string concatenations.
• Parameters:
  • None
• Return Value:
  • string: The name of the object.
• Example:

  -- This is a real usage example from game scripts
  me:message("My name is " .. me)
  

---

destroy

destroy()

• Description:
  Destroys the object, removing it from the game world. This is an asynchronous operation.
• Parameters:
  • None
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  -- Spawn a mob and then destroy it.
  local mob = me:spawn_mob("다람쥐", me:position())
  if mob then
      me:message("Mob spawned, will be destroyed shortly.")
      mob:destroy()
  end