VoidExpanse/scripting api: Difference between revisions

From AtomicTorchWiki
No edit summary
No edit summary
Line 1: Line 1:
= Scripting overview =
= Multiplayer server setup =


== Basic concepts ==
== GUI for multiplayer server ==
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 ===
'''Currently in development'''
* String IDΓÇÖs in mods can only contain alphanumeric characters and underscores. Any other characters are illegal.
We are planning to create a gui for Windows, Mac and Linux to provide easy, user-friendly server setup and management.
* Using underscore for variables and properties.
However, on console-based systems, like FreeBSD, there's always available server setup and management with console commands.
* 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) ===
== Multiplayer server setup ==
{{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 ===
To launch a multiplayer server on any system, your system needs to meet following requirements:
{{Main|VoidExpanse/Object_scripts|Object scripts}}
* .Net/Mono, compatible with .net framework 4.0
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.


=== Installation ===
1. Copy the following files from game distributive to your server machine:
* folder Server
* folder Mods


== VoidExpanse Scripting API ==
Installation complete!


=== Library inclusion and scopes usage ===
=== Launch ===
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.
'''Windows'''
* Inclusions of libraries directive must be the first lines in the script file (not necessarily, but preferably - to maintain order in scripts).
Launch AtomicTorch.SpaceRPG.Server.RuntimeWin.exe from ./Server/ folder.
* 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.
'''Other system with Mono'''
Launch AtomicTorch.SpaceRPG.Server.RuntimeWin.exe from ./Server/Mono folder with mono,
like this:
<pre>mono AtomicTorch.SpaceRPG.Server.RuntimeWin.exe</pre>


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


* [[VoidExpanse/scope-config]] (available: global)
Launch complete!
* [[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 ==
=== Settings ===
{{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.
'''SettingsServer.xml'''
Most of settings are stored in SettingsServer.xml, which is located in the same folder as server .exe file.
If it's not there, launch server once with "-new" argument, and it'll be created automatically.


In SettingsServer, '''do not modfify misc and network parts'''! It may cause malifunction.


== Consumables scripting ==
You may, however, modify <server> part on your own risk.
{{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.
'''Create a new game'''
When server starts, you can create a new game, or load an existing one.
To create a new game, type
<pre>-new [seed_key]</pre>
to create a new server.
Seed_key is a word, like "voidexpance" or "hellyeah", which will affect world generation on server.
For example, if you type
<pre>-new myworld</pre>
random world will be created, always the same for "myworld" seed key. And if you type
<pre>-new hellyeah</pre>
random world will be created too, but different from the one you'll get with "myworld".
In other words, seed_key word defines generated world.
Feel free to experiment, type in you nickname to create your personal world =)
 
 
'''Saving game'''
In multiplayer mode, server automatically saves game every time interval, specified in SettingsServer.xml (autosave_delay parameter).
You can save server game with console command ''savegame''.
<pre>savegame</pre> - will save you game to slot 0 under the name "CurrentWorld".
<pre>savegame 5 ServerNameWord</pre> - will save you game to slot 5 under the name "ServerNameWord".
 
'''Loading game'''
When server starts, you can create a new game, or load an existing one.
To load an existing game, use command
<pre>-load [slot_number]</pre>, for example, <pre>-load 0</pre>.
You can use the same command not only when server starts, but even during the game, just type in console:
<pre>load 0</pre>, and game from specified slot will be loaded.

Revision as of 03:25, 25 March 2014

Multiplayer server setup

GUI for multiplayer server

Currently in development We are planning to create a gui for Windows, Mac and Linux to provide easy, user-friendly server setup and management. However, on console-based systems, like FreeBSD, there's always available server setup and management with console commands.


Multiplayer server setup

To launch a multiplayer server on any system, your system needs to meet following requirements:

  • .Net/Mono, compatible with .net framework 4.0

Installation

1. Copy the following files from game distributive to your server machine:

  • folder Server
  • folder Mods

Installation complete!

Launch

Windows Launch AtomicTorch.SpaceRPG.Server.RuntimeWin.exe from ./Server/ folder.

Other system with Mono Launch AtomicTorch.SpaceRPG.Server.RuntimeWin.exe from ./Server/Mono folder with mono, like this:

mono AtomicTorch.SpaceRPG.Server.RuntimeWin.exe


Launch complete!

Settings

SettingsServer.xml Most of settings are stored in SettingsServer.xml, which is located in the same folder as server .exe file. If it's not there, launch server once with "-new" argument, and it'll be created automatically.

In SettingsServer, do not modfify misc and network parts! It may cause malifunction.

You may, however, modify <server> part on your own risk.


Create a new game When server starts, you can create a new game, or load an existing one. To create a new game, type

-new [seed_key]

to create a new server. Seed_key is a word, like "voidexpance" or "hellyeah", which will affect world generation on server. For example, if you type

-new myworld

random world will be created, always the same for "myworld" seed key. And if you type

-new hellyeah

random world will be created too, but different from the one you'll get with "myworld". In other words, seed_key word defines generated world. Feel free to experiment, type in you nickname to create your personal world =)


Saving game In multiplayer mode, server automatically saves game every time interval, specified in SettingsServer.xml (autosave_delay parameter). You can save server game with console command savegame.

savegame

- will save you game to slot 0 under the name "CurrentWorld".

savegame 5 ServerNameWord

- will save you game to slot 5 under the name "ServerNameWord".

Loading game When server starts, you can create a new game, or load an existing one. To load an existing game, use command

-load [slot_number]

, for example,

-load 0

.

You can use the same command not only when server starts, but even during the game, just type in console:

load 0

, and game from specified slot will be loaded.