This page is being updated as the game is being built. It will cover scripting, the API, command line arguments and more.
These parameters are passed when executing the game from the command line (they are not available in scripting).
--settings-import filepath
This will import a JSON dictionary of settings. Settings include variables such as music volume, graphics quality, network parameters and more. Importing and exporting settings is handy for when you might have a different setup (Internet vs LAN, IP settings etc.) or you want to get a group of people up and running quickly.
--settings-export filepath
This will export a JSON dictionary of settings and overwrite the file.
I wanted it to be really easy for non-programmers to be able to load their own assets (sounds, music, graphics, etc.). Instead of using a programming language, I'm using JSON files as scripts. You can use any text editor you want to type out a JSON file. Here is a completely empty script. It literally does nothing.
{
}
Actions are like functions or procedures in other programing languages. They are a list of commands (instructions) which you want to do. You can name actions whatever you'd like, but there are 2 special reserved names: "start" and "update". "start" is called when your script is first run. If your script is attached to an object (such as a ship, space station, etc.) "update" is called every frame (if your game runs at 60fps, update would be called 60 times a second). Here is another sample empty script, but this time with actions.
{
"actions": [
{
"id": "start",
"commands": []
},
{
"id": "update",
"commands": []
}
]
}
This script still doesn't do anything. We need to add some commands to "commands" array.
Each action has a list of "commands". The below script will load an ogg (mac, windows, linux needs ogg files for music, iOS and Android are mp3) and then play it.
{
"actions": [
{
"id": "start",
"commands": [
{ "cmd":"asset.add", "id":"music_theme0", "type":"audio", "path":"music/menu.ogg" },
{ "cmd":"audio.music.play", "id":"music_menu" }
]
}
]
}
Let's look at one of the lines:
{ "cmd":"asset.add", "id":"music_theme0", "type":"audio", "path":"music/menu.ogg" },
"cmd" is the "command" we want to perform. Here it's "asset.add" (I'll have a list of commands further down) which means we want to load an asset. An asset is any sound, graphic, 3D model, or text (other scripts, etc.). In this case "id" is the unique name we want to refer to this asset by. "id" names can not contain special characters (except for _ and can not start with a number). "type" is the... well it's the type of asset such as "audio", "material", "model", etc. I'll have more on these types further down. "path" is where to find the file. The path will be relative to where this script was loaded from. NOTE: If you use the same id twice, the new one will replace the old one.
Let's look at the next line:
{ "cmd":"audio.music.play", "id":"music_menu" }
The command here is "audio.music.play." This is saying we want to play background music (only 1 background song will play at a time). The "id" here "music_menu", is the name of the asset from the previous line. We could have for instance, loaded 5 music files (such as music_menu, music_battle, music_victory) and then just played the music_menu for now (and switched to another music asset later).
You can call actions inside your scripts using the command like the one below.
{ "cmd":"script.action", "id":"loadstuff" }
You can run a script from another script using a command such as:
{ "cmd":"script.run", "id":"script_battle" }
You can terminate the currently running script you are inside of by using the command below. If you have scripts that only run once (during a startup of something and don't use continual updates, you should use terminate to clean up memory).
{ "cmd":"script.terminate" }
When spawning objects either in a scene or in your campaign/skirmish scripts, you can assign them an AI "behavior" along with some settings.
"ai": { "behavior":"none" }
"ai": { "behavior":"forward", "behavior_time":600 }
"ai": { "behavior":"wander", "wander_pos":"0,0,0", "wander_distance":1000, "wander_time":60 }
"ai": { "behavior":"waypoint", "waypoint_list":[ "100,200,300", "-200,-500,300", "100,300,200" ], "waypoint_close":50 }
Assets are any sound effects, music, 3d models, textures and scripts your mod has.
Most assets will load using a relative file path. Some are special (materials, skyboxes, etc.) and have multiple files that make them up. Below are some examples.
{ "cmd":"asset.add", "id":"music_menu", "type":"audio", "path":"music/menu.ogg" }
{ "cmd":"asset.add", "id":"skybox_space", "type":"skybox", "front":"skybox/front.png", "back":"skybox/back.png", "left":"skybox/left.png", "right":"skybox/right.png", "up":"skybox/up.png", "down":"skybox/down.png" }
{ "cmd":"asset.add", "id":"script_badguy", "type":"script", "path":"script/badguy.json" }
{ "cmd":"asset.add", "id":"scene_uranus", "type":"scene", "path":"script/uranus.json" }
There are 4 different types of audio.
Playing Sounds
{ "cmd":"audio.music.play", "id":"music_menu" }
{ "cmd":"audio.effects.play", "id":"effects_blaster", "pos":"100,200,10" }
{ "cmd":"audio.ui.play", "id":"ui_bleep" }
These commands will play the sound specified by the id in their group. For music, the current song will be stopped. You'll notice for effects, you can specify a X, Y, Z position.
Stopping Sounds
{ "cmd":"audio.music.stop" }
{ "cmd":"audio.effects.stop" }
{ "cmd":"audio.ui.stop" }
These commands will stop all sounds that are playing in their group. Typically you do not need to stop UI/effects sounds because they do not loop, however may want to stop them all when switching scenes.
An "object" is... well... it's an object. A ship, a space station, pretty much anything that would run a script on it and fly around, shoot, rotate, take damage and blow up. Objects are typically made of 3D models. Some objects will have "components" attached to them, such as shields and weapons. Objects that you can control (such as ships) will have a list of "cameras" for when you are controlling the object.
Like scripts, the object file is specified with json. Here is a sample object definition file. You can list multiple 3D models that make up your object and specify their location and rotation. You can also see a sample list of camera placements below. Notice the "aft" camera has been rotate to point backwards. The Space Station in the game has a light in it. This helps make it stand out in the scene. You can get some cool effects by setting the colors/ranges/intensity of the light.
{
"models": [
{
"id":"model_cube",
"pos":"0, 0, 0",
"rot":"0, 0, 0"
}
],
"lights":
[
{ "type":"point", "color":"#ffffff", "intensity":1, "range":100 }
],
"cameras":[
{
"id":"forward",
"pos":"0, 0, 1",
"rot":"0, 0, 0"
},
{
"id":"aft",
"pos":"0, 0, -1",
"rot":"0, 180, 0"
}
]
}
A "scene" is a location in the game. You define all of the static (non updated over the network) objects as well as things such as the skybox, asteroids, and other objects. When a player enters a scene (or scenario), they system will load the scene file and create all of the starter objects. You can also manipulate the scene directly with commands.
Like scripts, the scene file is specified with json. Here is a sample scene definition file. You can specify the id of the skybox, lights, and objects that are in the scene.
skybox - This is the id of which skybox to load. There are some built-in ones "skybox_stars0", "skybox_stars1", "skybox_stars2", "skybox_stars3", "skybox_galaxy0".
music - The id of the background music for this scene.
script - The id of the script for this scene. For instance, the main menu has a simple script to setup the camera and rotate it.
lights - There are 3 kinds of lights you can add to the scene. Ambient light is the overall lighting in the scene. It touches everything. You can only declare this once. There is only 1 ambient light. Directional lights are infinitely long and don't have any fall-off. This is what you would typically use for a sun. Point lights are a sort of ball of light. They have a "range" you can set. You can set if a directional or point light casts shadows by setting "shadows" to "soft", "hard", or "none". For fans of lens flares, you can set if a light has a "flare". I have 1 built-in at the moment called "sun". For performance, you probably just want 1 directional light causing shadows and as few point lights casting shadows as possible if not needed.
spawnpoints - Where players are spawned. You can provide a list and whenever a player spawns, it will select one of the points randomly. Additionally, you can specify a distance_min, distance_max from that point and the system will randomly pick a point that is the distance from the position you chose. Finally, you can set the "rot" (rotation) if you want or use "lookat" to specify a point to be pointing/rotated to when spawned.
objects - The "objects" list is not synced over the network. If you don't specify position (pos) or rotation (rot) they will default to "0,0,0". Additionally, you can create a batch of objects like asteroids by specifying the list of objects to use, the count, distance and scale. Note you can put "@random" to get a random rotation. The system will use your "seed" to random generate the asteroids. Using the same seed will produce the same results on every platform. If you specify the type as "asteroid", the system will remove some scripting and optimize them a bit (this is because there could be 100+ asteroids in your scene).
You can add a name to an object (and a label). When spawning multiple objects (for instance you set "count" to 5, you can use a name such as "Alien-@num." This will cause the names to be Alien-0, Alien-1, Alien-2 (and so on).
If you leave "color" blank, the object will have no label, however you can put in any hex code you'd like here.
Notice that your scene can also have objects with AI. In the example we're saying we want to synchronize the objects. This is important for objects that move. You could use these kinds of objects to have a scene with a space station, that maybe has ships patrolling it or wandering about.
{
"skybox":"skybox_stars0",
"music":"music_battle0",
"script":"script_menu",
"lights":
[
{ "type":"ambient", "color":"#ffffff", "intensity":0.2 },
{ "type":"directional", "color":"#ffffff", "intensity":1.2, "rot":"0,0,0", "flare":"sun", "shadows":"soft" },
{ "type":"directional", "color":"#00b4ff", "intensity":0.1, "rot":"0,180,0" }
],
"spawnpoints":
{
"list": [
{
"pos":"0,0,0",
"distance_min":50,
"distance_max":100,
"lookat":"0,0,0"
}
]
}
"objects":[
{
"id":"object_spacestation"
},
{
"id":"object_debris",
"pos":"-20, 100, 10",
"rot":"0, 45, 90"
},
{
"list":["object_asteroid0", "object_asteroid1", "object_asteroid2", "object_asteroid3", "object_asteroid4", "object_asteroid5"],
"type":"asteroid",
"count":100,
"scale_min":50,
"scale_max":100,
"distance_min":150,
"distance_max":2000,
"rot":"@random",
"seed":12345
},
{
"id":"object_alien1",
"name":"Fighter-@num",
"color":"#00aa00",
"sync":"net",
"count":5,
"distance_min":400,
"distance_max":500,
"rot":"@random",
"lookat":"0,0,0",
"ai": { "behavior":"wander" }
}
]
}
These are commands you put into scripts that are run. You can set which skybox to use with this command:
{ "cmd":"scene.skybox", "id":"skybox_stars0" }
The transform of an object is it's position and rotation. You can use the transform commands to position, orient and turn objects. If you are using an object that has an "engine" on it like a spaceship. You shouldn't use these commands and instead use physics/forces.
{ "cmd":"transform.position", "id":"@camera", "value":"0,0,0" }
{ "cmd":"transform.rotation", "id":"@camera", "value":"0,90,0" }
{ "cmd":"transform.rotate", "value":"0,1,0" }
This is for the UI that is displayed on the main screen. Internally, the system has a HTML/CSS parser.
You can load text files containing html and css and uses those for the on screen UI.
{ "cmd":"asset.add", "id":"ui_menu", "type":"ui", "path":"html/menu.html" }
{ "cmd":"ui.set", "id":"ui_menu" }