Overview Screenshots Downloads News Documentation Thanks Simugraph Home Page

H-World - Scripts manual

Descriptions are up to date with H-World version 0.3.5

H-World uses Lua as scripting language. The scripts reside in the 'scripts' directory. At program start H-World reads 'init.lua' from the scripts directory. You can either put all your functions in that one file or just use the 'init.lua' file to read other lua scripts. The default game 'The Jungle' coming with H-World uses the latter approach.

More details about Lua can be found at www.lua.org.

Configuring scripts

There are several ways to invoke Lua scripts in H-World:

  1. Invoking scripts if items are used (since H-World 0.0.4): [module]/scripts/usages.lua
  2. Invoking scripts if items are weld or took off (since H-World 0.0.5): [module]/scripts/usages.lua
  3. Invoking scripts if items are combined (since H-World 0.1.5): [module]/scripts/recipes.lua
  4. Invoking scripts as user commands (since H-World 0.2.0): [module]/scripts/commands.lua
  5. Engine callbacks (since H-World 0.3.8): [module]/scripts/core.lua
  6. Invoking scripts as AI commands (since H-World 0.3.9): [module]/scripts/ai.lua

Some scripts are triggered automatically:

  1. Combat (since H-World 0.0.6): scripts/attacks.lua
  2. Item combinations/recipes (since H-World 0.1.5): scripts/recipes.lua
  3. Effects that are triggered per round (since H-World 0.1.6): scripts/effects.lua
  4. Engine callbacks (since H-World 0.3.8): [module]/scripts/core.lua
  5. Invoking scripts as AI commands (since H-World 0.3.9: scripts/ai.lua

Item usages

Items can be configured to have usages. A block like this is used to tell H-World which usages an item provides: 

usages = 1
usage[0].name = lua_call
usage[0].verb = quaff

The example is from a healing potion.

The usage name 'lua_call' tells H-World that this usage calls a lua function names 'quaff'. An item can have an number of usages. See item configuration for more details how to configure items in H-World.

The 'quaff' lua function looks like this:
example_quaff.html

The signature of a usage function is always function functionname (user, inventory, item). The user and item parameters are both of type thing that is the common base type for everything inside H-World.

Accessing/Changing item properties

Item properties can be read by the following function: 

value = thing_get_value(thing, "property_name")

Item properties can be set by the following function: 

thing_set_value(thing, "property_name", value)

Please read item configuration for more details how to configure item properties in H-World.

Wielding/taking off items

Items can have properties for calling lua functions if the item is weld or unweld by the player: 

lua_wield = functionname
lua_unwield = functionname

Items which have this properties defined just call the configured lua functions if they are weld or unweld. The functions signature is the same as for usage functions: 

function functionname (user, item)

In ./scripts/usages.lua there are two procedures base_wield(user, item) and base_unwield(user, item). They are called by the H-World CRPG engine every time that an item is weld or taken off. Global functionality that applies to all or a large number of items should go there.

See the section about configuring usages to learn more how to define and write the lua functions.

See item configuration for more details how to configure items in H-World.

Recipes

If an item in the inventory view is dropped onto another item of different type, then H-World calls drop_item(user, item, drop) which is defined in ./scripts/recipes.lua. This procedure then evalutes if those items are combinabale somohow, or if some effect is triggered by connecting those items.

There are a few examples for mixing potions implemented in the example game "The Jungle". Further ideas thet can be implemneted via recipes could be magical items that can be combined to more powerful magical items, socketed items and gems as knwon from Diablo II, or for technical setting, adding fuel or batteries to gadgets and devices. I guess the inventive game creator will find a lot more usages for recipes.

Engine callbacks

The H-World engine calls some Lua function upon certain events, e.g. creation of an item/monster or killing/destroying one. This allows to add custom code to these events. The callback functions are usually part of [module]/scripts/core.lua

Callback function Description
Call
  calculate_ident_string(thing, memorized)
Arguments
  thing: type thing_t, the thing to check
  memorized: nil if not memorized, non-nil if memorized
Return value
  ident string

Description:
  This function is called by the engine to determine an item identifier string. Different games will need different ident strings, thus this functionality was moved into this script.

Available:
  Since H-World 0.3.8

Call
  calculate_plain_ident_string(thing, memorized)
Arguments
  thing: type thing_t, the thing to check
  memorized: nil if not memorized, non-nil if memorized
Return value
  ident string

Description:
  This function is similar to calculate_ident_string() except that it doesn't include curses, prefixes and postfixes.

Available:
  Since H-World 0.3.8

Call
  check_item_constraints(limb, thing)
Arguments
  limb: type thing_t, the limb to hold the item
  thing: type thing_t, the thing to check
  return: 1 if ok, 0 otherwise
 

Description:
  Checks if the given item can be held by the limb (e.g. check size, type ...)

Available:
  Since H-World 0.3.8

Call
  on_creation(thing, n)
Arguments
  thing:type thing_t, the thing that just was created
  n:type number, always 0 so far
Return value
  always 0 so far

Description:
  This is called after a thing is created by the thing factory This function is the place to do game-specific customizations of items and monsters

Available:
  Since H-World 0.3.8

Call
  on_kill(thing, n)
Arguments
  thing: type thing_t, the thing to be destroyed
  n: type number, 0 if thing dies silently
Return value
  always 0 so far

Description:
  This is called if a things is about to be destroyed/killed. It is called immediately before the data structures are cleaned up.

Available:
  Since H-World 0.3.8

AI scripts

Beings in H-World can be configured to call Lua scripts as part of their AI (see [module]/data/beings.sects). Each AI action is a pair of Lua functions, one to check if it is good to execute the actions now, and one that actually executed the action. The AI driver will first evaluate all checks and then execute the actions that has the highest check result. Actions that have a check result of -1 are not executed at all, even if there are no other actions available.

Find below the AI function pairt from H-World 0.3.9 that handles monster sleep and wakeup procedures:

example_sleep.html

H-World call reference

The H-World engine provides a number of procedure calls to Lua scripts. Find each call described briefly below.

Thing methods

Procedure Description

Call
  thing_get_value(thing, property)

Arguments
  thing the thing to inspect
  property the name of the property to retrieve

Return value
  the value of the property

Description:
  This procedure determines the value of the requested property.

Available:
  Since H-World 0.0.4

Call
  thing_set_value(thing, property, value)

Arguments
  thing the thing to change
  property the name of the property to set
  value the new value of the property

Return value
  nil

Description:
  This procedure changes the value of a property.

Available:
  Since H-World 0.0.4

Call
  thing_get_item(thing)

Arguments
  thing the thing to get the item from

Return value
  the item (my be nil if the thing held no item)

Description:
  Things in H_world can hold up to one item. Usually this is used to model 'holding' or 'wearing' and item with/on a limb. This method returns the item held by the thing, or nil if no item is held.

Available:
  Since H-World 0.0.6

Call
  thing_set_item(limb, thing)

Arguments
  limb the limb to put the item to
  thing the thing to get the item from

Return value
  Always 0

Description:
  Things in H-World can hold up to one item. Usually this is used to model 'holding' or 'wearing' and item with/on a limb. This method sets the item held by the thing.

Available:
  Since H-World 0.1.5

Call
  thing_set_item_known(user, thing)

Arguments
  user the being to remember the item
  thing the thing to remember

Return value
  none

Description:
  Makes the user remember the item permanently. e.g. identifiying a potion will make the PC remember it, and let him immediately recognize further found potions of the same type.

Available:
  Since H-World 0.3.5

Call
  thing_find_limb(thing, limb_type, limb_subtype)

Arguments
  thing the thing tree to scan
  limb_type the limb type to scan for
  value the limb subtype to scan for (use nil to match any subtype)

Return value
  The limb or nil if no matching limb was found

Description:
  This method scans the things limb tree (body structure) for a matching limb and returns it. If no matching limb is found, nil is returned.

Available:
  Since H-World 0.0.6

Call
  thing_find_limb(thing, item)

Arguments
  thing the thing tree to scan
  item the item to scan for

Return value
  The limb holding the item or nil if no matching limb was found

Description:
  This method scans the things limb tree (body structure) for a limb holding the given item and returns the limb. If no matching limb is found, nil is returned.

Available:
  Since H-World 0.1.5

Call
  thing_replace_item(thing, old, new)

Arguments
  thing the thing tree to scan
  old the item to replace
  new the item to put instead of old

Return value
  No return value

Description:
  This method scans the things limb tree (body structure) for a limb holding the given item and replces the old item by the new one.

Available:
  Since H-World 0.1.5

Call
  thing_add_item_to_inv(thing, item)

Arguments
  thing the container to put the item into
  item the item to put into the conatiner

Return value
  1 if successful, nil otherwise

Description:
  This method puts an item into a container.

Available:
  Since H-World 0.1.5

Call
  thing_create(name)

Arguments
  name the name of the thing to create. This is the name of the things section in the config file.

Return value
  the created thing if successful, nil otherwise

Description:
  This method creates a new thing defined by the name.

Available:
  Since H-World 0.1.5

Call
  x, y = thing_get_location(thing)

Arguments
  thing the thing to ask for its location,

Return values:
  x and y coordinates of the thing

Description:
  This method asks a thing for its location on the map. Things that are not contained in the map (e.g. things from inventories) return -1, -1. Take care this method returns two values!

Available:
  Since H-World 0.2.0

Call
  thing_set_location(thing, x, y)

Arguments
  thing the thing to set the new location,
  x x coordinate
  y y coordinate

Return values:
  none

Description:
  This method a new location for the thing. This does not mean to put it on that square, it just sets the location values. Use -1,-1 for things that are not on the map, e.g. stored in a backpack.

Available:
  Since H-World 0.3.6

Call
  thing_get_inventory(thing)

Arguments
  thing the thing to ask for its inventory

Return values:
  a handle to access the inventory

Description:
  This method asks a thing for its inventory. It returns a handle to the inventory, that can be used to access the inventory in further steps.

Available:
  Since H-World 0.3.4

Call
  target = thing_target(shootist)

Arguments
  shootist the one who does the targetting

Return values:
  the target, or nil if there was no target chosen

Description:
  This method lets the player select a target interactively.

Available:
  Since H-World 0.2.10

Call
  delay = thing_throw(user, ammo)

Arguments
  user the one who throws the item
  ammo the thrown item

Return values:
  the time delay caused by the action of throwing

Description:
  This method lets the player select a target and projects the ammo from the users position to the target. The ammo will be deposit on the targets square.

Available:
  Since H-World 0.2.10

Call
  thing_kill(thing)

Arguments
  thing the thing to kill

Return values:
  none

Description:
  This method kills the thing, removes it from the map and cleans up the data structures.

Available:
  Since H-World 0.2.10

Call
  thing_is_animated(thing)

Arguments
  thing the thing to check

Return values:
  0 if the thing is animated, nil otherwise

Description:
  This call checks if the thing is animated. More precisely, it checks if this thing has an AI with some actions. Usually this is the right way to tell animated from inanimate things.

Available:
  Since H-World 0.3.9

Call
  thing_memorize(thing, catg, message)

Arguments
  thing the thing that shall memorize the message
  catg the category of the message. H-World 0.3.9 knows about quest and event categories to show in the book of memeories. Other categories can be used, but will not show in the book.

Return values:
  none

Description:
  This method makes the thing remember the message of the given category.

Available:
  Since H-World 0.3.9

Call
  thing_recall(thing, catg, n)

Arguments
  thing the thing that shall recall a message.
  catg the category of the message.
  n the message number, starting at 0.

Return values:
  the message

Description:
  This method lets the thing recall a message of a given category. Incrementing n from zero allows to iterate all messages of a category. If there are no more messages, the function will return nil.

Available:
  Since H-World 0.3.9

Inventory access methods

Call
  inventory_add_thing(inv, thing)

Arguments
  inv the inventory to put add the thing to
  thing the thing to add to the inventory

Return values:
  nil on failure, non-nil on success

Description:
  This method adds thing to an inventory. (e.g. can be used to put a thing into a backpack).

Available:
  Since H-World 0.3.4

Call
  inventory_remove_thing(inv, thing)

Arguments
  inv the inventory to remove the thing from
  thing the thing to remove from the inventory

Return values:
  nil on failure, non-nil on success

Description:
  This method removes a thing from an inventory.

Available:
  Since H-World 0.3.4

RNG calls

Procedure Description

Call
  rng_get_int(n)

Arguments
  n random range width

Return value
  a random integer value in range 0..n-1

Description:
  This procedure calculates a semi-random integer number in a range of 0..n-1

Available:
  Since H-World 0.0.4

Call
  rng_roll(dice, sides)

Arguments
  dice the number of dice to roll
  sides the number of sides per dice

Return value
  a random integer value in range dice..dice*sides

Description:
  This procedure simulates rolling several dice and returns the sum of all rolls.

Available:
  Since H-World 0.0.6

Call
  rng_roll(dice)

Arguments
  dice A string like "%10d5+50". This example means to roll 10 dice with 5 sides each, and add 50 to the result. The total is returned as result of the call. Behaviour on passing malformed dice descriptions is undefined.

Return value
  The total value of dice rolls plus the fixed value.

Description:
  This procedure simulates rolling several dice and returns the sum of all rolls plus a fixed value.

Available:
  Since H-World 0.3.9

Visual representation methods

Procedure Description

Call
  thing_visual_add_image(thing, image, redraw)

Arguments
  thing the thing to modify
  image the number of the image to add to the visual
  redraw pass 1 to force a map redraw. Pass 0 otherwise.

Return value
  nil

Description:
  This method adds a image to the things visual. The visual can hold up to 255 layered images. The last added image is the top layer, the first image the lowest layer. Don't use to many layers, otherwise rendering will be very slow.

Available:
  Since H-World 0.0.6

Call
  thing_visual_remove_image(thing, image, redraw)

Arguments
  thing the thing to modify
  image
the image number to remove
  redraw pass 1 to force a map redraw. Pass 0 otherwise.

Return value
  nil

Description:
  This methods removes the image with the given image number from the things visual.

Available:
  Since H-World 0.0.6

Call
  thing_visual_set_image(thing, inv_or_map, index, image, colorset, xoff, yoff, transparent, redraw)

Arguments
  thing the thing to modify
  inv_or_map pass 0 to alter the map visual. Pass 1 to alter the inventory visual of the thing.
  index the mage index. Must be in range 0..255.
  image the image handle.
  colorset pass 0 for original colors. 1..n to recolor the image according to a colorset. n depends on the number of configured colorsets. See [module]/data/game.props for the colorset configuration.
  xoff, yoff the horizontal and vertical image offsets.
  transparent pass 1 to force a this image being drawn semitransparent. Pass 0 otherwise.
  redraw pass 1 to force a map redraw. Pass 0 otherwise.

Return value
  nil

Description:
  This method allows to set images with all possible attributes. If an image for the same index was set already, the former image is overwritten. If no image existed, a new image is added to the visual, at the highest possible index (which might be lower from the index value passed in).

Available:
  Since H-World 0.3.8

Call
  load_tile_from_image(filename)

Arguments
  filename
the image filename

Return value
  tile handle. Can be passed to thing_visual_add_image() and related functions.

Description:
  This method read a PNG image from disk and converts it into a tile that can be drawn by the H-World engine. The tile can e.g. be used for thing_visual_add_image() to display an overlay over the base thing image.

Available:
  Since H-World 0.3.3

Map access methods

Procedure Description

Call
  square_get_thing(x, y, n)

Arguments
  x x-coordinate of the square
  y y-coordinate of the square
  n number of the item

Return value
  the thing or nil if no such thing or map square exists

Description:
  This method retrives the n-th item from a given square. If the square doesn't exist (invalid coordinates) or the item doesn't exists (invalid n value) it returns nil. Items are tightly packed, this means if there are m items on a square this method will succeed for n in 0..m-1. Thus you can iterate over all items by starting with n=0 and incrementing n until the method returns nil.

Available:
  Since H-World 0.2.0

Call
  square_put_thing(x, y, thing)

Arguments
 
  x x-coordinate of the square
  y y-coordinate of the square
  thing the item to put on the given square

Return value
  no return value

Description:
  This method puts a thing on a given square.

Available:
  Since H-World 0.2.0

Call
  square_remove_thing(x, y, thing)

Arguments
 
  x x-coordinate of the square
  y y-coordinate of the square
  thing the item to remove from the given square

Return value
  no return value

Description:
  This method removes a thing from a given square.

Available:
  Since H-World 0.3.6

Call
  square_set_trigger(x, y, trigger)

Arguments
  x x-coordinate of the square
  y y-coordinate of the square
  trigger the trigger number. (An integer value).

Return value
  no return value

Description:
  This method adds a trigger to a given square. [module]/traps.lua will get the trigger parameter passed if a being enters the square. It can be a trap as well as any other kind of function that is activated upon this event.

Available:
  Since H-World 0.3.8

Call
  square_is_visible(x, y)

Arguments
  x x-coordinate of the square
  y y-coordinate of the square

Return value
  nil if not visible, 0 otherwise

Description:
  This call checks if the square can be seen by the player.

Available:
  Since H-World 0.3.9

User interaction

Procedure Description

Call
  x, y = user_ask_direction()

Arguments
  no arguments

Return values
  x and y offsets

Description:
  This method asks the user for a direction. There are 9 possible directions, including x=0 and y=0 for no direction. x and y are given as integer values in the range -1,0,1

Available:
  Since H-World 0.2.0

Call
  user_ask_key()

Arguments
  no arguments

Return values
  the ASCII value of the key

Description:
  This method waits until the user presses a key and return the ASCII value of the key pressed.

Available:
  Since H-World 0.3.4

Hansjörg Malthaner
Last modified: 22-Sep-04