Objects and scripts




ObjectPtr dialog_obj()

Returns a pointer to the object (critter) the player is having a conversation or bartering with.



int get_flags(ObjectPtr obj)

Gets the current value of object flags (see define_extra.h for available flags).



get_object_data(ObjectPtr object, int offset)

Returns the data at the specified offset of an object (see OBJ_DATA_* constants in define_extra.h for offsets).


int get_script(ObjectPtr obj)
  • accepts a pointer to an object and returns its scriptID (line number in scripts.lst), or 0 if the object is unscripted.
  • returns -1 on argument error.



ObjectPtr loot_obj()

Returns a pointer to the target object (container or critter) of the loot screen.


int (ObjectPtr invenObj, ObjectPtr itemObj)

Returns number of itemObj inside invenObj’s inventory, note that both arguments are object pointers. useful when dealing with different stacks of same item (obj_is_carrying_obj_pid just returns total for all stacks of the same PID.)



bool obj_is_openable(object obj)

Returns True if the object is openable (i.e. has an opening/closing animation), False otherwise



ObjectPtr obj_under_cursor(bool onlyCritter, bool includeDude)

Returns the object under the cursor on the main game screen.

  • onlyCritter:
    • True - only checks critters and ignores their cover (roof tiles, walls, scenery, etc.)
    • False - checks all objects (can’t check critters under objects)
  • passing False to the includeDude argument will ignore dude_obj
    • NOTE: to get an object located on a tile when the cursor is in movement mode (hexagon cursor), use the tile_under_cursor function



ObjectPtr real_dude_obj()

Returns the initial dude_obj after set_dude_obj was used.


void remove_script(ObjectPtr obj)

Accepts a pointer to an object and will remove the script from that object.



void set_dude_obj(ObjectPtr critter)

Take control of a given critter. Passing value 0 will reset control back to “real” dude.



void set_flags(ObjectPtr obj, int flags)

Sets the current flags of an object. All flags are rewritten with given integer, so first get current flags with get_flags and use bwor/bwand to set/remove specific flag.



set_object_data(ObjectPtr object, int offset, int data)

Sets the data at the specified offset of an object.



void set_scr_name(string name)

Overrides the name of the script object that was set from scrname.msg.

  • The changed name will be reset each time the player leaves the map or reloads the game
  • Passing an empty string (“”) to the name argument or omitting it will allow the game to get the name for the object from pro_*.msg files
  • NOTE: this function is intended for use in normal game scripts and overrides the name only once for the same object until reset


void set_script(ObjectPtr obj, int scriptID)

Accepts a pointer to an object and scriptID, and applies the given script to an object (scriptID accept the same values as create_object_sid from sfall 3.6). If used on an object that is already scripted, it will remove the existing script first; you cannot have multiple scripts attached to a single object. Calling set_script on self_obj will have all sorts of wacky side effects, and should be avoided. If you add 0x80000000 to the sid when calling set_script, map_enter_p_proc will be SKIPPED. The start proc will always be run.


void set_self(ObjectPtr setObj)

Overrides the script’s self_obj for the next function call.

  • It is primarily used to allow the calling of functions which take an implicit self_obj parameter (e.g. drop_obj) from global scripts, but it can also be used from normal scripts.
  • self_obj will be reverted to its original value after the next function call.
  • Calling set_self(0) will also revert self_obj to its original value. It is recommended to call this after each use of set_self in normal scripts in order to avoid unforeseen side effects.
  • source_obj, target_obj, and similar functions will not work if preceded by set_self.
  • NOTE: for use_obj, use_obj_on_obj vanilla functions to work correctly, it is required to call set_self twice. You can also access the local variables in the script of an object after calling set_self twice.



int set_unique_id(ObjectPtr object, int flag)

Assigns a unique ID number to the object and returns it. If a unique ID number has already been assigned to an object, then ID number is returned without reassignment. flag is optional.

  • items with unique IDs will not stack with other items of the same type in the inventory
  • to just get the current ID number of an object, use get_object_data(object, OBJ_DATA_ID)
  • unique ID numbers are saved in your savegame, and have a range from 0x10000000 to 0x7FFFFFFF
  • there is also a unique ID number range for the player and party members from 18000 to 83535
  • to assign a new ID number generated by the engine to the object (i.e. unassign a unique ID), call the function with two arguments and pass -1 for the flag argument