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.
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 the operations 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)
load player position and 'global' variables (see below) from a file. Typically you call getGlobalVar right after this call to retrieve informations.
- saveGame(string)
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.
- setWaterEnable(boolean)
Parameter must be 0 or 1. Disable or enable water. Default value is enabled.
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
- setObjectLocalVariable1(number)
- setObjectLocalVariable2(number)
- number = getObjectLocalVariable1()
- number = getObjectLocalVariable2()
- 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 frame of the animation 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 background, configure the fog.
- 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 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 other 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
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.
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.