Engine and modding documentation
Back to readme
Level editor
To use the level editor: press A in-game and then click on the right-top menu. Use directional keys and page up / page down to move cursor. Save with 'S', and backup you .dat files regularly.
Note: the generation procedures (in "Generate landscapes" menu) use the current cube type to create earth and the next cube type to create ground. For example, if the current cube type is 2, it uses 2 for earth and 3 for ground. Do not generate landscapes if the last cube type is selected!
Script basics
The script is using the lua programming language. To modify the script, open the file world.lua with a text editor like notepad or Notepad++.
To setup the game, you must create a lua table named "Game" with the following methods:
- init()
Called when game starts. Use it for example to load misc sprites and models.
- uninit()
Called when game stops. Use it for example to unload misc sprites and models.
- manage()
Called regularly. Use it for example to manage game elements.
- draw3D()
Called regularly. Use it for example to draw misc 3d models.
- draw2D()
Called regularly. Use it for example to draw misc 2d sprites.
To create an active object, you must create a table with the following methods, and then add the name of this table in the initActiveObjects(...) call:
- load()
Called when an object of this type is going in view range.
- init()
Called when the current object is created.
- manage()
Called when the current object has to be managed.
- draw()
Called when the current object has to be drawed.
- uninit()
Called when the current object is destroyed.
- unload()
Called when the objects of this type are going out of view range.
Script API
All Lua standard libraries are available. The new additional available functions are as follow:
Misc:
- print(string)
print something in the console
- assert(number)
test a condition. If the condition is false (i.e. 0), abort game and show an error.
- boolean = isEditorMode()
return true if the editor mode is enabled
- setEditorMode(boolean)
enable or disable editor mode
- boolean = getKey(character)
return true if the corresponding keyboard key is pressed, false otherwise
You may also use "ASCII:number" to use any ascii character, like getKey("ASCII:27") for escape key. See wikipedia for more information about ASCII.
Furthermore, values between 256 and 267 included are F1 to F12 keys.
- boolean = getKeyNoRepeat(character)
same than above, but do it once until the key is released
- boolean is_left_click, boolean is_middle_click, boolean is_right_click, boolean is_wheel_up, boolean is_wheel_down, integer pos_x, integer pos_y = getMouseInfos()
return mouse informations
- integer = getTime()
return current time in miliseconds since game starts or computer starts
- (integer, integer) = getWindowSize()
return window size (width,height) in pixels
- integer = getPeriodDuration()
Return the duration in microseconds of the last display frame.
You should use this value for any operation which depends of time, to keep the same behaviour on every computer (i.e. whatever the framerate).
Example: position_x_player = position_x_player + getPeriodDuration() / 30000.0
- gameOver()
Stop the game and display 'Game over' on the screen.
- loadGame([string optional_filename])
load player position and 'global' variables (see below) from a file. Typically you call getGlobalVar right after this call to retrieve informations.
- saveGame([string optional_filename])
save player position and 'global' variables (see below) into a file. Typically you call setGlobalVar right before this call to save informations.
- quitGame()
Quit the game.
- saveWorld([string optional_filename])
Save the world data, default file is the loaded world data. Do not confuse with saveGame.
- setColor(number r,number g,number b,number a)
Change current color and transparency level for 2D text and sprites. These red, green, blue, and alpha (transparency) parameters must be between 0 and 255. Alpha value for opaque is 255. Current color is reset to white when drawing 3D.
- setFogColor(number r,number g,number b)
Change background fog color. Parameters must be between 0 and 255.
- initActiveObjects(string object1, string object2, ...)
Init all active objects. First parameter will be the object with id 0, second parameter will the one with id 1, etc. Please call this function once at init.
Math and utilities
- number x,number y,number z=cartesianCoordFromSphericalCoord(number angle_x, number, angle_y, number radius)
in degree units
- x,y = get2DPosFrom3D(number pos_x, number pos_y, number pos_z)
Sound
- pointer_to_sound = loadSound(string)
Load sound from a WAV or OGG vorbis file.
- playSound(pointer_to_sound)
Play a previously loaded sound.
- setSoundVolume(pointer_to_sound, number sound_volume)
Set sound volume, sound_volume should be between 0 and 1.
- isPlayingSound(pointer_to_sound)
Return 1 if the sound is playing, 0 otherwise.
Current active object interaction. These functions shall be called only in the methods init(), uninit(), manage() and draw() of an object.
- setObjectLocalVariable(string variable_name, number variable_value)
- number variable_value = getObjectLocalVariable(string variable_name)
- setObjectLocalVariablePos(integer index, number x, number y, number z)
- number x, number y, number z = getObjectLocalVariablePos(integer index)
- setObjectLocalVariableString(string variable_name, string variable_value)
- string variable_value = getObjectLocalVariableString(string variable_name)
- autoDestroyCurrentObject()
- number, number, number = getCurrentObjectPosition()
return current object position (x,y,z) in world coordinates
- setCurrentObjectPosition(number, number, number)
set current object position (x,y,z) in world coordinates
- number = getDistanceToPlayer()
return distance of the current object to the player
Player and camera interaction
- number, number, number = getPlayerPositionReal()
return player position (x,y,z) in world coordinates
- setPlayerPositionReal(number, number, number)
set new player position (x,y,z) in world coordinates
- number, number, number = getPlayerSpeed()
return player speed (x,y,z)
- setPlayerSpeed(number, number, number)
set new player speed (x,y,z)
- setPlayerMovementWalk()
- setPlayerMovementCar()
- setPlayerMovementFly()
- setPlayerMovementNone()
- integer = getPlayerMovementType()
return 0 if walk, 1 if car, 2 if fly, 3 if none
- setCameraAngleAndDistance(angle_x, angle_y, camera_distance_to_player)
in degree units
- angle_x, angle_y, camera_distance_to_player = getCameraAngleAndDistance()
in degree units, between -180 and 180
- setCurrentPosition(integer x, integer y, integer z)
- setCurrentPositionReal(number x, number y, number z)
- rotatePosition(number angle_x, number angle_y, number angle_z)
'Global' variables:
These variables are managed by the engine, and are accessed in the script through the functions setGlobalVar, getGlobalVar, and addToGlobalVar.
These variables are saved when the game is saved.
- setGlobalVar(string str, integer i)
Set the value i to the global variable str.
- integer = getGlobalVar(string str)
Get the value of the global variable str. Return 0 if the variable is not defined.
- integer = addToGlobalVar(string str, integer i)
Increment global variable str of i. Return the new value of the variable.
Text:
- drawText(string, integer x_pixel_position, integer y_pixel_position)
print text on the window at the position (x_pixel_position, y_pixel_position)
- drawText(string)
print text on the center of the screen
- scheduleDrawTextCenter(string text, integer nb_of_miliseconds)
2D sprites:
- pointer_to_2dsprite = load2DSprite(string filename)
load an image from a PNG or TGA file.
- draw2DSprite(pointer_to_2dsprite)
Draw the 2D sprite on the center of the screen
- draw2DSprite(pointer_to_2dsprite, integer x_pixel_position, integer y_pixel_position)
draw the 2D sprite on the window at the position (x_pixel_position, y_pixel_position)
- draw2DSprite(pointer_to_2dsprite, integer x_pixel_position, integer y_pixel_position, number angle)
draw the 2D sprite on the window at the position (x_pixel_position, y_pixel_position) with angle in degree
- draw2DSprite(pointer_to_2dsprite, integer x_pixel_position, integer y_pixel_position, number angle, integer hot_spot_x, integer hot_spot_y)
draw the 2D sprite on the window at the position (x_pixel_position, y_pixel_position) with angle in degree. Use (hot_spot_x,hot_spot_y) as hot spot point relative i.e. center of rotation, relative to (x_pixel_position,y_pixel_position)
- scheduleDraw2DSprite(string filename, integer x_pixel_position, integer y_pixel_position, integer nb_of_miliseconds)
draw the 2D sprite on the window at the position (x_pixel_position, y_pixel_position) during nb_of_miliseconds. Automatically load and unload sprite.
- scheduleDraw2DSprite(string filename, integer nb_of_miliseconds)
Draw on the center of the screen
- drawSpriteFullscreen(pointer_to_2dsprite)
Draw the 2d sprite at the center of the screen, add black all around. Do not draw anything 3D and freeze player commands while drawSpriteFullscreen is called. This way, you can add an interlude or an introduction story in the game.
- drawSpriteFullscreenStretched(pointer_to_2dsprite)
Same as drawSpriteFullscreen, but scale the sprite to fit the entire screen. If the sprite has not the same ratio than the screen, it adds black borders.
- unload2DSprite(pointer_to_2dsprite)
free 2d sprite from memory. You MUST do it before quitting game.
3D models:
- pointer_to_3dmodel = load3DModel(string filename)
load a 3D model from an OBJ file. The MTL file and the textures images (PNG, TGA) must be available in the same directory.
- pointer_to_3dmodel = load3DModelAnimated(integer frame_duration, string filename1 [, string filename2 [, ...]])
create an animated 3D model from several OBJ model files. Each model is a frame of the animation and takes frame_duration miliseconds time.
- draw3DModel(pointer_to_3dmodel)
draw the 3D Model on the current 3D position.
- unload3DModel(pointer_to_3dmodel)
free 3d model from memory. You MUST do it before quitting game.
- setModelAnimationSpeed(number )
set 3d model animation speed.
- stopModelAnimation()
stop model animation.
- startModelAnimation()
restart model animation.
Cube creation and collision functions
- startCubeCreation(number x,number y,number z)
Start a cube creation at position (x,y,z).
- integer is_finished, integer x1, integer y1, integer z1, integer x2, integer y2, integer z2 = manageCubeCreation()
Return true for is_finished if the cube creation ends. (x1,y1,z1) and (x2,y2,z2) then contain the cube positions (in cube counts).
- createCubeParallelepiped(integer x1,integer y1,integer z1,integer x2,integer y2,integer z2,integer type_of_cube)
Create several cubes, using the cube positions (in cube counts). This function may be used independantly of the two previous functions.
- removeCubeParallelepiped(integer x1,integer y1,integer z1,integer x2,integer y2,integer z2)
Remove several cubes, using the cube positions (in cube counts).
- removeCubesSphere(integer x,integer y,integer z, number radius)
Create a spherical hole at position (x,y,z)
- createCube(integer x,integer y,integer z,integer type_of_cube)
- removeCube(integer x,integer y,integer z)
- integer cube_type = getCubeTypeAt(integer x,integer y,integer z)
Return the cube type at location in cube counts (x,y,z). Return -1 if no cube of no collision there.
- integer cube_type, number x_center,number y_center, number z_center, number width, number height, number depth = getCollidingCubeInfosPosReal(number x, number y, number z)
Get informations about the cube on location (x,y,z). cube_type is set to -1 if there is no cube or it's not a colliding cube.
Object creation functions
- createObject(number x,number y,number z, string type, boolean is_global)
Create a new object at position (x,y,z) of type type. If is_global is true, the object "manage" method of this object will be called even when the object is too far to be visible.
- boolean has_removed = removeObject(number x,number y,number z)
Remove the first object at accurate position (x,y,z), if any.
- string object_type = getObjectTypeAt(number x,number y,number z)
Remove the first object type id at accurate position (x,y,z), if any, or an empty string, if nothing found
Interactions with the game configuration. These functions allows you to change the values loaded from world.xml during the game execution.
Notes:
- These functions does not modify the config.xml file itself.
- Some of the config.xml values may not be updated during the game execution and therefore calling the functions on these values will have no effect.
- changeConfigValueInt(string variable_name, int value)
- changeConfigValueBool(string variable_name, boolean value)
- changeConfigValueDouble(string variable_name, number value)
- changeConfigValueString(string variable_name, string value)
Pathfinding
- clearGraph()
- addSegmentInGraph(number pt1_x,number pt1_y,number pt1_z, number pt2_x,number pt2_y,number pt2_z)
- removeSegmentFromGraph(number pt1_x,number pt1_y,number pt1_z, number pt2_x,number pt2_y,number pt2_z)
- integer nb_nodes = findPathInGraph(number start_x,number start_y,number start_z, number end_x,number end_y,number end_z)
Find a way from start to end, if any (this may not be the shortest way). Return the number of nodes used to reach end, or -1 if not found.
Import 3D meshes
With 3DsMax
Export as OBJ
Then in the world.lua file:
MyObject = {
model3D = 0,
--load the model into memory
load = function()
model3D = load3DModel('models/obj_my_object/my_object.obj')
end,
--do object-related things
manage = function()
end,
--draw the model
draw = function()
draw3DModel(model3D)
end,
--free the model from memory
unload = function()
unload3DModel(model3D)
end
}
Then add in initActiveObjects() call in Game->init function :
initActiveObjects("MyObject")
Then add the object into the game editor, pressing 'x' key.
Note: if you have several objects of the same type, for example '0' in the game, the function lua_load_0 is called once,
when any of these objects is being visible, i.e. not hidden by the fog. The function lua_unload_0 is called when no more object is visible.
Config file
Some elements of the game are configured in world.xml.
Program command line arguments
Application.exe takes the following parameters:
- --fullscreen : enable fullscreen mode at game start
- --world_dat <data-file> : select custom game world file (default is world.dat)
- --world_lua <lua-file> : select custom game script file (default is world.lua)
- --world_xml <config-file> : select custom game configuration file (default is world.xml)
On Windows, edit the .bat files to change it.
Note: to print benchmark in the console: press '*' in game