builtin character - boyism80/fb GitHub Wiki

Built-in Functions Documentation (Character)

This document describes functions available to character type objects.

• Basic Information Functions
  • look
  • color
  • sex
  • money
  • birthday
  • active
  • title
• Stats Functions
  • level
  • exp
  • base_hp
  • base_mp
  • base_str
  • base_dex
  • base_int
  • base_dam
  • base_hit
• Item Functions
  • item
  • items
  • equipments
  • dropitem
  • mkitem
  • rmitem
  • weapon
  • weapon_damage
  • armor_color
• State and Appearance Functions
  • state
  • assert
  • disguise
  • super_hide
• Class and Promotion Functions
  • class
  • promotion
• Storage Functions
  • deposited_money
  • stored_item
  • store_item
  • retrieve_item
• Group and Clan Functions
  • group
  • create_group
  • clan
  • create_clan
  • destroy_clan
• Achievement Functions
  • achievements
  • achievement
  • push_achievement
  • erase_achievement
• Communication Functions
  • whisper
  • send_mail
• Dialog Functions
  • dialog
  • list
  • input
  • menu
  • item
  • slot
• Game System Functions
  • nation
  • gain
  • detect
  • world
  • script
  • ad
  • web
• Mob Functions
  • spawn_mob
  • spawned_mobs
  • creature
  • teleport
• Spell Functions
  • mkspell
  • rmspell

Basic Information Functions

look

Provides functionality to get or set the character's appearance ID.

look()

• Description:
  Returns the character's current appearance ID.
• Parameters:
  • None
• Return Value:
  • number: Current appearance ID
• Example:

  -- This is a real usage example from game scripts
  me:look(tonumber(value))
  

look(value:number)

• Description:
  Sets the character's appearance to the specified ID.
• Parameters:
  • value:number: Appearance ID to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:look(me:look() + 1)
  

---

color

Provides functionality to get or set the character's color.

color()

• Description:
  Returns the character's current color value.
• Parameters:
  • None
• Return Value:
  • number: Current color value
• Example:

  -- This is a real usage example from game scripts
  me:color(tonumber(value))
  

color(value:number)

• Description:
  Sets the character's color to the specified value.
• Parameters:
  • value:number: Color value to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:color(tonumber(value))
  

---

sex

Provides functionality to get or set the character's gender.

sex()

• Description:
  Returns the character's current gender.
• Parameters:
  • None
• Return Value:
  • number: Gender value (SEX_MAN = 0, SEX_WOMAN = 1)
• Example:

  -- This is a real usage example from game scripts
  if me:sex() == SEX_MAN then
      me:sex(SEX_WOMAN)
  else
      me:sex(SEX_MAN)
  end
  

sex(value:number)

• Description:
  Sets the character's gender to the specified value.
• Parameters:
  • value:number: Gender value (SEX_MAN = 0, SEX_WOMAN = 1)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  if me:sex() == SEX_MAN then
      me:sex(SEX_WOMAN)
  else
      me:sex(SEX_MAN)
  end
  

---

money

Provides functionality to get or set the character's money.

money()

• Description:
  Returns the character's current money amount.
• Parameters:
  • None
• Return Value:
  • number: Current money amount
• Example:

  -- This is a real usage example from game scripts
  local money = me:money()
  if money < price then
      me:dialog(npc, '돈이 모자랍니다.')
      return true
  end
  

money(value:number)

• Description:
  Sets the character's money to the specified amount.
• Parameters:
  • value:number: Money amount to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:money(me:money() + tonumber(money))
  

---

birthday

Provides functionality to get or set the character's birthday.

birthday()

• Description:
  Returns the character's birthday. Returns nil if no birthday is set.
• Parameters:
  • None
• Return Value:
  • number|nil: Birthday value or nil if not set
• Example:

  -- This is a real usage example from game scripts
  local birthday = me:birthday()
  if birthday then
      me:message("Your birthday: " .. birthday)
  end
  

birthday(value:number)

• Description:
  Sets the character's birthday to the specified value.
• Parameters:
  • value:number: Birthday value to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:birthday(20241225)
  

---

active

active(item:fb.game.item)

• Description:
  Activates (uses) the specified item from the character's inventory.
• Parameters:
  • item:fb.game.item: Item object to activate
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local potion = me:item("도토리")
  if potion then
      me:active(potion)
  end
  

---

title

Provides functionality to get or set the character's title.

title()

• Description:
  Returns the character's current title.
• Parameters:
  • None
• Return Value:
  • string: Current title
• Example:

  -- This is a real usage example from game scripts
  local title = you:title()
  if title == nil then
      title = ''
  else
      title = string.format('%s\n', title)
  end
  

title(value:string)

• Description:
  Sets the character's title to the specified string.
• Parameters:
  • value:string: Title to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:title(value)
  

Stats Functions

level

When called on an object (self) without arguments, returns the character's current level. When value:number is passed, sets the character's level to that value (0~255 range).

level()

• Description:
  When called without arguments, returns the character's current level
• Parameters: None
• Return Value: number
• Example:

  -- This is a real usage example from game scripts
  if me:level() < 5 then
      me:dialog(npc, '아직 너의 정성이 부족하니 다음에 이 곳에 올 때에는 보다 큰 각오를 갖고 나를 찾아오도록 하여라.')
  end
  

level(value:number)

• Description:
  When value:number is passed, sets the character's level to that value (0~255 range)
• Parameters:
  • value:number: Level to set (0~255)
• Return Value: None
• Example:

  -- This is a real usage example from game scripts
  local level = table.unpack(args)
  me:level(tonumber(level))
  

---

exp

Provides functionality to get or set the character's experience points.

exp()

• Description:
  Returns the character's current experience points.
• Parameters:
  • None
• Return Value:
  • number: Current experience points
• Example:

  -- This is a real usage example from game scripts
  local exp = table.unpack(args)
  exp = tonumber(exp)
  me:exp(exp)
  

exp(value:number)

• Description:
  Sets the character's experience points to the specified amount.
• Parameters:
  • value:number: Experience points to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local exp = table.unpack(args)
  exp = tonumber(exp)
  me:exp(exp)
  

---

base_hp

Provides functionality to get or set the character's base HP.

base_hp()

• Description:
  Returns the character's base HP (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base HP value
• Example:

  -- This is a real usage example from game scripts
  local value = table.unpack(args)
  me:base_hp(tonumber(value))
  me:hp(me:maxhp())
  

base_hp(value:number)

• Description:
  Sets the character's base HP to the specified value.
• Parameters:
  • value:number: Base HP to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local value = table.unpack(args)
  me:base_hp(tonumber(value))
  me:hp(me:maxhp())
  if me:state() == STATE_GHOST then
      me:state(STATE_NORMAL)
  end
  

---

base_mp

Provides functionality to get or set the character's base MP.

base_mp()

• Description:
  Returns the character's base MP (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base MP value
• Example:

  -- This is a real usage example from game scripts
  local base_mp = me:base_mp()
  me:message("Base MP: " .. base_mp)
  

base_mp(value:number)

• Description:
  Sets the character's base MP to the specified value.
• Parameters:
  • value:number: Base MP to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:base_mp(500)
  

---

base_str

Provides functionality to get or set the character's base strength.

base_str()

• Description:
  Returns the character's base strength (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base strength value
• Example:

  -- This is a real usage example from game scripts
  local base_str = me:base_str()
  me:message("Base strength: " .. base_str)
  

base_str(value:number)

• Description:
  Sets the character's base strength to the specified value.
• Parameters:
  • value:number: Base strength to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local value = table.unpack(args)
  me:base_str(tonumber(value))
  

---

base_dex

Provides functionality to get or set the character's base dexterity.

base_dex()

• Description:
  Returns the character's base dexterity (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base dexterity value
• Example:

  -- This is a real usage example from game scripts
  local base_dex = me:base_dex()
  me:message("Base dexterity: " .. base_dex)
  

base_dex(value:number)

• Description:
  Sets the character's base dexterity to the specified value.
• Parameters:
  • value:number: Base dexterity to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local value = table.unpack(args)
  me:base_dex(tonumber(value))
  

---

base_int

Provides functionality to get or set the character's base intelligence.

base_int()

• Description:
  Returns the character's base intelligence (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base intelligence value
• Example:

  -- This is a real usage example from game scripts
  local base_int = me:base_int()
  me:message("Base intelligence: " .. base_int)
  

base_int(value:number)

• Description:
  Sets the character's base intelligence to the specified value.
• Parameters:
  • value:number: Base intelligence to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local value = table.unpack(args)
  me:base_int(tonumber(value))
  

---

base_dam

Provides functionality to get or set the character's base damage.

base_dam()

• Description:
  Returns the character's base damage (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base damage value
• Example:

  -- This is a real usage example from game scripts
  local base_dam = me:base_dam()
  me:message("Base damage: " .. base_dam)
  

base_dam(value:number)

• Description:
  Sets the character's base damage to the specified value.
• Parameters:
  • value:number: Base damage to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:base_dam(20)
  

---

base_hit

Provides functionality to get or set the character's base hit rate.

base_hit()

• Description:
  Returns the character's base hit rate (without equipment bonuses).
• Parameters:
  • None
• Return Value:
  • number: Base hit rate value
• Example:

  -- This is a real usage example from game scripts
  local base_hit = me:base_hit()
  me:message("Base hit rate: " .. base_hit)
  

base_hit(value:number)

• Description:
  Sets the character's base hit rate to the specified value.
• Parameters:
  • value:number: Base hit rate to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:base_hit(80)
  

Item Functions

item

Provides functionality to access items from the character's inventory by name or slot index.

item(name:string)

• Description:
  Returns the first item with the specified name from the character's inventory.
• Parameters:
  • name:string: Name of the item to find
• Return Value:
  • fb.game.item|nil: Item object or nil if not found
• Example:

  -- This is a real usage example from game scripts
  local potion = me:item("도토리")
  if potion then
      me:active(potion)
  end
  

item(index:number)

• Description:
  Returns the item at the specified inventory slot index.
• Parameters:
  • index:number: Inventory slot index (0-based)
• Return Value:
  • fb.game.item|nil: Item object or nil if slot is empty
• Example:

  -- This is a real usage example from game scripts
  local item = me:item(0)  -- Get item from first slot
  if item then
      me:message("First slot item: " .. item:model():name())
  end
  

item(model:fb.model.item)

• Description:
  Returns the first item matching the specified item model from the character's inventory.
• Parameters:
  • model:fb.model.item: Item model to search for
• Return Value:
  • fb.game.item|nil: Item object or nil if not found
• Example:

  -- This is a real usage example from game scripts
  local model = name2item("도토리")
  if model then
      local item = me:item(model)
      if item then
          me:active(item)
      end
  end
  

---

items

items()

• Description:
  Returns a table containing all non-empty items in the character's inventory.
• Parameters:
  • None
• Return Value:
  • table: Table with slot indices as keys and item objects as values
• Example:

  -- This is a real usage example from game scripts
  for slot, item in pairs(me:items()) do
      me:message("Slot " .. slot .. ": " .. item:model():name())
  end
  

---

equipments

equipments()

• Description:
  Returns a table containing all equipped items.
• Parameters:
  • None
• Return Value:
  • table: Table with equipment parts as keys and equipment objects as values
• Example:

  -- This is a real usage example from game scripts
  for parts, equipment in pairs(me:equipments()) do
      local model = equipment:model()
      me:message("Equipped: " .. model:name())
  end
  

---

dropitem

dropitem(index:number, drop_all:boolean)

• Description:
  Drops an item from the specified inventory slot.
• Parameters:
  • index:number: Inventory slot index (1-based)
  • drop_all:boolean: If true, drops entire stack; if false, drops one item
• Return Value:
  • fb.game.item|nil: Dropped item object or nil if failed
• Example:

  -- This is a real usage example from game scripts
  local dropped = me:dropitem(1, false)  -- Drop one item from slot 1
  

---

mkitem

mkitem(name:string, count:number, store:boolean)

• Description:
  Creates an item and adds it to the character's inventory.
• Parameters:
  • name:string: Name of the item to create
  • count:number: Number of items to create (default: 1)
  • store:boolean: Whether to store in inventory (default: true)
• Return Value:
  • fb.game.item|nil: Created item object or nil if failed
• Example:

  -- This is a real usage example from game scripts
  me:mkitem(name, tonumber(count))
  

---

rmitem

Provides functionality to remove items from the character's inventory using different target types.

rmitem(target[, count:number][, delete_type:ITEM_DELETE_TYPE])

• Description:
  Removes items from the character's inventory.
• Parameters:
  • target: Can be item object, model object, slot index, or item name
  • [count:number]: Number of items to remove (default: 1)
  • [delete_type:ITEM_DELETE_TYPE]: Deletion type (ITEM_DELETE_TYPE_REMOVED, ITEM_DELETE_TYPE_REDUCE, default: ITEM_DELETE_TYPE_REMOVED)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:rmitem(4)  -- Remove item from slot 4
  me:rmitem("목도", 2)  -- Remove 2 "목도" items
  me:rmitem(0, 3, ITEM_DELETE_TYPE_REDUCE)  -- Remove 3 items from slot 0 with reduce type
  

---

weapon

Provides functionality to get or set the character's equipped weapon.

weapon()

• Description:
  Returns the character's currently equipped weapon.
• Parameters:
  • None
• Return Value:
  • fb.game.weapon|nil: Equipped weapon object or nil if none
• Example:

  -- This is a real usage example from game scripts
  local weapon = me:weapon()
  if weapon ~= nil and weapon:model():name() == message then
      me:message(string.format('%s 푸른 빛으로 빛납니다.', name_with(message, '은', '는')))
      me:weapon_damage(damage)
      return true
  end
  

weapon(weapon:fb.game.weapon)

• Description:
  Equips the specified weapon.
• Parameters:
  • weapon:fb.game.weapon: Weapon object to equip
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local weapon = me:item("목검")
  if weapon then
      me:weapon(weapon)
  end
  

---

weapon_damage

Provides functionality to get or set the character's weapon damage.

weapon_damage()

• Description:
  Returns the character's current weapon damage.
• Parameters:
  • None
• Return Value:
  • number: Current weapon damage
• Example:

  -- This is a real usage example from game scripts
  me:weapon_damage(damage)
  

weapon_damage(value:number)

• Description:
  Sets the character's weapon damage to the specified value.
• Parameters:
  • value:number: Weapon damage to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:weapon_damage(damage)
  

---

armor_color

Provides functionality to get or set the character's armor color.

armor_color()

• Description:
  Returns the character's current armor color.
• Parameters:
  • None
• Return Value:
  • number|nil: Current armor color or nil if not set
• Example:

  -- This is a real usage example from game scripts
  me:armor_color(tonumber(value))
  

armor_color(value:number|nil)

• Description:
  Sets the character's armor color to the specified value.
• Parameters:
  • value:number|nil: Armor color to set (nil to remove color)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:armor_color(10)  -- Set to black color for north team
  

State and Appearance Functions

state

Provides functionality to get or set the character's state.

state()

• Description:
  Returns the character's current state.
• Parameters:
  • None
• Return Value:
  • number: Current state value
• Example:

  -- This is a real usage example from game scripts
  local current_state = me:state()
  me:message("Current state: " .. current_state)
  

state(value:STATE)

• Description:
  Sets the character's state to the specified value.
• Parameters:
  • value:STATE: State to set (STATE_NORMAL, STATE_GHOST, STATE_TRANSLUCENCY, STATE_RIDING, STATE_DISGUISE, STATE_HALF_CLOACK, STATE_CLOACK)
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:state(STATE_TRANSLUCENCY)
  me:message("Changed state to translucency")
  

---

assert

Validates the character's state against allowed states. Supports both table and individual argument formats in a single unified function.

assert()

• Description:
  When called without parameters, always returns true (success).
• Parameters: None
• Return Value: boolean: Always returns true
• Example:

  -- This is a real usage example from game scripts
  local success = me:assert()  -- Always returns true
  

assert(states:table)

• Description:
  Validates the character's state against a table of allowed states. Throws an exception if the character's current state is not in the allowed states list.
• Parameters:
  • states:table: Table of allowed STATE values (e.g., {STATE_NORMAL, STATE_GHOST})
• Return Value:
  • nil: Success when states are validated
  • string: Error message if validation fails
• Example:

  -- This is a real usage example from game scripts
  local error = me:assert({STATE_NORMAL, STATE_GHOST})
  if error then
      me:message("State validation failed: " .. error)
      return
  end
  

assert(state1, state2, ...)

• Description:
  Alternative syntax that validates the character's state against multiple states passed as individual arguments. Functionally identical to the table version.
• Parameters:
  • state1, state2, ...: Multiple individual STATE values (STATE_GHOST, STATE_RIDING, etc.)
• Return Value:
  • nil: Success when states are validated
  • string: Error message if validation fails
• Example:

  -- This is a real usage example from game scripts
  local error = me:assert(STATE_NORMAL, STATE_GHOST)
  if error then
      me:message("State validation failed: " .. error)
      return
  end
  

Note: This function intelligently detects whether the first parameter is a table or individual states and processes accordingly, providing maximum flexibility for different coding styles.

---

disguise

When called on an object (self) without arguments or when not given a non-nil value, returns the disguised model ID if the character is disguised, otherwise returns nil. When value:number is passed, disguises the character as that model ID.

disguise()

• Description:
  When called without arguments or when not given a non-nil value, returns the disguised model ID if the character is disguised, otherwise returns nil
• Parameters: None
• Return Value: number or nil
• Example:

  -- This is a real usage example from game scripts
  me:disguise(tonumber(value))
  

disguise(value:number|nil)

• Description:
  When value:number is passed, disguises the character as that model ID. When nil is passed, removes disguise.
• Parameters:
  • value:number: Disguise model ID to set
  • value:nil: Remove disguise
• Return Value: None
• Example:

  -- This is a real usage example from game scripts
  local look = name2mob('다람쥐'):look()
  me:disguise(look)
  

---

super_hide

Provides functionality to get or set the character's super hide state.

super_hide()

• Description:
  Returns the character's current super hide state.
• Parameters: None
• Return Value: boolean: Current super hide state
• Example:

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

super_hide(value:boolean)

• Description:
  Sets the character's super hide state to the specified value.
• Parameters:
  • value:boolean: Super hide state to set (true to hide, false to show)
• Return Value: None
• Example:

  -- This is a real usage example from game scripts
  me:super_hide(true)  -- Enable super hide
  me:super_hide(false) -- Disable super hide
  

Class and Promotion Functions

class

When called on an object (self) without arguments, returns the character's class (CLASS). When value:CLASS is passed, sets the character's class to that value.

class()

• Description:
  When called without arguments, returns the character's class (CLASS)
• Parameters: None
• Return Value: number
• Example:

  -- This is a real usage example from game scripts
  if me:class() ~= CLASS_NONE then
      me:dialog(npc, '이미 직업이 있지 않느냐? 한번 선택한 직업은 바꿀 수 없느니라.')
      return
  end
  

class(value:CLASS)

• Description:
  When value:CLASS is passed, sets the character's class to that value
• Parameters:
  • value:CLASS: Class to set (CLASS_WARRIOR(1), CLASS_MAGE(3), etc.)
• Return Value: None
• Example:

  -- This is a real usage example from game scripts
  local class, promotion = name2class(name)
  if class ~= nil then
      me:class(class)
      me:promotion(promotion)
  end
  

---

promotion

When called on an object (self) without arguments, returns the character's current promotion (job advancement) state value. When value:number is passed, changes the character's promotion state to that value.

promotion()

• Description:
  When called without arguments, returns the character's current promotion (job advancement) state value
• Parameters: None
• Return Value: number
• Example:

  -- Getter example: Display current promotion state
  local promo = me:promotion()
  me:message("Current promotion: " .. promo)
  

promotion(value:number)

• Description:
  When value:number is passed, changes the character's promotion state to that value
• Parameters:
  • value:number: Promotion state to set
• Return Value: None
• Example:

  -- Setter example: Change promotion state to 2
  me:promotion(2)
  me:message("Changed promotion to 2")
  

Storage Functions

deposited_money

Provides functionality to get or set deposited money (bank money).

deposited_money()

• Description:
  Returns the character's deposited money amount.
• Parameters:
  • None
• Return Value:
  • number: Current deposited money amount
• Example:

  -- This is a real usage example from game scripts
  local deposited = me:deposited_money()
  me:message("Deposited money: " .. deposited)
  

deposited_money(value:number)

• Description:
  Sets the character's deposited money to the specified amount.
• Parameters:
  • value:number: Deposited money amount to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:deposited_money(me:deposited_money() + 10000)
  

---

stored_item

Provides functionality to access stored items.

stored_item()

• Description:
  Returns a table containing all stored items.
• Parameters:
  • None
• Return Value:
  • table: Table with indices as keys and stored item objects as values
• Example:

  -- This is a real usage example from game scripts
  for i, stored_item in pairs(me:stored_item()) do
      me:message("Stored item: " .. stored_item:model():name())
  end
  

stored_item(index:number)

• Description:
  Returns the stored item at the specified index.
• Parameters:
  • index:number: Index of the stored item
• Return Value:
  • fb.game.item|nil: Stored item object or nil if not found
• Example:

  -- This is a real usage example from game scripts
  local stored = me:stored_item(0)
  if stored then
      me:message("First stored item: " .. stored:model():name())
  end
  

---

store_item

store_item(item:fb.game.item, count:number)

• Description:
  Stores an item from inventory to storage.
• Parameters:
  • item:fb.game.item: Item object to store
  • count:number: Number of items to store (default: 1)
• Return Value:
  • boolean: True if successful, false otherwise
• Example:

  -- This is a real usage example from game scripts
  local item = me:item("도토리")
  if item and me:store_item(item, 5) then
      me:message("Stored 5 acorns")
  end
  

---

retrieve_item

retrieve_item(item:fb.game.item, count:number)

• Description:
  Retrieves a stored item back to inventory.
• Parameters:
  • item:fb.game.item: Stored item object to retrieve
  • count:number: Number of items to retrieve (default: 1)
• Return Value:
  • fb.game.item|nil: Retrieved item object or nil if failed
• Example:

  -- This is a real usage example from game scripts
  local stored = me:stored_item(0)
  if stored then
      local retrieved = me:retrieve_item(stored, 1)
      if retrieved then
          me:message("Retrieved item")
      end
  end
  

Group and Clan Functions

group

Provides functionality to get the character's group or execute a function with group access.

group()

• Description:
  Returns the character's current group object, or nil if not in a group.
• Parameters: None
• Return Value: fb.game.group|nil: Group object or nil if not in a group
• Example:

  -- This is a real usage example from game scripts
  local group = me:group()
  if group then
      me:message("You are in group: " .. group:master())
  else
      me:message("You are not in a group")
  end
  

group(func:function)

• Description:
  Executes the provided function with the character and group as parameters. The group object is locked during function execution, but becomes invalid if yield functions are used inside the callback.
• Parameters:
  • func:function: Function to execute with (character, group) parameters
• Return Value: Varies based on function return
• Example:

  -- This is a real usage example from game scripts
  me:group(function(ch, group)
      if group then
          me:message("Group master: " .. group:master())
          local members = group:members()
          me:message("Group has " .. #members .. " members")
      end
  end)
  

⚠️ CRITICAL WARNING: Thread Safety for group()

The group object has inherent thread safety limitations that can cause race conditions.

Lock Scope Rules

1. Direct Object Access: me:group()

• Lock scope: Valid until the next yield function is called
• Safe usage: Only when no yield functions are used after getting the object
• Unsafe after: Any yield function call (me:sleep(), me:input(), me:menu(), etc.)

-- ✅ SAFE: No yield functions used
local group = me:group()
if group then
    local master = group:master()  -- Safe: no yield occurred
    me:message("Group master: " .. master)
end

-- ❌ DANGEROUS: yield function breaks the lock
local group = me:group()  -- Lock acquired
me:sleep(1000)           -- yield occurs - lock RELEASED!
local master = group:master()  -- UNSAFE! Lock is gone, may crash

2. Function Callback Access: me:group(function)

• Lock scope: Valid only during function execution
• Safe usage: Only when no yield functions are used inside the callback
• Data copying: Never copy group data outside the function scope

-- ✅ SAFE: No yield inside function
me:group(function(ch, group)
    if group then
        local master = group:master()  -- Safe: within function scope
        me:message("Group master: " .. master)
    end
    -- Lock released when function ends
end)

-- ❌ DANGEROUS: yield inside function
me:group(function(ch, group)
    if group then
        me:sleep(1000)  -- yield occurs - lock RELEASED!
        local master = group:master()  -- UNSAFE! Lock is gone
    end
end)

-- ❌ DANGEROUS: copying data outside function scope
local copied_group = nil
me:group(function(ch, group)
    copied_group = group  -- NEVER do this!
end)
-- copied_group is now invalid - lock was released

Common yield-causing functions

• me:sleep(), me:input(), me:menu(), me:prompt()
• Any function that waits for user input or time delays

---

create_group

create_group(name:string)

• Description:
  Creates a new group with the specified name. The character becomes the group leader.
• Parameters:
  • name:string: Name of the group to create
• Return Value:
  • boolean: true if group creation succeeded, false otherwise
• Example:

  -- This is a real usage example from game scripts
  local success = me:create_group("MyGroup")
  if success then
      me:message("Group created successfully")
  else
      me:message("Failed to create group")
  end
  

---

clan

Provides functionality to get the character's clan or execute a function with clan access.

clan()

• Description:
  Returns the character's current clan object, or nil if not in a clan.
• Parameters: None
• Return Value: fb.game.clan|nil: Clan object or nil if not in a clan
• Example:

  -- This is a real usage example from game scripts
  local clan = me:clan()
  if clan then
      me:message("You are in clan: " .. clan:name())
  else
      me:message("You are not in a clan")
  end
  

clan(func:function)

• Description:
  Executes the provided function with the character and clan as parameters. The clan object is locked during function execution, but becomes invalid if yield functions are used inside the callback.
• Parameters:
  • func:function: Function to execute with (character, clan) parameters
• Return Value: Varies based on function return
• Example:

  -- This is a real usage example from game scripts
  me:clan(function(ch, clan)
      if clan then
          me:message("Clan name: " .. clan:name())
          local members = clan:members()
          me:message("Clan has " .. #members .. " members")
      end
  end)
  

⚠️ CRITICAL WARNING: Thread Safety for clan()

The clan object has inherent thread safety limitations that can cause race conditions.

Lock Scope Rules

1. Direct Object Access: me:clan()

• Lock scope: Valid until the next yield function is called
• Safe usage: Only when no yield functions are used after getting the object
• Unsafe after: Any yield function call (me:sleep(), me:input(), me:menu(), etc.)

-- ✅ SAFE: No yield functions used
local clan = me:clan()
if clan then
    local name = clan:name()  -- Safe: no yield occurred
    me:message("Clan name: " .. name)
end

-- ❌ DANGEROUS: yield function breaks the lock
local clan = me:clan()   -- Lock acquired
me:sleep(1000)          -- yield occurs - lock RELEASED!
local name = clan:name()  -- UNSAFE! Lock is gone, may crash

2. Function Callback Access: me:clan(function)

• Lock scope: Valid only during function execution
• Safe usage: Only when no yield functions are used inside the callback
• Data copying: Never copy clan data outside the function scope

-- ✅ SAFE: No yield inside function
me:clan(function(ch, clan)
    if clan then
        local name = clan:name()  -- Safe: within function scope
        me:message("Clan name: " .. name)
    end
    -- Lock released when function ends
end)

-- ❌ DANGEROUS: yield inside function
me:clan(function(ch, clan)
    if clan then
        me:sleep(1000)  -- yield occurs - lock RELEASED!
        local name = clan:name()  -- UNSAFE! Lock is gone
    end
end)

-- ❌ DANGEROUS: copying data outside function scope
local copied_clan = nil
me:clan(function(ch, clan)
    copied_clan = clan  -- NEVER do this!
end)
-- copied_clan is now invalid - lock was released

Common yield-causing functions

• me:sleep(), me:input(), me:menu(), me:prompt()
• Any function that waits for user input or time delays

---

create_clan

create_clan(name:string)

• Description:
  Creates a new clan with the specified name. The character becomes the clan leader.
• Parameters:
  • name:string: Name of the clan to create
• Return Value:
  • nil|string: nil on success, error message string on failure
• Example:

  -- This is a real usage example from game scripts
  local result = me:create_clan("MyClan")
  if result then
      me:message("Failed to create clan: " .. result)
  else
      me:message("Clan created successfully")
  end
  

---

destroy_clan

destroy_clan()

• Description:
  Destroys the character's current clan. Only the clan leader can destroy the clan.
• Parameters: None
• Return Value:
  • nil|string: nil on success, error message string on failure
• Example:

  -- This is a real usage example from game scripts
  local result = me:destroy_clan()
  if result then
      me:message("Failed to destroy clan: " .. result)
  else
      me:message("Clan destroyed successfully")
  end
  

Achievement Functions

achievements

achievements()

• Description:
  Returns a table containing all achievements that the character has earned.
• Parameters: None
• Return Value:
  • table: Table with indices as keys and achievement objects as values
• Example:

  -- This is a real usage example from game scripts
  local achievements = me:achievements()
  for i, achievement in pairs(achievements) do
      me:message("Achievement: " .. achievement:name())
  end
  

---

achievement

achievement(id:number)

• Description:
  Returns the achievement with the specified ID if the character has earned it.
• Parameters:
  • id:number: Achievement ID to retrieve
• Return Value:
  • fb.game.achievement|nil: Achievement object or nil if not found
• Example:

  -- This is a real usage example from game scripts
  local achievement = me:achievement(1001)
  if achievement then
      me:message("You have achievement: " .. achievement:name())
  else
      me:message("You don't have this achievement")
  end
  

---

push_achievement

Provides functionality to grant achievements to the character.

push_achievement(id:number[, text:string][, icon:number][, color:number])

• Description:
  Grants an achievement to the character with optional custom text, icon, and color.
• Parameters:
  • id:number: Achievement ID to grant
  • [text:string]: Optional custom text for the achievement
  • [icon:number]: Optional custom icon ID
  • [color:number]: Optional custom color
• Return Value:
  • fb.game.achievement|nil: Achievement object if newly granted, nil if already possessed
• Example:

  -- This is a real usage example from game scripts
  local achievement = me:push_achievement(1)  -- Grant achievement with ID 1
  if achievement then
      me:message("New achievement unlocked!")
  end
  me:push_achievement(2, "Custom achievement text")  -- Grant with custom text
  

---

erase_achievement

erase_achievement(id:number)

• Description:
  Removes the achievement with the specified ID from the character.
• Parameters:
  • id:number: Achievement ID to remove
• Return Value:
  • boolean: true if achievement was removed, false if not found
• Example:

  -- This is a real usage example from game scripts
  local success = me:erase_achievement(1001)
  if success then
      me:message("Achievement removed")
  else
      me:message("Achievement not found")
  end
  

Communication Functions

whisper

whisper(to:string, message:string)

• Description:
  Sends a whisper message to another character. This is an async operation that may fail if the target is not found.
• Parameters:
  • to:string: Name of the target character
  • message:string: Message to send
• Return Value:
  • nil|string: nil on success, error message string on failure
• Example:

  -- This is a real usage example from game scripts
  local result = me:whisper("운영자", "Hello!")
  if result then
      me:message("Failed to send whisper: " .. result)
  else
      me:message("Whisper sent successfully")
  end
  

---

send_mail

send_mail(to:string[, title:string][, contents:string])

• Description:
  Sends a mail to another character with optional title and contents.
• Parameters:
  • to:string: Name of the recipient character
  • [title:string]: Mail title (default: "mail title")
  • [contents:string]: Mail contents (default: "mail contents")
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:send_mail("운영자")  -- Send with default title and contents
  me:send_mail("운영자", "중요한 메일")  -- Send with custom title
  me:send_mail("운영자", "중요한 메일", "이것은 메일 내용입니다")  -- Send with custom title and contents
  

Dialog Functions

dialog

dialog(obj:fb.game.object|fb.model.object, message:string, [button_prev:boolean], [button_next:boolean])

• Description:
  Shows a dialog box to the character with the specified message and optional navigation buttons.
• Parameters:
  • obj:fb.game.object|fb.model.object: Object or model to show dialog from
  • message:string: Dialog message to display
  • [button_prev:boolean]: Whether to show previous button (default: false)
  • [button_next:boolean]: Whether to show next button (default: false)
• Return Value: User response (varies based on dialog type)
• Example:

  -- This is a real usage example from game scripts
  local response = me:dialog(npc, "Welcome to our shop!", true, true)
  if response then
      me:message("User responded: " .. tostring(response))
  end
  

---

list

list(obj:fb.game.object|fb.model.object, message:string, items:table, [button_prev:boolean], [preset:table])

• Description:
  Shows a list dialog with multiple selectable items and optional character appearance preset.
• Parameters:
  • obj:fb.game.object|fb.model.object: Object or model to show dialog from
  • message:string: Dialog message to display
  • items:table: Array of strings representing list items
  • [button_prev:boolean]: Whether to show previous button (default: false)
  • [preset:table]: Character appearance preset with keys: sex, state, face, hair_color, weapon, weapon_color, armor, armor_color, shield, shield_color
• Return Value: Selected item index (1-based) or nil if cancelled
• Example:

  -- This is a real usage example from game scripts
  local face = 3  -- Face ID to preview
  local preset = {
      ['face'] = face
  }
  local index, button = me:list(npc, '다음에 또 수술을 해 줄 수는 있지만, 수술을 계속한다고 결코 좋아지지는 않는다. 이 모습을 선택하겠느냐?', 
                                {'선택', '이전 모습으로', '다음 모습으로', '수술 포기'}, false, preset)
  if index == nil then
      return
  end
  me:message("You selected option: " .. index)
  

---

input

input(obj:fb.game.object|fb.model.object, message:string, [message_top:string], [message_bot:string], [maxlen:number], [prev:boolean])

• Description:
  Shows an input dialog for text entry with optional additional messages and constraints.
• Parameters:
  • obj:fb.game.object|fb.model.object: Object or model to show dialog from
  • message:string: Main dialog message
  • [message_top:string]: Additional message at top
  • [message_bot:string]: Additional message at bottom
  • [maxlen:number]: Maximum input length (default: 255)
  • [prev:boolean]: Whether to show previous button (default: false)
• Return Value: User input string or nil if cancelled
• Example:

  -- This is a real usage example from game scripts
  local input = me:input(npc, "Enter your name:", "Please provide", "Max 20 characters", 20, false)
  if input then
      me:message("You entered: " .. input)
  else
      me:message("Input cancelled")
  end
  

---

menu

menu(obj:fb.game.object|fb.model.object, message:string, options:table)

• Description:
  Shows a menu dialog with selectable options.
• Parameters:
  • obj:fb.game.object|fb.model.object: Object or model to show dialog from
  • message:string: Dialog message to display
  • options:table: Array of strings representing menu options
• Return Value: Selected option index (1-based) or nil if cancelled
• Example:

  -- This is a real usage example from game scripts
  local options = {"Start Quest", "Check Progress", "Abandon Quest"}
  local choice = me:menu(npc, "Quest Management", options)
  if choice == 1 then
      me:message("Starting new quest...")
  elseif choice == 2 then
      me:message("Checking quest progress...")
  end
  

---

item

item(obj:fb.game.object|fb.model.object, message:string, items:table)

• Description:
  Shows an item selection dialog with a list of items and their prices or counts.
• Parameters:
  • obj:fb.game.object|fb.model.object: Object or model to show dialog from
  • message:string: Dialog message to display
  • items:table: Array of item tables, each containing {item_model_or_name, price_or_count}
• Return Value: Selected item name string or nil if cancelled
• Example:

  -- This is a real usage example from game scripts
  local shop_items = {
      {"도토리", 100},
      {name2item("목검"), 500},  -- Can use item model
      {"가죽갑옷", 1000}
  }
  local selected = me:item(npc, "상점에 오신 것을 환영합니다!", shop_items)
  if selected then
      me:message("Selected item: " .. selected)
  end
  

---

slot

slot(obj:fb.game.object|fb.model.object, message:string, slots:table)

• Description:
  Shows a slot dialog for selecting inventory slots.
• Parameters:
  • obj:fb.game.object|fb.model.object: Object or model to show dialog from
  • message:string: Dialog message to display
  • slots:table: Array of slot indices to display
• Return Value: Selected slot index or nil if cancelled
• Example:

  -- This is a real usage example from game scripts
  local available_slots = {1, 2, 3, 4, 5}  -- Slots 1-5
  local choice = me:slot(npc, "Select an inventory slot:", available_slots)
  if choice then
      me:message("You selected slot: " .. choice)
  end
  

Game System Functions

nation

Provides functionality to get or set the character's nation.

nation()

• Description:
  Returns the character's current nation.
• Parameters:
  • None
• Return Value:
  • number: Nation value
• Example:

  -- This is a real usage example from game scripts
  local nation = me:nation()
  me:message("Your nation: " .. nation)
  

nation(value:number)

• Description:
  Sets the character's nation to the specified value.
• Parameters:
  • value:number: Nation value to set
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:nation(1)
  

---

gain

gain(...items:fb.game.item)

• Description:
  Adds multiple items to the character's inventory at once.
• Parameters:
  • ...items:fb.game.item: Variable number of item objects to add
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  local items = map:belows(x, y, OBJECT_TYPE_ITEM)
  me:gain(table.unpack(items))
  

---

detect

Provides functionality to get or set the character's detect ability.

detect()

• Description:
  Returns whether the character has detect ability enabled.
• Parameters:
  • None
• Return Value:
  • boolean: True if detect is enabled, false otherwise
• Example:

  -- This is a real usage example from game scripts
  if me:detect() then
      me:message("Detect is enabled")
  end
  

detect(value:boolean)

• Description:
  Sets the character's detect ability.
• Parameters:
  • value:boolean: True to enable detect, false to disable
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:detect(true)  -- Enable detect
  

Mob Functions

spawn_mob

spawn_mob(name:string, [position:table|x:number, y:number], [owned:boolean])

• Description:
  Spawns a mob with the specified name at the given position. If no position is provided, spawns at the character's current location.
• Parameters:
  • name:string: Name of the mob to spawn
  • [position:table]: Position as table {x, y} (optional)
  • [x:number, y:number]: Position as separate coordinates (optional)
  • [owned:boolean]: Whether the spawned mob is owned by the character (default: true)
• Return Value:
  • fb.game.mob|nil: Spawned mob object or nil if failed
• Example:

  -- This is a real usage example from game scripts
  local mob = me:spawn_mob("가재", {100, 200}, true)
  if mob then
      me:message("Spawned mob at position")
  end
  
  -- Spawn at character's current position
  local mob2 = me:spawn_mob("다람쥐")
  

---

spawned_mobs

spawned_mobs()

• Description:
  Returns a table containing all mobs spawned by this character.
• Parameters:
  • None
• Return Value:
  • table: Table with indices as keys and spawned mob objects as values
• Example:

  -- This is a real usage example from game scripts
  local mobs = me:spawned_mobs()
  for i, mob in pairs(mobs) do
      me:message("Spawned mob " .. i .. ": " .. mob:model():name())
  end
  

---

creature

creature()

• Description:
  Returns the character's creature type or ID.
• Parameters:
  • None
• Return Value:
  • number: Character's creature type/ID
• Example:

  -- This is a real usage example from game scripts
  local creature_type = me:creature()
  me:message("Creature type: " .. creature_type)
  

---

teleport

teleport(target:fb.game.character)

• Description:
  Teleports the character to the target character's location.
• Parameters:
  • target:fb.game.character: Target character to teleport to
• Return Value:
  • boolean: true if teleport succeeded, false otherwise
• Example:

  -- This is a real usage example from game scripts
  local target = find_character("PlayerName")
  if target then
      local success = me:teleport(target)
      if success then
          me:message("Teleported successfully")
      else
          me:message("Teleport failed")
      end
  end
  

Spell Functions

mkspell

mkspell(name:string)

• Description:
  Adds a spell to the character's spell list by name. Returns the slot index where the spell was added, or 0 if failed.
• Parameters:
  • name:string: Name of the spell to add
• Return Value:
  • number: Slot index (1-based) where spell was added, or 0 if failed
• Example:

  -- This is a real usage example from game scripts
  me:mkspell(name)
  

---

rmspell

Provides functionality to remove spells from the character's spell list.

rmspell()

• Description:
  Removes all spells from the character's spell list.
• Parameters:
  • None
• Return Value:
  • None
• Example:

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

rmspell(slot:number)

• Description:
  Removes the spell at the specified slot index.
• Parameters:
  • slot:number: Slot index of the spell to remove
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:rmspell(slot)
  

rmspell(name:string)

• Description:
  Removes the spell with the specified name.
• Parameters:
  • name:string: Name of the spell to remove
• Return Value:
  • None
• Example:

  -- This is a real usage example from game scripts
  me:rmspell(learned_spells[selected+1])