Difference between revisions of "SourceCode Overview"

Revision as of 12:51, 8 August 2007

Warning : preliminary documentation This part is about the C++ SourceCode and Lua Scripts for SFZ.

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.<br>
large parts of SFZ are coded in lua to ensure high flexibility, <br>
and customizability without recompiling, while keeping performance critical code in c++.

http://lugre.sf.net is a lib/framework we use across multiple projects, with Lua-bindings for Ogre3d and several other utils (networking,sound,...)

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

i'll leave out the lugre_ prefix of filenames 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				pressing v takes a screenshot...
 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

<ghoulsblade> many c++ files come in pairs, like   gfx3D.cpp and gfx3D_L.cpp   _L contains the lua bindings
<ghoulsblade> gfx3d and gfx2d are the main parts of the ogre lua binding
<ghoulsblade> they capsule scenenodes and graphical entities 
<ghoulsblade> i.e.  a scenenode with a mesh-entity in c++ ogre is capsuled in a gfx3d object in our code
<ghoulsblade> there is also a big dump for lots of global lua function bindings in   lugre/src/lugre_scripting*
<ghoulsblade> we use a custom smartpointer thing that is a bit different from the usual definition of smartpointer
<ghoulsblade> 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
<ghoulsblade> that is because most of the time objects and graphics are explicitly destroyed,  but other code elements might be still tracking them
<ghoulsblade> 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
<ghoulsblade> another point of interest is fifo.h  , a general purpose buffer writer/reader
<ghoulsblade> it has a lua binding and is used extensively for networking stuff
<ghoulsblade> lugre_robstring.cpp has a few string utils i collected over the years in many different projects
<ghoulsblade> 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
<ghoulsblade> 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
<ghoulsblade> shell.h has a few os-specific utils like listing files, getting timestamp, etc
<ghoulsblade> input.h is a wrapper for some input systems, currently used with OIS that comes with ogre
<ghoulsblade> also has keycode-name association 
<ghoulsblade> lugre_ogrewrapper.cpp is the ogre boilerplate and some utils (like screenshot, mousepicking) 
<ghoulsblade> that file kindof replaces the ogre example framework