:: STARSHIP RUBICON ::
:: A MODDER'S GUIDE ::

Starship Rubicon v2.1
June 2015

If there's interest, I'll fill this out more in possible future updates. Hopefully this'll be enough to get you started.

=========================================================
======================== SUMMARY ========================
=========================================================

A [MISSION] manages the metagame for multiple map/starnode scripts. The mission script is the same name as the mission folder it is in. It controls which map or starnode scripts are available to choose (metameta) and what to do once one is selected (meta, eg, choose a ship).
	Lua functions: metameta() and meta()

A [MAP] is a single flying-around-and-shooting level. It consists of both a map file (which encodes the terrain, ships, etc) and a lua script. The script is usually specific to a single map, though it doesn't have to be. It mostly controls the events and end conditions of maps.
	Lua functions: init() and update()

A [STARNODE] is the FTL-style network of nodes you hop around on. They're a little more complicated than a map script, so there's no ingame editor for them. In brief, the script sets up the size of the network, places specific "rooms" which are collections of actors (these are all pulled from starmapSource/), and organizes what enemies appear and in what combinations.
	Lua functions: starnode_setup()

[ROOMS] and [ACTORS] ...

A [CHASSIS] is the archtype for ships. When a ship is created, it pulls all of its base stats, graphics, and physics from the its chassis type. Chassis scripts are in shipSource/
	Lua functions: init() and setIcon()
	
A [CONFIG] is a specific loadout of components for a ship. Found in configSource/, they are just strings of human-readable text that Rubicon can generate and read in a simple format. Each config file has the extension ".ship" and has the filename of the form "<owner>_<chassis>_<name>":
	The <owner> is either "base" (the default global thing the game falls back on), a pilot name (storing a player's custom loadout), or a mission name (I never really used this, but it lets you use a different default config for a mission without overriding the original shared one).
	The <chassis> is just the name of the chassis the config is for.
	The <name> is just the name of this specific config.
	
	
A [COMPONENT] is, pretty simply, one of those pieces of equipment you can fit on your ship. Defined in componentSource/, the lua script defines the name, description, shape, what guns and abilities it provides, stat bonuses, the cost, etc.
	Lua functions: init() 

A [GUN] is a weapon that gets added to a ship by a component. The type of gun it is (Auto, Semi, Beam, or Release) is set by the component, and only certain functions are available for certain types of guns (e.g. gun.initBeam() only works for Beam guns). Their initial stats are set by init() and their effect when they fire is set by fire(). For speed's sake, the functions update() and shot_update() are never actually called unless gun.skipUpdate or shot.skipLuaUpdate are set to 0.
	Lua functions: init(), update(), fire(), and shot_update()


An [EMITTER], defined in effectSource/, allows a *lot* of different behaviors for graphical effects. An emitter will generate some number of sprites with variable scales, speeds, rotations, and how fast each of these change. They can either be placed in certain spots (i.e. explosions) or attached to ships (i.e. shields).
	Lua functions: init()

[TERRAIN] and [BACKDROPS] are sort of just a set little pieces of lua code to run (for terrain, at a specific spot on a map) on setup and possibly during a map. They might just throw up some graphics through an emitter (e.g. nebulae) or make some ships (inert or otherwise). As with guns, updateHost() and shipWithin() aren't called unless terrain.callUpdate and terrain.callWithin are set to 1.
	Lua functions: initHost(), updateHost(), shipWithin(), setIcon()



=================================================================
======================== MISSIONS & MAPS ========================
=================================================================

--- Zone Editor ---
For buttons that have numbers, you can generally left-click to increase them and right-click to decrease.

[ Border Tab ]
Set how large the map is. Modify width and height by pressing their buttons, the number shown is the map RADIUS in tiles. Each tile corresponds to a 256x256 pixel square of the map.

[ Terrain Tab]
Pretty self-explanatory. Left-click to paint, right-click to delete. The stage will run the appropriate terrain lua script at that location.

[ Entity Tab ]
Left-click to paint, right-click to delete. Technically, you're placing the respawn.lua terrain with a whole bunch of its values set. It allows you to control how ships arrive on the map.

	BEHAVIOR :
	Spawned ships can have their behavior overridden with the selected script.
	
	FACTION :
	The faction of the spawned ship. By default, 0 is neutral, 1 is the player, and 3 is vile nemesis.
	
	COUNT :
	How many ships to spawn per set
	
	STATE :
	Certain mission scripts will activate or inactivate spawn groups at set times (e.g. waves.lua will activate groups in order as previous ones are finished -- so for waves you should place all enemies as inactive)

	MODE :
	"once" -- will spawn one set and then deactivate
	"continual" -- will keep spawning for as long as it's active & triggered
	"immediate" -- the set starts on the field (one-shot)
		
	DELAY :
	How many milliseconds in between spawning members of the set
	
	GROUP :
	Used by the script to activate certain respawn terrains. ALSO used by the "waypoint group" trigger to denote WHICH waypoint it pays attention to
	
	TRIGGER :
	"start active" -- doesn't use the trigger system
	"waypoint group" -- watches a waypoint and only spawns if that waypoint is active
	"delay countdown" -- uses the delay timer as a countdown instead? I'm not 100% sure this still works. it's from back when I was experimenting with how best to introduce waves of enemies.


[ Backdrop Tab ]
Toggle different backdrop scripts to be run for this map. As opposed to terrain, these aren't tied to specific tiles.

[ Waypoint Tab ]
Waypoints mark specific tiles for the mission script to use. They can also detect if the player is nearby (in tiles) and be visible on the minimap or as a beacon.


--- Starmaps ---

WARNING regarding punctuation in character dialogue: I didn't (and still don't) know jack squat about data serialization, so I had to hack together my own save file format for starmaps; this ended up using a lot of plain text and I use the characters $ & * @ | as spacers. THIS MEANS that if you use any of them in character dialogue, things are gonna crash when you save/load! (doesn't apply to banter.lua)


=======================================================
======================== SHIPS ========================
=======================================================

The AI for all the shipped ships is hardcoded for speed's sake. However, since I am benevolent, I've made it possible to write your own AI with lua scripts. Take a look at test.lua in AISource/ -- any chassis with a behavior not recognized will look for a lua file of that name.




===================================================================
======================== COMPONENTS & GUNS ========================
===================================================================




=======================================================
======================== NOTES ========================
=======================================================

Protool: entering the pilot name "WIK" will unlock the ingame root ship editor. Using this will allow you to change base ship configs without manually changing their files.

I've left a number of .bmx files laying around for your reference. Changing them won't do anything (as they get compiled into the application rather than being run in real time like the .luas) but I thought they might be handy for people who want to know what functions they can call from the luas. ALSO KNOWN AS: the poorest of the poor man's laziest effort at documentation.


