Objects and scripts

Functions

dialog_obj

sfall.h

ObjectPtr dialog_obj()

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

get_flags

sfall.h

int get_flags(ObjectPtr obj)

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

get_object_data

sfall.h

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).

get_script 

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.

loot_obj

sfall.h

ObjectPtr loot_obj()

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

obj_is_carrying_obj 

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.)

obj_is_openable

sfall.h

bool obj_is_openable(object obj)

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

obj_under_cursor

sfall.h

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

real_dude_obj

sfall.h

ObjectPtr real_dude_obj()

Returns the initial dude_obj after set_dude_obj was used.

remove_script 

void remove_script(ObjectPtr obj)

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

set_dude_obj

sfall.h

void set_dude_obj(ObjectPtr critter)

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

set_flags

sfall.h

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

sfall.h

set_object_data(ObjectPtr object, int offset, int data)

Sets the data at the specified offset of an object.

set_scr_name

sfall.h

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

set_script 

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.

set_self 

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.

set_unique_id

sfall.h

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