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

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

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

tile_get_description (tile_number)

get the description for a given tile number

Parameters:

tile_number int

Returns:

string

anim_get_number_of_entries ()

get the number of tile animations

Returns:

int

anim_get_tile (anim_index)

get the tile number for a given animation number

Parameters:

anim_index int index of animation

Returns:

int

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

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

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

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

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

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

party

party_is_in_combat_mode ()

Check to see if the party is currently in combat mode

Returns:

boolean

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

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

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

map_can_put (location)

Can you put an actor at a given map location

Parameters:

location MapCoord or x,y,z

Returns:

boolean

map_can_put_obj (location)

Can you put an object at a given map location

Parameters:

location MapCoord or x,y,z

Returns:

bool

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

map_is_on_screen (location)

Checks if the map location is currently on screen

Parameters:

location MapCoord or x,y,z

Returns:

bool

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

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

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

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

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

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

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

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

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

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

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

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

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

Actor.move (actor, location)

Move actor to location.

Parameters:

actor Actor
location MapCoord or x,y,z

Returns:

bool

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

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

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

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

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

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

Nuvie

Contents

Modules

Module script

Functions

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Returns:

Parameters:

Parameters:

Returns:

Tables

Fields:

Fields:

Fields:

Fields:

Object

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Usage:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Usage:

player

Returns:

Returns:

Returns:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

party

Returns:

Parameters:

Module `script`