
*** boxEngine Documentation v101
*** Michael Figarelli
*** m2cengine@gmail.com

*** unofficial forum: reddit.com/r/boxengine


boxEngine is a simple openGL graphics engine (built on SDL) exposed to Lua.  This doc serves as a 'quickstart' for anyone interested in scriping their own boxEngine code.

====== Running Scripts

it is recommended you start the Command Prompt shortcut provided, and manually run boxEngine.exe.  Providing no arguments will run the lua script 'default.lua', located in 'data\scripts\' .  To run another script, add the parameters '-s scriptfile.lua'.  The provided scripts can be ran with:

boxEngine						//runs the standard default script, which uses all the available 
								  exposed engine functions.  left-click changes cam mode.
boxEngine -s blast.lua			//runs the included example game, Super Mega Ultimate Blasty Sharp Pointy Destiny of Blades, Guns, Boobs and Other Stuff 4 2000 Series - Game of the Month / No Sound Edition ( for windows )... (SMUBlaSPoDoBlaGuBaOS)
boxEngine -s helloWorld.lua		//runs helloWorld.lua, a good starting point for your custom scripts
boxEngine -s objView.lua		//runs objView.lua, the object model viewer.  scrolling up/down 
								  changes the object index number, pressing 1 or 2 changes the geom library

Other parameters available are '-r screenwidth screenheight' to set the resolution and '-f' to set fullscreen.



====== Script Functions

Within each lua script ran through boxEngine, the following functions should be defined in lua:

function Init( )
* called once when the engine is initialized.

function KeyHappen( inVal, inDown, inT )
* called whenever a key is pressed or depressed :( - also called on mouseclicks / mousescrolls.  Note that mouse scrolling sends a down/up instantly.

function Draw( t, dt )
* called every frame - this is where all your drawing should take place.  t is the value of the current time in seconds, and dt is the delta time - the time in seconds since the previous frame.

It is assumed that any startup code you need will (for the moment) be global.



====== Engine Functions

The following functions are exposed to Lua:

Push()
* pushes the current scene matrix.

Pop()
* pops the current scene matrix.

Move( x )
Move( x, y )
Move( x, y, z )
* moves / translates the current scene matrix.

Scale( v )
* scales the current x, y, and z matrix vals by v.

Scale( x, y, z )
* scales the current scene matrix.

Rotate( x, y, z, angle )
* rotates the current scene matrix (angle) amount around the normal defined by x, y, z.

LookAt( camX, camY, camZ, targetX, targetY, targetZ )
* sets the 3d camera looking at the target

SetCam( dimension [, mode ] )
* dimension must be 2 or 3 - a value of 2 will set the window to 2d mode, 3 will set to 3d mode.
* if dimension = 3, mode [ optionally ] sets the field of view angle.
* if dimension = 2, mode defaults to 0 if not specified, can be 0, 1, or 2.
* mode = 0 will stretch 2d cords from -1 -> 1 on both axis
* mode = 1 will stretch 2d cords from -1 -> 1 on the largest axi [ the other will be cropped <= 1 ]
* mode = 2 will stretch 2d cords from -1 -> 1 on the y axi.

GetMouseScalar()
* returns mouseX, mouseY mouse values, with the origin corresponding to the center of the window - corresponds to current SetCam mode - useful for gui or 2d pointer games.  Will not run off edge of screen.

GetMouseTotal()
* returns totalX, totalY mouse values - these are useful for calculating view angle in 3d mode.

===== MEDIA (textures, shaders, geometry)

AddGeom( file [, group ] )
* adds geometry objects from file (type: bxo) into specified group.  If no group is specified, goes into default group of "".

AddTex( file [, group ] )
* adds texture image from file (type: bmp, jpg, png) into specified group [ default group "" ].

AddShad( file [, group ] )
* adds shader [type: shad] into group...


== NOTE: calling specific instances of each type of media works the same, with the exception that calling tex(-1) and shad(-1) unbinds any bound texture or shader.
== This explanation covers geometry, but note that Geom(...) can be substituted with Shad(...) or Tex(...) and behave similarly.

Geom( globalindex )
Geom( groupname, index )
Geom( groupname, name )
Geom( name )
Not supported:  Geom( groupindex, ... )

* Geometry is handled in a 'Geometry Manager'.  To use geometry, first call 'AddGeom(...)' to add geometry, possibly with a specified group.  Usually, geometry files 
include multiple objects - all will be loaded into the specified group.  Internally, geometry is not -really- loaded until you first draw it ( note that geometry actually creates/checks 
for a hash-matched geometry index file, bxi, which has metadata on geometry to load.  tex/shads don't use metadata ).

* The fastest way to reference geometry is by the globalindex (but don't rely on an object having the same index between runs, we will add a GetIndex(..) function).  Internally, 
all media objects are stored in a global resizable array, and the groups reference indeces of this array.

* Note that calling Geom( name ) is equivalent to calling Geom( "", name ), so don't expect a specified group-loaded object to be globally referenced through Geom( name ).

== Geom-specific functions

NewGeom( name )
NewGeom( group, name )
* creates empty geom obj, returns glob index:

4param:
Place( srcGroup, srcName/index, dstGroup, dstName/index )

3param:
Place( srcGroup, srcName/index, dstGlobIndex )

2param:
Place( srcName, dstName ) //operates in "" group
Place( srcGlobIndex, dstGlobIndex )

* Places one piece of geometry into another, with the current geometry matrix ( explained below ) and geom texture matrices applied.

== Geom-Matrices

GPush()
GPop()
GRotate( x,y,z,angle )
GScale( x,y,z )
GMove( x,y,z )
GReset()

== Misc

DrawLine( x1, y1, z1, x2, y2, z2 )
* Draws a line. duh.

== Lighting

SetLighting( onoff )
* turns on or off lighting.  does not work when a shader is active, and setting lighting on will override the current Color() setting.

SetLight( index, x, y, z )
* sets index 0 or 1 light to position ( x, y, z ) - calling this will turn on lighting, and enable this specific light.  only 2 lights are currently available.

SetLightColor( lightNum, r, g, b )
* Sets a light's color. duh.

SetLightAtten( lightNum, constant, linear, exponential )
* Sets a light's atten values. duh.

SetAmbientColor( r, g, b )
* Sets the ambient color when lighting is enabled. duh.

Color( r, g, b, a )
* sets the current color state.  will have no effect on lighted or shaded geometry.

Color( val )
* equivalent to Color( lum, lum, lum, 1 )

BackColor( r, g, b, a )
* sets color the screen is cleared with every frame

Cull( cullOnOff )
* turns on/off backface culling

SetDepth( depthRead, depthWrite )
* sets the state of the depth buffer.

Blend( mode )
mode:
-1 turns off openGL blending
0 sets standard alpha blending
1 sets additive alpha blending 
if you are using transparency or transparent textures, turn this on ( performance is better with it off ).  Has no effect when lighting is enabled.

Blend( src, dst )
src ranges from 0-8, and sets src blend operation:
GL_ZERO, GL_ONE, GL_DST_COLOR, GL_ONE_MINUS_DST_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, GL_ONE_MINUS_DST_ALPHA, GL_SRC_ALPHA_SATURATE

dst ranges from 0-7 and sets dst blend operation:
GL_ZERO, GL_ONE, GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, GL_ONE_MINUS_DST_ALPHA

Logic( val )
-1 disables logic ( default setting )
0-15 sets the current blend logic mode.  Note that setting this will override Blend() settings.
val sets logic op to:
GL_CLEAR, GL_SET, GL_COPY, GL_COPY_INVERTED, GL_NOOP, GL_INVERT, GL_AND, GL_NAND, GL_OR, GL_NOR, GL_XOR, GL_EQUIV, GL_AND_REVERSE, GL_AND_INVERTED, GL_OR_REVERSE, GL_OR_INVERTED


GetMouseScalar()
Returns the X and Y value of the mouse - corresponds to the Camera 2d mode ( for example, SetCam( 2, 0 ) will clamp x & y to -1, 1, SetCam( 2, 2 ) will clamp y to -1, 1, and x to the appropriate ratio ).

SetMouseVis( inOn )
shows or hides mouse - does not need to be called every frame (infact, it shouldn't).

SetMouseFree( inFree )
set free for 2d mode [ or menu selection ], do not set free if using as 3d pov!

BeginRTTFull()
* call this before your scene (and call EndRTTFull() at the end) to use full-screen shaders. ( Note that this will likely have better performance later on )

EndRTTFull()
* bind a shader before calling this at the end of your scene, and it will apply to the rendered image.

== 3d Noise:

Noise( x, y, z )
* returns a float value representing an interpolated point in a 3d noise grid.  The return value will generally range from -.4 to .4, often returning zero.
The noise is calulated as a 3d 'simplex noise'

SetNoiseSeed( inSeed )
* Sets the noise random seed.


====== Adding Geometry / Texture / Shader Content:

For all content, if you wish to add to the standard content library, simply put an image, shader, or geometry [custom .bxo format] file into the appropriate data directory.

Geometry: to create new geometry content, a blender python script is provided.  See the included blender files for reference.  Note the name and path of the .blend file determines the .bxo path and filename.

Shaders: see current shaders for reference - a .shad file includes both the vertex and fragment sections.

Sidenote: 'p' takes a screenshot!

Have fun!  Please share any interesting scripts ( with screenshots ) on whatever website the 'forum' is deemed to be!

m2c
