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
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++
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, 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.
Math and utilities
- number x,number y,number z=cartesianCoordFromSphericalCoord(number angle_x, number, angle_y, number radius)
in degree units
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 object interaction. These functions shall be called only in lua_manage_x and lua_draw_x
- setObjectLocalVariables(number, number, number, integer, string)
- number, number, number, integer, string = getObjectLocalVariables
- 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 = getPlayerPosition()
return player position (x,y,z) in world coordinates
- setPlayerPosition(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
- setCurrentPosition
(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)
- drawTextCenter(string)
print text on center of the window
2D sprites:
- pointer_to_2dsprite = load2DSprite(string filename)
load an image from a PNG or TGA file.
- 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)
- 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.
Core drawing functions. Typically you call them into lua_loop.
- clearBackground()
Clear screen.
- time1 = draw3DWorld()
draw all 3D elements, and call all the lua_draw_x functions of objects.
time1 is the duration of the call in microseconds
- time2 = draw2DWorld()
draw all 2D elements, except the ones you want to draw yourself
time2 is the duration of the call in microseconds
Cube and object creation and cube 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 is_finished if the cube creation ends. (x1,y1,z1) and (x2,y2,z2) then contain the cube positions (in cube counts).
- createCubeAggregate(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.
- boolean is_colliding = isCollidingPoint(number x, number y, number z)
check if the location (x,y,z) is stuck into a cube, return 1 if yes
- integer cube_type, number x_center,number y_center, number z_center, number width, number height, number depth = getCollidingCubeInfos(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.
- createObject(number x,number y,number z, integer type)
- boolean has_removed = removeObject(number x,number y,number z)
- boolean has_removed = removeCubeAggregate(number x,number y,number z)
- removeCubesSphericalHole(number x,number y,number z, number radius)
- removeCube(number x,number y,number z)
- getObjectTypeAt(number x,number y,number z)
Functions called by the engine. You MUST fill them:
- lua_onInitGame()
Called when game starts. Use it for example to load misc sprites and models.
- lua_onUninitGame()
Called when game stops. Use it for example to unload misc sprites and models.
- lua_load_x() where x is a number (starting at 0).
Called when the object with the type id x is loaded.
- lua_draw_x() where x is a number.
Called when the object with the type id x is drawed.
- lua_unload_x() where x is a number.
Called when the object with the type id x is freed. For optimisation reasons, this is done when objects of this type are out of view range.
- lua_loop()
Main function. Called regurarly.
- integer = lua_getNbObjects()
Must return the number of object types available. For example if you return 2 in this function, it means that you must write the functions
lua_load_0, lua_draw_0, lua_unload_0, lua_load_1, lua_draw_1, and lua_unload_1.
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)
Import 3D meshes
With 3DsMax
Export as OBJ
Then in the world.lua file:
--init variable model3D
model3D = 0
--load the model into memory
function lua_load_0()
model3D = load3DModel('my_object.obj')
end
--do object-related things
function lua_manage_0()
end
--draw the model
function lua_draw_0()
draw3DModel(model3D)
end
--free the model from memory
function lua_unload_0()
unload3DModel(model3D)
end
Then increment the return value of lua_getNbObjects() of one:
function lua_getNbObjects()
return 1
end
Then add the object into the game editor, pressing 'x' key.
Note: if you have several objects of the same type '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)
- --benchmark : show more debug and benchmark informations on the console