Nuvie Lua Scripting API

# Module `script`

## Functions

clear_scroll () | Clear the message scroll
print (string) | Print a string to the message scroll
display_prompt (string) | Print the prompt string to the message scroll
nuvie_load (path) | Load a lua script from the data/scripts/ directory
config_get_boolean_value (config_key) | Get a boolean value for a given key from the config file
config_get_game_type () | Get the currently running game type
config_get_language () | Get the currently selected language
objlist_seek (position) | Seek to a given position in the objlist data
objlist_read1 () | Read a 1 byte integer number from the current position in the objlist data.
objlist_write1 (value) | Overwrite objlist data at the current position with a 1 byte unsigned number.
objlist_read2 () | Read a 2 byte integer number from the current position in the objlist data.
objlist_write2 (value) | Overwrite objlist data at the current position with a 2 byte unsigned number.
game_get_ui_style () | Get the currently selected UI style
map_export_tmx_files () | export map to Tiled TMX files.
tileset_export ([overWriteFile=false]) | export tileset to a bmp file ‘data/images/tiles/nn/custom_tiles.bmp’ in the current savegame directory.
tile_get_flag (tile_number, flag_set, bit_number) | get a tile flag for a given tile number
tile_get_description (tile_number) | get the description for a given tile number
anim_get_number_of_entries () | get the number of tile animations
anim_get_tile (anim_index) | get the tile number for a given animation number
anim_set_first_frame (anim_index, anim_start_tile) | set the starting animation frame for a given animation number
anim_get_first_frame (anim_index) | get the starting animation frame for a given animation number
anim_play (anim_index) | start playing animation
anim_stop (anim_index) | stop playing animation
play_end_sequence () | play the game end sequence then quit.
play_sfx (sfx_id[, async_playback=false]) | play a sound effect
wind_set_dir (direction) | Set the current wind direction (U6).
wind_get_dir () | Get the current wind direction (U6).
is_god_mode_enabled () | Is the god mode cheat currently active?
set_armageddon (new_value) | Set armageddon flag
load_text_from_lzc (filename, index) | Loads text from a given LZC file.

## Tables

Obj | An in-game object
MapCoord | A map coordinate
Schedule | An actor schedule entry
Actor | An Actor object

## Object

Obj.new ([obj[, obj_n[, frame_n[, quality[, qty[, x[, y[, z]]]]]]]]) | Create a new Obj.
Obj.moveToMap (obj[, location]) | Move an object to the map.
Obj.moveToInv (obj, actor_num) | Move an object into an Actor’s inventory
Obj.moveToCont (obj, container) | Move an object into a container
Obj.removeFromCont (obj) | Remove an object from its container.
Obj.use (obj) | Call the old C++ usecode logic for a given object.
Obj.removeFromEngine (obj) | Remove an object from the game engine.
usecode_look (object) | Call the C++ usecode look function for a given Obj
find_obj (z, obj_n[, frame_n[, quality]]) | Iterate through all objects of a specific type on a given map level.
find_obj_from_area (location, width, height) | Iterate through all objects within a given area.
objs_at_loc (location) | Iterate through objects at a given map location
find_volcano_near_player (location) | Find a volcano object near the player.
container_objs (container[, is_recursive=false]) | Iterate through objects in a container.

## player

player_get_name () | Get the player name
player_get_gender () | Get the gender of the player
player_get_location () | Get the location of the player
player_get_karma () | Get the player’s karma value (U6)
player_set_karma (value) | Set the karma value for the player (U6)
player_dec_alcohol (value) | Decrement the player’s alcohol counter (U6)
player_move (location, teleport) | Move player to given map location
player_set_actor (actor) | Make the given actor the player controlled actor.
player_is_in_solo_mode () | Check if the player is currently in solo mode

## party

party_is_in_combat_mode () | Check to see if the party is currently in combat mode
party_set_combat_mode (value) | Toggle combat mode
party_set_party_mode () | Set party mode.
party_move (location) | Move party to a given map location
party_use_entrance (entrance, exit) | Walk party members to an entrance and teleport them to the exit on the other side.
party_get_size () | Returns the number of members in the party
party_get_member (member_num) | Get the Actor object for a given party member
party_update_leader () | Get the current party leader and update player
party_resurrect_dead_members () | Resurrect dead party members
party_exit_vehicle (location) | Exit party members from vehicle
party_dismount_from_horses () | Dismount all party members from their horses (U6)
party_set_in_vehicle (value) | Toggle party vehicle mode
party_show_all () | Show all party members on the map.
party_hide_all () | Hide all party members on the map.
party_members () | Iterate through party members.

## map

map_get_obj (location[, obj_n[, inc_multi_tile_objs=false]]) | Get an object from the map
map_remove_obj (location[, obj_n]) | Remove an object from the map.
map_can_put (location) | Can you put an actor at a given map location
map_can_put_obj (location) | Can you put an object at a given map location
map_enable_temp_actor_cleaning (value) | Toggle automatic cleaning of out of area temporary actors.
map_is_water (location) | Check map location for water
map_is_on_screen (location) | Checks if the map location is currently on screen
map_get_impedence (x, y, z[, ignore_objects=true]) | Get the impedance of a map location
map_get_tile_num (location[, get_original_tile_num=false]) | get the map tile number for a given map location
map_get_dmg_tile_num (x, y, z) | get the tile number for given location if the map tile can do damage.
map_can_reach_point (x, y, x1, y1, z) | Returns true if a line between points x,y and x1, y1 does not cross any missile boundary tiles
map_line_hit_check (x, y, x1, y1, z) | Returns the first point on a line between x,y and x1, y1 where a missile boundary tile is crossed If no boundary tiles are crossed on the line then x1, y1 are returned

## effects

quake_start (magnitude, duration) | start earthquake effect.
explosion_start (tile_number, x, y) | Create an explosion at x,y on the current level.
projectile_anim (startx, starty, targetx, targety, speed, trail, initial_tile_rotation[, rotation_amount=0[, src_tile_y_offset=0]]) | Creates a single tile projectile effect.
projectile_anim_multi (tile_number, startx, starty, targets, speed, trail, initial_tile_rotation) | Create multiple projectile effects emanating from (startx,starty) going to multiple target locations
hit_anim (x, y) | Hit effect.
fade_out () | execute the pixelated map window fade out effect
fade_in () | execute the pixelated map window fade in effect
fade_tile (location, from_tile[, to_tile]) | pixel fade from one tile to another.
fade_obj (obj, fade_color, fade_speed) | black fade effect on a given object
xor_effect (duration) | xor effect.
xray_effect (duration) | xray effect.
peer_effect () | peer effect.
wing_strike_effect () | wing strike effect.
hail_storm_effect (location) | hail storm effect (U6).
wizard_eye_effect (start_location) | wizard’s eye effect (U6).

## time

timer_set (timer_idx, value) | Set specific game timer counter (U6).
timer_get (timer_idx) | Get specific game timer counter (U6).
timer_update_all (value) | Set all timer counters with a given value
clock_get_year () | Get the current year
clock_get_month () | Get the current month
clock_get_day () | Get the current day
clock_get_minute () | Get the clock minute value
clock_get_hour () | Get the clock hour value
clock_inc (minutes) | Increase the game clock by a number of minutes

## io

input_select (allowed_characters, can_escape) | Get input from the keyboard
input_select_integer (allowed_characters, can_escape) | Get an integer number as input from the player.
mouse_cursor_visible (visible) | Toggle mouse cursor visibility.
mouse_cursor_set_pointer (pointer_index) | Select which mouse cursor pointer to use.
script_wait (duration) | Pause the script.

## mapwindow

mapwindow_center_at_location (x, y, z) | Centre the mapwindow at a given location.
mapwindow_get_location () | Get the current location that the mapwindow is displaying.
mapwindow_set_location (x, y, z) | Set the current location that the mapwindow is displaying.
mapwindow_set_enable_blacking (enable_blacking) | Toggle mapwindow ‘blacking’.

## UI

display_text_in_scroll_gump (text) | Display string in scroll gump if in new style.
lock_inventory_view (actor) | Lock the inventory view to a specific Actor.
unlock_inventory_view () | Unlock the inventory view

## Actor

Actor.new (obj_n[, x=0[, y=0[, z=0[, alignment=NEUTRAL[, worktype=8]]]]]) | Create a new temporary Actor.
Actor.clone (actor, location) | Clone an actor as a new temporary actor.
Actor.get (actor_number) | Get an Actor object from an actor number
Actor.get_player_actor () | Get the current player Actor object
Actor.kill (actor[, create_body=true]) | Call the C++ Actor::die() method
Actor.hit (actor, damage) | Call the C++ Actor::hit() method
Actor.get_range (actor, target_x, target_y) | Calls the get_combat_range script function with the wrapped absolute x,y distances to the target
Actor.move (actor, location) | Move actor to location.
Actor.walk_path (actor) | Move the actor one space along their pathfinding path.
Actor.is_at_scheduled_location (actor) | Checks to see if the actor is currently at their scheduled worktype location.
Actor.can_carry_obj (actor, object) | Checks to see if the actor can carry an object.
Actor.can_carry_obj_weight (actor, object) | Checks to see if the actor can carry an object’s weight.
Actor.black_fade_effect (actor, fade_color, fade_speed) | Fade the black pixels in the actor’s tile to a specified color.
Actor.fade_out (actor, fade_speed) | Pixel fade out the actor’s tile to nothing.
Actor.show_portrait (actor) | Display the actor’s portrait
Actor.hide_portrait (actor) | Hide the actor’s portrait.
Actor.talk (actor) | Talk to actor.
Actor.unlink_surrounding_objs (actor, make_temp) | For multi-tile actors, disconnect their surrounding objects.
Actor.use (actor) | Call the C++ actor usecode logic.
Actor.resurrect (actor, location, body_obj) | Resurrect a dead actor.
Actor.inv_add_obj (actor, obj[, stack_objs=false]) | Add an object to the actor’s inventory.
Actor.inv_remove_obj (actor, obj) | Remove an object from the actor’s inventory
Actor.inv_remove_obj_qty (actor, obj_n, qty) | Remove a number of stackable objects from the actor’s inventory
Actor.inv_get_readied_obj_n (actor, location) | Returns the obj_n the object that is readied at a given location.
Actor.inv_ready_obj (actor, obj) | Ready an object from the actor’s inventory.
Actor.inv_unready_obj (actor, obj) | Unready an object from the actor.
Actor.inv_has_obj_n (actor, obj_n) | Check if the actor has an object of type obj_n in their inventory.
Actor.inv_get_obj_n (actor, obj_n[, frame_n[, quality]]) | Get the first object of type obj_n from the actor’s inventory.
Actor.inv_get_obj_total_qty (actor, obj_n) | Get the total number of objects of type obj_n in the actor’s inventory
map_get_actor (location[, excluded_actor]) | Get the actor at map location.
update_actor_schedules ([teleport_actors=false]) | Update all actor schedules.
actor_inventory (actor[, is_recursive=false]) | Iterate through objects in the actor’s inventory.
Actor.set_talk_flag (actor, flag) | Set one of the actor’s talk flags
Actor.get_talk_flag (actor, flag) | Get the value of one of the actor’s talk flags
Actor.clear_talk_flag (actor, flag) | Clear one of the actor’s talk flags
Actor.get_number_of_schedules (actor) | Get the number of schedule entries
Actor.get_schedule (actor, index) | Get an Actor schedule entry

## Functions

clear_scroll ()
  Clear the message scroll
print (string)
  Print a string to the message scroll

  ### Parameters:

  - string the string to print
display_prompt (string)
  Print the prompt string to the message scroll

  ### Parameters:

  - string the string to print
nuvie_load (path)
  Load a lua script from the data/scripts/ directory

  ### Parameters:

  - path lua file relative to data/scripts directory

  ### Returns:

  contents of the lua file as a function block on success.

             A string is returned on compilation failure.
             nil is returned if the file cannot be opened

config_get_boolean_value (config_key)
  Get a boolean value for a given key from the config file

  ### Parameters:

  - config_key config key to be retrieved

  ### Returns:

  boolean config value
config_get_game_type ()
  Get the currently running game type

  ### Returns:

  a two character string representing the current game type. “U6”, “MD” or “SE”
config_get_language ()
  Get the currently selected language

  ### Returns:

  a two character string representing the currently selected language. “en” is the default if no language has been selected.
objlist_seek (position)
  Seek to a given position in the objlist data

  ### Parameters:

  - position position to seek to in bytes relative to the start of the file
objlist_read1 ()
  Read a 1 byte integer number from the current position in the objlist data. The current position is incremented by 1 after the read.

  ### Returns:

  value
objlist_write1 (value)
  Overwrite objlist data at the current position with a 1 byte unsigned number. The current position is incremented by 1 after the write.

  ### Parameters:

  - value number to write. This number will be cast to uint8

  ### Returns:

  true on success false on failure
objlist_read2 ()
  Read a 2 byte integer number from the current position in the objlist data. The current position is incremented by 2 after the read.

  ### Returns:

  value
objlist_write2 (value)
  Overwrite objlist data at the current position with a 2 byte unsigned number. The current position is incremented by 2 after the write.

  ### Parameters:

  - value number to write. This number will be cast to uint16

  ### Returns:

  true on success false on failure
game_get_ui_style ()
  Get the currently selected UI style

  ### Returns:

  The UI style

  - 0 = Original style
  - 1 = New style
  - 2 = Original+ cutoff map
  - 3 = Original+ full map
map_export_tmx_files ()
  export map to Tiled TMX files. This creates 1 TMX file per map level. They are saved into the currently active save game directory.

  ### Returns:

  bool returns true if the tmx files were created successfully. false on error
tileset_export ([overWriteFile=false])
  export tileset to a bmp file ‘data/images/tiles/nn/custom_tiles.bmp’ in the current savegame directory.

  ### Parameters:

  - overWriteFile bool specifies if the output file should be overwritten if it already exists. (default false)

  ### Returns:

  bool returns true if the was written to disk. false otherwise
tile_get_flag (tile_number, flag_set, bit_number)
  get a tile flag for a given tile number

  ### Parameters:

  - tile_number int
  - flag_set int either 1, 2 or 3
  - bit_number int bit number of flag from flag_set 0..7

  ### Returns:

  bool or nil return flag or nil on error
tile_get_description (tile_number)
  get the description for a given tile number

  ### Parameters:

  - tile_number int

  ### Returns:

  string the descriptive string for the given tile number.
anim_get_number_of_entries ()
  get the number of tile animations

  ### Returns:

  int number of animations
anim_get_tile (anim_index)
  get the tile number for a given animation number

  ### Parameters:

  - anim_index int index of animation

  ### Returns:

  int tile number
anim_set_first_frame (anim_index, anim_start_tile)
  set the starting animation frame for a given animation number

  ### Parameters:

  - anim_index int index of animation loop to change
  - anim_start_tile int the tile number of the start animation
anim_get_first_frame (anim_index)
  get the starting animation frame for a given animation number

  ### Parameters:

  - anim_index int index of animation

  ### Returns:

  int tile number of first animation frame
anim_play (anim_index)
  start playing animation

  ### Parameters:

  - anim_index int index of animation to play
anim_stop (anim_index)
  stop playing animation

  ### Parameters:

  - anim_index int index of animation
play_end_sequence ()
  play the game end sequence then quit. The file ending.lua is used from the relevant game’s script directory.
play_sfx (sfx_id[, async_playback=false])
  play a sound effect

  ### Parameters:

  - sfx_id int the sound effect index number.
  - async_playback bool if true then the sfx is played back asynchronously. (default false)
wind_set_dir (direction)
  Set the current wind direction (U6).

  ### Parameters:

  - direction int new wind direction
wind_get_dir ()
  Get the current wind direction (U6).

  ### Returns:

  integer
is_god_mode_enabled ()
  Is the god mode cheat currently active?

  ### Returns:

  bool
set_armageddon (new_value)
  Set armageddon flag

  ### Parameters:

  - new_value bool
load_text_from_lzc (filename, index)
  Loads text from a given LZC file.

  ### Parameters:

  - filename string the lzc file to extract the text from
  - index int offset in the lzc file to load the text from

  ### Returns:

  string the extracted text

## Tables

Obj
  An in-game object

  ### Fields:

  - parent (Obj|Actor) The parent of this object. Either an object if this object is in a container. Or an Actor if this object is in an inventory.
  - luatype string This returns “obj” readonly
  - x int x position
  - y int y position
  - z int z position
  - xyz MapCoord The object’s Location in a MapCoord table. readonly
  - obj_n int object number
  - frame_n int frame number
  - quality int
  - qty int quantity
  - name string The object name from the ‘look’ table. readonly
  - look_string string

    A printable look description

         a book
         an elephant
         5 torches

    readonly
  - on_map bool Is the object on the map? readonly
  - in_container bool Is the object in a container? readonly
  - readied bool Is this object readied in someone’s inventory? readonly
  - stackable bool Is this object able to be stacked together? readonly
  - weight number The object’s weight readonly
  - tile_num int The tile number corresponding to the obj_n + frame_num values readonly
  - getable bool Is this object getable by the player? readonly
  - ok_to_take bool Is it considered stealing if the player gets this object?
  - status int Object status
  - invisible bool Toggle object visibility
  - temporary bool Toggle temporary status writeonly
MapCoord
  A map coordinate

  ### Fields:

  - x int
  - y int
  - z int 0 for the 1024x1024 surface level, 1..5 for the dungeon levels
Schedule
  An actor schedule entry

  ### Fields:

  - day_of_week int
  - worktype int
  - x int
  - y int
  - z int
Actor
  An Actor object

  ### Fields:

  - xyz table containing location

    table format `<code> {["x"]=x, ["y"]=y, ["z"]=z} </code>` readonly

  - luatype string This returns “actor” readonly
  - actor_num int readonly
  - align int

    alignment

    - 0 = DEFAULT
    - 1 = NEUTRAL
    - 2 = EVIL
    - 3 = GOOD
    - 4 = CHAOTIC
  - alive bool readonly
  - asleep bool
  - base_obj_n int
  - charmed bool
  - cold bool (MD) bit 0 on the status flags. Set when the actor is cold.
  - combat_mode int
  - corpser_flag bool (U6) Has the actor been dragged underground by a corpser
  - cursed bool
  - dex int dexterity
  - direction int

    The direction that the actor is facing.

    - 0 = NORTH
    - 1 = EAST
    - 2 = SOUTH
    - 3 = WEST
    - 4 = NORTHEAST
    - 5 = SOUTHEAST
    - 6 = SOUTHWEST
    - 7 = NORTHWEST
    - 8 = NONE
  - exp int experience
  - frame_n int
  - frenzy bool (MD) battle frenzy
  - hit_flag bool Used by U6 to determine if an actor has been hit.
  - hp int hit points
  - hypoxia bool (MD) bit 6 on the obj flags. Tells if the actor is oxygen deprived
  - in_party bool Is the actor a mamber of the party? readonly
  - in_vehicle bool Is the actor currently in a vehicle? readonly
  - int int intelligence
  - level int
  - magic int
  - max_hp int readonly
  - mpts int movement points
  - name string readonly
  - obj_flag_0 bool obj flag 0
  - obj_n int
  - old_align int Old alignment
  - old_frame_n int readonly
  - paralyzed bool
  - poisoned bool
  - protected bool
  - sched_loc int The location defined for the Actor’s currently active schedule entry. readonly
  - sched_wt int The worktype of the currently active schedule. readonly
  - str int strength
  - temp bool Is this a temporary actor? readonly
  - tile_num int The tile number based on the obj_n + frame_n combination. readonly
  - visible bool Is the actor currently visible?
  - wt int worktype
  - x int
  - y int
  - z int

## Object

Obj.new ([obj[, obj_n[, frame_n[, quality[, qty[, x[, y[, z]]]]]]]])
  Create a new Obj. This function can clone and existing object or create a new object from one or more parameters.

  ### Parameters:

  - obj Obj Object to clone
  - obj_n int Object number
  - frame_n int Frame number
  - quality int Quality
  - qty int Quantity
  - x int x map position
  - y int y map position
  - z int z map position

  ### Returns:

  Obj The newly created object
Obj.moveToMap (obj[, location])
  Move an object to the map.

  ### Parameters:

  - obj Obj Object to move
  - location MapCoord or x,y,z Map location. If not supplied the location will be taken from the object’s x,y and z variables
Obj.moveToInv (obj, actor_num)
  Move an object into an Actor’s inventory

  ### Parameters:

  - obj Obj Object to move
  - actor_num int Actor number
Obj.moveToCont (obj, container)
  Move an object into a container

  ### Parameters:

  - obj Obj Object to move
  - container Obj Container object to move into
Obj.removeFromCont (obj)
  Remove an object from its container. The object will be unlinked from the engine after this operation. It will be freed after it goes out of scope.

  ### Parameters:

  - obj Obj Object to move
Obj.use (obj)
  Call the old C++ usecode logic for a given object. (U6)

  ### Parameters:

  - obj Obj Object to use
Obj.removeFromEngine (obj)
  Remove an object from the game engine. The object will be unlinked from the engine after this operation. It will be freed after it goes out of scope.

  ### Parameters:

  - obj Obj Object to unlink
usecode_look (object)
  Call the C++ usecode look function for a given Obj

  ### Parameters:

  - object Obj object to look at

  ### Returns:

  bool returns true if the Obj has a C++ usecode look function
find_obj (z, obj_n[, frame_n[, quality]])
  Iterate through all objects of a specific type on a given map level.

  ### Parameters:

  - z int map level to search
  - obj_n int object number to search for
  - frame_n int filter search based on specific frame number
  - quality int filter search based on specific quality value

  ### Usage:

        local loc = player_get_location()
        for obj in find_obj(loc.z, 223, 1) do
          if obj ~= nil then
            explode_obj(obj)
          end
        end

find_obj_from_area (location, width, height)
  Iterate through all objects within a given area.

  ### Parameters:

  - location MapCoord or x,y,z location for the effect to take place
  - width int width of area to search
  - height int height of area to search
objs_at_loc (location)
  Iterate through objects at a given map location

  ### Parameters:

  - location MapCoord or x,y,z
find_volcano_near_player (location)
  Find a volcano object near the player. This function searches an area +/– 5 tiles around the location specified. The search starts top left and finishes bottom right. The first volcano/fumarole object found is returned.

  ### Parameters:

  - location MapCoord or x,y,z centre of the search area

  ### Returns:

  Obj or nil first volcano/fumarole object found or nil if none found.
container_objs (container[, is_recursive=false])
  Iterate through objects in a container.

  ### Parameters:

  - container Obj container object to search.
  - is_recursive bool should we search containers inside the container? (default false)

  ### Usage:

        local child
        for child in container_objs(obj) do  -- look through container for effect object.
          if child.obj_n == 337 then --effect
            found = true
            print("\nIt's trapped.\n");
            break
          end
        end

## player

player_get_name ()
  Get the player name

  ### Returns:

  string player name
player_get_gender ()
  Get the gender of the player

  ### Returns:

  - 0 = Male
  - 1 = Female
player_get_location ()
  Get the location of the player

  ### Returns:

  MapCoord
player_get_karma ()
  Get the player’s karma value (U6)

  ### Returns:

  karma value
player_set_karma (value)
  Set the karma value for the player (U6)

  ### Parameters:

  - value new karma value
player_dec_alcohol (value)
  Decrement the player’s alcohol counter (U6) If value is greater than the counter the the counter is left at zero.

  ### Parameters:

  - value number to decrement counter by
player_move (location, teleport)
  Move player to given map location

  ### Parameters:

  - location MapCoord or x,y,z map location to move player to.
  - teleport bool spawn eggs if true
player_set_actor (actor)
  Make the given actor the player controlled actor.

  ### Parameters:

  - actor Actor
player_is_in_solo_mode ()
  Check if the player is currently in solo mode

  ### Returns:

  bool true if the player is in solo mode otherwise false

## party

party_is_in_combat_mode ()
  Check to see if the party is currently in combat mode

  ### Returns:

  boolean true if the party is in combat mode otherwise false
party_set_combat_mode (value)
  Toggle combat mode

  ### Parameters:

  - value boolean
party_set_party_mode ()
  Set party mode. The first member in the party becomes the leader.
party_move (location)
  Move party to a given map location

  ### Parameters:

  - location MapCoord or x,y,z map location to move party to.
party_use_entrance (entrance, exit)
  Walk party members to an entrance and teleport them to the exit on the other side.

  Warning: This function uses an old timer based class. So it will execute synchronously on subsequent calls to the main update loop.

  FIXME: This logic should probably be done in pure script with pathfinder helper functions. ;–)

  ### Parameters:

  - entrance x,y,z entrance location
  - exit MapCoord or x,y,z exit location
party_get_size ()
  Returns the number of members in the party

  ### Returns:

  int number of party members
party_get_member (member_num)
  Get the Actor object for a given party member

  ### Parameters:

  - member_num int index of party member to retrieve

  ### Returns:

  Actor or nil returns nil if actor cannot be found for given index
party_update_leader ()
  Get the current party leader and update player
party_resurrect_dead_members ()
  Resurrect dead party members
party_exit_vehicle (location)
  Exit party members from vehicle

  ### Parameters:

  - location MapCoord or x,y,z map location to move party to once they exit the vehicle
party_dismount_from_horses ()
  Dismount all party members from their horses (U6)
party_set_in_vehicle (value)
  Toggle party vehicle mode

  ### Parameters:

  - value bool
party_show_all ()
  Show all party members on the map.
party_hide_all ()
  Hide all party members on the map.
party_members ()
  Iterate through party members.

  ### Usage:

        local actor
        for actor in party_members() do
          actor.poisoned = false
        end

## map

map_get_obj (location[, obj_n[, inc_multi_tile_objs=false]])
  Get an object from the map

  ### Parameters:

  - location MapCoord or x,y,z
  - obj_n object number
  - inc_multi_tile_objs bool Should this search also include surrounding multi-tile objects that cover this location? (default false)

  ### Returns:

  Obj or nil
map_remove_obj (location[, obj_n])
  Remove an object from the map.

  Once removed from the map the object has no engine location and will be cleaned up in the next GC

  ### Parameters:

  - location MapCoord or x,y,z
  - obj_n object number

  ### Returns:

  boolean success/failure
map_can_put (location)
  Can you put an actor at a given map location

  ### Parameters:

  - location MapCoord or x,y,z

  ### Returns:

  boolean true if actor an be placed at location otherwise false
map_can_put_obj (location)
  Can you put an object at a given map location

  ### Parameters:

  - location MapCoord or x,y,z

  ### Returns:

  bool true if an object an be placed at location otherwise false
map_enable_temp_actor_cleaning (value)
  Toggle automatic cleaning of out of area temporary actors.

  ### Parameters:

  - value bool
map_is_water (location)
  Check map location for water

  ### Parameters:

  - location MapCoord or x,y,z

  ### Returns:

  bool true if the map at location is a water tile otherwise false
map_is_on_screen (location)
  Checks if the map location is currently on screen

  ### Parameters:

  - location MapCoord or x,y,z

  ### Returns:

  bool true if the map location is currently on screen otherwise false
map_get_impedence (x, y, z[, ignore_objects=true])
  Get the impedance of a map location

  ### Parameters:

  - x int
  - y int
  - z int
  - ignore_objects bool Ignore objects while calculating impedance (default true)

  ### Returns:

  int impedance
map_get_tile_num (location[, get_original_tile_num=false])
  get the map tile number for a given map location

  ### Parameters:

  - location MapCoord or x,y,z
  - get_original_tile_num bool return the original tile_num. (default false)

  ### Returns:

  int or nil
map_get_dmg_tile_num (x, y, z)
  get the tile number for given location if the map tile can do damage. If the base map tile does not do damage then objects at the map location are also searched and the tile number of the first object that can damage the player is returned.

  ### Parameters:

  - x int
  - y int
  - z int

  ### Returns:

  int or nil tile number of the damaging tile or nil if no damaging tiles are found at the location
map_can_reach_point (x, y, x1, y1, z)
  Returns true if a line between points x,y and x1, y1 does not cross any missile boundary tiles

  ### Parameters:

  - x int
  - y int
  - x1 int
  - y1 int
  - z int

  ### Returns:

  bool
map_line_hit_check (x, y, x1, y1, z)
  Returns the first point on a line between x,y and x1, y1 where a missile boundary tile is crossed If no boundary tiles are crossed on the line then x1, y1 are returned

  ### Parameters:

  - x int
  - y int
  - x1 int
  - y1 int
  - z int

  ### Returns:

  int,int an x,y coord

## effects

quake_start (magnitude, duration)
  start earthquake effect. This shakes the mapwindow and makes a sound.

  ### Parameters:

  - magnitude int quake strength
  - duration int duration of effect in milliseconds

  ### Returns:

  bool always returns true
explosion_start (tile_number, x, y)
  Create an explosion at x,y on the current level. This function returns an iterator function to iterate through a list of Actors and Objects that were hit by the explosion.

  ### Parameters:

  - tile_number int
  - x int
  - y int

  ### Returns:

  table A table containing the hit Actor and Obj objects.

  ### Usage:

          local hit_items = explosion_start(0x17e, actor.x, actor.y)

          for k,v in pairs(hit_items) do
            if v.luatype == "actor" then
              actor_hit(v, random(1, 0x14))
            end
          end

projectile_anim (startx, starty, targetx, targety, speed, trail, initial_tile_rotation[, rotation_amount=0[, src_tile_y_offset=0]])
  Creates a single tile projectile effect. This travels in a straight line from (startx,starty) to (targetx,targety) the tile can leave a trail and rotate whilst moving.

  ### Parameters:

  - startx int
  - starty int
  - targetx int
  - targety int
  - speed int how far the tile travels each update. The tile will move speed * 2 pixels along the line each iteration
  - trail bool if true a copy of the tile will be left at intervals along the line
  - initial_tile_rotation int in degrees
  - rotation_amount int in degrees (default 0)
  - src_tile_y_offset int use by U6 projectile tiles which need to be centred vertically before rotation. eg arrows. (default 0)

  ### Returns:

  bool Always returns true
projectile_anim_multi (tile_number, startx, starty, targets, speed, trail, initial_tile_rotation)
  Create multiple projectile effects emanating from (startx,starty) going to multiple target locations

  ### Parameters:

  - tile_number int
  - startx int
  - starty int
  - targets {MapCoord,...}
  - speed int
  - trail int
  - initial_tile_rotation int

  ### Returns:

  table or bool A table containing the hit Actor and Obj objects. Or false if argument 4 isn’t a table
hit_anim (x, y)
  Hit effect. Displays the hit/damage tile over the map at a given location for a short period of time. The hit sfx is also played.

  ### Parameters:

  - x int
  - y int

  ### Returns:

  bool Always returns true
fade_out ()
  execute the pixelated map window fade out effect
fade_in ()
  execute the pixelated map window fade in effect
fade_tile (location, from_tile[, to_tile])
  pixel fade from one tile to another. If to_tile is not supplied the fade to blank

  ### Parameters:

  - location MapCoord or x,y,z location for the effect to take place
  - from_tile int tile number of the tile to fade from
  - to_tile int tile number of the tile to fade to
fade_obj (obj, fade_color, fade_speed)
  black fade effect on a given object

  ### Parameters:

  - obj Obj object to fade
  - fade_color int the colour (palette index) to fade the black pixels to.
  - fade_speed int
xor_effect (duration)
  xor effect. XOR the colours on the mapwindow

  ### Parameters:

  - duration int in milliseconds
xray_effect (duration)
  xray effect. Disable map blacking. (see through walls)

  ### Parameters:

  - duration int in milliseconds
peer_effect ()
  peer effect. Display an overview of the current area in the MapWindow. Any new actions cancel the effect and return to the script. (area is 48x48 tiles around the player, regardless of MapWindow size)
wing_strike_effect ()
  wing strike effect. A dragon flies across the screen. (U6)
hail_storm_effect (location)
  hail storm effect (U6). Hail stones rain down on the mapwindow.

  ### Parameters:

  - location MapCoord or x,y,z
wizard_eye_effect (start_location)
  wizard’s eye effect (U6).

  ### Parameters:

  - start_location MapCoord or x,y,z

## time

timer_set (timer_idx, value)
  Set specific game timer counter (U6). These counters are decremented each turn and are used for things like torch duration, eclipse etc.

  ### Parameters:

  - timer_idx int
  - value int
timer_get (timer_idx)
  Get specific game timer counter (U6). These counters are decremented each turn and are used for things like torch duration, eclipse etc.

  ### Parameters:

  - timer_idx int

  ### Returns:

  integer value of the timer
timer_update_all (value)
  Set all timer counters with a given value

  ### Parameters:

  - value int
clock_get_year ()
  Get the current year

  ### Returns:

  integer
clock_get_month ()
  Get the current month

  ### Returns:

  integer
clock_get_day ()
  Get the current day

  ### Returns:

  integer
clock_get_minute ()
  Get the clock minute value

  ### Returns:

  integer
clock_get_hour ()
  Get the clock hour value

  ### Returns:

  integer the hour in 24 hour format
clock_inc (minutes)
  Increase the game clock by a number of minutes

  ### Parameters:

  - minutes int the number of minutes to increment the clock by

## io

input_select (allowed_characters, can_escape)
  Get input from the keyboard

  ### Parameters:

  - allowed_characters string set to nil if all characters are permitted
  - can_escape bool can the player use escape to skip input

  ### Returns:

  string characters input by the player
input_select_integer (allowed_characters, can_escape)
  Get an integer number as input from the player. The characters input by the player are converted into an integer using the C function strtol()

  ### Parameters:

  - allowed_characters string set to nil if all characters are permitted
  - can_escape bool can the player use escape to skip input

  ### Returns:

  integer number input by the player
mouse_cursor_visible (visible)
  Toggle mouse cursor visibility.

  ### Parameters:

  - visible bool
mouse_cursor_set_pointer (pointer_index)
  Select which mouse cursor pointer to use.

  ### Parameters:

  - pointer_index int
script_wait (duration)
  Pause the script. Tile animation will continue while the script is paused.

  ### Parameters:

  - duration int in milliseconds

## mapwindow

mapwindow_center_at_location (x, y, z)
  Centre the mapwindow at a given location.

  ### Parameters:

  - x int
  - y int
  - z int
mapwindow_get_location ()
  Get the current location that the mapwindow is displaying. This is the top left corner of the mapwindow.

  ### Returns:

  MapCoord
mapwindow_set_location (x, y, z)
  Set the current location that the mapwindow is displaying. This is the top left corner

  ### Parameters:

  - x int
  - y int
  - z int
mapwindow_set_enable_blacking (enable_blacking)
  Toggle mapwindow ‘blacking’. Blacking hides tiles that are not visible to the player because they are obscured by a wall.

  ### Parameters:

  - enable_blacking bool

## UI

display_text_in_scroll_gump (text)
  Display string in scroll gump if in new style. Otherwise display on regular message scroll.

  ### Parameters:

  - text string the text to display in the scroll
lock_inventory_view (actor)
  Lock the inventory view to a specific Actor.

  ### Parameters:

  - actor Actor
unlock_inventory_view ()
  Unlock the inventory view

## Actor

Actor.new (obj_n[, x=0[, y=0[, z=0[, alignment=NEUTRAL[, worktype=8]]]]])
  Create a new temporary Actor.

  ### Parameters:

  - obj_n int
  - x int (default 0)
  - y int (default 0)
  - z int (default 0)
  - alignment int (default NEUTRAL)
  - worktype int (default 8)

  ### Returns:

  Actor or nil
Actor.clone (actor, location)
  Clone an actor as a new temporary actor.

  ### Parameters:

  - actor Actor Actor to clone
  - location MapCoord or x,y,z Location to place newly cloned actor.
Actor.get (actor_number)
  Get an Actor object from an actor number

  ### Parameters:

  - actor_number int

  ### Returns:

  Actor
Actor.get_player_actor ()
  Get the current player Actor object

  ### Returns:

  Actor
Actor.kill (actor[, create_body=true])
  Call the C++ Actor::die() method

  ### Parameters:

  - actor Actor
  - create_body bool Create a dead body on the map? (default true)
Actor.hit (actor, damage)
  Call the C++ Actor::hit() method

  ### Parameters:

  - actor Actor
  - damage int
Actor.get_range (actor, target_x, target_y)
  Calls the get_combat_range script function with the wrapped absolute x,y distances to the target

  ### Parameters:

  - actor Actor
  - target_x int
  - target_y int

  ### Returns:

  int range
Actor.move (actor, location)
  Move actor to location.

  ### Parameters:

  - actor Actor
  - location MapCoord or x,y,z

  ### Returns:

  bool Returns true is the move was successful. False if the move fails.
Actor.walk_path (actor)
  Move the actor one space along their pathfinding path.

  ### Parameters:

  - actor Actor
Actor.is_at_scheduled_location (actor)
  Checks to see if the actor is currently at their scheduled worktype location.

  ### Parameters:

  - actor Actor

  ### Returns:

  bool
Actor.can_carry_obj (actor, object)
  Checks to see if the actor can carry an object. It first checks that the object is get-able then checks that the actor can physically carry the object’s weight.

  ### Parameters:

  - actor Actor
  - object Obj

  ### Returns:

  bool
Actor.can_carry_obj_weight (actor, object)
  Checks to see if the actor can carry an object’s weight.

  ### Parameters:

  - actor Actor
  - object Obj

  ### Returns:

  bool
Actor.black_fade_effect (actor, fade_color, fade_speed)
  Fade the black pixels in the actor’s tile to a specified color.

  ### Parameters:

  - actor Actor
  - fade_color int
  - fade_speed int
Actor.fade_out (actor, fade_speed)
  Pixel fade out the actor’s tile to nothing.

  ### Parameters:

  - actor Actor
  - fade_speed int
Actor.show_portrait (actor)
  Display the actor’s portrait

  ### Parameters:

  - actor Actor
Actor.hide_portrait (actor)
  Hide the actor’s portrait. The party view is shown if in original UI mode.

  ### Parameters:

  - actor Actor
Actor.talk (actor)
  Talk to actor. The script will pause until the conversation has ended.

  ### Parameters:

  - actor Actor
Actor.unlink_surrounding_objs (actor, make_temp)
  For multi-tile actors, disconnect their surrounding objects.

  ### Parameters:

  - actor Actor
  - make_temp bool Should the objects be made temporary?
Actor.use (actor)
  Call the C++ actor usecode logic.

  ### Parameters:

  - actor Actor
Actor.resurrect (actor, location, body_obj)
  Resurrect a dead actor. If the actor’s body is not on the map then the actor will be placed at a random map location around the player.

  ### Parameters:

  - actor Actor
  - location MapCoord or x,y,z Location to put the resurrected actor on the map
  - body_obj Obj The dead actor’s body object.
Actor.inv_add_obj (actor, obj[, stack_objs=false])
  Add an object to the actor’s inventory.

  ### Parameters:

  - actor Actor
  - obj Obj
  - stack_objs bool Should we stack obj.qty into existing objects? (default false)
Actor.inv_remove_obj (actor, obj)
  Remove an object from the actor’s inventory

  ### Parameters:

  - actor Actor
  - obj Obj
Actor.inv_remove_obj_qty (actor, obj_n, qty)
  Remove a number of stackable objects from the actor’s inventory

  ### Parameters:

  - actor Actor
  - obj_n int Type of object to remove.
  - qty int Number of objects to remove.

  ### Returns:

  int returns the number of objects actually removed. This may be less than were requested.
Actor.inv_get_readied_obj_n (actor, location)
  Returns the obj_n the object that is readied at a given location.

  ### Parameters:

  - actor Actor
  - location int
    - 0 = HEAD
    - 1 = NECK
    - 2 = BODY
    - 3 = ARM
    - 4 = ARM_2
    - 5 = HAND
    - 6 = HAND_2
    - 7 = FOOT

  ### Returns:

  int returns obj_n or -1 if nothing is readied at the specified location.
Actor.inv_ready_obj (actor, obj)
  Ready an object from the actor’s inventory.

  ### Parameters:

  - actor Actor
  - obj Obj
Actor.inv_unready_obj (actor, obj)
  Unready an object from the actor. First attempt to unready object using usecode. If there is no unready usecode then just unready the object normally.

  ### Parameters:

  - actor Actor
  - obj Obj
Actor.inv_has_obj_n (actor, obj_n)
  Check if the actor has an object of type obj_n in their inventory.

  ### Parameters:

  - actor Actor
  - obj_n int object number to search for

  ### Returns:

  bool
Actor.inv_get_obj_n (actor, obj_n[, frame_n[, quality]])
  Get the first object of type obj_n from the actor’s inventory.

  ### Parameters:

  - actor Actor
  - obj_n int object number to search for
  - frame_n int search on frame number
  - quality int search on object quality

  ### Returns:

  Obj returns an object or nil if no match was found
Actor.inv_get_obj_total_qty (actor, obj_n)
  Get the total number of objects of type obj_n in the actor’s inventory

  ### Parameters:

  - actor Actor
  - obj_n int object number to search for

  ### Returns:

  int
map_get_actor (location[, excluded_actor])
  Get the actor at map location.

  ### Parameters:

  - location MapCoord or x,y,z
  - excluded_actor Actor Actor to be excluded from search results

  ### Returns:

  Actor returns the actor or nil if no actor was found
update_actor_schedules ([teleport_actors=false])
  Update all actor schedules. Schedules change on the hour.

  ### Parameters:

  - teleport_actors bool Should actors teleport to their new scheduled location? (default false)
actor_inventory (actor[, is_recursive=false])
  Iterate through objects in the actor’s inventory.

  ### Parameters:

  - actor Actor
  - is_recursive bool should we search containers inside the inventory? (default false)

  ### Usage:

         local ac = 0
         local obj

         for obj in actor_inventory(actor) do
            if obj.readied then
               local armour = armour_tbl[obj.obj_n]
               if armour ~= nil then
                  ac = ac + armour
               end
            end
         end

Actor.set_talk_flag (actor, flag)
  Set one of the actor’s talk flags

  ### Parameters:

  - actor Actor
  - flag int The flag to set. 0..7
Actor.get_talk_flag (actor, flag)
  Get the value of one of the actor’s talk flags

  ### Parameters:

  - actor Actor
  - flag int The flag to get. 0..7

  ### Returns:

  bool returns the flag value
Actor.clear_talk_flag (actor, flag)
  Clear one of the actor’s talk flags

  ### Parameters:

  - actor Actor
  - flag int The flag to clear. 0..7
Actor.get_number_of_schedules (actor)
  Get the number of schedule entries

  ### Parameters:

  - actor Actor

  ### Returns:

  int
Actor.get_schedule (actor, index)
  Get an Actor schedule entry

  ### Parameters:

  - actor Actor
  - index int The index of the schedule to retrieve

  ### Returns:

  Schedule

generated by LDoc 1.4.2