Hexahedra‎ > ‎

Lua API

This page is just for me to jot down some ideas. It is very likely everything will change drastically in the near future.

Classes

player

Provide info such as name, position, head angle, inventory,... Functions for moving, sending messages to the console, etc.
Some kind of associative array would also be neat, so plugins can store extra bits of info. (For example, a health system can be implemented using player stats (see below), but to move the player back to a spawn point, you'll need to store this location somewhere.)

position

A simple (x, y, z) position. Tweak the metatables so an offset can be applied using the + operator.

function position:surrounding ( )

Returns an array with the six neighboring positions.

item

Something that can be stored in a player's inventory...

Materials

function define_material (int type_id, table properties)

The type ID is any number between 1 and 65535. Zero is reserved for empty blocks.
The properties table can be used to define (or change) the following aspects of this material:

 Property   Type
Description
 namestring
A short description.
 texturesarrayAn array of indices to the texture atlas, defining which textures to use for each face of a cube made of this material. This array consists of 1, 2, 3, or 6 elements.
 shapestring
Used for blocks that aren't actually cubes. The string refers to a 16 x 256 black & white PNG file. The image should be interpreted as 16 slices of 16 x 16 voxels, like an MRI scan. White pixels are air, black pixels are solid. Used for making ladders, buttons, fences, etc.
 opacity  float
0 being completely transparent, and 1 being opaque.
 can_placefunction
A function to determine whether a given player can place a block of this material at a given position.
 can_destroyfunction
Similar to can_place for the destruction of blocks.
 on_placefunction
Called when a player places a block of this material.
 on_damagefunction
Player started damaging the block.
 on_destroyfunction
Player destroys a block.
 on_touchfunction
Player touches a block.
 on_walkfunction
Player walks on a block.
 on_activatefunction
Player activated the block.
 random_checkfunction
Will be called at random intervals.


Items

function define_item (int type_id, table properties)

...


Events and hooks

function add_hook (string hook_name, function callback)

Add a hook. The following hooks exist:

 NameParameters
Description
 tick
 Gets called every second.
 player_chat player who, string text
 The player just typed something in his console.
 player_cmd player who, string cmd, string param
 The player issued a command (something in the console starting with '/').
 player_login player who
 A player has logged in to the game.
 scripts_loaded
  All scripts have been loaded. Useful for plugins that depend on other plugins.



function on_approach (position where, int distance, int hysteresis, function callback)

The callback is invoked when a player or mob gets within distance blocks of a given position. This event will not trigger again until the player moves away further than a distance of hysteresis blocks.


Player stats and user interface

function register_player_stat (string name, string suggested_widget, int initial_value, int initial_max)

Register a player stat, such as health, mana, hunger, or charisma. The name is used by other functions to refer to this stat, but it is also sent to the client so it can be displayed to the user. The suggested widget is a hint to the clients how to render this stat. How it will look depends on the theme/skin the player is using.

 Suggested_widgetMight be shown as...
 healthZelda-style hearts container.
 barA colored horizontal bar graph, with the current and max value shown inside the bar.
 moneyA simple number with a dollar sign, or perhaps as separate copper, silver and gold values (radix 100 display).
 scalarA simple numeric value, possibly with a slash and the max value next to it.
 scoreA number, shown in a larger font.
 


function player:set_stat (string name, int value)   { / get_stat }

Update a stat that was registered with register_player_stat earlier. The client should update the corresponding widget on the screen accordingly.


function player:set_stat_max (string name, int max)   { / get_stat_max }

Set a different maximum value for the stat. If the new max is lower than the current value, the current value is changed to max.


function add_stat_hook (string name, function callback)

Register a callback to respond to stat changes. The signature is (player who, string name, int value, int old_value).


The game world

function get_block (position where)



function get_surrounding_blocks (position where)



function get_light_levels (position where)



function set_block (position where, block new_type)



function set_block_data (position where, string data)



Other

function log (string message)

Add a message to a log file.


function register_plugin (string name, table properties)

Provide the server (and whoever happens to look at your script) with a description of this plugin. It is not mandatory.

 NameDescription
 authorWho wrote this, perhaps with email or other contact info.
 versionVersion number.
 urlWebsite associated with the plugin, for documentation etc.


function server_name ()

Returns the name of this server.


function server_version ()

Returns the version of the server software.




Comments