SourceCode Overview
Warning : preliminary documentation This part is about the C++ SourceCode and Lua Scripts for SFZ.
Contents
Overview
src/ : sfz c++ source files (.cpp) include/ : sfz c++ header files (.h) data/ : sfz data files data/lua/ : sfz lua scripts (.lua) lugre/src/ : lugre c++ source files (.cpp) lugre/include/ : lugre c++ header files (.h) lugre/lua/ : lugre lua scripts (.lua)
The c++ source code is in the src/ directory, the headers are in include/
The lua code is in the data/lua/ directory, one main.lua and several libs. Large parts of SFZ are coded in lua to ensure high flexibility and customizability without recompiling, while keeping performance critical code in C++.
Lugre is a lib/framework we use across multiple projects, with Lua-bindings for Ogre3d and several other utils (networking, sound, etc).
Data
the data/ dir contains all data, lua scripts are under data/lua/
main.material contains definitions of materials used by ogre OgreCore.zip standard materials and fonts lua/ contains lua scripts lua/main.lua central lua file lua/udata.lua helper used for lua binding (luabind.h)
C++
For most things there are:
include/thing.h as header src/thing.cpp for the actual code src/thing_L.cpp for luabindings/wrappers
SFZ
*main.cpp main function *object.h .cpp _L.cpp game object baseclass (for ships,asteroids,...) *location.h .cpp _L.cpp group/sub-scenegraph hierarchy *objectcontroller.h .cpp _L.cpp autopilot utils *physicform.h .cpp physics/collision info (so far empty) *resyncreceiver.h .cpp _L.cpp receiving of position resync messages via tcp/udp *sfz_scripting.h .cpp luabindings for global functions *GhoulPrimitives.h .cpp obsolete, geometry generation codesnippets *GhoulPrimitivesLoft.cpp obsolete, geometry generation codesnippets *GhoulPrimitivesOgre.cpp obsolete, geometry generation codesnippets *HUDElement2D.h .cpp _L.cpp obsolete, aiming codesnippets
Lugre
All the Lugre files have the "lugre_" prefix which has been removed for clarity.
*game.h .cpp mainclass, init, step, deinit *main.h .cpp boilerplate utils, parsing win32 commandline, opening win32 console window... *scripting.h .cpp lua framework *scripting.ogre.cpp luabindings for ogre utils *scripting.general.cpp luabindings for misc utils *luaxml.h .cpp luabinding for tinyxml parser *luabind.h template class for luabindings of classes *ogrewrapper.h .cpp central interface to ogre *robrenderable.h .cpp util for custom geometry renderables *meshshape.h .cpp used for mousepicking of meshes *widget.h .cpp _L.cpp gui system core *beam.h .cpp _L.cpp 3d-beam-like geometry generator *bitmask.h .cpp _L.cpp 2d image mousepicking mask utils *camera.h .cpp _L.cpp luabinding for ogre cam *viewport.h .cpp _L.cpp luabinding for ogre viewport *material.h .cpp _L.cpp luabinding for ogre material *rendertexture.h .cpp _L.cpp luabinding for ogre render-to-texture holder *gfx2D.h .cpp _L.cpp luabinding for 2D graphics *gfx3D.h .cpp _L.cpp luabinding for 3D graphics *SortedOverlayContainer.h gui-element class (z-ordering) *BorderColourClipPaneOverlay.h gui-element class (border rect) *ColourClipPaneOverlay.h gui-element class (rect) *ColourClipTextOverlay.h gui-element class (text) *RobRenderableOverlay.h gui-element class (custom 2D geometry) *sound.h .cpp _L.cpp sound and musik wrapper *sound_fmod.cpp sound implementation using fmod *sound_openal.cpp sound implementation using openal *net.h .cpp _L.cpp networking *fifo.h _L.cpp general purpose first in first out buffer, used by net *prefix.h should be included first in every source file, for os specific macros *shell.h .cpp os specific utils : directory listing, timer, ... *input.h .cpp keyboard, mouse, see also ogrewrapper.cpp for OIS access *listener.h .cpp baseclass for listener pattern *smartptr.h baseclass for smartptr design pattern *timer.h .cpp timed callbacks, stepper, fps-calc, etc *profile.h .cpp runtime callstack and calltime measurement *tiny?.h ?.cpp tiny xml parser *robstring1.2.h .cpp string utils *random.h .cpp _L.cpp custom random utils used for procedural stuff
Lua
SFZ
main.lua main file lib.mainmenu.lua the menu before the game starts lib.client.lua client lib.client.message.lua client netmessage handling lib.server.lua server lib.server.message.lua server netmessage handling lib.netmessagelist.lua network protocol lib.object.lua gameobject main file lib.object.movement.lua orientation,movement lib.object.pos.lua distance calc, global2local lib.object.search.lua nearest, raypick lib.object.hp.lua damage lib.object.shield.lua shields lib.object.weapon.lua firepower, cooldown lib.object.destroy.lua cleanup,register listeners lib.object.container.lua cargo,weaponslots lib.object.furniture.lua tables,computers,grates,ladders... lib.object.hangar.lua launch and dock fighters, exit in spacesuit lib.mission.lua mission system lib.service.lua service system for stations/planets, e.g. repair lib.target.lua targeting system (next,prev,nearest...) lib.trade.lua trading system buy/sell stuff lib.autopilot.lua autopilot system lib.plugin.lua plugin system lib.system.lua solar systems lib.location.lua group/sub-scenegraph hierarchy system lib.effect.lua effect system, lasers,explosions... lib.music.lua music system, tracklist, shuffles lib.shipedit.lua ship editor lib.shipeditmodule.lua modules/shipparts in editor lib.shipeditguess.lua educated guessing of good ship positions lib.shipeditloadsave.lua load and save ship-designs to disk lib.preview.lua mesh to image via render-to-texture lib.interior.walk.lua walking around lib.shipvoxelgrid.lua collision, interior lib.shipgfx.lua optimising ship meshes, removing inner walls lib.loft.lua geometry generation testarea.lua experiments lib.keybinds.lua maps keys to actions, edit this to change your controls lib.keys.lua networking enums for abstract key names lib.buymenu.lua obsolete lib.map.lua obsolete lib.hud.lua obsolete
Lugre
lib.input.lua keyboard/mouse events lib.gui.lua gui : event distribution lib.guimaker.lua gui : creation utils lowlevel lib.plaingui.lua gui : creation utils highlevel lib.guiutils.lua gui : logo,bottomline,fps-display lib.edittext.lua gui : text-input fields lib.tooltip.lua gui : tooltips lib.movedialog.lua gui : dialog movement utils lib.chatline.lua gui : text-input line at the bottom of the screen, chat history lib.fadelines.lua gui : console-lines at the bottom slowly fading out lib.contextmenu.lua gui : right-click menu lib.cursor.lua gui : mouse-icon lib.listener.lua listener system lib.material.lua material utils lib.cam.lua camera handling, 3rd person utils lib.netmessage.lua network protocol framework lib.plugin.lua plugin system lib.sound.lua sound system lib.time.lua timeout,stepper,fpscalc lib.types.lua type system (flyweight design-pattern) lib.beam.lua geometry generation lib.box.lua geometry generation lib.primitive.lua geometry generation lib.prism.lua geometry generation lib.voxel.lua mesh 2 voxel utils lib.util.lua misc utils, vector, quaternion lugre.lua main include file udata.lua luabinding helper, loaded from c++ code early
notes
many c++ files come in pairs, like gfx3D.cpp and gfx3D_L.cpp _L contains the lua bindings
gfx3d and gfx2d are the main parts of the ogre lua binding
they capsule scenenodes and graphical entities
i.e. a scenenode with a mesh-entity in c++ ogre is capsuled in a gfx3d object in our code
there is also a big dump for lots of global lua function bindings in lugre/src/lugre_scripting*
we use a custom smartpointer thing that is a bit different from the usual definition of smartpointer
instead of releasing memory when all references are deleted, our smartpointers act as listeners to the death-event of the target, and set themselves to null if the target is destroyed
that is because most of the time objects and graphics are explicitly destroyed, but other code elements might be still tracking them
this way the others don't have to be manually notified that the target is gone, they can just check if the smartpointer is null
another point of interest is fifo.h , a general purpose buffer writer/reader
it has a lua binding and is used extensively for networking stuff
lugre_robstring.cpp has a few string utils i collected over the years in many different projects
it has a nice printf syntax that outputs an std::string that often comes in handy as i don't like the << syntax that much
also has explode and a few other utils, some of the code is also inlined in robstring.h but i think it isn't used too much in sfz as most string stuff is done in lua
shell.h has a few os-specific utils like listing files, getting timestamp, etc
input.h is a wrapper for some input systems, currently used with OIS that comes with ogre
also has keycode-name association
lugre_ogrewrapper.cpp is the ogre boilerplate and some utils (like screenshot, mousepicking)
that file kindof replaces the ogre example framework
what does the PROFILE do?
It was originally planned for measuring (profiling) code execution time and callcount, we mainly use it to provides stacktrace info in release builds. It should be written a the start of nearly all somewhat bigger functions that aren't called too often (to prevent performance hit). Tt's a trick using an empty object just to install a callback at function start and when the function returns (empty object is destroyed automatically when the stack is cleaned up). The code for it is in lugre/include/lugre_profile.h and lugre/src/lugre_profile.cpp . It enables some nice things, like including a stacktrace in warning and debug messages without interrupting the program
