SGE - The Lua Framework | Overview | Documentation | Download | Contact
Concept
At start-up, SGE calls sge.lua file. Game objects may be created through Lua-inteface. The game object is a rectangle with texture and some properties. Simple example script see on page bottom. Below the list of functions available in Lua scripts.


System functions

Name Description
sgeClose () Close application.
sgeGetDisplaySizeX () Return display width in pixel.
sgeGetDisplaySizeY () Return display height in pixel.
sgeTimerAdd (TimerID, Delay) Create timer. Timer will call OnTimer (TimerID) function each Delay ms.
sgeTimerDrop (TimerID) Remove timer.
sgeLog (Text) Write text string in log file.
sgeDoLuaString (Text) Execute Text string in Lua.
sgeTextureLoad (Path) Load texture in memory from bmp file placed on indicated Path. Return value is texture handle if the texture is loaded, otherwise is -1.
sgeTextureDrop (TextureID) Remove texture from memory. Return value is 1 if the texture is unloaded, otherwise is -1.
sgeSetBackground (Path) Set background image according to indicated Path. Be sure that size of bmp file exceed display size for both dimensions.



Render functions

Name Description
sgeSetLayer (LayerID) Set render layer. The LayerID must be integer. Only object with render layer equals to Layer or 0 (the magic value) will be present on screen.
sgeSetMaskColor (R, G, B) Set the transparent color of object textures. The color is defined in RGB format.
sgeFade (Time) This function instruct SGE that display must be became dark (if Time > 0) or clear up (if Time < 0). When operation is succeeded then OnFadeDone (Time) procedure will be call.
sgeFadeStop () Break fade process.
sgeXDraw (TextureID, Time, XDrawType, R, G, B) This function setup XDraw effect. The points of TextureID will be draw (R, G, B)-color according with their color and XDrawType (one of LESS_COLOR, EQUALS_COLOR or MORE_COLOR). After Time ms effect complited and OnXDrawDone (TextureID, Time, XDrawType) will be call.
sgeXDrawStop () Break XDraw process.


Sound functions

Name Description
sgeSoundInit (FreqMix, bps, IsStereo) Init sound system according with incoming parameters. Must be call before any another sound function be used. Return value is 1 if operation is succeeded, otherwise is -1.
sgeMusicLoad (Path) Load music track in memory from MOD file placed on indicated Path. Return value is a music handle if the track is loaded, otherwise is -1.
sgeMusicLoad (MusicID) Remove music track from memory. Return value is 1 if the track is unloaded, otherwise is -1.
sgeMusicPlay (MusicID) Play the music track. Return value is 1 if operation is succeeded, otherwise is -1.
sgeMusicStop () Stop the music track. Return value is 1 if operation is succeeded, otherwise is -1.
sgeMusicPause () Pause the music track. Return value is 1 if operation is succeeded, otherwise is -1.
sgeMusicResume() Resume the music track. Return value is 1 if operation is succeeded, otherwise is -1.
sgeMusicSetVolume () Set the volume of music track. The volume must be in range 1..100. Return value is 1 if operation is succeeded, otherwise is -1.
sgeEffectLoad (Path) Load effect in memory from WAV file placed on indicated Path. Return value is a effect handle if the file is loaded, otherwise is -1.
sgeEffectDrop (EffectID) Remove effect from memory. Return value is 1 if the track is unloaded, otherwise is -1.
sgeEffectPlay (EffectID) Play effect. Return value is 1 if the track is unloaded, otherwise is -1.


Events
This function will be call when some of event is coming.
Name Description
OnTimer (TimerID) The function is called when timer is over.
OnMouseDown (x, y) The function is called when user presses the touch screen.
OnMouseMove (x, y) The function is called when user moves the mouse.
OnMouseUp (x, y) The function is called when user releases the stylus from the touch screen.
OnKeyDown (KeyID) The function is called when user presses the hardware key.
OnKeyUp (KeyID) The function is called when user releases the hardware key.
OnFadeDone (Time) The function is called when fade effect is done.
OnXDrawDone (TextureID, Time, XDrawType) The function is called when XDraw effect is done.
OnGoalReached (ObjectID, x, y) The function is called when object with ObjectID reached his goal on screen.
OnCollision_ID1_ID2 (State) The function is called when two objects with ID1 and ID2 are collided. Both of objects must have PhysicType is not 0 and layer equals to current render layer. The state define the type of collision: 1 is a collision, 0 is a split of objects.


Objects
These functions manipulate game objects.
Name Description
sgeObjectAdd (ObjectID, LayerID) The function create game object. The ObjectID is not the unique value. The LayerID defined when object will be appear on screen. The objects with Layer = 0 always are present on screen (if they have texture, of course).
sgeObjectDrop (ObjectID) Droped one or more objects with id is equals to ObjectID.
sgeGetObjectByID (ObjectID) Return the object pointer by spesified ObjectID.
sgeGetObjectFromPoint (x, y) Return the pointer on first appropriate object. The object must have layer same as current render layer and UserType not equals to 0. If object not found, then NULL is return.

These functions are available only through object.
Name Description
:GetID () Return object id.
:SetLayer (LayerID) Set object render layer. The object will be visible on screen when it has layer same as current render layer and texture.
:GetLayer () Return object layer.
:SetSize (SizeX, SizeY) Set sizes in pixel of object. Both values must be positive.
:GetSizeX () Return object width in pixel.
:GetSizeY () Return object height in pixel.
:SetPosition (PosX, PosY) Set object position on screen. Both values must be positive. Remark: position (0, 0) is a top left corner of display.
:GetPositionX () Return object postion in pixel on horizontal.
:GetPositionY () Return object postion in pixel on vertical.
:SetSpeed(Speed, SpeedUp) Set speed and speedup of object. The object can accept :MoveTo command at least one of parameters is not null.
:GetSpeed () Return object speed.
:GetSpeedUp () Return object speedup.
MoveTo (ToX, ToY) () The function is called when object with ObjectID reached his goal on screen.
:GetGoalX () Return the horizontal component of destination point.
:GetGoalY () Return the vertical component of destination point.
:SetPhysicType (TypeID) Set physical type. The TypeID must be integer. The object maybe be generate OnCollision_ID1_ID2 call on collision with another objects if their physical types is not zero.
:GetPhysicType () Return physical type of object.
:SetUserType (TypeID) Set user type of object. The TypeID must be integer. If object type is zero then object cann't be returned from sgeGetObjectFromPoint (x, y) independently of render layer.
:GetUserType () Return user type of object.
:SetTexture (TextureID) Set object texture. Be sure that texture with TextureID was loaded early.
:SetTextureCoord (CoordX, CoordY) Define the texture shift for object. Both values must be positive. If at least one of CoordX + SizeX or CoordY + SizeY exceed texture horizontal and vertical sizes then object not appear on the screen.
:SetAnimation (FramesCount, FramePerSec, ScrollTextureXPerFrame, ScrollTextureYPerFrame)Set object animation. If animation frames situated horizontal on object texture than ScrollTextureXPerFrame must be equals to frame width and ScrollTextureYPerFrame mus be 0.

Constants
These constansts are available in Lua scripts.
Name Description
VERSION SGE version. Presently value is 0.9.
OS Type of operation system. Maybe Win32 or WinCE.
PATH SGE folder path.
LESS_COLOR This is a XDraw type.
EQUAL_COLOR This is a XDraw type.
MORE_COLOR This is a XDraw type.



Appendix 1 - The Lua
At start, strongly recommend to having familiarized with Lua documentaton on official site.
Below some remarks to this
-- Use double dots to concatenation strings
a = "abc"
b = "def"
c = a..b -- c is "abcdef"
-- Use "~=" to "not equals" compare. Not use "<>" or "!="
if (f ~= NULL) then ...
-- I have some trouble with running Lua script. Add --[[xxx]]-- at the end scripts if script is right but not work



Appendix 2 - Where is ini file support?
The ini files are not support in SGE directly. You can use standart lua function to work with text files, like e.g.
-- Save parameter
f = io.open (PATH.."sge.ini", "w")
if (f ~= NULL) then
      f:write ("UserName=\"Andrey\"") -- don't fogget about quotes for text variables
      f:write ("Health=100")
      f:close ()
else
      sgeLog ("Couldn't open "..PATH.."sge.ini")
end

-- Load parameter
f = io.open (PATH.."sge.ini", "r")
if (f ~= NULL) then
      f:close ()
      dofile (PATH.."sge.ini")
else
      UserName = "Andrey"
      Health = 100
end


Appendix 3 - Script example
-- It is a comment. IMPORTANT: the letter case is enable, so be sure when write names.
-- print "Hello world" into log file
sgeLog ("Hello world!")

-- Init sound system with 16000Hz, 8 bps and mono parameters
sgeSoundInit (16000, 8, 0)

-- Load music (MOD file) and effect (WAV file)
idMsc = sgeMusicLoad ("media/music.mod")
idEff = sgeEffectLoad ("media/effect.mod")

-- Play these sounds
sgeMusicPlay (idMsc)
sgeEffectPlay (idEff)

-- Set background picture
sgeSetBackground ("media/bg.bmp")

-- Load texture
idTex = sgeTextureLoad ("media/tex.bmp")

-- Create new game object and demand him to move
idObj = 1
objNew = sgeObjectAdd (idObj, 0) -- create object and get point on it
-- Draw attentition that access to object properties implemented through symbol ":"
objNew:SetSize (50, 50) -- set size 50 on 50 pixels
objNew:SetPosition (10, 10) -- set position in top left corner
objNew:SetTexture (idTex)
objNew:SetSpeed (100, 0)
objNew:MoveTo (200, 200) -- demand object to move in buttom right corner
-- function will be call when object reached buttom right corner
-- Into log will be written "Object with id = 1 reached the point (200, 200)"
fuction OnGoalReached (ObjectID, x, y)
      sgeLog ("Object with id = "..Object.." reached the point ("..x..", "..y..")")
end

Last update: September 2007