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 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++
Available functions:
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 1 if the user has activated editor
- boolean = getKey(character)
return 1 if the corresponding keyboard key is pressed, 0 otherwise
- 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.
- 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 file.
- playSound(pointer_to_sound)
Play a previously loaded sound.
- 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
'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).
- createCube(integer x1,integer y1,integer z1,integer x2,integer y2,integer z2,integer type_of_cube)
Create a cube, 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
- createObject(number x,number y,number z, integer type)
- removeElement(number x,number y,number z)
Functions called by the engine. You MUST fill them:
- lua_onInitGame()
Called when game starts (before game load).
- lua_onUninitGame()
Called when game stops (after game save).
- 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, bool 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 world.dat file
- --world_lua <lua-file> : select custom world.lua file
- --world_xml <config-file> : select custom world.xml file
- --benchmark : show more debug and benchmark informations on the console