AtomicTorchWiki - User contributions [en]

VoidExpanse/scripting api

2014-05-21T12:28:42Z

Ixby: /* Scripting overview */

= Scripting overview =

== Basic concepts ==
Scripting is done via actions that custom scripts can subscribe to. There are number of actions that are called by server automatically, plus users can create their own actions and call them when needed. This also makes possible for users to create scripting frameworks for others to use.
Each action has one argument (ΓÇ£argsΓÇ¥) that is a JavaScript object containing several variables inside depending on a particular action. In some actions this ΓÇ£argsΓÇ¥ object can be empty. But either way it allows for unified format for all actions within the scripting system.

=== Scripting naming convention ===
* String IDΓÇÖs in mods can only contain alphanumeric characters and underscores. Any other characters are illegal.
* Using underscore for variables and properties.
* Using CamelCase for functions and methods.
* zxc_q - ΓÇ£qΓÇ¥ in the variable always represents ΓÇ£quantityΓÇ¥ or ΓÇ£number of ...ΓÇ¥.
* zxc_id - ΓÇ£idΓÇ¥ always means either string id from XML file if it is of the type of string, or if it is uint then it is entity (instance) id of some object.
* zxc_req - ΓÇ£reqΓÇ¥ always means ΓÇ£requirementsΓÇ¥.
* All mods should prefix their variables, functions, classes, storage keys and all the rest with a key for isolation from other mods, example of such prefix would be ΓÇ£prf_ΓÇ¥ -> ΓÇ£prf_some_variableΓÇ¥, ΓÇ£prf_SomeFunctionΓÇ¥.

=== Internal scripts (Overridable) ===
{{Main|VoidExpanse/Internal_scripts|Internal scripts}}
These scripts are called usually once and only in a particular situation. Each of these script files must exist in only one instance. If a new script is added the previous one will be overridden. Each of the script files must implement only one script action. Usually players should not modify these scripts unless they want to completely re-implement some game feature.

=== Global scripts (called in the world dynamically) ===
{{Main|VoidExpanse/Global_scripts|Global scripts}}
Global scripts are executed continuously during gameplay. For each event there could be many bound scripts. Also it is possible to create custom actions and subscribe to them.

=== Object scripts ===
{{Main|VoidExpanse/Object_scripts|Object scripts}}
Object scripts are scripts attached to a particular game object. When that object starts an action, if script has an appropriate handler for this action it will be executed.

=== Events ===
[[VoidExpanse/events|List of Events]]

== VoidExpanse Scripting API ==

=== Library inclusion and scopes usage ===
Preprocessor directive <code>include(libname.js);</code> includes a library scripts into a current JS instance. Library scripts also can include each other (no echo effect will appear).

Allows to use functions and objects of these libraries in this particular script instance.
* Inclusions of libraries directive must be the first lines in the script file (not necessarily, but preferably - to maintain order in scripts).
* All include directives must be before first function declaration.

Preprocessor directive <code>using(scopename);</code> allows to use specific scope in a specific script. Scope name must be an existing scope name (see scopes below). Except for some specific scopes (like topic or npc), which are available only in specific places, like topic scripts or AI behaviors.

=== Scopes ===
Each scope contains a number of functions available from it.

* [[VoidExpanse/scope-config]] (available: global)
* [[VoidExpanse/scope-script]] (available: global)
* [[VoidExpanse/scope-actions]] (available: global)
* [[VoidExpanse/scope-server]] (available: global)
* [[VoidExpanse/scope-generator]] (available: global)
* [[VoidExpanse/scope-spawn]] (available: global)
* [[VoidExpanse/scope-station]] (available: global)
* [[VoidExpanse/scope-chat]] (available: global)
* [[VoidExpanse/scope-console]] (available: global)
* [[VoidExpanse/scope-storage]] (available: global)
* [[VoidExpanse/scope-game]] (available: global)
* [[VoidExpanse/scope-ship]] (available: global)
* [[VoidExpanse/scope-visual]] (available: global)
* [[VoidExpanse/scope-player]] (available: global)
* [[VoidExpanse/scope-topic]] (available: only in topics)
* [[VoidExpanse/scope-topics]] (available: global)
* [[VoidExpanse/scope-relations]] (available: global)
* [[VoidExpanse/scope-npc]] (available: global)
* [[VoidExpanse/scope-timer]] (available: global)
* [[VoidExpanse/scope-debug]] (available: global)

== Device scripts ==
{{Main|VoidExpanse/Device_scripts|Device scripts}}
Devices uses effect scripts, which is similar to any object scripts, but uses itΓÇÖs own special system of arguments. These scripts are shared between instances of the same device type, therefore global variables in this scripts are denied.

There are four possible functions for device script.

== Consumables scripting ==
{{Main|VoidExpanse/Consumable_scripting|Consumables scripting}}
Consumables can be programmed with standart xml-values, but, in order to implement something
special, one can use special techniques, described in this article.

VoidExpanse/Adding Ships

2014-05-21T05:19:29Z

Ixby:

The easiest way to get a feel for modifying the available hulls within the game, is to look at the core game files and use them as examples/templates.

== Core Game Mod ==

The game is designed to incorporate mods easily, and the single-player/main game is designed as a standard mod that is loaded by default.
In the main VoidExpanse directory, there is a ''ModsConfig.xml'' file, which looks something like this...

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<mods>
<mod>core_0.1.0</mod>
</mods>

You need to edit this file to include each mod you wish to add to your game, which I'll explain below.

Notice the only mod it loads by default is ''core_0.1.0''; You can find this mod in your VoidExpanse main folder under /Mods/core.cpk

''Core.cpk'' includes all of the basic game files, such as hulls, weapons, and devices, but also includes AI behavior and basic game scripts.
The game package also provides two example 'mods' in the /Mods/ directory, but these are listed as .mpk files (''devmod.mpk'' & ''masacre.mpk'')

''Both of these mod/pack files (.cpk and .mpk) are basically .zip files that contain the game information''

Open the Core.cpk file as you would a .zip file, and you'll see two folders, plus a ''headers.xml''

Your headers.xml file should look like this, straight out of core.cpk...

<?xml version="1.0" encoding="utf-8"?>
<root>
<id>core</id>
<title>Core Game Data</title>
<author>AtomicTorch Studio</author>
<description>Base mod for VoidExpanse. Contains all required game data to play the game.</description>
<version>0.1.0</version>
<updated>20.08.2013</updated>
<modtype>2</modtype> 
</root>

Make a copy of that ''headers.xml'' file, but don't change the name.
Now make a basic compressed file, let's say called ''testmod.mpk'' and edit your copy of headers.xml...
The only important thing to change is the ID, which should match your .mpk filename. So, for this example it should look like this:

<?xml version="1.0" encoding="utf-8"?>
<root>
'''<id>testmod</id>'''
<title>Core Game Data</title>
<author>AtomicTorch Studio</author>
<description>Base mod for VoidExpanse. Contains all required game data to play the game.</description>
<version>0.1.0</version>
<updated>20.08.2013</updated>
<modtype>2</modtype> 
</root>

Now, when you place your ''testmod.mpk'' file into the /Mods directory with the rest of the game files (core.cpk and the other .mpk files), it will load when you begin the game.
Right now, though, there is nothing inside the mod file to load!

The final step is making sure the mod gets loaded.
Open up the ''ModsConfig.xml'' from the main game directory. We need that ID and VERSION here...
If my mod file was ''testmod.mpk'' and I left the <version> at 0.1.0, my ''ModsConfig.xml'' should look like this:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<mods>
<mod>core_0.1.0</mod>
<mod>testmod_0.1.0</mod>
</mods>

Don't forget the underscore between the id/filename and the version info.

Simple, right?

----

== Actually Adding a Ship ==

Now that you have an empty .mpk file (except for the ''headers.xml''), you can start adding things like ships and weapons.
There are three basic requirements for adding a ship item to the game:
1.Item Data
2.Model Data
3.Texture Data
If there was a 4th requirement, it might be the sound effects, but I'm not sure.

The easiest way to begin is to make a copy of the starter shuttlecraft, since it costs nothing and is available immediately.
You can skip the last two(/three) requirements by just copying the basic Item Data file and making ''slight'' adjustments...

Open up core.cpk and you'll see two directories: ''Data'' and ''Content''

For now, you just want ''Data''...Go further, into ''/items'', and you'll see the files for each usable item/cargo in the game. In this case, we want to just copy the ''hull_shuttle.xml'' file.
Copy it somewhere, and rename it to something else...For these purposes, it will be renamed to ''hull_skiff.xml''.

After renaming it, open up the file and you'll see quite a bit of stuff in there. Ignore it all for now, and focus on the top bit...It should look something like this:

<root>
<header>
<game_version>1.0.0</game_version>
<id>hull_shuttle</id>
<title>Civilian shuttle hull</title>
<description>It would probably be a good idea to get rid of this as soon as you can...</description>

The important thing here is to rename the ''<id>'' like we did before, when creating the mod file. In this case, my ''<id>'' line would look like this:

<id>hull_skiff</id>

And change the <title> to something else, so you can verify that it works later on

<title>Civilian Skiff</title>

Save that .xml file (''hull_skiff.xml''), and open up your mod file .mpk...
The game looks through your .mpk file the same way it looks through the core .cpk game files, so your new ''hull_skiff.xml'' needs to be placed in ''/data/items'' inside your mod file (the same file path where we got the original ''hull_shuttle.xml'').

So finally, if you kept the same naming conventions as I did here, you should have:

1. A compressed/zip file named ''testmod.mpk''
2. A modified ''headers.xml'' file inside ''testmod.mpk''
3. A modified ModsConfig.xml file that includes your mod
4. A /data/items/hull_skiff.xml file inside your mod .mpk

This should be enough for the game to register and load your new Civilian Skiff, which is almost identical to the starter shuttle...except for the name. But hey, everything is in the brand, right?

[[VoidExpanse/Items_(Hull)|Check out the breakdown of the hull .xml file here]]

VoidExpanse/Items (Hull)

2014-05-21T05:17:21Z

Ixby: Created page with " == HULL/SHIP ITEM FILE BREAKDOWN == ''See Core Mod / Adding Ships for information about how to add a new ship/item into the game.'' We'll use..."

== HULL/SHIP ITEM FILE BREAKDOWN ==

''See [[VoidExpanse/Adding_Ships|Core Mod / Adding Ships]] for information about how to add a new ship/item into the game.''

We'll use the basic shuttle item file as a template, found in core.cpk/data/items/hull_shuttle.xml

Opening the .xml file, it should have a whole bunch of nicely spaced lines of nonsense that I can't format easily to showcase as an example.
So we'll do it piece by piece...

'''Header'''

<root>
<header>
<game_version>1.0.0</game_version>
<id>hull_shuttle</id>
<title>Civilian shuttle hull</title>
<description>It would probably be a good idea to get rid of this as soon as you can...</description>
<enabled>1</enabled>
</header>

<game_version> Leave it alone.

<id> The filename, without extension

<title> The item name as shown in-game (in store or inventory)

<description> The description as shown in-game...

<enabled> I'm guessing just a discrete way to control the item's availability, for debug?

'''Graphics'''
<gfx>
<icon>items/hull_shuttle.png</icon>
</gfx>

The only thing here is the path to the in-game icon picture for the item. In this case, we are using the icon provided in the core game files. If you want to use your own icon, you need to add it to your mod (.mpk) file:

''Item icons are placed into'' MOD.mpk/content/textures/items ''and must have the same name as called under the <gfx> section above.''

'''<DATA>'''

Pretty much the remainder of the hull/item file is covered under the <data> header...

<type> Unknown?

<shops_level> The minimum level of shop that will carry the item; Level 1 items are carried by the starting station.

<price> The item's unmodified price

<upgrades_max> Unknown?

<upgrades> Unknown?

<requirements> Skill (or other?) requirement for usage of the item/hull. (eg. Heavy Frigates)

<effects> The effects header defines the basic hull/item parameters such as health, inventory space, etc..See Effect Types later on for more info...

''<item_data> This header section defines the actual model and textures to use for the item/hull.''

'''<GFX>'''
<world_model> The name of the plain model file (.obj) located in MOD.mpk/content/hulls/
<world_textures> The three required textures for the model. ''See the core.cpk/content/textures/hulls files for examples.''
<diffuse> Diffuse texture
<specular> Specular texture
<normal> Normal texture
<inventory_model> The same reference as <world_model> above.
<inventory_textures> Same textures referenced above; Change as required for your own file names.
<world_scale> This seems to scale the 3D model in-game; Values higher than 1 will increase the ship's size.
<inventory_scale> Unknown?

'''<SFX>'''
Sound effect references for the hull, primarily the sound of the engines and the ship exploding.

'''<PHYSICS>'''
<mass> The 'mass' of the hull/item, play with it to see the effects.
<shapes> Assuming that this defines the collision area for the ship. They seem to always have a defined mass of 1.

'''<EQUIPMENT_SLOTS>'''
<consumables> The number of consumable slots on the hull
<devices> The number of device slots on the hull
<boosters> The number of booster slots on the hull

'''<WEAPON_SLOTS>'''
<id> ??
<slot_type> Assuming type of weapon..Laser/Cannon/Missile
<slot_size> Size of slot 1/2/3/?
<display_type> ??
<direction> 0; Base direction the weapon is facing, 0 being ahead?
<rotation_angle> Turret degrees of freedom
<rotation_speed> Turret rotation speed
<position> Position of turret model on ship

'''<TRAILS>'''
This section defines the engine and RCS trails left by the ship during movement.
Color scheme is typically something like <color>R:G:B:Intensity</color>

'''<BLINKS>'''
This defines the intermittent (if desired) lights on the ship model. You can define the colors, position, and intervals of the lights.

VoidExpanse/Adding Ships

2014-05-21T04:34:10Z

Ixby: /* Actually Adding a Ship */

VoidExpanse/modding

2014-05-21T04:08:46Z

Ixby: /* Assets modding */

VoidExpanse was created to have an almost unlimited modding potential. Almost every aspect of game can be modified and extended.
There are no hardcoded scripts and in-game logics, everything you see in VoidExpanse now was created as root mod. This concept is similar to
early GameBryo versions.

Modding consists of two essential parts:
* Assets modding
* Scripting

== Assets modding ==

All objects in game are assets. They are, basically, XML files, which are located in "[MOD]/data" folder.
For example, if you want to add a new item or a ship - it'll be Asset modding.

For example, let's take a look at ship "shuttle".
Hull of this ship is presented in "data/items/hull_shuttle.xml". In this file, all basic info about hull contined:
weapons slots, model, textures, blinks, engine trails, physics etc.

Basically, to add a new ship all that you need is to add one more hull item to "data/items" folder of your mod. And model with textures, of course.
To make ship adding easy, we've created a special tool - VE Physics Adjuster, which is quite easy to use.

[[VoidExpanse/Adding_Ships|Core Mod / Adding Ships]]

== Scripting ==

Scripting is the most important and essential part of the game. Everything - from galaxy creation to damage and prices calculations - are scripted and
moddable.

More information on scripting is in [[VoidExpanse/scripting_api|Scripting section]] of this wiki.

VoidExpanse/modding

2014-05-21T04:07:54Z

Ixby: /* Assets modding */

VoidExpanse was created to have an almost unlimited modding potential. Almost every aspect of game can be modified and extended.
There are no hardcoded scripts and in-game logics, everything you see in VoidExpanse now was created as root mod. This concept is similar to
early GameBryo versions.

Modding consists of two essential parts:
* Assets modding
* Scripting

== Assets modding ==

All objects in game are assets. They are, basically, XML files, which are located in "[MOD]/data" folder.
For example, if you want to add a new item or a ship - it'll be Asset modding.

For example, let's take a look at ship "shuttle".
Hull of this ship is presented in "data/items/hull_shuttle.xml". In this file, all basic info about hull contined:
weapons slots, model, textures, blinks, engine trails, physics etc.

Basically, to add a new ship all that you need is to add one more hull item to "data/items" folder of your mod. And model with textures, of course.
To make ship adding easy, we've created a special tool - VE Physics Adjuster, which is quite easy to use.

[[VoidExpanse/Adding_Ships]]

== Scripting ==

Scripting is the most important and essential part of the game. Everything - from galaxy creation to damage and prices calculations - are scripted and
moddable.

More information on scripting is in [[VoidExpanse/scripting_api|Scripting section]] of this wiki.

VoidExpanse/Adding Ships

2014-05-21T04:06:06Z

Ixby:

VoidExpanse/Adding Ships

2014-05-21T01:49:11Z

Ixby: Created page with "The easiest way to get a feel for modifying the available hulls within the game, is to look at the core game files and use them as examples/templates."

The easiest way to get a feel for modifying the available hulls within the game, is to look at the core game files and use them as examples/templates.