EXCOSC Base Code
----------------

This zip file contains the c++ source code for a game skeleton that can be
modded via lua scripts. There are project files for MSVC 2010 and XCode 3, and
a cmake project you can use to build it on Linux, BSD etc. See the INSTALL file
for more information on how to build the cmake project, including what
dependencies you'll need. The zip file comes with a very basic example game to
demonstrate how to use the skeleton.

It's designed for the EXCOSC game jam, so it acts simultaneously as an Open
Sound Control server and client, and offers simple functions for responding to
and transmitting OSC messages from lua.


Running the Binaries
--------------------
The binaries accept various command line parameters, including the port and
address settings necessary for them to communicate with other EXCOSC games.
These are:

-lp <port number> Sets the port to listen for messages on (default: 5678)
-sa <ip address>  Sets the ip address to send messages to (default: 127.0.0.1)
-sp <port number> Sets the port to send messages to (default: 5679)

On Windows, to run 2 EXCOSC games which communicate with each other, you would
use the following two commands from cmd.exe:

EXCOSCBase.exe -lp 5678 -sa 127.0.0.1 -sp 5679
EXCOSCBase.exe -lp 5679 -sa 127.0.0.1 -sp 5678

On OSX, you would enter the following two commands in two separate Terminal
windows:

open EXCOSCBase.app --args -lp 5678 -sa 127.0.0.1 -sp 5679
open EXCOSCBase.app --args -lp 5679 -sa 127.0.0.1 -sp 5678

Note that OSX's Terminal loads some locale settings by default which interfere
with the EXCOSCBase executable's unicode conversion routines. If it crashes
when you try and start it from Terminal, you will have to turn those locale
settings off, by:

1.) Open the Preferences dialog.
2.) In the Settings tab, select the Advanced tab.
3.) Un-check the 'Set locale environment variables on startup' check box.
4.) Restart Terminal.


Directory Structure
-------------------
The EXCOSCBase binary requires 4 folders in order to function:
fonts
images
scripts
sounds

Anything in the images and sounds folders will be loaded when the binary
starts up. The file types it understands are .jpg and .png for the images, and
.ogg for the sounds.

The scripts folder holds the lua scripts which will make up your game. Any .lua
file in this folder will be automatically loaded when the binary starts up and
when the user hits F5 to reload them.

The fonts folder contains a couple of font files and their credit texts.
Unfortunately the binaries are currently unable to automatically load fonts in
the same way they do images and sounds, and you're limited to my choice of
fonts.

All these folders are included in the zip file with the contents necessary to
constitute a simple demonstration game. To make your own game, simply delete the
contents of images, scripts and sounds, copy the 'Blank GameState.lua' file into
scripts and start coding. There is a complete reference of the various types and
functions the game skeleton provides in the 'LuaReference.txt' file.


In addition to the above folders, there are 3 .dll files which must be present
for the Windows executable to function:
portaudio_x86.dll
SDL-2.0.dll
SDL_image-2.0.dll


Also, because it is licensed under the GPL (see below) the 'license-code.txt'
file must be included when distributing your own game using the skeleton. The
'license-art.txt' file only applies to the example sound and visual assets and
can be discarded if you don't want to license your own assets CC BY-SA.


Lua Debugging
-------------
The game skeleton doesn't provide much in the way of assistance for debugging
script errors. If an error occurs, a (hopefully helpful) error message will
be displayed and written to a text file at:
<home dir>/NiallsAVLibLuaLog<some long number>.txt

There is also a writeDebugOutput() function which you can use in a printf
fashion to display debug text on screen.


Full List of Command-Line Parameters
------------------------------------
--width [val] | -w [val]:       Set the width of the window.
--height [val] | -h [val]:      Set the height of the window.
--windowed | -win:              Sets whether to go windowed or not.
--drawer [name] | -d [name]:    Sets the renderer to use. Can be GLESDrawer
                                (newer, more efficient) or GLImmediateDrawer
                                (older, more compatible).
--debug | -debug:               Output debug info to
                                <home dir>/NiallDebugFile<some long number>.txt.
--listenPort [val] | -lp [val]: Sets the port to listen for OSC messages on.
--sendAddress [val] | -sa [val]:Sets the ip address to send OSC messages to.
--sendPort [val] | -sp [val]:   Sets the port to send OSC messages to.
--help:                         Display this help.

These can also be set from the config.txt file that will be generated
when the program is first run. It resides alongside the keyconfig.txt file at:

Windows XP:      Documents and Settings/<user name>/Application Data/EXCOSC Base
Windows Vista/7: Users/<user name>/AppData/Roaming/EXCOSC Base
Linux etc.:      /home/<user name>/.EXCOSC Base
OSX:             /Users/<user name>/Library/Application Support/EXCOSC Base


Important License Details
-------------------------
The c++ code which constitutes the binaries is licensed under the GPL v3. This
means that any lua code you write to interface with them will also be licensed
under the GPL. I'm assuming this won't be a major issue given the circumstances
of the jam and the fact that any lua scripts you write will be readable from
any standard text editor.

The example sound and visual assets are licensed under the Creative Commons
Attribution-ShareAlike license.


- Niall Moody (08/08/13).
