VoidExpanse/scripting api

2014-07-25T03:27:02Z

Tjmonk15: Grammar, punctuation, phrasing edits.

= Scripting overview =

== Basic concepts ==
Scripting is done via actions that custom scripts can subscribe to. There are a number of actions that are called by servers automatically, plus users can create their own actions and call them when needed. This also makes it possible for users to create scripting frameworks/libraries for others to use.
Each action has one argument (ΓÇ£argsΓÇ¥) that is a JavaScript object containing several properties depending on which action is being called. In some actions this ΓÇ£argsΓÇ¥ object can be empty. But either way, it allows for a 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.
* Use underscore for variables and properties.
* Use CamelCase for functions and methods.
* zxc_q - ΓÇ£qΓÇ¥ in the variable always represents ΓÇ£quantityΓÇ¥ or ΓÇ£number of ...ΓÇ¥.
* zxc_id - ΓÇ£idΓÇ¥ always means either a string id from a XML file if it is of the type of string, or if it is a uint then it is an entity (instance) id of some object.
* zxc_req - ΓÇ£reqΓÇ¥ always means ΓÇ£requirementsΓÇ¥.
* All mods should prefix their variables, functions, classes, storage keys, etc with a key for isolation from other mods. An example of such a prefix would be ΓÇ£prf_ΓÇ¥ -> ΓÇ£prf_some_variableΓÇ¥, ΓÇ£prf_SomeFunctionΓÇ¥.

=== Internal scripts (Overridable) ===
{{Main|VoidExpanse/Internal_scripts|Internal scripts}}
These scripts are usually only called 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 a 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 script into the current JS instance. Library scripts can also include other libraries (no echo effect will appear).

Allows modders to use functions and objects of these libraries in this particular script instance.
* Include 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 the first function declaration in the file.

Preprocessor directive <code>using(scopename);</code> allows modders to use a 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 these scripts are denied.

There are four possible functions for device script.

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

VoidExpanse/Consumable scripting

2014-07-25T03:16:09Z

Tjmonk15: Grammar, punctuation, phrasing edits.

== Consumables Scripting ==

In most cases the standard xml-structures are more than enough to implement consumable effects. However, if we need
to do something special, for example, restock ammo, self-destruct, teleport or kill all ships in front of the player, you will need scripts.

There are no hard rules for scripting consumables, here are just a couple of tips.
For example, if we need to create a consumable that refills ammo in all of the players ballistic weapons.
First of all, we need to create a basic consumable xml, with an empty effects node.
<pre>
<effects>

</effects>
</pre>

Then, you create a new global script in folder /scripts/globals/, in which you hook some function to a special trigger:
<pre>
function OnInit()
{
actions.BindToTrigger("onConsumableUsed", "onBallisticAmmoConsumableUsed",
{id: "consumable_ballistic_ammo"});
}
</pre>
After that, every time a player uses a consumable with the xml-id "consumable_ballistic_ammo", function "onBallisticAmmoConsumableUsed" will be called.

Now, all that's left is to implement the actual ammo refill:
<pre>
function onBallisticAmmoConsumableUsed( args )
{
var ballisticWeapons = ship.GetWeaponsOfType( args.ship_id, 2 );
if(ballisticWeapons == null) return;

for(var i =0; i < ballisticWeapons.length; i++)
{
ship.RefillAmmoForWeapon( args.ship_id, ballisticWeapons[i] );
}
}
</pre>

That's all, now we have a consumable that refills ammo the of all ballistic weapons!

AtomicTorchWiki - User contributions [en]

VoidExpanse/scripting api

VoidExpanse/Consumable scripting