ModdingGuide

Content

  1. Requirements for Darkstar One Modding
  2. Darkstar One Modding Options
  3. Preparations and Sample Mod
    1. Tutorial Mod
    2. "darkstarmod.ini"
    3. Mod Directory
  4. Ini Files
    1. Solar Systems
    2. Planets
    3. Cluster and Solar Systems
    4. Cargo Vessels and Cargo Vessel Definitions
    5. All Other Data
  5. Creating Your Own Texts
  6. Self-made Sounds
    1. Playing of Sound Effects
    2. Creating a Database File
  7. Script System
    1. General Information about Script Functions
    2. Script Structure
    3. The Transition Table
    4. Function Parameters V and Data
    5. Sequence of a Script
    6. Script Events
    7. Script Types
    8. Sample Script
    9. Further Samples
    10. Script Tools
    11. The Script Debugger
    12. Breakpoints
    13. Variables, Stack et al
    14. Script Compiler
  8. Modifying 3D Objects
    1. File Structures
    2. General Procedure
    3. Structure of XML Scene Files
    4. Types of Objects
    5. AVCMesh
    6. Level of Detail and AVCLODSelector
    7. The X File Converter
    8. Blender Compiler
    9. Sample Blender (simple_blender)
  9. Additional Tools
  10. How to Replace the Container Model (Sample)
  11. Circulating Mods

Requirements for Darkstar One Modding

Modding will be supported beginning with Darkstar One Version 1.2. The required update is readily available in the internet at http://www.ascaron.com. The version number is displayed at the bottom of the main menu.

Darkstar One Modding Options

Here they are - the modding tools for your favorite game. Before you start, there are a few things to be considered. Modding is not easy and you will have to be knowledgeable in programming as well as having artistic abilities.

Unfortunately, Darkstar One was not made to support external changes. All modding opportunities were supplementary implementations. Therefore, it may not necessarily be easy to use them.

That said, with the tools and short guides that are being introduced here it will be possible to amend Darkstar One according to your preferences. Create your own missions, add more solar systems or even create your own ship models. It can be done with some effort and enthusiasm.

These are the modding opportunities for DSO:
  • Missions
    You can write missions, which will be either offered at the terminal or triggered in space under certain conditions as soon as you enter a solar system. Created missions may contain new texts, new voice-over files or new sounds.
  • Ini-files
    All available configuration files (*.ini) can be modified. This will have an impact on the
    • structure of solar systems
    • trade system
    • parameters for shields, weapons etc.
  • Graphics
    Available 3D models (objects) and textures may be exchanged or amended. Note: You will not be able to add new objects. Currently, the object formats are only supported in the X-format. A converter for the format used with Darkstar will be available. Read more in the chapter "Amending 3D Objects".

Preparations and Sample Mod

All modifications must observe a certain directory structure, which will be explained here. Version 1.2 of Darkstar One will create a "Customization" subfolder in the "My Documents\Ascaron Entertainment\Darkstar One\" folder. Every mod must be stored in separate folders within this folder. You can freely choose the name for these subfolders. Once the mod has been correctly installed, you will be able to select it from the main menu of Darkstar One from the "Mods" menu. The name of the mod will be determined in the file "darkstarmod.ini" which must exist for each mod (see below).

Tutorial Mod

The mod tools will install a sample modification in the folder "Tutorial" in "My Documents\Ascaron Entertainment\Darkstar One\Customization".
"Tutorial" contains a full modification including all files (source codes, string tables) that were used to create it. All samples and explanations in this modding guide are referring to contents of the modding tutorial. Therefore, the mod "Tutorial" will be a good reference for your own mods.

"darkstarmod.ini"

Each mod contains a "darkstarmod.ini" which is structured like this:
[darkstarmod]
mod_name = (name of the mod)
mod_desc = (short, one-line description)

The name and the description will be displayed in the selection menu for modifications.

Mod Directory

This is the structure of a mod directory:
/inifiles
All .ini files should be available in this folder (simply extract from "ds_3dadd.cpr" if you want to make any changes).
/scripts
All .lua files, which you created or compiled will be found in here
/sound
All sound files (preferably mp3) belong in here.
/strings
The resource file "user_strings.res" for new texts is found in this directory. Furthermore, a zip file with the name "user_data.zip" is available for 3D data. The structure of this file is explained in the chapter "3D". Missing directories or files will prompt the game to use the default data. The prime example are the *.ini files. If they are missing in the mod, the original Darkstar One files will be loaded. The sample modification will explain all opportunities for changing the game.

In order to guarantee the compatibility of the save games, each modification will save its own save games. If you save a game while mod "A" is active, this save game will only be available for modification "A". Only compatible save games will be displayed for each mod.

".Ini" Files

The entire game logic (solar systems, trade logic) receives its initial data from text files. Upon starting the program, these files are read and a new binary file will be created if necessary. Many files are dependant on each other (amount of solar systems in clusters etc.). These dependencies will be mentioned if and when they exist.
In order to adapt a modification to the logic, all required files have to be copied into the "inifiles" directory of the resprective mod. The sources are available in the archive "ds_3dadd.cpr". Rename to "ds_3dadd.zip", unpack and copy the files.
A short description of the files and the part of the logic they contain will follow.

Creating a ".Bin" file

All ".ini" files are loaded during the start-up process and stored in a binary file ("ini_file.bin"). If you change the configuration files, the binary file must be deleted in order to be recreated during the next start of the program. When you restart the program again, only this binary file will be loaded in order to optimize speed.
Note
Please be sure to copy all files. One or more missing files will result in a corrupted ".Bin" file.

Solar Systems

Darkstar One may contain a maximum number of 403 solar systems. They are defined in the file "StarSystem.ini" and they are numbered from 0 to 402. Each system consists of these attributes:
  • Artefakt: Does an artifact exist in this system?
  • Bedroht: Is this system occupied by pirates yes / no
  • Bürger: Number of inhabitants in Billion
  • Cluster: Number of the cluster where the system is situated
  • Energylevel: The higher the level, the more particles drift in space
  • Faction: Which faction does this system belong to (0=Galactic Union, 1=Pirate system, 2=neutral)?
  • FunctionX1/2/3 and Function_Y: Define parameters for trading simulation
  • Nachbarregel: Defines the systems that have to be entered in order to make this system available
  • Piratengang: Index of pirate gang (65535 if no pirate gang is present)
  • Planeten: Number of planets in the system (? "Planets.ini")
  • PosX, PosY: Position on the navigation map
  • Prodution1-5: Which goods are produced in this system
  • Produktionsfaktor: Amount of produced goods. Factor 0 to 1
  • Regierung: Form of government (0=Democracy, 1=Dictatorship, 2=Federation, 3=Anarchy, 4=Empire, 5=Monarchy)
  • Sichtbarkeitstyp: Under which conditions does this system become available (0=starting the game, 2=enter neighboring system, 4=story related, 6=never, 7=hidden system) ?
  • StarLightID: The system lighting defines the security of the system that results from the form of government (anarchies are unsafe and therefore, they have a reddish light setting. Democracies are safe and have a more friendly and lighter setting) and refers to the "StarLight.ini" (where the light settings for the systems are defined)
  • UniqueItem: >0, if a unique item is hidden within the system

Planets

Each system consists of a fixed number of objects such as a sun, one or more planets, meteorite fields, stations and one jump gate. The parameters in the "Planets.ini" are self-explanatory.

Cluster and Solar Systems

Each clusters features a configuration file (cluster.ini) and consists of three definitions:
  • amount of cargo vessels
  • definition of the cargo vessels
  • production values of the goods "contained" within the cluster

Cargo Vessels and Cargo Vessel Definitions

Structure of a cargo vessel definition:
  • starting system
  • target system
  • type of cargo vessel
  • amount of goods carried
  • types of goods and their respective quantities
This data defines all cargo vessels within a cluster. We recommend not changing this data manually. The initial distribution is handled automatically by Darkstar One when the game is started.

The amount of goods available in each system within the cluster is defined separately from the cargo vessel definitions. The quantity is defined for each of the 24 available types of goods within the game.

All Other Data

The files all contain commentary and they are divided into these areas:•Spielerschiff: Afterburners.ini, Engines.ini, Equipment.ini, Thrusters.ini, Upgrades.ini, StarFlight.ini
  • Spielerschiff (everything relating to the player’s ship): Engines.ini, Equipment.ini, Thrusters.ini, Upgrades.ini, StarFlight.ini
  • Handel (trading): Goods.ini, Prices.ini
  • Objekte (objects): Meteorids.ini, TradeStation.ini, StarShip.ini
  • Bewegung general movement): StarFlight.ini
  • Simulation: Time.ini, HitPoint.ini
  • Effekte (effects): Projectiles.ini, Explosion.ini, ExplosionDef.ini

Creating Your Own Texts

In order to create your own scripts and missions you will have to create new texts. Darkstar One is using a special resource format in order to simplify the work on localizations. Internally, Darkstar uses so-called StringIDs; therefore, you will have to create your own IDs. Ideally, you should use Microsoft Excel in order to create them. The StringID is entered into the first column, the actual text in the next column. The StringID will identify the text in the game.

The Excel file must be saved as an XML sheet. The file below is also available as a sample file in the tutorial mod.

In order to use the texts in the game, the Excel file must be converted. A program called "Xml2ResConverter.exe" is available in the "Tools" folder. You will have to specify three files: the original global.res file of Darkstar One (in order to avoid conflicts with existing StringIDs), the XML file and the target file. The target file ("user_strings.res") must be copied into the mod’s directory. The Excel file must be closed during the conversion.

That is all you have to do. The texts will now be available for all missions via their StringIDs. In order to have a text appear in a certain place of the script, you will have to specify the StringID, i.e. NGUI.ShowSubtitle ("ID_MY_FIRST_STRING_ID").

Image: The list of strings in Excel. Left is the StringID, right is the corresponding text.

Self-made Sounds

You will be able to embed your own sound files for mission scripts into your modification. Similar to the texts, these files are not addressed by their file names but rather by an ID. However, these IDs are not manually assigned; instead, they are created from the structure of the directories and the file names. Initially, three subfolders for the main groups ("(stream)", "(sfx2d)" and "(sfx3d)") should be created in the modification’s "Sound" folder. The names of the subfolders must be in brackets.

Stream

Files in this main group are played as a stream. Music files should be saved here.

2d

Simple stereo effects belong into this folder

3d

Folder for three-dimensional effects

New subgroups may be created for every main group by creating new directories called 'grp_groupname'.

Playing of Sound Effects

Once a sound database has been created with the "KlangKollektor" (german for "sound collector") tool, all effects and music are ready to be used in scripts. The script programmer can access the IDs of the effects by using the created groups. You can play them by using "NSound.PlayUserSound". The parameters are the groups (not the main groups) without the prefix "grp_". If the sound effect is stored in "(sfx2d)/grp_maingroup/grp_subgroup/sound.mp3" you can address a specific sound:
    NSound.PlayUserSound( "maingroup.subgroup.sound" )
Or you can address a random sound from a group:
    NSound.PlayUserSound( "maingroup.subgroup" )
If you do not specify a sound, a random sound from that group will be played.

Creating a Database File

With the "KlangKollektor" Tool, you will be able to create a user_sounds.xml file from the directory structure and the .asset files. This file will be loaded when the game is started; it will register all files with their specific names and make them available for the script programmer.

Create file:
    KlangKollektor.exe -o user_sounds.xml sound

Script System

Darkstar One uses a lua-based script system (http://www.lua.org) with slight modifications for missions.
All scripts (missions as well as story missions) use a condition-based system. Instead of implementing separate functions for each event, so-called transitions are defined which become active according to the current step of the mission. Thus, scripts for the missions can be written in chronological order, which makes understanding a script much easier.
Essential for writing scripts is a sound knowledge of lua, especially the tables. General programming knowledge will also be useful.
We will only address the basics of the system here; an extensive documentation of the script commands can be found in the "html" folder of the documentation.

General Information about Script Functions

All functions of the script system are divided into logical subgroups, each with their own name spaces. These are the groups:
NScript | General script functions
NMission | Missions specific functions
NComm | Dialogue system, radio messages etc.
NGUI | Graphical interface (show textes etc. )
NPlayer | Everything concerning the player and his ship
NCamera | Cameras for ingame cutscenes
NStarSystem | Functions concerning wingmen (space ship groups)
NWing | Space ships in general
NShip | Raumschiffe allgemein
NObject | Objects in general
NWaypoint | Waypoint system
All groups contain creational functions for the respective groups and a variety of additional functions.
Each namespace that is used within a script must be imported beforehand (see sample script). All functions follow a consistent scheme: Each function is assigned to exactly one parameter, the parameter table. The return value is also defined in one table, the return value table.
Both tables contain named fields, which have to be filled and submitted. Functions that do not have any parameters will be assigned with an empty table. There are no functions without argument.
In order to analyze the return value table you must also look at the named fields, otherwise you will not be able to retrieve the data.
    V.Container = NContainer.Create( { Type=CONTAINER_SHIP, Ship=V.Ship} ).Container
Now would be a good time to familiarize yourself with the commands of the respective groups :-)

Script Structure

Basically, a script consists of the command "NScript.Register". The rest of the script is contained as parameter(s).
NScript.Register( {
    Name = < Missionname >,
    Group = < GroupId >,
    Type = < Missiontyp >,
    Transistions = < Transitiontable > } )

The Transition Table

The transition table is a lua table with an arbitrary number of transitions. Each transition is a table with four elements.
{ < MinStep >, < MaxStep >, < Event >, < Function > }
MinStep and MaxStep are float values and the condition of the mission has to be between (including) these values in order for the function to run properly. Event is a string with the name of the event. If a faulty event name is used, an evaluation will be triggered. If all three conditions are true, the code will be activated in function using parameter V and Data. A complete transition would look like this:
{ nil, nil, "MissionStart", function( V, Data )
    NGUI.ShowInfoText( Text="IDM_NEW_LOGENTRY" )
    NStarSystem.SetAsMissionTarget( {System=2,Set=1 })
    V.Step=1
end },
Here, the float values for MinStep and MaxStep are defined as "nil". Nil stands for an undefined value and it will result in always executing this transition when the event MissionStart is triggered. Also, V.Step is set to 1 at the end in order to define the condition of the mission. When a transition is supposed to change the following status, V.Step must be assigned. V.Step should be started with a float value >0, as C++ does not differentiate between nil and 0. In order to stick with the concept, you should start with V.Step = 1. As and may differ, transitions, which can be applied to a number of conditions, can be written. This is especially interesting for shortcuts within the mission. If 3 to 14 events can happen in the conditions but can be avoided by leaving the solar system, you should use this transition:
{ 3.0, 14.0, "LeaveSystem", function( V, Data )
    V.Step = 15
end },
Each event will evaluate all possible defined transitions. The sequence is not defined. You should bear that in mind.

Function Parameters V and Data

Each script, or rather each mission contains a "script global" table V, which will be submitted to each function as a parameter. This parameter enables the forwarding of conditions, variables etc between transitions.
The variable "V.Step" is very important here, as it contains the current progress of the mission (which will activate the relevant transitions). This table contains an arbitrary number of variables, depending on how the author of the scripts intends to use them.
The "Date" table, however, depends on the respective events, which are triggered. It contains every variable that is connected to the event. The parameters are available in the documentation of the events.

Sequence of a Script

All scripts follow a consistent scheme:

Load

Before starting a script, it will be run completely once, i.e. the "NScript.Register" command will be executed; however, the functions within the defined transitions will not be executed.

Initialize

In order to determine, whether a script should be executed, an "Init" event is triggered, which requires an answer of either 0 or 1, where 1 = "yes, start the script".

Start

When the script is started, the "init" will be executed again. If the return value is not 1, an error will occur. Afterwards, the event "create" will be triggered. The condition is undefined at this time. Therefore, "create" has to be a (nil,nil) transition. At this stage, the V table can be written for the first time and the step can be set (it is important to do this ? V.Step = 1). The next event will be "MissionStart", which will be executed straight after "Create". Afterwards, random events may be assigned by the program.

End

The script will end as soon as the condition of the mission is set to MSTATE_ACHIEVED or MSTATE_FAILED. This condition is separate from the entry in V.Step and is set by the function "Event.SetState()". Once these conditions have been set, the appropriate event "Achieved" or "Failed" will be triggered.

Skript Events

An extensive list of all used events is available in the html documentation. So go, take a look :)

Script Types

There are different types of missions. Two special mission types are available for self-made scripts, which the game will give preference to: MTYPE_USER_TERMINAL and MTYPE_USER_SPACE. Terminal missions are offered on terminals within the stations. When such a mission can be created (i.e. "init" returns a 1) it will take precedence and be displayed. The same applies to space missions, which are triggered by entering a new system via the hyper jump gate. When several, equal missions are available, the "MTYPE_USER" missions will be preferred.

Sample Script

We would like to demonstrate how to create a mission with a sample script (terminal mission). Before programming a script, you should know exactly what you want your mission to do/be. Once you have determined this concept, you can work the script step by step and change it into lua code.

The Idea

For our first script, we will create a simple rescue mission, where a container must be collected and returned to the station.

Note

The described script can be found in the tutorial under /scripts/skript_tut001.lua
The sequence of the script should be:

  • The missions should only be offered in the start system
  • When the mission has been accepted at the terminal, the container should be created near the station when the station is left. One string should cover the content ("Darkstar One Dokumentation")
  • When the container has been collected, the task should be adapted. The player will receive a message to return to the station.
  • If the player returns the container, the mission will be accomplished
  • If the player lands on the station without the container, nothing happens
  • If the player leaves the system, the mission will fail
  • If the player destroys the container, the mission will fail
As you can see, it is important to cover all possible actions of the player in order to create a consistent, believable mission. Especially those actions leading to the failure of a mission must be carefully considered.

The Script

The lua template from the TutorialMod "template.luatemplate") is the basis for our sample. Copy it and rename to .lua. Everything marked with <$...$> must be filled in by the script author.
The "Import" part of the template imports all important namespaces and additional functions. Always keep this line just to be on the safe side.
Here is the actual mission header, the "NScript.Register" command:

NScript.Register( {
    --name
    Name = <$ INSERT SCRIPT NAME HERE $>,
    --group
    Group = 0,
    --type
    Type = <$ INSERT SCRIPT TYPE HERE $>,
    --transition table
    Transitions = {
All you have to do here is to insert the name of the script (a string) as well as the type of script. A list of all possible script types is available in the html documentation.
Name = "SKRIPT_TUT_001",
--group
Group = 0,
--type
Type = MTYPE_USER_TERMINAL,
The transitions follow immediately after. Essential transitions are already implemented in the template and all you have to do is fill them with mission specific details. Each mission should yield a reward for the player. Therefore, we enter a transition variable in the "V" table of "MissionStart".
{ --Mission starts
nil, nil, "MissionStart", function( V, Data )
--the necessary initializations should happen here
V.Reward = 9876; -- credits for the player
--the actual mission starts here
V.Step = 1
end },
The step of the mission is set to 1 here, which means that the mission will start now. You should use "V.Reward" for rewards since this variable is already used in the template.
The preliminaries are done - you can now implement the actual mission steps. We will take you through our basic concept step by step.
The first step ("The mission may only be offered in the start system") must be entered into the "Init" transition. This function will be queried every time a mission is offered or created. "Init" must return true or false depending on whether the mission may be started or not.
local start_system = MissionLib.GetStarSystemId()
if start_system == 8 then
    return{ Ready = true }
end
return{ Ready = false }
The "MissionLib" function "GetStarSystemID()" supplies the ID of the solar system where the player is currently located. If he is in system eight (the start system of the game), the mission may start. Otherwise, it will not start. If true is returned, the "Create" transition will be initiated. Depending on the mission type, "MissionStart" will be initiated; in this case, it will be initiated when the player accepts the mission at the terminal.
We will also adjust the necessary steps in this "MissionStart" transition.
NStarSystem.SetAsMissionTarget( { System = MissionLib.GetStarSystemId(), Set = true } )
MissionLib.LogUpdateStory()
V.Step = 1
The current solar system will be marked as the active mission system on the navigation map. We will also let the player know that his logbook has changed (this "MissionLib" is readily available during installation and contains a variety of helpful additional functions.) Additionally, Step will be set to 1. This will start the actual mission. Now, it will be useful to have the source code for the tutorial mission handy.
The first event that we want to look at is "Station". If someone enters or leaves a station, this event will be triggered. When this happens, we will create a container via NContainer.Create, that will be filled with mission specific goods. In the end, we will save the handle of the container in the mission global table V and will advance the step of the mission further (V.Step=2).
This will activate additional transitions, which will "watch" over the player’s activities. Three of these events will be observed: "System" in case the player leaves the system, "Container" in case the container is destroyed and "Grab" for collecting the container. If the container is destroyed or if the player leaves the system too early, the state of the mission will be set to MSTATE_FAILED. The mission will be finished (and it will trigger the appropriate "Failed" event).
If the player collects the container (transition "Grab"), the mission will be set to step 3 and another transition will become active ("Station"). This new transition is the reaction to entering the station. If the player carries the container, it will set the state to MSTATE_ACHIEVED.

Further Samples

There are another two mission scripts in the sample mod, which explain the creation of opponents as well as the dialogue system.
  • skript_tut002.lua
  • skript_tut003.lua
  • skript_tut004.lua

Skript Tools

Writing scripts is great, but sooner or later you will have to debug them. A very efficient LUA-Debugger is available via HTML. As long as the game is running, the frontend is available at "localhost:54321" via a webbrowser.

The Script Debugger

Once you have loaded the page, follow the "Missions" link. You will find a table listing all currently active missions. Further down is a list of all other missions that have been loaded.

Image: Table of the currently active missions. The name of the script, its current status and a link to the source of the script are displayed.

Breakpoints

In order to set breakpoints you will have to display the source code. Click on the link "View script source" or go to the page "localhost:54321/Framework/ViewScript".

Image: Script Code in the LUA Debugger. Clicking on line number will set (or remove) a breakpoint at the next executable line. Breakpoints are marked by the prefix '@'.

Variables, Stack et al

When a breakpoint is reached and the game stops, the display will change. At the top, debug data will appear, at the bottom left the source is displayed and on the right the current variables (local, global, stack etc.) will appear. It might be necessary to reload the site in order to refresh it.
If you have worked with a debugger before, it should not take long to familiarize yourself with this one. Commands and input that will be executed via the "Eval" button must be entered in the window at the top left. "Step" will jump into the currently displayed function (do not forget "next" to switch to source if possible).

Image: Script display when a breakpoint has been reached

Script Compiler

When all scripts are finished and tested, a file that will contain all scripts in byte code can be created with the script compiler ("Tools" directory).
scriptcompiler.exe -o user_scripts.bin *.lua
In order to be able to compile the LUA files it is essential that these files from the Darkstar directory are available:
  • BattleLib.Lua
  • BattleLibEx.lua
  • CameraLib.lua
  • MissionLib.lua
Afterwards, they can be deleted from the mod directory. If you do not want to compile your LUA files, this step is not necessary. The created "user_scripts.bin" file must be located in the "scripts" folder; otherwise, Darkstar One will be unable to access it.

Note

Once the scripts have been compiled, they will be inaccessible. Therefore, it will not be possible to add more breakpoints.

Modifying 3D Objects

Once writing scripts for new missions and changing the galaxy has become boring, you will be able to exchange 3D objects or implement new textures. Unfortunately, we are not able to release the entire tool chain due to legal restrictions; therefore, creating and implementing modified objects is slightly more complex, but not impossible to do ;).

File Structures

All files necessary for three-dimensional visuals are stored in these three archives:
  • ds_3dgen.cpr
  • ds_3dobj.cpr
  • ds_3dtex.cpr
    • If you want to change 3D files, you should unpack these archives first.

Note

  • Cpr archives can be packed or unpacked with any "zip" decompression program if you replace the suffix ".cpr" with ".zip".
  • Do NOT unpack the archives into the Darkstar One folder!
Once you have unpacked the archives you will see a "3DView" folder, which contains most of the important data.

General Procedure

In order to change a model or a texture, you should isolate the original data and copy it into the directory of the future mod. However, make sure that you observe the directory structure (originating from "3DView"). As some of the models have fixed objects that the program will need to address, we recommend changing the "3do" references and possibly the shader within the XML files only. Completely replacing an XML file is extremely complex and time-consuming.
The next step is creating a "3do" file with the converter and writing appropriate blenders.

Structure of XML Scene Files

A game model consists of an XML scene that refers to all applied resources. These resources are the actual model (in "3do" format), the used shaders (blender) as well as the applied textures. Originating from the root node, all objects are structured hierarchically (scene graph). Generally, an object is compiled of several separate objects, which are assigned to certain "tasks". The best thing to do is to load an object (i.e. "Freighter_A_0.xml") in the "TakeALookXP" tool (see paragraph 7.7). You will be able to go through the hierarchy of a scene and view the respective ‘sub’objects. That should make matters easier to understand.

Types of Objects

  • AVCWorldRoot: base node
  • AVCTransformationNode: basic transformation node
  • AVCMesh: basic mesh in ".3do" format
  • AVCShieldMesh: mesh for an object’s shield
  • AVCGlowObject: mesh for the "glowing" areas of an object
  • AVCDistortionObject: mesh for the distortion effect (i.e. heat haze) of an object
  • AVCLODSelector: level-of-detail step definition

AVCMesh

This is the most important type of object: it defines the object that will be displayed. It contains „EffectContainer". The number of these containers corresponds with the number of materials in the „3do" object that is being used. This is important when entering a new object. A blender (shader) is assigned to each effect container (Path="..."). Material attributes as well as further parameters for the blender are entered as child nodes of the respective containers.
An „EffectContainer" looks as follows:
<EffectContainer path="test/test.bsd9">
<Material>
+0.000000 +0.261784 +0.344000 +0.000000
+0.471080 +0.471080 +0.471080 +0.000000
+0.000000 +0.761000 +1.000000 +0.000000
+0.025000 +0.050000 +0.100000 +0.000000
+100.000000
</Material>
<Parameters>
<Float semantic="..." value="+1.00000" />
...
</Parameters>
</EffectContainer>
The material consists of diffuse, ambient, specular and emissive color as well as shininess. All colors are specified in RGBA. The material attributes as well as the parameters will be available for the specified blender by semantics. Further details are available under "Blender Compiler".
Important: If several LOD levels exist in "3do" object, the number of effect containers is equal to the sum of all materials in the LOD levels.

Level of Detail and AVCLODSelector

Darkstar One supports several LOD levels per object with the "3do" format. Separate from the number of LOD levels in the object file, an object of the type "AVCLODSelector" is required in the XML scene. This object will define the distance when the levels are switched and which parts of the objects may be switched off during the scene.
<Object Type=".?AVCLODSelector@@" ... LODNumber="2">
LODNumber does not define the number of levels within the mesh; instead, it defines the number of "LODDesc" (LOD Descriptions), which are following. This description will define which parts of the objects are changing in comparison to the previous scene. The partial objects are addressed by their names, according to the hierarchy of the scene.
<LODDesc Clients="2">
lod_0|object_a 1 +0.00000
lod_0|object_b 1 +0.00000
</LODDesc>
<LODDesc Distance="+25.000000" Clients="2">
lod_0|object_a 0 +0.000000
lod_0|object_b 1 +0.750000
</LODDesc>
"Clients" defines the number of objects that will be changed. "Distance" defines the distance to the viewer that has to be reached in order to activate the LOD level. The path in the scene to the affected object defines a client. 0=switch object off, 1=switch object on. The latter value is set to a value between zero and one. It will select the LOD level within the "3do" file. Zero is the first level, one the last. A value greater than ‘one’ may be entered, but only if the object is switched off.

The X File Converter

A rudimentary tool is available to convert models from the "x" format to .3do. Starting the tool is easy:
3do_convert <lod1.x> <lod2.x> ... <output.3do>
Simply enter the source files. The last parameter defines the return file. That is all. Please note that the entered "x" files should correspond with the various level-of-detail meshes (unless you want to convert a spaceship into a container when the object reaches a certain distance in game). One level will be sufficient for an initial test.
3do_convert <input.x> <output.3do>
The converter creates a simple preview ("output.xml") which can be seen with the "TakeALookXP"-Tool. All LODs are included in the object.

Blender Compiler

You will be able to create your own shaders for self-made models with the help of the blender compiler. Sound knowledge of programming shaders is essential; otherwise, this will not be fun at all. As a simple example, we will use a blender that will only transform the vertices and will assign a color. (This color may be defined in the XML scene file.)

Sample Blender (simple_blender)

In order to create a blender you will need two files: the shader ("fx" format) and a corresponding XML file. Initially, it is important to define the used Techniques in the XML file. You may enter several of these techniques; the first functional one will be used (from left to right).
<?xml version="1.0" encoding="utf-8" ?>
<Blender>
    <Effect include="simple_blender.fx">
    </Effect>
    <Variables/>
    <EffectAnimators totaltime="2.0">
    <EffectAnimator name="DOIT" duration="2.0" techniques="simple">
    <Trigger animator="DOIT" time="2.0" />
    <Init />
    <Main />
    </EffectAnimator>
    </EffectAnimators>
</Blender>
This template can be applied; however, you should amend the "fx" file ;)
There is a multitude of values in an effect that the engine will initialize. Among those are certain matrixes. The tutorialmod contains an example in "3DView/my_objects/simple_blender.fx" as well as "3DView/my_objects/simple_blender.xml".

Initialized Values

The values initialized by the engine are listed with their semantics:
  • World: Worldmatrix
  • WorldView: Worldmatrix*Viewmatrix
  • WorldViewProjection: World*View*Projection
  • WorldInverseTransposed: Wordmatrix invertiert und transponiert
  • View: ViewMatrix
  • ViewInverse: Inverses der Viewmatrix
  • ViewProjection: View*Projection
  • Projection: Projectionmatrix
    • The above named matrixes can be used in the shader Further values can be entered into the shader from the scene description using "<Material>" or "<Parameters>".

Material

A material description consists of ambient, diffuse, specular and emissive color. These values are to be used in the shader with these semantics:
  • Ambient
  • Diffuse
  • Specular
  • Emission

Parameters

Semantics are assigned to all parameters in order to enable the shader to address them. There are several types of semantics for parameters:
  • Float: simple float-Value
  • Vector: float4

Lighting

Objects in Darkstar One can be illuminated by a maximum of four light sources. Shader that want to use lighting will receive the number of light sources from the engine and will relate them to the shader via the "uniform" parameter. You should view the blender sample that is supplied by the "Blendercompiler". In there, an array of shaders is created with the appropriate parameters for the number of active light sources.

Additional Tools

Once you have created a new object, you can look at it by using "TakeALookXP". In order to familiarize yourself with the tool, you might want to look at some objects from the unzipped archives.
Left: hierarchic structure of the XML scene file, below the camera settings. Right the 3D view as well as the returned debug data.
The converter tool will also create an "output.xml" file, where you will be able to view your converted objects.

How to Replace the Container Model (Sample)

As a simple example, we will use a cargo container and replace it with another simple model.
First, we will create the required folder structure in the mod directory. We create a "3DView" directory and copy the "Container.xml" as well as the "Contain_low.xml" from the archive "ds_3dgen.cpr". In this folder we create a subfolder "my_objects" for our own data. Next, we will have to convert our object and create an appropriate blender. We will copy these files into the "my_objects" folder. Once that is done, we will search the files "Container.xml" and "Container_low.mal" for the node that we need to change. Typically, this node is a "?AVCMESH@@" type. Be careful to replace the effect containers appropriately for your own blender and mesh. The paths also have to be correct (here: "my_objects/ .3do" etc.). That is all. The "3DView" folder that we created must now be packed into a zipfile called "user_data.zip" and it must be located in the root of the mod directory.

Files with the suffix *_low.xml

All 3d objects exist as XML file as well as "*_low.xml" file. The files with the suffix "_low" are required for shader 1.1 graphics cards and they use adapted blenders. Further adjustments will be needed for older graphics cards.

Circulating Mods

Once a mod is finished and tested, you may distribute it freely. However, you do not need to submit all files (unless other users should further advance them). These files may be omitted when distributing a mod:
  • ".lua"-files, once a .bin file has been compiled from them (and they have thereby been error-checked)
  • All graphics files, once a user_data.zip has been created
  • All ".ini" files, once the ini_files.bin has been created


Scripting commands

Packages

All functions are organized as "Packages" which work as namespaces. A package contains all functions which belongs to a single or groups of logical objects. NWing for example, contians all functions operating on the logic-class CWing, NPlayer everything which has to do with the player and the playership.

To use the functions of a package, you have to import it via import.

--  import Packages
import "NPlayer"
import "NSound"
...
...
NPlayer.AddReward( { Reward=NPlayer.StandardReward( {} ).Credits } )
NSound.SetCustomMusic( { Title="victory" } )
...
...

Functions

All functions are used in the same way. Every function gets a parameter (Parametertable) and returns a value (Returntable).

Both tables consist of named (arrays of) variables containing (parameter or return) values. Functions without parameters contain an empty array - so there are no functions without parameters. Importent to know is, that every return value must always be a table! A simple get-function to return a value needs to use the table.

Example:
-- WRONG
V.Container = NContainer.Create( { Type=CONTAINER_SHIP, Ship=V.Ship } )
-- RIGHT
V.Container = NContainer.Create( { Type=CONTAINER_SHIP, Ship=V.Ship } ).Container

The documentation uses following pattern

  • < Name of the Event > : < Parametertable > : < Returntable >
  • Object starting the event
  • Parametertable
  • Returntable
  • Examples
Italic names show optional parameters. In that case a default-parameter or default-range is shown after the descriptinon. If there is no entry all values of that datatype are valid. Explanations to the datatypes are shown under "Datatypes". In some cases a parameter needs further parameters. In this case all dependent parameters are shown with '|'.

Example:
Create( { Type, Size, Ship|PosDesc|Position } ) : { Container }

Depending on Type the parameter 'Ship' or 'PosDesc' or 'Position' is necessary.

Data types

There are following data types:
  • float : a floating point value
  • int : signed integer
  • unsigned int : unsigned integer
  • bool : bool value ( true | false )
  • enum : enumeration of a predefined named constant
  • string : zero terminatd string
  • table[n]:[] : Table with entries of type < Type >
The data type bool which is not included in the used LUA-version is emulated. true will be used as 1 (int) and false as nil - a non existing variable. If you leave out a bool-value it will be identically used like false, but for better readability it is recommended to use always true or flase.

NStarsystem.SetAsMissionTarget( { System=V.System0, Set=false } )
-- is identical to
NStarsystem.SetAsMissionTarget( { System=V.System0 } )
-- This one is semantical irritating

The datatyp table starts the numbering always with 1, meaning that table[3] defines a table with entries table[1], table[2] and table[3]. The line table[n] is used for an table witrh arbitrary entries (1 to n).

Note: These datatypes are only for documentation purposes and does nothing have in common with datatypes from LUA.

Enumeration types

Some enumeration types are used from multiple functions. to avoid repetition an overview of some enumeration types is given below. Are the names of the enumeration types not self-explanatory, a short description is given.

Container types

All available container types.
Value | Comment
CONTAINER_SMALL | Container 50t
CONTAINER_MEDIUM | Container 100t
CONTAINER_LARGE | Container 200t
CONTAINER_ARTEFACT | Artefact-Container (perhaps with unique items)
CONTAINER_PASSENGER | Passenger container attached to shuttles
CONTAINER_ROCK | Container, created while blasting a meteroid

Spawn areas

Areas where Wings can be spawned Nearly all areas are located relativly to the position of the hypergate and the tradestation in a system. The tradestation is located on position (0,0,0), the hypergate is at (0,0,10000) [unit = meters]. We will use this vector (TS-HG) as orientation for all other areas, used in the game.

Value | Parameter | Comments
POSDESCR_PLAYERSHIP | -/- | Spherehull surrounding the playership (center), Diameter 2-4km
POSDESCR_INTERCEPTION | -/- | Spherehull with a diameter of 2-4km. The center of the sphere is located 4 km away, around the middle of TS-HG (0,0,5000).
POSDESCR_OFFSET | -/- | Sphere with a diameter of 3km. It is located 3km away, around a point 3km away of the hypergate on TS-HG (0,0,7000).
POSDESCR_ASTEROID | -/- | Sphere with a diameter of 0.5 km. Its center is 1km away from the middle of an asteroid on the opposite side to the tradestation. Are there more than one asteroid in the system, one asteroid is choosen randomly.
POSDESCR_TRADESTATION1 | -/- | Sphere with a diameter of 0.5 km. Its center is 1km away from the tradestationcenter on the opposite side to the hypergate (0,0,-1000).
POSDESCR_TRADESTATION2 | -/- | Spherehull around the tradestation with a diameter of 1-3 km.
POSDESCR_RESEARCHSTATION | -/- | Sphere with a diameter of 0.5 km. Its center is 1km away from the middle of a researchstation on the opposite side to the tradestation. Are there more than one researchstations in the system, one researchstation is choosen randomly.
POSDESCR_WELCOME | -/- | A cycle with a diameter of 100m. The center is located 100m in front of the dockinggate of the tradestation.
POSDESCR_METEROIDS | -/- | The center of a meteroid field (there can only be one field in a system).
POSDESCR_ESCORT | -/- | A torus, centered at the middle of TS-HG (0,0,5000)
POSDESCR_HANGAR | Object | Start from an object with a hangar
POSDESCR_WINGDISTANCE | Object and Distance | A position from a specified wing in space
POSDESCR_EXPLICIT | Position | A defined position in space
POSDESCR_HYPERSPACE | -/- | System will be entered through the hypergate
POSDESCR_HYPERSPACE_CRUISER | -/- | Cruisers may enter the system at any position
POSDESCR_FIRST_PLANET | -/- | Position above the first planet (behind tradestation)
POSDESCR_ACTIONTURRET | Position | Position is a position relative to the action turret
POSDESCR_CRUISER_ENTRY | Position, FrontDir, UpDir | can be used with Skaa and Cruiserwings like POSDESCR_EXPLICIT. Ships will enter the system with a hyperspaceeffect and slow down on the given position.
When there are more than one researchstation / asteroid, one of them is randomly selected. When you try to create e.g. tree wings on one asteroid, it cant be assumed that all tree wings are created on the same asteroid. Use instead the explicit parameter with the number/id of that object (asteroid).

Trading goods

All available goods for trading
Value | Comment
GOODS_COALHYDRATES | Kohlenhydrate
GOODS_PROTEINS | Proteine
GOODS_LIFEFORMS | Lebensformen
GOODS_VEGFIBERS | Pflanzefasern
GOODS_METALS | Metalle
GOODS_PRECMETALS | Edelmetalle
GOODS_CRYSTALS | Kristalle
GOODS_ALLOYS | Legierungen
GOODS_MACHINERY | Maschinen
GOODS_ELECTRONICS | Elekronik
GOODS_COMPUTERS | Computer
GOODS_SHIPTECHS | Schiffstechnik
GOODS_MEDICINE | Medizin
GOODS_CHEMICALS | Chemikalien
GOODS_LIQUOR | Likör
GOODS_FERTILIZER | Dünger
GOODS_ENERGYCELLS | Energiezellen
GOODS_FUELRODS | Brennstäbe
GOODS_ISOTOPES | Isotope
GOODS_SUPERCONDUCTORS | Halbleiter
GOODS_VIDEOGAMES | Videospiele
GOODS_LUXURIES | Luxusgüter
GOODS_ANDROIDS | Androiden
GOODS_DRUGS | Drogen

Ammunition

Value | Comment
AMMO_TYPE_LASER = 0 | Standard weapon Humans
AMMO_TYPE_RAILGUN | Standard weapon Morlok
AMMO_TYPE_PHASER | Standard weapon Raptor
AMMO_TYPE_SONIC | Standard weapon Octo
AMMO_TYPE_ENERGY | Standard weapon Wasp
AMMO_TYPE_PHOTON | Standard weapon Thul
AMMO_TYPE_SKAADRILL | Standard weapon Skaa
AMMO_TYPE_SWARM | Rocket
AMMO_TYPE_HELLFIRE | Rocket
AMMO_TYPE_BIGBANG | Rocket

RadarMapColors

Used colors of the radarmap. The color does not influence any behaviour or attitude to the player.
Value | Comment
RADARMAP_INVISIBLE | Object is not shown
RADARMAP_SHIP_FRIEND | friendly object (green)
RADARMAP_SHIP_HOSTILE | hostile object (red)
RADARMAP_SHIP_OFFICIAL_WING |
RADARMAP_SHIP_CRUISER |
RADARMAP_SHIP_THREAT | Threat (orange)
RADARMAP_SHIP_NEUTRAL | neutral ship ()
RADARMAP_INVALID | invalid color?

Ship types

Value | Comment
ST_PLAYERSHIP | the playership
ST_TRADERSHIP | a tradeship
ST_SHUTTLE | Shuttle, transporting container between freighters and tradestations
ST_CONSUMPTION_SHUTTLE | Shuttle, transporting container between tradestations and orbiters
ST_PRODUCTION_SHUTTLE | Shuttle, transporting container between orbiters and tradestations
ST_POLICE | Police
ST_PIRATESHIP | Pirates!
ST_WINGMAN | Wingman
ST_CRUISER | great and small Cruiser
ST_SKAADRONE | Skaadrone
ST_MILITARYFIGHTER | Military fighter
ST_CARGODRONE | Cargodrone
ST_WEAPONBASE | Weaponbase
ST_PIRATEFREIGHTER | pirate freighter
ST_SKAASWARM | center of a skaaformation ST_SKAADRONE
ST_CANYONSHIP | Ship in the Canyonmission (flying on a hardcoded Spline)
ST_COMMSAT | Satellite
ST_TRADERDRONE | Cargodrone of a freighter
ST_COLLECTOR_SHUTTLE | Cargoshuttle
ST_SHIELDGEN | Missionobject from the canyon mission

Volk

All Races
Value | Comment
RACE_HUMAN | Human
RACE_MORLOK | Mortok
RACE_RAPTOR | Raptor
RACE_OCTO | Oc'to
RACE_WASP | Arrak
RACE_THUL | Thul
RACE_SKAA | S'kaa

Wing types

Value | Comment
WINGTYPE_HUNTER | Hunterwing
WINGTYPE_FREIGHTER50T | Freighter with 50T freight modules
WINGTYPE_FREIGHTER100T | Freighter with 100T freight modules
WINGTYPE_FREIGHTER200T | Freighter with 200T freight modules
WINGTYPE_POLICE | Police
WINGTYPE_MILITARY | Military
WINGTYPE_CRUISER1 | Cruiser with hangar
WINGTYPE_CRUISER2 | Cruiser without hangar
WINGTYPE_WEAPONBASE | a weapenbase with one cannon
WINGTYPE_PIRATES | Pirates for attacking other targets
WINGTYPE_RAIDERS | Pirates for attacking other targets and stealing cargo
WINGTYPE_PIRATEFREIGHTER | Pirate freighters
WINGTYPE_PIRATEFREIGHTER50T | Pirate freighter with 50T freight modules, all other ships are Hunter
WINGTYPE_PIRATEFREIGHTER100T | Pirate freighter with 100T freight modules, all other ships are Hunter
WINGTYPE_PIRATEFREIGHTER200T | Pirate freighter with 200T freight modules, all other ships are Hunter
WINGTYPE_SKAA | a Skaa-formation.
WINGTYPE_FREIGHTER200CAP | Freighterwing with a capacity of 200t
WINGTYPE_FREIGHTER400CAP | Freighterwing with a capacity of 400t
WINGTYPE_FREIGHTER600CAP | Freighterwing with a capacity of 600t
WINGTYPE_BASESHIP | Piratebase
WINGTYPE_WEAPONBASE2 | Weaponbase with 2 Cannons


AddFilter

AddFilter( { Camera, Filter, Value1, Value2 } ) : {}

Applies special effects to a camera. Effects which shall have an effect in the beginning should be created immediately after creation of the camera.*

Parameter table
Identifier | Datatype | Values | Comment
Camera | unsigned int | CCameraHandle | Camera handle
Filter | unsigned int | TCameraFilter | Effect to apply to the camera
Value1 | float | n/a | Meaning depends on the type of effect
Value2 | float | n/a | Meaning depends on the type of effect

Return table
empty

TCameraFilter-table
Filter | Time of effect | Effect | Parameter 1 | Parameter 2
CAMERA_FILTER_BLACK | Camera start | Image remains black for a specified time. | - | -
CAMERA_FILTER_BLACK_IN | Camera start | Fade in from black | - | -
CAMERA_FILTER_BLACK_OUT | Kameraende | Fade out into black | - | -
CAMERA_FILTER_BLUR | always |  | - | -
CAMERA_FILTER_SHAKE | always | Camera shakes | - | -
CAMERA_FILTER_WHITE_IN | Camera start | Fade in from white | - | -
CAMERA_FILTER_WHITE_OUT | Kameraende | Fade out into white | - | -
CAMERA_FILTER_FLASH | Camera start | Fades into white and then returns to normal values. | Duration of the white out in seconds. | Duration of the fading into normal values, in seconds.
CAMERA_FILTER_FOV | always | Continuously changes the camera angle. | Duration until the maximum change of camera angle is reached. | Factor to use for the camera angle.

Example

-- Create a camera at some position
V.Camera1 = NCamera.CreatePosCam( { Object=V.Ship, Position={2000.0,400.0, 200.0}, Time=4.5 } ).Camera
-- The end shall be a fade out
NCamera.AddFilter( { Camera=V.Camera1, Filter=CAMERA_FILTER_BLACK_OUT } )
-- The camera shall fade in from black
NCamera.AddFilter( { Camera=V.Camera1, Filter=CAMERA_FILTER_BLACK_IN } )}


CreateBoundCam

CreateBoundCam( { TargetObject, BindObject, Distance, Time, Immediate } ) : { Camera }

Creates a camera which is bound to "BindObject" and is directed at "TargetObject"*

Parameter table
Identifier | Data type | Values | Comment
TargetObject | unsigned int | CObjectHandle or CWingHandle | CWing or CSpaceObject to look at
BindObject | unsigned int | CObjectHandle | the CSpaceObject which defines the view on "TargetObject"
Distance | float | n/a | Camera distance between BindObject and TargetObject. If distance is negative then the BindObject can be seen
Time | float | 0.0f < Time | Duration of camera in seconds
Immediate | bool | default=false | Switch to camera immediately(true), or put into queue(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- Creates a camera with a view at a hunter ship, looking from the player ship. Lifespan ist 8.5 seconds.
-- The camera is 50m away from the hunter and will be created immediately.
V.Camera = NCamera.CreateBoundCam( { TargetObject=V.Hunter, Time=8.5 } ).Camera


CreateDeath

CreateDeath( { Object, Time } ) : { Camera }

Creates a camera which shows an object and keeps doing so after its destruction. The duration can be supplied in "Time". The camera will always be started immediately.*

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | CSpaceObject to show
Time | float | 0.0f < Time, default=infinite | Duration of the camera after the death of the object.

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera


CreateDialog

CreateDialog( { Wing, Type, Time, Immediate } ) : { Camera }

Creates a camera on a wing which can be used for dialogues. The camera is destroyed after "Time" seconds and will then trigger a Camera event.*

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of the shown Wing
Type | enum | DIALOG_TYPE_1, DIALOG_TYPE_EIGHT, DIALOG_TYPE_TURN | Type of camera
Time | float | 0.0f < Time, default=2000.0f | Duration of the camera in seconds
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- Create a dialogue camera showing the freighter
V.Camera = NCamera.CreateDialog( { Wing=V.Trader, Type=DIALOG_TYPE_EIGHT, Immediate=true } ).Camera


CreateDialogObj

CreateDialogObj( { Object, Type, Time, Immediate } ) : { Camera }

Creates a predefined camera for a CSpaceObject in space. The camera is destroyed after "Time" seconds and will then trigger a Camera event.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of the shown CSpaceObjects
Type | enum | DIALOG_TYPE_1, DIALOG_TYPE_EIGHT, DIALOG_TYPE_TURN | Type of camera
Time | float | 0.0f < Time, default=2000.0f | Duration of the camera in seconds
Immediate | bool | default=false | Show immediately(true), or queue the camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle from the created camera

Example

-- Create a dialogue camera showing the freighter
V.Camera1 = NCamera.CreateDialogObj( { Object=V.Ship, Type=DIALOG_TYPE_EIGHT, Immediate=true } ).Camera
-- Create a dialogue camera showing a container (Regardless of what you want to talk about with a container).
V.Camera2 = NCamera.CreateDialogObj( { Object=V.Container, Type=DIALOG_TYPE_1 } ).Camera


CreateFreeCam

CreateFreeCam( { TabTargetPosition, TabCamPosition, Time, BaseObj, Immediate } ) : { Camera }

Creates a camera which moves along specified cam positions and which is directed at specified target positions. If "BaseObj" is specified then all coordinates are relative to that object and the camera will move with this object.

Parameter table
Identifier | Data type | Values | Comment
TabTargetPosition | table:table[3]:float | n/a | Table of absolute target positions/td>
TabCamPosition | table:table[3]:float | n/a | Table of absolute camera positions
Time | float | 0.0 < Time | Duration of camera in seconds
BaseObj | unsigned int | CObjectHandle | Object, relative to which the camera is to be positioned
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table

Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of the shown Wing
Type | enum | MENACE_TYPE_1, MENACE_TYPE_2, MENACE_TYPE_3, MENACE_TYPE_4 | Type of camera
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- create a free camera which flies through a series of positions
V.Camera = NCamera.CreateFreeCam( { TabTargetPosition ={ {0.0,0.0,100.0}, {100.0,0.0,100.0}, {100.0,0.0,0.0}, {0.0,0.0,0.0} }, TabCamPosition={ {1000.0,0.0,1000.0}, {0.2000,0.0,1000.0}, {-1000.0,0.0,1000.0} }, Time=10.0, Immediate=true } ).Camera


CreateMenace

CreateMenace( { Wing, Type, Immediate } ) : { Camera }

Creates a "Menace cam" for a specified wing. "Type" chooses one of several predefined cameras with different motion sequences. The camera is destroyed after "Time" seconds and will then trigger a Camera event.*

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of the shown Wing
Type | enum | MENACE_TYPE_1, MENACE_TYPE_2, MENACE_TYPE_3, MENACE_TYPE_4 | Type of camera
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- Create a menace cam showing a pirate wing
V.Camera = NCamera.CreateMenace( { Wing=V.PirateWing, Type=MENACE_TYPE_1, Immediate=true } ).Camera


CreateObject

CreateObject( { Object, TurnSteps, PostSteps, AngleX1, AngleX2, AngleY1, AngleY2, Distance1, Distance2, Immediate } ) : { Camera }

Creates a camera which is directed at an object and moves according to the supplied parameters. The camera can rotate around x- and y-axes and can vary its distance to the object. These motions will happen within "TurnSteps" units of DST (Dark Star Time; 25DST = 1s). After TurnSteps and PostSteps have run out the camera will selfdestruct and trigger a "Camera" event.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | The object to show
TurnSteps | unsigned int | 0 < TurnSteps | Duration of the motion, in timesteps (DST)
PostSteps | unsigned int | n/a | Duration of sustainment after the motion is complete.
AngleX1 | float | n/a | starting angle in degrees relative to the x-axis of the object.
AngleX2 | float | n/a | Target angle in degrees relative to the x-axis of the object.
AngleY1 | float | n/a | starting angle in degrees relative to the y-axis of the object.
AngleY2 | float | n/a | Target angle in degrees relative to the y-axis of the object.
Distance1 | float | 0.0f < Distance1 | Starting distance to the object.
Distance1 | float | 0.0f < Distance2 | Target distance to the object.
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- Creates a camera which shows a ship from up above and which turns to the back of the ship within 5 seconds while gaining distance to the ship.
-- The camera then remains in this position for 1 second before it becomes destroyed.
V.Camera = NCamera.CreateObject( {    Object=V.Ship,    TurnSteps=125,    PostSteps=25,    AngleX1=45.0,    AngleX2=45.0,    AngleY1=180.0,    AngleY2=0.0,    Distance1=50.0,    Distance2=150.0,    Immediate=true  } ).Camera


CreatePosCam

CreatePosCam( { Object, Position, Time, Immediate } ) : { Camera }

Creates a predefined camera for a Wing or CSpaceObject in space. The camera is positioned at a specified location and is directed at the object. The camera is destroyed after "Time" seconds and will then trigger a Camera event.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CWingHandle oder CObjectHandle | Handle of the shown CWing or CSpaceObject
Position | table[3]:float | n/a | Absolute position of the camera
Time | float | 0.0f < Time | Duration of the camera in seconds
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- Create a pos cam lasting 4.5 seconds, showing a freighter
V.Camera1 = NCamera.CreatePosCam( { Object=V.Ship, Position={2000.0,400.0, 200.0}, Time=4.5 } ).Camera
-- A second pos cam of 6 seconds duration is put in queue
V.Camera2 = NCamera.CreatePosCam( { Object=V.Ship, Position={2000.0,-400.0, 300.0}, Time=6.0, Immediate=false } ).Camera


CreateSplineCam

CreateSplineCam( { Name, Cam, Aim, CamOffset, AimOffset, Zoom, Time, Immediate } ) : { Camera }

Create a predefined camera which was previously exported from the program "Maya". The file contains a camera spline (curve).*

Parameter table
Identifier | Data type | Values | Comment
Name | string | Dateiname | Name of the Maya file
Cam | unsigned int | CObjectHandle | Handle of the object to which the camera spline will be bound.
Aim | unsigned int | CObjectHandle | Handle of the object the camera will be directed at.
CamOffset | table[3]:float | n/a | Offset to use for the camera position. {0,0,0} is the object's position.
AimOffset | table[3]:float | n/a | Offset to use for the target position. This is relative to the object.
Zoom | float | n/a | Scaling factor of the camera spline.
Time | float | 0.0 < Time | Duration of the camera in seconds.
Immediate | bool | default=false | Show immediately(true), or queue camera(false)

Return table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the created camera

Example

-- Create a spline camera by loading an external file.
V.Camera = NCamera.CreateSplineCam( { Name="filename", Time=10.0, Immediate=true } ).Camera


Destroy

Destroy( { Camera } ) : {}

Destroy a camera and thereby trigger a "Camera" event.*

Parameter table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the camera that is to be destroyed

Return table
leer

Example

-- create a camera
V.Cam = CreatePosCam( { Object, Position, Time, "Immediate" }
-- destroy the camera when a communication has finished.
1.001, 1.001, "CommEnd", function( V, Data )
    NCamera.Destroy( { Camera=V.Cam } )
    V.Cam = nil
    V.Step = 1.002
end


End

End( { Camera } ) : {}

Finishes a camera but plays all applied effects like whiteout, blackout etc. The camera will be destroyed thereafter and trigger a "Camera" event.*

Parameter table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the camera which is to be destroyed

Return table
empty


GetWingRelPos

GetWingRelPos( { Wing, Angle } ) : { Position }

Calculates a position in space from which the complete wing can be seen.*

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of the wing
Angle | float | -180.0..180.0 | Angle in the x-z plane in degrees

Return table
Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | Absolute camera position

Example

-- Calculate a position
V.Position=NCamera.GetWingRelPos( { Wing=V.Wing, Angle=90.0 } ).Position
-- Create a camera which shows the wing
V.Camera=NCamera.CreatePosCam( { Object=V.Wing, Position=V.Position, Time=10.0 }.Camera


ChangeToCanyon

ChangeToCanyon( { Canyon, Segment } ) : {}

Puts the player ship into a canyon/tunnel and places it into segment "Segment". No effect if the player is already inside a canyon.

Parameter table
Identifier | Data type | Values | Comment
Canyon | unsigned int | 0 | number id of the canyon model, 0 == Kabro's tunnel, 1 == Skaa tunnel
Segment | unsigned int | n/a | number id of the segment. The number of valid id's is dependent on the 3d model.

Return table
empty

Example

-- Put the player ship into the starting segment of Kabro's tunnel
NCanyon.ChangeToCanyon( { Canyon=0, Segment=0 } )


ChangeToSpace( {} ) : {}

Switch back to space from a canyon. No effect if the player already is in space.

Parameter table
empty

Return table
empty

Example

-- The player is in a canyon.
-- Teturn the player to space
NCanyon.ChangeToSpace( {} )


ChangeToWeaponFactory( {} ) : {}

Places the player ship at the start of the "Bronis weapon factory" level. has no effect if the player is in a canyon/tunnel or already inside the weapons factory.

Parameter table
empty

Return table
empty

Example

-- Place the player in the start of the weapons factory.
NCanyon.ChangeToWeaponFactory( {} )


CreateForceField

CreateForceField( { Type, Locator, Notify } ) : { Handle }

Creates a force field into a canyon/tunnel or the weapons factory. The force field may only be created if the respective model offers spawn positions ("Locator") for these. If "Notify" is set to true then the field may be passed but will trigger a "CANYON_TRIGGER" event containing this field's handle. Remark: Nothing will prevent creation of two or more force fields at the same position. Behaviour in this case is undefined though.

Parameter table
Identifier | Data type | Values | Comment
Type | unsigned int | n/a | Type of force field
Locator | unsigned int | n/a | Index of the locator (Increasing numbers starting with 0).
Notify | bool | default = false | The player can collide with the field (false) or passing the field triggers an event (true).

Return table
Identifier | Data type | Values | Comment
Handle | unsigned int | CStartShiphandle | Handle of the created force field.

Example


CreateGenerator

CreateGenerator( { Type, Locator } ) : { Handle }

Creates a shield generator in a canyon or the weapons factory. The generator counts as a StarShip. Destruction can be detected by observing the "StarshipDestroyed" event. The generator can only be created if the 3d model offers spawn points ("Locator"). Remark: Nothing will prevent creation of two or more generators at the same position. Behaviour in this case is undefined though.

Parameter table
Identifier | Data type | Values | Comment
Type | unsigned int | Generator type index | Type of generator (see below)
Locator | unsigned int | n/a | Index of the locator (Increasing numbers starting with 0).

Return table
Identifier | Data type | Values | Comment
Handle | unsigned int | CStarShiphandle | Handle of the generator

Generator types
Name | Comment
GENERATOR_KABRO | The generator model of the first canyon mission
GENERATOR_SKAA | A generator in the Skaa tunnel
GENERATOR_SKAA_CORE | The main reactor of the Skaa mothership.
GENERATOR_BRONIS_0 | A blue generator of the bronis weapons factory
GENERATOR_BRONIS_1 | A red generator of the bronis weapons factory
GENERATOR_BRONIS_2 | A red generator of the bronis weapons factory


CreateShip

CreateShip( { Type, Look, Race, Level, Segment, StartSpline, EndSpline } ) : { Ship }

Creates a canyon ship using the supplied parameters. "StartSpline" and "EndSpline" will not always be used but are mandatory to be supplied (see table below). The ships normally do not have any velocity except for the type "CST_ENTER".

Parameter table
Identifier | Data type | Values | Comment
Type | enum | CST_ON_SPLINE, CST_ON_SPLINE_REVERSE, CST_ENTER, CST_ENTER_REVERSE, CST_HOVER, CST_HOVER_REVERSE, CST_LANDING | Motion sequence of the ship (see table below)
Look | enum | SPACE_TRANSPORTER, SPACE_PIRATE, SPACE_POLICE, SPACE_MILITARY, SPACE_HUNTER, SPACE_SKAADRONE, SPACE_PIRATE_FREIGHTER | Model type
Race | enum | Race | Race of the ship
Level | unsigned int | n/a | Level of the ship
Segment | unsigned int | (depends on the canyon model) | Number of the segment to place the ship in.
StartSpline | enum | SPLINE_PLAYER, SPLINE_AI_0, SPLINE_AI_1, SPLINE_AI_2, SPLINE_AI_3, SPLINE_OVERTURN, SPLINE_ENTER | Spline to create the ship on.
EndSpline | enum | SPLINE_PLAYER, SPLINE_AI_0, SPLINE_AI_1, SPLINE_AI_2, SPLINE_AI_3, SPLINE_OVERTURN, SPLINE_ENTER | Spline the ship will switch to (Certain "Type" values, see table).

Return table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the created ship

Type table for the 'Type' parameter
Type | StartSpline | EndSpline | Description
CST_ON_SPLINE | yes | no | Ship will be placed onto the first position of the spline within this segment and then follow the spline.
CST_ON_SPLINE_REVERSE | yes | no | Ship will be placed onto the last spline position of this segment, flying in reverse direction.
CST_ENTER | no | yes | Ship will be placed onto the "SPLINE_ENTER" spline of the segment and follow this until end. It then switches to "EndSpline" and follows that spline.
CST_ENTER_REVERSE | no | yes | Ship will be placed onto the "SPLINE_ENTER" spline of the segment and will follow this until end. It then switches to "EndSpline" and follows that spline in reverse direction. Will only work if "SPLINE_ENTER" was also designed for an opposite direction.
CST_HOVER | yes | yes | Ship will be placed onto the first position of the "StartSpline" spline and hover there. Calling a SetShipLiftOff() command for this ship will make it lift off and follow the spline "EndSpline".
CST_HOVER_REVERSE | yes | yes | Ship will be placed onto the first position of the "StartSpline" spline and hover there. Calling a SetShipLiftOff() command for this ship will make it lift off and follow the spline "EndSpline" in opposite direction.
CST_LANDING | yes | yes | Ship will be placed onto the first position of the "StartSpline" spline and follow this until its end. It will then approach the first position of "EndSpline". The alignment is controlled by the first two points of "EndSpline".

Example

-- Create a Mortok pirate which dives down into the canyon.
V.Ship = NCanyon.CreateCanyonShip(
{
    Type = CST_ENTER,
    Look = SPACE_HUNTER,
    Race = RACE_MORTHOK,
    Level = V.AILevel,
    Segment = V.EntrySegment,
    StartSpline = SPLINE_ENTER,
    EndSpline = SPLINE_AI_0 + Splinechoice )
}.Ship


DestroyForceField

DestroyForceField( { Handle } ) : {}

Destroys the specified force field.

Parameter table
Identifier | Data type | Values | Comment
Handle | unsigned int | CStartShiphandle | Handle of the force field

Return table
empty


SetMaxY

SetMaxY( { Value } ) : {}

Sets the maximum y-value above canyon niveau where height control will prevent further increase in height of the player.

Parameter table
Identifier | Data type | Values | Comment
Value | float | 0.0 < Value | Height value

Return table
empty


SetMinY

SetMinY( { Value } ) : {}

Sets a minimum y-value above canyon niveau below which the height controls starts to limit further decrease in height. Should be approximately 50m below the maximum value.

Parameter table
Identifier | Data type | Values | Comment
Value | float | 0.0 < Value | Height value

Return table
empty


SetShipHostile

SetShipHostile( { Ship, Hostile } ) : {}

Sets the hostility status of a ship inside the canyon.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship. Needs to be a canyon ship.
Hostile | bool | n/a | Ship is hostile (true) or friendly (false)

Return table
empty


SetShipLiftOff

SetShipLiftOff( { Ship, Spline } ) : {}

A ship is forced to lift off and follow a spline. Will only have an effect on ships created with CST_HOVER or CST_HOVER_REVERSE, otherwise it will be ignored.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship. Needs to be a canyon ship.
Spline | enum | SPLINE_PLAYER, SPLINE_AI_0, SPLINE_AI_1, SPLINE_AI_2, SPLINE_AI_3, SPLINE_OVERTURN, SPLINE_ENTER | Spline to switch into.

Return table
empty


SetShipSpeed

SetShipSpeed( { Ship, Speed, Value } ) : {}

Sets the velocity of a canyon ship. If "Ship" does not reference a ship of type "STARSHIP_TYPE_CANYONSHIP" then the function will fail with an error message.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship. Needs to be a canyon ship.
Speed | enum | SPEED_DYNAMIC, SPEED_FIXED | Type of speed behaviour (see table below).
Value | float | 0.0f <= Value, default=1.0f | Speed used for "SPEED_FIXED"

Return table
empty

Type table for the "Speed" parameter
Value | Description
SPEED_DYNAMIC | The ship adjusts to the speed of the player ship and tries to stay in its vicinity. If the ship is behind the player ship it will always try to outrun and get in front of him. The speed will always be at least a minimal speed, so the ships never stop completely.
SPEED_FIXED | The ship is assigned a speed value "Value", which it tries to keep.

Example


SetTurn

SetTurn( { Turn } ) : {}

The player is usually not allowed to turn around during a canyon mission. In zones for free flight, this can be disabled.

Parameter table
Identifier | Data type | Values | Comment
Turn | bool | n/a | Player ship may turn(true) or it may not(false).

Return table
Identifier | Data type | Values | Comment


ToggleSplineMode( {} ) : {}

Toggles the controls of the ship between free flight mode and spline mode. The spline mode can be used for game controlled sequences with action cams.

Parameter table
empty

Return table
empty


AddMessage

AddMessage( { Text, Voice, Video, Sender, CommInOut, Actor } ) : { Message }

Sends a high-priority radio message which automatically aborts all currently active messages of the simulation. If multiple messages are sent using this function, they will be played sequentially. If a radio message ends, a "CommEnd" event will be triggered. If the "Video" parameter is used instead of "Sender" then a video is chosen that fits the ships type and race. If the "Actor" parameter is used and if this is an NPC Actor (Ramirez, Eona, Nicolai etc.), then that actor will be used. This actor will have priority over the normal actor of the sender, even if "Sender" is supplied. This makes it possible to have a trade station use "Jiju" as its actor without having to call a SetActor() for the station.

Parameter table
Identifier | Data type | Values | Comment
Text | string | StringId from the String database. | Text to display with this message.
Voice | string | Prefix of an identifier of a stream resource from the "KlangErzeugerDefault.xml" (KlangErzeuger = SoundCreator) or an absolute identifier for a stream resource from that file. | Stream to play. If a sender is supplied then "Voice" is the prefix of an identifier from a stream resource from the "KlangErzeugerDefault.xml". The identifier will be extended by the suffix "_<RACE>_<ACTOR>". Race and actor will be extracted from the sender of the message. If no sender is supplied then "Voice" is the absolute identifier of a stream resource from the "KlangErzeugerDefault.xml".
Video | string | Path to a .bik video file (complete path + ".bik"). | The video to play along with the message. If none is specified, the video will be chosen based on the sender of the message. If no sender is specified then an empty video (green screen with static noise) will be played.
Sender | unsigned int | CObjectHandle | Sender of the radio message. Used to select video and sound file.
CommInOut | bool | default=false | CommIn and CommOut video snippets (a green opening or closing screen) are played(true) or left away(false)
Actor | string | Name of an actor | Actor, to use for this radio message. Needs to be an NPC and not a standard actor.

Return table
Identifier | Data type | Values | Comment
Message | unsigned int | n/a | Id of the message (Needs to be stored to handle a later "CommEnd" event).

Example

-- Send a radio message
-- If the supplied ship is a human hunter with actor 0 then the video will be "HUNTER_HUMAN_00.bik"
-- and the sound file will be "IDM_GLOBAL_5000_MSG_TXT_SPOKEN_HUMAN_00.mp3".
V.MsgId = NComm.AddMessage(
{
    Text="IDM_GLOBAL_5000_MSG_TXT",
    Voice="IDM_GLOBAL_5000_MSG_TXT_SPOKEN",
    Sender=V.Ship,
    CommInOut=true
} ).MessageId

-- Kayron is to say something
NShip.SetActor( { Ship = MissionLib.GetPlayerHandle(), Actor = "kayron" } )
NComm.SendMessage(
{ Sender =
    MissionLib.GetPlayerHandle(),
    Text = "IDM_DONT_TALK_AROUND",
    CommInOut = false
} )

-- Eona says something but the actor of the player ship will not be changed
NComm.SendMessage(
{
    Sender = MissionLib.GetPlayerHandle(),
    Text = "IDM_EONA_WOBBLEDY",
    Actor = "eona",
    CommInOut = false
} )

-- Ramirez says something although he is not present in space.
NComm.SendMessage(
{
    Text = "IDM_GHOST",
    Actor = "ramirez",
    CommInOut = true
} )


IsQueueEmpty

IsQueueEmpty( {} ) : { Empty }

Checks if the message queue is empty.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Empty | bool | n/a | No messages present (true) or messages are present (false)

Example


Create

Create( { Type, Size, Ship|PosDesc|Position } ) : { Container }

Erzeugt einen Container des angegebenen Typs ( siehe Typtabelle ). Depending on the type one of the parameters "Ship", "PosDesc" or "Position" is necessary. If the ship is the player ship and it has docked at the station then a mission container can be created using "CONTAINER_SHIP". This slot will be taken by the container.

Parameter table

Identifier | Data type | Values | Comment
Type | enum | CONTAINER_SPACE, CONTAINER_SHIP, CONTAINER_POSITION | Type of container creation.
Size | enum | CONTAINER_SMALL, CONTAINER_MEDIUM, CONTAINER_LARGE, CONTAINER_ARTIFACT, CONTAINER_SPECIAL | Size or type of the container.
Ship | unsigned int | CStarShipHandle | Ship to attach the container to. Must be able to carry this size of container.
PosDesc | enum | Example | Position
Position | table[3]:float | n/a | Absolute space coordinates

Return table

Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the created container.

Type table for the "Type" Parameter

Type | Necessary parameter | Description
CONTAINER_SPACE | PosDesc | Container will be created in the supplied creation region.
CONTAINER_SHIP | Ship | Container will be created and docked. Ship must be a freighter.
CONTAINER_POSITION | Position | Container is created at an arbitrary position in space (or close to it).

Example

-- Create a container on a freighter
V.Container = NContainer.Create( { Type=CONTAINER_SHIP, Ship=V.Trader } ).Container

-- Create a container behind the trade station
V.ContainerSpace = NContainer.Create( { Type=CONTAINER_SPACE, PosDesc=POSDESCR_OFFSET } ).Container

-- Create a container in 1000m distance above the trade station.
V.ContainerPos = NContainer.Create( { Type=CONTAINER_POSITION, Position={0,1000,0} } ).Container


CreateLoot

CreateLoot( { Ship, UniqueItems, Artefact } ) : { Container }

Creates a loot (previously artifact) container with the specified contents. If neither UniqueItems nor Artefact is supplied then an artifact will be put into the container. The loot container can only be created for a ship which is currently exploding, that means during handling of its "StarshipDestroyed" event. The container will be placed at the position of the ship and will initially move along the last velocity vector of the ship. At the same time it slightly rotates.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship which is currently exploding.
UniqueItems | unsigned int | 1-100 | Number of secret service weapons contained in the container.
Artefact | unsigned int | 1 | If >0 then an artifact will be put into the container.

Return table
empty

Example

{   -- Create loot container with 2 secred service weapons
    1.0, 1.0, "StarshipDestroyed", function( V, Data )
    if Data.Ship == V.BossShip then
        NContainer.CreateLoot( { Ship=V.BossShip, UniqueItems=2 } )
    end
end },


Destroy

Destroy( { Container } ) : {}

Destroys the specified container. The container disappears and does NOT trigger a "CONTAINER_DESTROYED" event.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container

Return table
empty

Example

{   -- Player reaches the station in the destination system: destroy the stored mission container
    2.001, 2.001, "EnterStation",
    function( V, Data )
        if V.DestSystem == Data.System then
            if V.Cont then
                NContainer.Destroy( { Container=V.Cont } )
                V.Cont = nil
            end
        end
    end
}


Equip

Equip( { Container, Goods, Amount } ) : {}

Fills an existing container with the supplied goods. If "Amount" is not specified then the container will be filled to its full capacity. If "Amount" exceeds the remaining capacity then the excess will be ignored. For mission goods (containers filled with a StringId) the "Amount" parameter has no effect.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container.
Goods | enum oder string | trade good or StringId from the string database. | Trade good or mission good
Amount | unsigned int | n/a | Amount of the trade good

Return table
empty

Example

-- Completely fill a container with machinery.
NContainer.Equip( { Container=V.Conti, Goods=GOODS_MACHINERY } )

-- Fill a container with a mission good
NContainer.Equip( { Container=V.Conti, Goods="IDM_GLOBAL_5000_GOODS" } )

-- Fill a container with different trade goods
NContainer.Equip( { Container=V.Conti, Goods=GOODS_MACHINERY, Amount=20 } )
NContainer.Equip( { Container=V.Conti, Goods=GOODS_CRYSTALS, Amount=50 } )
NContainer.Equip( { Container=V.Conti, Goods=GOODS_PROTEINS, Amount=30 } )


Explode

Explode( { Container } ) : {}

Makes the container explode and be destroyed. A "CONTAINER_DESTROYED" event will be triggered.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container

Return table
empty


GetAlignment

GetAlignment( { Container } ) : { Position, Front, UpDir }

Returns the alignment in space of a container.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of a container.

Return table
Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | Absolute coordinates of the containers
Front | table[3]:float | n/a | Vector of the container axis' direction
UpDir | table[3]:float | n/a | y-axis (parallel to the axis going through the container connectors)

Example

-- Create an artifact container
V.Cont = NContainer.Create( { Type=CONTAINER_SPACE, Size=CONTAINER_ARTIFACT, PosDesc=POSDESCR_INTERCEPTION } ).Container

-- Retrieve the alignment of the container
V.Position = NContainer.GetAlignment( { Container=V.Cont } ).Position


GetMissionGood

GetMissionGood( { Container } ) : { SpecialGood, SpecialName }

Returns data about which mission goods are in the container.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the checked container.

Return table

Identifier | Data type | Values | Comment
SpecialGood | bool | n/a | Is set to true if a mission good is contained
SpecialName | String | n/a | The StringId of the mission good if there is one.

Example

  -- Retrieve info about eventual mission goods
  Good = NContainer.GetMissionGood( { Container=V.Container } )
  if Good.SpecialGood then
    -- do something
  end


GetType

GetType( { Container } ) : { Type }

Returns the type of container. If the container does not exist, a -1 will be returned as the type.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container to check.

Return table
Identifier | Data type | Values | Comment
Type | int | Container type | Type of the container

Example

  -- We need to find out if the container is an artifact container
  cont = NContainer.GetType( { Container=V.Container } )
  if ( cont.Type == CONTAINER_ARTIFACT ) then
    -- Proceed with other logic
  end


SetAlignment

SetAlignment( { Container, Position, Front, UpDir } ) : {}

Sets the alignment of a container and places it on a specified location. The front of it points at position "Front". If "UpDir" is not specified then the container will be aligned to the y-axis of the system. The position needs to be unoccupied in order for the logic to not detect a collision within the next timestep.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container
Position | table[3]:float | n/a | Absolute coordinates (default value is the current position)
Front | table[3]:float | n/a | Direction vector the container axis points at(default is the current direction)
UpDir | table[3]:float | n/a | Direction vector the upside of the container faces.

Return table
empty

Example

-- Create an artifact container
V.Cont = NContainer.Create( { Type=CONTAINER_SPACE, Size=CONTAINER_ARTIFACT, PosDesc=POSDESCR_INTERCEPTION } ).Container

-- Place the container on a certain position
NContainer.SetAlignment( { Container=V.Cont, Position={0.0,3000.0,0.0}, Front={0.0,-3000.0,10000.0} } )

-- Orientate the container in such a way that it is lieing on the x-z plane.
NContainer.SetAlignment( { Container=V.Cont } )


SetArtefact

SetArtefact( { Container } ) : {}

Only works with containers created with the type ARTEFACT. The artifact flag is set so the player will receive an artifact point as soon as he picks up the container.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container

Return table
empty

Example

-- Create an artifact container
V.Cont = NContainer.Create( { Type=CONTAINER_SPACE, Size=CONTAINER_ARTIFACT, PosDesc=POSDESCR_INTERCEPTION } ).ContainerV.Conti
NContainer.SetArtefact( { Container=V.Cont } )


SetIllegal

SetIllegal( { Container, Illegal } ) : {}

Marks or unmarks a container as illegal, so the police which the police may notice during a scan of the freight.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container.
Illegal | bool | n/a | Container contains illegal goods(true) or it does not(false)

Return table
empty

Example

-- Create a container with "hot stuff"
V.Cont = NContainer.Create( { Type=CONTAINER_SPACE, PosDesc=POSDESCR_INTERCEPTION } ).Container
NContainer.Equip( { Container=V.Cont, Goods="IDM_GLOBAL_5000_GOODS" } )
NContainer.SetIllegal( { Container=V.Cont, Illegal=true } )


SetUniqueItems

SetUniqueItems( { Container, Number } ) : {}

Only works with containers created with the type ARTEFACT. The number of contained unique items is set. The unique items will be transferred to the storage of the player ship as soon as the player picks up the container. Currently only secret service weapons are created. "Number"=0 will delete all unique items.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container
Number | int | 0..100 | Number of unique items in the container.

Return table
empty

Example

-- Create an artifact container
V.Cont = NContainer.Create(
{
    Type=CONTAINER_SPACE,
    Size=CONTAINER_ARTIFACT,
    PosDesc=POSDESCR_INTERCEPTION
} ).ContainerV.Conti
NContainer.SetUniqueItems( { Container=V.Cont, Number=2 } )


Message

Message( { Message } ) : {}

Outputs a message in the script-channel. After the message the calling script is shown. This function does not work in release mode.

Parametertable
Identifier | Data type | Values | Comment
Message | string | n/a | Enter your message

Rückgabetabelle
leer

Beispiel

 -- Debug message output
 NDebug.Message( { Message="Enter text here" } )


GameOver( {} ) : {}

An important mission failed, so the game ends. Popup with "Mainmenu" and "Load game" will follow.

Parameter table
empty

Return table
empty

Example

{   -- Mission fehlgeschlagen, Spiel vorbei
    1.0, nil, "Failed", function( V, Data )
    MissionLib.UnregisterMission( "IDM_BAR_007" )
    NGame.GameOver( {} )
    return { Timeout=0 }
    end
},


GetTime

GetTime( {} ) : { Time }

Returns the real time since the start of the game in seconds.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Time | float | n/a | Real time since game start.

Example


Pause

Pause( { Pause } ) : {}

Pauses or startes the game

Parameter table
Identifier | Data type | Values | Comment
Pause | bool | n/a | pause game (true) or run (false)

Return table
empty

Example


Save

Save( { Name | ( Chapter, Subchapter ) } ) : {}

Saves a game with the given name. Filepath and Filename extension are added by the program. An already existing file will be overwritten. If the parameter "Chapter" is used a name from the mission and chapternumber is contructed. If you want to use an other name, it must be defined using the NMission.SetName() function. Together with the parameter "Chapter" the parameter "Subcahpter" can be used.
This function creates an infomessage: "Game saved"

Parameter table
Identifier | Data type | Values | Comment
Name | string | StringId from the LokaTool | Name of savegame
Chapter | unsigned int | n/a | number of chapter

Return table
empty

Example

 -- Save game
 NGame.Save( { Name="Test" } )


AddWings

AddWings( { Group, WingList } ) : {}

All wings in WingList will be attatched to the AI-Group specified.

Parameter table
Identifier | Data type | Values | Comment
Group | unsigned int | CEventHandle | Handle of AI-Group
WingList | table[n]:[<unsigned int>] | List of CWingHandle | Handles of Wings, which are part of that group

Return table
empty

Example

--Create groups
local groups=NGroupAi.Create()
--Enter wings in the first
NGroupAi.AddWings( {Group=groups.GroupA, WingList={wing1, wing2} } )
--Enter wings in to the second group
NGroupAi.AddWings( {Group=groups.GroupB, WingList={wing3, wing4, wing5} } )


Create

Create( {} ) : { GroupA, GroupB }

Creates two enemy AI-groups and returns the handles. The groupes exists until a Destroy-command arrives.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
GroupA | unsigned int | CEventHandle | Handle of first AI-group
GroupB | unsigned int | CEventHandle | Handle of second AI-grup

Example

--Create groups
local groups=NGroupAi.Create()

--First group
NGroupAi.AddWings( {Group=groups.GroupA, WingList={wing1, wing2} } )

--Second Groups
NGroupAi.AddWings( {Group=groups.GroupB, WingList={wing3, wing4, wing5} } )


Destroy

Destroy( { Group } ) : {}

Marks this group to be deleted in the next logicstep.

Parameter table
Identifier | Data type | Values | Comment
Group | unsigned int | CEventHandle | Handle of the AI-Group to be deleted

Return table
empty

Example

--Create group
local groups=NGroupAi.Create()

--first group to delete
NGroupAi.Destroy( {Group=groups.GroupA} } )

--second group will be deletet automaticly


RemoveHostilePlayer

RemoveHostilePlayer( { Group } ) : {}

The players opponent-state will be deleted from that AI-group

Parameter table
Identifier | Data type | Values | Comment
Group | unsigned int | CEventHandle | Handle of AI_group


SetPlayerHostile

SetPlayerHostile( { Group } ) : {}

The player will be seen as Enemy from that AI-group. All wings in that AI-group will be hostile to the player.

Parameter table
Identifier | Data type | Values | Comment
Group | unsigned int | CEventHandle | Handle of a AI-group


SubWings

SubWings( { Group, WingList } ) : {}

All wings in WingList will be removed from the given AI-group. The AI_group will be persistent even if there are no wings in it.
Identifier | Data type | Values | Comment
Group | unsigned int | CEventHandle | Handle of AI-group
WingList | table[n]:[<unsigned int>] | List of CWingHandle | Handles of wings, which should be removed from that AI-group.

Return table
empty

Example

--create group
local groups=NGroupAi.Create()
--first group
NGroupAi.AddWings( {Group=groups.GroupA, WingList={wing1, wing2, wing3} } )
--remove them
NGroupAi.SubWings( {Group=groups.GroupA, WingList={wing1, wing2} } )


Blink

Blink( { Button } ) : {}

A button starts blinking util the user use the button

Parameter table
Identifier | Data type | Values | Comment
Button | enum | GUI_BTN_COMMUNICATION, GUI_BTN_PLASMA, GUI_BTN_ROCKET, GUI_BTN_TARGETMAP, GUI_BTN_LOGBOOK, GUI_BTN_LOGBOOK_UPGRADE, GUI_BTN_NAVMAP, GUI_BTN_MENU, GUI_BTN_HYPERJUMP, GUI_BTN_CONTAINER_GET, GUI_BTN_TIME, GUI_BTN_UPGRADE, GUI_BTN_CONTAINER_DROP | Button name

Example


ClearSubtitle( {} ) : {}

Removes a shown subtitle

Parameter table
empty

Return table
empty

Example

-- Clears the subtitle
NGUI.ClearSubtitle( {} )


Disable

Disable( { Feature } ) : {}

Deactivates a GUI Feature (e.g. Shortcut, Button etc. )

Parameter table
Identifier | Data type | Values | Comment
Feature | enum | GUI_HYPERJUMP, GUI_NAVMAP, GUI_TARGETVIEW | Feature

Return table
empty

Example

--deactivate the Navmap
NGUI.Disable( { Feature=GUI_NAVMAP } )


Enable

Enable( { Feature } ) : {}

Activates a GUI Feature (e.g. Shortcut, Button etc. )

Parameter table
Identifier | Data type | Values | Comment
Feature | enum | GUI_HYPERJUMP, GUI_NAVMAP, GUI_TARGETVIEW | Feature

Return table
empty

Example

--enable Navmap
NGUI.Enable( { Feature=GUI_NAVMAP } )


ShowInfoText

ShowInfoText( { Text, Replace } ) : {}

Shows an info message in the upper part of the screen (duration ca. 3 sec.) The parameter "Replace" can hold a list of StringIds, which can replace empty spaces in the Text. The spaces will be filled with the strings in "Replace" (in that order) so that "Replace[1]" replaces "%1" in "Text".

Parameter table
Identifier | Data type | Values | Comment
Text | string | n/a | StringId from user_strings.res
Replace | table[n]:string | n/a | List withg StringIds from LokaTool

Return table
empty

Example

-- simple message
NGUI.ShowInfoText( { Text="IDM_GLOBAL_5000_INFO_0" } )

-- message with replacements
NGUI.ShowInfoText( { Text="IDM_GLOBAL_5000_INFO_1", Replace={ "IDM_SYSTEMNAME_00", "IDM_NPCNAME_05" } } )


ShowMovie

ShowMovie( { Video } ) : {}

shows a fullscreen video and pauses the simulation until the video is done. If the video ends a "Movie"-event is fired.

Parameter table
Identifier | Data type | Values | Comment
Video | string | n/a | Name of the vide. Path and file name extension are added by the program itself ( e.g. "cutscene0" --> "videos/movies/cutscene0.bik"

Return table
empty

Example

 -- play video
 NGUI.ShowMovie( { Video="cutscene0" } )


ShowSubtitle

ShowSubtitle( { Text} ) : {}

Shows a subtitle in the lower part of the screen until ClearSubtitle() was called. If you call ShowSubtitle again, the text is added to the text already displayed. A dialog- or radio-message deletes any subtitle at once.

Parameter table
Identifier | Data type | Values | Comment
Text | string | n/a | StringId from user_strings.res

Return table
empty

Example

-- simple subtitle
NGUI.ShowSubtitle( { Text="IDM_GLOBAL_5000_SUB_00" } )

-- add text
NGUI.ShowSubtitle( { Text="IDM_GLOBAL_5000_SUB_01" } )


Create

Create( { Script, Run } ) : { Success }

Creates a mission using the given script

Parameter table
Identifier | Data type | Values | Comment
Script | string | n/a | Name of script
Run | bool | default=false | Mission runs at once

Return table
Identifier | Data type | Values | Comment
Success | bool | n/a | Mission created successfully

Example

-- Mission start
NMission.Create( { Script="GLOBAL_5000", Run=true } )


CreateTimer

CreateTimer( { Time } ) : { Timer }

Creates a "Timer"-event after n sec. simulation time.

Parameter table
Identifier | Data type | Values | Comment
Time | float | Time > 0.0f | Time in seconds.

Return table
Identifier | Data type | Values | Comment
Timer | unsigned int | CEventHandle | Handle of created 'Timer'-event

Example

-- Creates a timer-event in 5 sec.
V.Timer = NMission.CreateTimer( { Time=5 } ).Timer


GetState

GetState( { Mission } ) : { State }

Returns the state of a mission (V.STATE)

Parameter table
Identifier | Data type | Values | Comment
Mission | unsigned int | CMissionHandle | Handle of a mission

Return table
Identifier | Data type | Values | Comment
State | enum | MSTATE_ACHIEVED, MSTATE_ENDED, MSTATE_FAILED, MSTATE_OFFERING, MSTATE_RUNNING | state of the mission

Example

-- get the state
if MSTATE_OFFERING == NMission.GetState( {} ).State then
  DoSomething()
end

-- get a state from another mission
local _state = NMission.GetState( { Mission=V.OtherMission } )
if MSTATE_RUNNING == _state.State then
  DoSometing2()
end


SetName

SetName( { Name } ) : {}

Sets a name for a mission, used for creating savegames.

Parameter table
Identifier | Data type | Values | Comment
Name | string | StringId from user_strings.res | Missions name

Return table
empty

Example


SetState

SetState( { State, /Mission/ } ) : {}

sets the state od a mission (V.STATE)

Parameter table
Identifier | Data type | Values | Comment
State | enum | MSTATE_ACHIEVED, MSTATE_ENDED, MSTATE_FAILED, MSTATE_OFFERING, MSTATE_RUNNING | state to set
Mission | unsigned int | CMissionHandle | Handle of a mission

Return table
empty

Example

-- Sets the actual state of that mission
if 5 == _count then
    NMission.SetState( { State=MSTATE_ACHIEVED } )
end

-- again for another mission
if 5 == _count then
    NMission.SetState( { Mission=V.OtherMission, State=MSTATE_ACHIEVED } )
end


Create

Create( { Name, Model, Location } ) : { NPC }

Creates an NPC in the actual system. The NPC is sitting at the bartable and has a marking over his head. If the user clickes on the NPC a "Text"-event is fired, which creates a dialog with "OK" and "QUIT". The functionality is like the terminalmenu. Presses the player "OK" a "MissionStart"-event is fired and the dialog will be closed and the NPC becomes inactive and cant be clicked any longer.

Parameter table
Identifier | Data type | Values | Comment
Name | string | StringId aus der user_string.res | Name of NPCs
Model | string | Model-Name | Name of character model
Location | string | "01", "02", "03", "04" | Locator (seat position)
System | StarSystemId | 0-399 | System for creating the NPC

Return table
Identifier | Data type | Values | Comment
NPC | unsigned int | CNPCHandle | Handle of created NPC

Example

-- creating a Morthok
V.NPCName = NObject.GetName( { Race = RACE_MORTHOK } ).Name
V.NPC = NNPC.Create( { Model = "Ratsmitglied2", Location = "01", Name = V.NPCName } ).NPC


Destroy

Destroy( { NPC } ) : { }

Destroys a NPC.

Parameter table
Identifier | Data type | Values | Comment
NPC | unsigned int | CNPCHandle | Handle of NPC

Return table
empty

Example

{   -- Player leaves station --> NPC removed.
    1.0, 1.0, "Station", function( V, Data )
    if V.NPC then
        NNPC.Destroy( { NPC = V.NPC } )
        V.NPC = nil
    end
end },


ActivateRing

ActivateRing( { Handle, Activate } ): {}

Activates or deactivates the ring

Parameter table
Identifier | Data type | Values | Comment
Handle | unsigned int | n/a | Handle of a CStaticObject
Activate | int | n/a | > 0: Ring will be activated 1: Ring will be deactivated.

Return table
empty

Example


AddDialog

AddDialog( { Object, Exclusive } ) : {}

Adds the calling mission in the dialog of the object. If the dialog of the object is called, the mission recievs a "dialog"-event and has to supply text messages for the dialog. If "Exclusive" true, the standard dialog of the object will be completely overwritten, so there are no standard texts available.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of a Objekts ( ship or station )
Exclusive | bool | default=false | Standard dialogs will be overwritten (true) or dialog data will be entered (false)

Return table
empty

Example


ClearMissionObjects( {} ) : {}

Removes a mission marker from all objects in space.

Parameter table
empty

Return table
empty

Example


CloseHyper

CloseHyper( { Effect } ) : {}

Closes a hyperspace effect of the hypergate

Parameter table
Identifier | Data type | Values | Comment
Effect | unsigned int | CHyperSpaceDoorHandle | Handle of a hyperspace-effect

Return table
empty

Example

-- closes effect
NObject.CloseHyper( { Effect=V.Hyper } )


CreateExplosion

CreateExplosion( { Position, Type, Size, Damage } ) : {}

Creates an explosion at the given coordinates with the given type. Damage can be defined. "Size" defines the radius of the damage-area but has no effect on the visible explosion.

Parameter table
Identifier | Data type | Values | Comment
Position | table[1-3]:float | n/a | coordinate
Type | string | n/a | name for the explosiontype from Explosion.ini
Size | float | default=50.0 | radius of the explosion
Damage | float | default=0.0 | Damage for objects in Range

Return table
empty

Example


CreateHyper

CreateHyper( { Object, Open } ) : { Effect }

Creates the hypergate effect, at object position. Size is dependend from the object. Is the parameter open >0 you get a full size effect else the effect builds up.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of a SpaceObject
Open | int | n/a | >0 you get a full size effect else the effect builds up.

Return table
Identifier | Data type | Values | Comment
Effect | unsigned int | CHyperSpaceDoorHandle | Handle of Hyperspace effect

Example

-- Hyperspace effect around a freighter
V.Effect = NObject.CreateHyper( { Object=V.Trader, Open=1 } ).Effect


CreateMine

CreateMine( { Position, AimShip, Shooter } ) : { Mine }

Creates a mine at the position.

Parameter table
Identifier | Data type | Values | Comment
Position | table[1-3]:float | n/a | coordinate
AimShip | string | n/a | explosiontype from Explosion.ini
Shooter | unsigned int | default=0 | Shooter == 0, a normal mine is created, else the mine can fire

Return table
Identifier | Data type | Values | Comment
Mine | unsigned int | CProjectileHandle | Handle of the Mine

Example

--create a Mine
V.Mine = NObject.CreateMine( { Position={ 1000, 2000, 3000 } } ).Mine


CreateRing

CreateRing( { Position, Front } ): { Handle }

Creates a ring at the given position. Ring is directed in the front direction

Parameter table
Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | Position
Front | table[3]:float | n/a | Direction of the object

Return table
Identifier | Data type | Values | Comment
Handle | unsigned int | n/a | CStaticObject Handle

Example


CreateSatellite

CreateSatellite( { Position, Turrets, LevelOffset, Nation, Center, Distance } ) : { Satellite, Wing }

Creates a communication satellite at the given position. Weapons are optional. If an orbiter-handle is giveb in "Center", the satellite orbits the orbiter in a "Distance". In that case postion is changed to have the right distance.

Parameter table
Identifier | Data type | Values | Comment
Position | table[1-3]:float | n/a | coordinate
Turrets | unsigned int | n/a | Number of attack stations
LevelOffset | int | n/a | Level offset to the player
Nation | unsigned int | possible Races | Race, if no value is given the race of the system is used
Center | unsigned int | COrbiterHandle | Handle of a Orbiters
Distance | float | > 0.0 | Distance from orbiter

Return table
Identifier | Data type | Values | Comment
Satellite | unsigned int | CStarShipHandle | Handle of the satellite
Wing | unsigned int | CWingHandle | Handle of satellite-wings

Example

-- Satellites
V.Sat = NObject.CreateSatellite( { Position={ 1000, 2000, 3000 } } ).Satellite


DestroyMine

DestroyMine( { Mine } ) : {}

Destroys a mine

Parameter table
Identifier | Data type | Values | Comment
Mine | unsigned int | CProjectileHandle | Handle of the Mine

Return table
empty

Example

-- Mine destruction
NObject.DestroyMine( { Mine = V.Mine } )


DestroyRing

DestroyRing( { Handle } ): {}

A ring is deleted

Parameter table
Identifier | Data type | Values | Comment
Handle | unsigned int | n/a | Handle of CStaticObject

Return table
empty

Example


DistanceFromPlayer

DistanceFromPlayer( { Object } ) : { Distance }

Returns the distance to the players ship.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object

Return table
Identifier | Data type | Values | Comment
Distance | float | 0.0f < Distance | Distance in meters

Example

-- Distance to object
local _dist = NObject.DistanceFromPlayer( { Object=V.PirateShip } ).Distance


EnableContainerHits

EnableContainerHits( { Container, AiHits } ) : {}

The AI may not shot on container. If the AI should destroy a container it must be allowed first.

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of a Container
AiHits | unsigned int | 0..1 | ist AiHits = 0 , no hits allowed

Return table
empty

Example

-- Container may be destroyed
NObject.EnableContainerHits( { Container=V.Container, AiHits=1 } )


EndDialog

EndDialog( { Object } ) : {}

Ends a running dialog of an object

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of object ( ship or station )

Return table
empty

Example


Freeze

Freeze( { Object, Freeze } ) : {}

Freezes an object or unfreezes it. A frozen Object doesn't recieve timesteps from the simulation and has no collision. To be used in action cams.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of object
Freeze | bool | n/a | freeze object (true) or unfreeze (false)

Return table
empty

Example

-- Ramirez is freezed
NObject.Freeze( { Object= V.Ramirez, Freeze=true } )


GetAmmoDamage

GetAmmoDamage( { Ammo, Level } ): { DamageHull, DamageShield }

Calculates the damage of a ammunition of a level. If no level is given the level of the player is used.

Parameter table
Identifier | Data type | Values | Comment
Ammo | unsigned int | Munitionssorten | Ammunition
Level | unsigned int | 0..9 | level

Return table
Identifier | Data type | Values | Comment
DamageHull | float | >= 0 | Hull damage
DamageShield | float | >= 0 | Schield damage

Example


GetArtefact

GetArtefact( {} ): { Handle }

Looks for the first artefactcontainer in the system.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Handle | unsigned int | n/a | Handle of ArtefaktContainers

Example


GetAsteroidPos

GetAsteroidPos( { Asteroid, Index} ) : { Position }

Returns a position in an asteroid, where a container could be created. If no valid position is found (0,0,0) will be returned.

Parameter table
Identifier | Data type | Values | Comment
Asteroid | unsigned int | CObjectHandle | Handle of an asteroid
Index | int | n/a | Index of an asteroid position

Return table

Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | absolute coordinate

Example

-- Find a position
V.Position = NObject.GetAsteroidPos( { Asteroid=V.Asteroid, Index=3 } } )


GetAsteroidPosCont

GetAsteroidPosCont( { Asteroid, Index} ) : { Position }

Returns a position in an asteroid, where the mining container could be created. If no valid position is found (0,0,0) will be returned.

Parameter table
Identifier | Data type | Values | Comment
Asteroid | unsigned int | CObjectHandle | Handlewert of an asteroid
Index | int | n/a | Index for an asteroid position

Return table
Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | absolute coordinate

Example

-- looking for a position
V.Position = NObject.GetAsteroidPosCont( { Asteroid=V.Asteroid, Index=3 } } )


GetFrontDir

GetFrontDir( { Object } ) : { FrontDir }

returns the Z-axis of an object as vector.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object

Return table
Identifier | Data type | Values | Comment
FrontDir | table[3]:float | n/a | direction of Z

Example

-- get the direction
V.Sat = NObject.CreateSatellite( { Position={ 1000, 2000, 3000 } } ).Satellite
V.Dir = NObject.GetFrontDir( { Object=V.Sat } ).FrontDir


GetName

GetName( { Race } ) : { Name }

Returns the StringId of a pirate names of the given race.

Parameter table
Identifier | Data type | Values | Comment
Race | unsigned int | Rasse | Race index

Return table
Identifier | Data type | Values | Comment
Name | string | n/a | StringId name

Example

-- get a name
V.Name = NObject.GetName( { Race=RACE_MORTHOK } ).Name

-- give a special name to a freighter
NObject.SetSpecialName( { Object=V.Trader, Name=V.Name } )


GetNameArray

GetNameArray( { Number } ) : { NameArray }

returns a table of "number" pairs defining pirate names and races

Parameter table
Identifier | Data type | Values | Comment
Number | unsigned int | n/a | number of names

Return table
Identifier | Data type | Values | Comment
NameArray | table[Number]:table:{string,int} | n/a | Names and Races

Example

-- calculate the array
V.Names = NObject.GetNameArray( { Number=8 } ).NameArray

-- give a special name to an object
NObject.SetSpecialName( { Object=V.Ship1, Name=V.Names[ 1 ][ 1 ] } )

-- again for another object
NObject.SetSpecialName( { Object=V.Ship2, Name=V.Names[ 2 ][ 1 ] } )


GetPosition

GetPosition( { Object } ) : { Position }

Returns the coordinates of an object

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object

Return table
Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | Position of that cbject

Example

-- Get the position of an object
V.Sat = NObject.CreateSatellite( { Position={ 1000, 2000, 3000 } } ).Satellite
V.Pos = NObject.GetPosition( { Object=V.Sat } ).Position


GetUpDir

GetUpDir( { Object } ) : { UpDir }

Return the Y-axis of an object as vector

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object

Return table
Identifier | Data type | Values | Comment
FrontDir | table[3]:float | n/a | Direction of Y-axis

Example

--get Up Direction
V.Sat = NObject.CreateSatellite( { Position={ 1000, 2000, 3000 } } ).Satellite
V.Dir = NObject.GetUpDir( { Object=V.Sat } ).UpDir


OrbiterTurretLock

OrbiterTurretLock( { Object, Lock } ): {}

Defines if a CTurretOrbiter may have turrets. Trade and researchstations and asteroids are CTurretOrbiter.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | n/a | Handle of a CTurretOrbiter
Lock | int | n/a | Lock > 0 no turrets are allowed else turrets are allowed

Return table
empty

Example


Place

Place( { Object, Position, Front, LookAt, BaseObj } )

Places an object at a position and a direction. If "BaseObj" is given, "LookAt" and "Position" are used relative to BaseObj.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CObjectHandle | Handle of an object
Position | table[3]:float | n/a | Position
Front | table[3]:float | n/a | Direction
LookAt | table[3]:float oder unsigned int | Vektor oder CObjectHandle | Position or Objekt, where the camera should look at
BaseObj | unsigned int | CObjectHandle | Objekt for relative positioning

Return table
empty

Example


PlayerLanding

PlayerLanding( { Object, Accept } ) : {}

Allows or disallowes a player to land on a CSpaceObject owning a hangar.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handlewert of a SpaceObjects
Accept | int | n/a | >0 allows a landing, else no landing is allowed

Return table
empty

Example

-- Allowing the player to land on an asteroid hangar
NObject.PlayerLanding( { Object=V.Asteroid, Accept=1 } } )


RadarMapColor

RadarMapColor( { Object, Color } ) : {}

Changes the color for a CSpaceObject. No changes in behavior or enemy state are made here. To change the color back to default RADARMAP_INVALID must be the color parameter.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object,
Color | int | Radarmap Colors | Radarcolor

Return table
empty

Example

-- Change color to friendly
NObject.RadarMapColor( { Object=V.StarShip, Color=RADARMAP_SHIP_FRIEND } } )


RemoveDialog

RemoveDialog( { Object } ) : {}

Removes the mission from the dialog of the object. A running dialog will be quit at once.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of an object ( ship or station )

Return table
empty

Example


ResetActor

ResetActor( { Object} ) : {}

Sets the standard actor for an object.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of an Objekts ( ship or station )

Return table
empty

Example


ScanObject

ScanObject( { Object, Aim, Time, Scanner } ) : {}

Makes a CSpaceObject scanning another CSpaceObject. Duration: "Time". There is no range control

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object, which should do the scan
Aim | unsigned int | CObjectHandle | Object, scaning. If there is no target no scan is done
Time | float | n/a | duration. Default = 1 sec.
Scanner | int | n/a | Index of scanning beams. 0 is default value

Return table
empty

Example

-- Player scans a container
NObject.ScanObject( { Object = V.PlayerShip, Aim = V.Container, Time = 1.0 } )


SetActor

SetActor( { Object, Actor } ) : {}

look at NShip.SetActor()

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of an Object ( ship or station )
Actor | unsigned int oder string | 0, 1 or Name of actor | number of an actor. 0 and 1 are default actors or explicite actors

Return table
empty

Example


SetMissionFlag

SetMissionFlag( { Object, Set } ) : {}

Sets a mission flag on an object.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of a SpaceObjects
Set | unsigned int | 0..1 | Set = 0 Flag is removed else flag is set

Return table
empty

Example

-- Make a Missionflag
NObject.SetMissionFlag( { Object=V.Trader, Set=1 } )

-- Remove flag
NObject.SetMissionFlag( { Object=V.Trader } )


SetSpecialName

SetSpecialName( { Object, Name } ) : {}

Sets a special name for an object. Name is displayed in targetlist.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of a SpaceObject
Name | string | StringId from user_strings.res | Name des Ojekts

Return table
empty

Example

-- Give it a name
NObject.SetSpecialName( { Object=V.Trader, Name="IDM_GLOBAL_5000_TRADERNAME" } )


TriggerDialog

TriggerDialog( { Object } ) : {}

Activates the dialog of an object.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of an Objekts ( ship or station )

Return table
empty

Example


ActivateScanner( {} ) : {}

The player may use the scanner of his ship.

Parameter table
empty

Return table
empty

Example

NPlayer.ActivateScanner( {} )


AddAmmo

AddAmmo( { Ammo, Number } ) : { Stored }

Number Rockets of Typ Ammo will be available for the player

Parameter table
Identifier | Data type | Values | Comment
Ammo | unsigned int | Index in Projectiles.ini | Index of the rocket type
Number | unsigned int | > 0 | number of rockets

Return table
Identifier | Data type | Values | Comment
Stored | unsigned int | <= Number | number of all rockets on board

Example

-- give the player a Big-Bang (Level 3, Step 4) geben
NPlayer.AddAmmo( { Ammo = 12, Number = 1 } )


AddCredits

AddCredits( { Credits } ) : {}

Gives an amount money to the player

Parameter table
Identifier | Data type | Values | Comment
Credits | unsigned int | n/a | Credits

Return table
empty

Example

-- Cheater!
NPlayer.AddCredits( { Credits=50000} )


AmmoInfo

AmmoInfo( { Type } ) : { Count }

Returns the number of rockets onboard the players ship.

Parameter table
Identifier | Data type | Values | Comment
Type | enum | AMMO_TYPE_SWARM, AMMO_TYPE_HELLFIRE, AMMO_TYPE_BIGBANG | Rocket typ

Return table
Identifier | Data type | Values | Comment
Count | unsigned int | n/a | Number of rockets

Example


DeactivateScanner( {} ) : {}

Deactivates the scanner onboard the players ship

Parameter table
empty

Return table
empty

Example

-- scanner deactivated
NPlayer.DeactivateScanner( {} )


DestroyPlayerShip

DestroyPlayerShip( {} ) : { Done }

If the players ship is in Space, the ship is destroyd and the Deathcam is started

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Done | bool | n/a | true, if the players ship is destroyed.

Example

NPlayer.DestroyPlayerShip( {} )


EndEscort( {} ) : {}

The playership leaves the wing it was escorting

Parameter table
empty

Return table
empty

Example

--Target system reached, leave wing
if WING_ENTER_SYSTEM == Data.Event then,
    NPlayer,EndEscort( {} )
end


EquipmentInfo

EquipmentInfo( { Type } ) : { Level, Count, Size }

Returns information about Equipment.
It is only for EQUIPMENT_CARGO_COMPUTER and EQUIPMENT_ORE_COLLECTOR implemented.

Parameter table
Identifier | Data type | Values | Comment
Type | enum | EQUIPMENT_ORE_COLLECTOR or EQUIPMENT_CARGO_COMPUTER | Type of equipment

Return table
Identifier | Data type | Values | Comment
Level | unsigned int | n/a | Level of equipment
Count | unsigned int | n/a | EQUIPMENT_CARGO_COMPUTER: Number of cargo drones EQUIPMENT_ORE_COLLECTOR: number of ore collectors
Size | unsigned int | n/a | Container size compatibility EQUIPMENT_CARGO_COMPUTER

Example

-- Informations about the installed fright computer
local info = NPlayer.EquipmentInfo( { Type = EQUIPMENT_CARGO_COMPUTER } )

-- player must be capable of carrying 100t freight modules
if 1 < info.Count and CONTAINER_SMALL < info.Size then
    ...
end


EscortNPC

EscortNPC( { Ship } ) : { Wing }

Playership enters a wing

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of target ship

Return table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of WIngs, the player entered

Example

-- Player escorts freighter
NPlayer.EscortNPC( { Ship=V.Jophur } )


GetContainer

GetContainer( {} ) : { Number, Container0, Container1, Container2 }

Returns the handles of the container the player is carrying.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Number | unsigned int | 0 .. 3 | Number of containers
Container0 | unsigned int | CContainerHandle | Handle of Container1
Container1 | unsigned int | CContainerHandle | Handle of Container2
Container2 | unsigned int | CContainerHandle | Handle of Container3

Example


GetCriminalRecord

GetCriminalRecord( { System } ) : { Crime }

The criminal record points from the given System are returned. If the system in invalid the actual system is inspected.

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | 0 .. 402 | system number

Return table
Identifier | Data type | Values | Comment
Crime | float | 0.0 .. 5.0 | Penalty points

Example

-- Penalty points
crime = NPlayer.GetCriminalRecord( {} ).Crime

-- Penalty points in sol-system
earth = NPlayer.GetCriminalRecord( { System=29} ).Crime


IsEona

IsEona( {} ) : { Eona }

Checks, if Eona is onboard.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Eona | bool | n/a | Eona is onbord(true) or not(false)

Example


IsObjectInView

IsObjectInView( { Object } ) : { InView }

Checks, if an object is in players view.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object

Return table
Identifier | Data type | Values | Comment
InView | bool | n/a | true, if object is in view

Example

if NPlayer.IsObjectInView( { Object=V.Sat } ).InView then
    V.Step = 2.0
end


LeaveSpaceStation( {} ) : {}

Forces the playership to leave a station. Has no effect, if the ship is already in space.

Parameter table
empty

Return table
empty

Example

NPlayer.LeaveSpaceStation( {} )


LockHyperJump

LockHyperJump( { Lock } ) : {}

Disables the players hyperspace drive

Parameter table
Identifier | Data type | Values | Comment
Lock | bool | n/a | Hyperspace blocked(true) Hyperspace allowed(false)

Return table
empty

Example


LockSystemEntry

LockSystemEntry( { Locked } ) : ()

Systementry is disabled or allowed. If the entry is denied the playership waits in the hypergate until the entry is allowed (entry-cam).

Parameter table
Identifier | Data type | Values | Comment
Locked | int | n/a | if Locked>0 , then system is locked, else allowed

Return table
empty

Example

-- leave player out
NPlayer.LockSystemEntry( {Locked=1} )
-- for special cameras
-- Allow Entry
NPlayer.LockSystemEntry()


MoveAhead( {} ) : ()

If a actioncam is active the playership flies directly ahead. After the cam the player gets the steering back.

Parameter table
empty

Return table
empty

Example

-- create a Camera
V.Camera = NCamera.CreateBoundCam( { TargetObject=V.Hunter, Time=8.5 } ).Camera
-- Player flies away...
NPlayer.MoveAhead()


SelectNearestEnemy( {} ) : {}

Selects the enemy with the shortest distance to the player.

Parameter table
empty

Return table
empty

Example


SelectTarget

SelectTarget( { Object } ) : {}

Selects an object as target

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Object

Return table
empty

Example

-- selects a satellite
NPlayer.SelectTarget( { Object=V.Sat } )


SendMail

SendMail( { Category, Text } ) : {}

Sends an Email to the player. Hint: valid categories are to find in the LokaTool under "MISSION/STORYLINE/EMAIL".

Parameter table
Identifier | Data type | Values | Comment
Category | string | StringId from LokaTool | Title and category in the mail
Text | string | StringId from LokaTool | Message text

Return table
empty

Example

-- Player gets personal news.
NPlayer.SendMail( { Category="IDM_EMAIL_CAT_PERSONAL", Text = "IDM_BLUBB" } )


SetMultipliers

SetMultipliers( { RollFactor, RotFactor, MaxSpeedFactor, AccelFactor, MaxShiftFactor, ShiftAccelFactor, BoostFactor, MinSpeedFactor, MinBrakeSpeed } ) : {}

Changes the properties of the playership. If a value is missing the default value will be used. All values refer to the basic values of the ship. BoostFactor = 2.0 mean double speed for the afterburner.
Exceptions:'MinSpeedFactor' relates to the actual max. speed; 'MinBrakeSpeed' is an absolute value

Parameter table
Identifier | Data type | Values | Comment
RollFactor | float | 0.0 <= RollFactor | Roll factor for Z-Achse ( Max. value and acceleration )
RotFactor | float | 0.0 <= RotFactor | Roll factor for X and Y-Achse ( Max. value and acceleration )
MaxSpeedFactor | float | 0.0 <= MaxSpeedFactor | Factor for max. Speed
AccelFactor | float | 0.0 <= AccelFactor | Factor for accelleration ( Thrust and Afterburner )
MaxShiftFactor | float | 0.0 <= MaxShiftFactor | Factor for max. speed of vector thrusters
ShiftAccelFactor | float | 0.0 <= ShiftAccelFactor | Factor for the acceleration of the thrusters
BoostFactor | float | 0.0 <= BoostFactor | Factor for max. boost speed
MinSpeedFactor | float | 0.0 <= MinSpeedFactor | Factor for min. speed (only for the canyon )
MinBrakeSpeed | float | n/a | Min. back speed ( should be <= 0.0 )

Return table
empty

Example


StandardReward

StandardReward( { Factor } ) : { Credits }

Returns the standard reward of the actual level. The reward can be multiplied.

Parameter table
Identifier | Data type | Values | Comment
Factor | float | 0.0f < Factor | Factor for reward

Return table
Identifier | Data type | Values | Comment
Credits | unsigned int | n/a | Reward in Credits

Example

-- player gets reward
NPlayer.AddCredits( { Credits=NPlayer.StandardReward( { Factor=2.0 } ).Credits } )


StartFollow

StartFollow( { Wing, Offset } ) : {}

the playership follows another wing. Player looses control but no camera is used. Are all wingpositions used an offset of (0,100,0) will be used. IMPORTANT: The player is not a member of that wing.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of the wing, the player follows

Return table
empty

Example

-- Player follows Ramirez
NPlayer.StartFollow( { Wing=V.Ramirez } )


StopFollow( {} ) : {}

The playership stops following another wing and the player gets steering back.

Parameter table
empty

Return table
empty

Example

-- Player gets steering back
NPlayer.StopFollow( {} )


Register

Register( { Name, Type, Group, Transitions } ) : {}

Registers a mission script in the mission system.

Parameter table
Identifier | Data type | Values | Comment
Name | string | n/a | internal name of the script. Must be unique
Type | enum | MTYPE_GLOBAL, MTYPE_TERMINAL, MTYPE_SPACE, MTYPE_BAR, MTYPE_VIDEO, MTYPE_STORY, MTYPE_STORY_TERMINAL, MTYPE_ALWAYS | Missiontype.
Group | unsigned int | n/a | Group index (not used)
Transitions | table[n]:{float,float,string,function} | n/a | List of all mission states

Return table
empty

Example

NScript.Register( {
    -- name
    Name="HUMAN_000",
    -- group
    Group=0,
    -- type
    Type=MTYPE_TERMINAL,
    -- transition table
    Transitions={
    {
        nil, nil, "Init",
        function( V, Data )
        ...
        end
    }
    ...
} } )


AddContainer

AddContainer( { Ship, Container } ) : {}

Docks a container to a freighter. Is the given handle no freighter an error occures.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship, must be a frieghter
Container | unsigned int | CContainerHandle | Handle of the container

Return table
empty

Example

 NShip.AddContainer( { Ship=V.Trader, Container=V.Conti } )


AddDialog

AddDialog( { Ship, Exclusive } ) : {}

Adds the calling mission in the dialog of the ship. If the dialog of the ship is called, the mission recievs a "dialog"-event and has to supply text messages for the dialog. If "Exclusive" true, the standard dialog of the object will be completely overwritten, so there are no standard texts available.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of target ship
Exclusive | bool | default=false | Standard dialogs will be overwritten (true) or dialog data will be entered (false)

Return table
empty

Example

-- Freighter gets ne dialogs.
NShip.AddDialog( { Ship=V.Trader, Exclusive=true } )


CreateRandomCargo

CreateRandomCargo( { Ship } ) : { ContainerList }

Creates for all cargo spaces container with random goods. Does only work with frieghters

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship, must be a freighter

Return table
Identifier | Data type | Values | Comment
ContainerList | table[n]:unsigned int | CContainerHandle | List of container handles

Example

-- put random cargo on a freighter
NShip.CreateRandomCargo( { Ship=V.Trader } )


DropContainer

DropContainer( { Ship, Container } ) : {}

Forces an freighter to drop the given container.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship, must be a freighter
Container | unsigned int | CContainerHandle | Handle of container to drop

Return table
empty

Example

-- drop a container
NShip.DropContainer( { Ship=V.Trader, Container=V.Conti } )


DumpCargo

DumpCargo( { Ship, Destroy } ) : { ContainerList }

Forces a ship to drop all containers. If "Destroy" == true all containers are destroyed immediately else the function returns a list of container handles.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Destroy | bool | n/a | destroy carge (true) or drop it (false)

Return table
Identifier | Data type | Values | Comment
ContainerList | table[n]:unsigned int | CContainerHandle | List of dropped containers

Example


EquipContainer

EquipContainer( { Ship, Goods } ) : { Container }

Creates a container with the given goods and docks it on the given ship. "Ship" must ´be a freighter. If there is no free cargobay an error occurs.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship, must be a freighter
Goods | enum oder string | Trade goods or StringId from user_strings.res | Id of trade goods or name of mission good

Return table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of a container

Example

-- equip container with trade goods
NShip.EquipContainer( { Ship=V.Trader, Goods=GOODS_COMPUTERS } )

-- equip container with a mission goods
NShip.EquipContainer( { Ship=V.Trader, Goods="IDM_GOODS_FURBALLS" } )


EscortPlayer

EscortPlayer( { Ship } ) : { Wing }

Adds a AI-ship to the players wing.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship

Return table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of player wing

Example

NShip.EscortPlayer( { Ship=V.Hunter } )


Explode

Explode( { Ship } ) : {}

The given ship will be destroyed.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship

Return table
empty

Example

-- destroy the pirate
NShip.Explode( { Ship=V.Pirate } )


GetAlignment

GetAlignment( { Ship } ) : { Pos, Front, UpDir }

returns the alignment of a ship

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handlof a ship

Return table
Identifier | Data type | Values | Comment
Pos | table[3]:float | n/a | absolute coordinate of the ship
Front | table[3]:float | n/a | direction Z-axis
UpDir | table[3]:float | n/a | direction Y-axis

Example

-- get alignment of player
local align = NShip.GetAlignment( { V.Player } )

-- use alignment for an other ship
NShip.SetAlignment( { Ship=V.Hunter, Front = align.Front, UpDir = align.UpDir } )


GetHideOut

GetHideOut( {} ) : { Ship, Wing }

searches for a pirate hideout in the system.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of hide out
Wing | unsigned int | CWingHandle | Handle of the wing belonging to the hideout

Example


GetNumCargoBays

GetNumCargoBays( { Ship, Free } ) : { NumCargoBays }

Returns the number of cargo spaces

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Free | bool | default=false | true, if only free spaces should be counted

Return table
Identifier | Data type | Values | Comment
NumCargoBays | unsigned int | n/a | Number of spaces

Example

if 0 < NShip.GetNumCargoBays( { Ship=V.Trader, Free=true } ).NumCargoBays then
    V.Conti = NShip.EquipContainer( { Ship=V.Trader, Goods="IDM_GOODS_FURBALLS" } ).Container
end


JoinWing

JoinWing( { Ship, Wing } ) : { Success }

A ship should join a wing

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Wing | unsigned int | CWingHandle | Handle of a wing

Return table
Identifier | Data type | Values | Comment
Success | bool | n/a | true, if the ship joined successfully

Example

local _list = NWing.List( { Wing=V.Alpha } ).ShipListfor _id, _ship in _list do
    NShip.JoinWing( { Ship=_ship, Wing=V.Jophur } )
end


Protect

Protect( { Ship, Protect } ) : {}

A ship is protected. The hull status can't be under 1%

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Protect | bool | n/a | protection (true) or no protection (false)

Return table
empty

Example

-- Ship may not by destroyed
NShip.Protect( { Ship=V.Jophur, Protect=true } )


ProtectCargo

ProtectCargo( { Ship, Protect } ) : {}

Prohibits the dropping of containers of a freighter. Is true for all mission freighters and false for normal freighters. A freighter dropping its cargo is no longer hostile. It will be hostile again, if fired upon.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship, must be a freighter
Protect | bool | n/a | no cargo dropping allowed (true) or dropping allowed (false)

Return table
empty

Example

-- Freighter may drop its cargo
NShip.Protect( { Ship=V.Trader, Protect=false } )


RemoveDialog

RemoveDialog( { Ship } ) : {}

Removes the mission from that ships dialog. A running dialog will be disrupted.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship

Return table
empty

Example

NShip.RemoveDialog( { Ship=V.Trader } )


RemoveWeapons

RemoveWeapons( { Ship } ) : {}

Removes all weapons fram a ship

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship

Return table
empty

Example

-- removing weapons
NShip.RemoveWeapons( { Ship=V.Jophur } )


SetActor

SetActor( { Ship, Actor } ) : {}

sets the actor for a ship, used for radio messages. Actors can be choosen via an index (0 or 1) or set directly with a string ( e.g. "hummil00").

Actor: Races
String | Rasse
hum | Menschen
rap | Raptor
arr | Arrack
mor | Mortok
thu | Thul
oct | Octo
Actor: Type

string | Type
mil | Military, Police, Civil
hun | Hunter
pir | Pirates
sta | Stations
tra | Freighter (no pirates)
Actors: NPCs
This list is not complete!

string | NPC
robert | Robert
eona | Eona
ramirez | Ramirez
nicolai | Nicolai

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Actor | unsigned int or string | 0, 1 or String combination of Race+Type+Number | Number of actor. 0 and 1 are standard actors of all races or Explicit string of an actor

Return table
empty

Bespiele

-- Frighters get always standard actor 1
-- Is the freighter from the Mortok,"mortra01" will be used
NShip.SetActor( { Ship=V.Trader, Actor=1 } )
-- The hunter should be ramirez
NShip.SetActor( { Ship=V.Ramirez, Actor="ramirez" } )


SetAlignment

SetAlignment( { Ship, Position, Front, UpDir } ) : {}

Sets a ship on a given position. The "Nose" of the ship always look at front. If no UpDir is given, the ship is aligned to the Y-axis.

Note: the function may not be used, if a ship must be on a special location (Loading infront of a station, ships while hyperjumping) The position must be free, because the logic will detect a collision in the next timestep.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Position | table[3]:float | n/a | absolute coordinates (default is the actual position)
Front | table[3]:float | n/a | direction vector (default is actual direction)
UpDir | table[3]:float | n/a | vector, to define up-direction.(default is Y-axis of the system)

Return table
empty

Example

-- Playership is set on top of the trade station and is directed to the hypergate
NShip.SetAlignment( { Ship=V.Player, Position={0.0,3000.0,0.0}, Front={0.0,-3000.0,10000.0} } )
-- normal alignment
NShip.SetAlignment( { Ship=V.Player } )


SetBoss

SetBoss( { Ship, BossId } ) : {}

The ship gets a Boss flag. It gets special moves.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
BossId | unsigned int | n/a | Id, for special moves

Return table
empty

Example

-- Ship is a boss
NShip.SetBoss( { Ship=V.Pirate, BossId=1 } )
-- no longer a boss
NShip.SetBoss( { Ship=V.Pirate, BossId=0 } )


SetCloaked

SetCloaked( { Ship, Set } ) : {}

Cloaks a ship

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Set | bool | n/a | cloak (true) or decloak (false)

Return table
empty

Example


SetCrime

SetCrime( { Ship, Set} ) : {}

The ship is a GoodGuy and the player gets penalty points if he fires upon it. Pirates and Hunters are BadGuys and does not give penalty points.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Set | bool | n/a | GoodGuy gives penalties(true) oder BadGuy(false)

Return table
empty

Example


SetDurability

SetDurability( { Ship, Hull, Shield } ) : {}

Sets the multiplier for the max. hull- and shield points.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Hull | float | 0.0f < Hull, default = 1.0 | sets the multiplier for hull hitpoints
Shield | float | 0.0f < Shield, default = 1.0 | sets the multiplier for shield hitpoints

Return table
empty

Example


SetInvulnerable

SetInvulnerable( { Ship, Set} ) : {}

Makes a immune to damage

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Set | bool | n/a | ship is invurnable (true) or not (false)

Return table
empty

Example


SetPlanetCollision

SetPlanetCollision( { Ship, Set } ) : {}

Removes collision of a planet. Ships may fly through it.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Set | bool | n/a | Collision active (true) or inactive (false)

Return table
empty

Example


SetPlayerFriend

SetPlayerFriend( { Ship, Set } ) : {}

the ship does not react at once, if the player fires upon it

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Set | bool | n/a | ignors player some time(true) or normal behavior (false)

Return table
empty

Example


SetRecharge

SetRecharge( { Ship, EnergySecs, ShieldSecs, PlasmaSecs } ) : {}

Adjust the power generation of a ship (for weapon and shield reload times)

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
EnergySecs | float | EnergySecs < 0 | Weapons recharge time in seconds
ShieldSecs | float | ShieldSecs < 0 | Shield recharge time in seconds
PlasmaSecs | float | default = 1.0 | If the value is > 0.0 the plasma gun will be reloaded

Return table
empty

Example

-- regenerate weapons energy, Shields need 2 minutes
NShip.SetRecharge( { Ship=V.Pirate, ShieldSecs=120.0 } )


TraderLogicOn

TraderLogicOn( { Ship } ) : {}

Activates the trading logic on a freighter

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship, must be a freighter

Return table
empty

Example

-- Freighter acts now like an normal Trader
NShip.TraderLogicOn( { Ship=V.Trader } )


TriggerDialog

TriggerDialog( { Object } ) : {}

Activates the dialog of a ship.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handle of the object (ship or station)

Return table
empty

Example

-- Player is near a target and gets a message.
if V.Waypoint == Data.Waypoint then
    NShip.TriggerDialog( { Ship=V.Trader } )
end


UseMissiles

UseMissiles( { Ship, Ammo} ) : {}

A ship gets a rocket launcher with an defined ammunition type

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of a ship
Ammo | enum | AMMO_TYPE_BIGBANG, AMMO_TYPE_HELLFIRE, AMMO_TYPE_SWARM | Rocket type

Return table
empty

Example

-- Ship may use rockets
NShip.UseMissiles( { Ship=V.Jophur, Ammo=AMMO_TYPE_HELLFIRE } )


PlaySound

PlaySound( { Sound, Volume, Mode } ) : {}

Plays a sound effeckt. If Mode is 0 or 1 the sound can later be stopped. Only one sound can be played at ones at mode 0 or 1. To stop a playing sound use an empty string in this function.

Parameter table
Identifier | Data type | Values | Comment
Sound | string | Name of a sound ressource defined in KlangErzeugerDefault.xml | Name of a sound ressource
Volume | float | 0.0 ... 1.0 | volume
Mode | unsigned int | default = ~0 | play once ( 0 ), looped ( 1 )

Return table
empty

Example

-- Play sound once
NSound.PlaySound( { Sound="FXFire" } )

-- Soundloop
NSound.PlaySound( { Sound="DataTransmission", Mode=1 } )

-- stop looped Sound
NSound.PlaySound( { Sound="" } )


SetCustomMusic

SetCustomMusic( { Title } ) : {}

Plays the given music (looped). Musik has the highest priority and can't be dirrupted. Music can only be stoppt by 'SetDefaultMusic'

Parameter table
Identifier | Data type | Values | Comment
Title | string | Name of a stream resource from KlangErzeugerDefault.xml | Titel of the music

Return table
empty

Example

-- Musik
NSound.SetCustomMusic( { Title="ballaballa" } )


SetDefaultMusic( {} ) : {}

Stopps any playing userdefined music. music will be restarted from the music manager.

Parameter table
empty

Return table
empty

Example

-- Stop the music
NSound.SetDefaultMusic( {} )


SetRoomType

SetRoomType( { Type } ) : {}

Sets a sound environment. If type is empty the default value will be used.

Parameter table
Identifier | Data type | Values | Comment
Type | enum | look at the table below | room type

Return table
empty

Type table for parameter type
Identifier | Comment
ENVIRONMENT_GENERIC | Default setting. (Debugger value: 0)
ENVIRONMENT_PADDEDCELL | Padded cell reverb. (Debugger value: 1).
ENVIRONMENT_ROOM | Simple room reverb. (Debugger value: 2).
ENVIRONMENT_BATHROOM | Bathroom reverb. (Debugger value: 3).
ENVIRONMENT_LIVINGROOM | Living room reverb. (Debugger value: 4).
ENVIRONMENT_STONEROOM | Stone room reverb. (Debugger value: 5).
ENVIRONMENT_AUDITORIUM | Auditorium reverb. (Debugger value: 6).
ENVIRONMENT_CONCERTHALL | Concert hall reverb. (Debugger value: 7).
ENVIRONMENT_CAVE | Cave reverb. (Debugger value: 8).
ENVIRONMENT_ARENA | Arena reverb. (Debugger value: 9).
ENVIRONMENT_HANGAR | Hanger reverb. (Debugger value: 10).
ENVIRONMENT_CARPETEDHALLWAY | Carpeted hallway reverb. (Debugger value: 11).
ENVIRONMENT_HALLWAY | Hallway reverb. (Debugger value: 12).
ENVIRONMENT_STONECORRIDOR | Stone corridor reverb. (Debugger value: 13).
ENVIRONMENT_ALLEY | Alley reverb. (Debugger value: 14).
ENVIRONMENT_FOREST | Forest reverb. (Debugger value: 15).
ENVIRONMENT_CITY | City reverb. (Debugger value: 16).
ENVIRONMENT_MOUNTAINS | Mountains reverb. (Debugger value: 17).
ENVIRONMENT_QUARRY | Quarry reverb. (Debugger value: 18).
ENVIRONMENT_PLAIN | Open plain reverb. (Debugger value: 19).
ENVIRONMENT_PARKINGLOT | Parking lot reverb. (Debugger value: 20).
ENVIRONMENT_SEWERPIPE | Sewer pipe reverb. (Debugger value: 21).
ENVIRONMENT_UNDERWATER | Underwater reverb. (Debugger value: 22).
ENVIRONMENT_DRUGGED | Drugged reverb. (Debugger value: 23).
ENVIRONMENT_DIZZY | Dizzy reverb. (Debugger value: 24).
ENVIRONMENT_PSYCHOTIC | Psychotic reverb. (Debugger value: 25).

Example


EndSiege

EndSiege( { System } ) : {}

Ends the state of siege in a system.

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | SystemId : 0-399 | Id of a system

Return table
empty

Example

-- System is free now
NStarSystem.EndSiege( { System=29 } )


GetCombineName

GetCombineName( { System } ) : { Name }

Returns the StringId of a corporation valid in that system

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | 0-399 | Id of system

Return table
Identifier | Data type | Values | Comment
Name | string | StringId from LokaTool | Name of a company of that system

Example


GetHandleFromId

>GetHandleFromId( { Id } ) : { Handle }

Returns a system handle from a systemId

Parameter table
Identifier | Data type | Values | Comment
Id | unsigned int | 0-399 | Id of a system

Return table
Identifier | Data type | Values | Comment
Handle | unsigned int | CStarHandle | Handle of a system

Example

-- Get the handle of systemId 12
local _handle = NStarSystem.GetHandleFromId( { Id=12 } ).Handle


GetIdFromHandle

GetIdFromHandle( { Handle } ) : { Id }

Returns a systemID from a handle

Parameter table
Identifier | Data type | Values | Comment
Handle | unsigned int | CStarHandle | Handle of a system

Return table
Identifier | Data type | Values | Comment
Id | unsigned int | 0-399 | Id of a system

Example

-- gets a id of a system handle
local _id = NStarSystem.GetIdFromHandle( { Handle=V.SystemHandle } ).Id


GetPirateField

GetPirateField() : { Orbiter, Valid }

Returns a handle of an orbiter, where a pirate gange is at home. Works only in the actual system.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Orbiter | unsigned int | OrbiterId | Meteorid field with a pirate gang
Valid | bool | n/a | is set, if the meteorid field is existent

Example

-- fint the handle of a pirates gang home
V.Meteorid = NStarSystem.GetPirateField()
-- is the orbiter valid?
if V.Meteorid.Valid then
   -- get the position or do whatever you like.


ListOrbiters

ListOrbiters( {} ) : { OrbiterList }

Returns a list of all orbiter ( Stations, Asteroids, Planets, Moons ) in the actual system

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
OrbiterList | table[n]:unsigned int | CObjectHandle | Orbiter handle list

Example

local _list = NStarSystem.ListOrbiters( {} ).OrbiterList...


RemoveStoryLock

RemoveStoryLock( { System } ) : {}

removes the "Story lock" of a system. Note: Use this only after achieving a "Bar-Mission"

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | SystemId : 0-399 | System

Return table
empty

Example


SetAsMissionTarget

SetAsMissionTarget( { System, Set, Hidden } ) : {}

Marks a system as "Missiontarget" with an M on the navmap

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | SystemId : 0-399 | Id of a system
Set | bool | n/a | Marks (true) or demarks the system (false)
Hidden | bool | n/a | Marking is visible or not

Return table
empty

Example

NStarSystem.SetAsMissionTarget( { System=V.System0, Set=true } )


SetAsStoryTarget

SetAsStoryTarget( { System, Set } ) : {}

Marks a system as "Storysystem". Only for missions of type MTYPE_STORY.

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | SystemId : 0-399 | Id of a system
Set | bool | n/a | Marks (true) or demarks the system(false)

Return table
empty

Example

NStarSystem.SetAsStoryTarget( { System=V.System0, Set=true } )


SetVisible

SetVisible( { System } ) : {}

Shows a system at the navmap

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | SystemId : 0-399 | System to be shown

Return table
empty

Example

-- Player gets a new system
NStarSystem.SetVisible( { System=29 } )


Unlock

Unlock( { System } ) : {}

The player gets a new key to a system, gets a message and the new system is automatically shown on the navmap.

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | SystemId : 0-399 | New system

Return table
empty

Example

-- Player gets a system key
NStarSystem.Unlock( { System=29 } )


Progress

Progress( {} ) : { Chapter, Subchapter }

Returns the story state with the chapter and subchapter numbers.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Chapter | unsigned int | n/a | Actal Chapter
Subchapter | unsigned int | n/a | Actual subchapter

Example

-- Create a mission only after the prolog
if 0 < NStory.Progress( {} ).Chapter then
    ...
    return 1
end


AddNews

AddNews( { Header, Body, Lifetime } ) : {}

Adds a newsmessage in the news section of the terminal

Parameter table
Identifier | Data type | Values | Comment
Header | string | StringId from LokaTool | Headline
Body | string | StringId from LokaTool | Text of message
Lifetime | unsigned int | n/a | Lifetime in days

Return table
empty

Example

-- News about Thul-Attacks
NTerminal.AddNews( { Header="IDM_NEWS_THUL_HDR", Body="IDM_NEW_THUL_TEXT", Lifetime=20 } )


Blink

Blink( { Type } ) : {}

An interface element starts blinking

Parameter table
Identifier | Data type | Values | Comment
Type | enum | BLINK_BTN_NAVMAP, BLINK_BTN_TARGETMAP, BLINK_BTN_COMMUNICATION, BLINK_BTN_LOGBUCH, BLINK_BTN_SHIP, BLINK_BTN_SPELLWEAPON, BLINK_BTN_ROCKETS, BLINK_BTN_OPTIONS | element selection

Return table
empty

Example

-- Rocketbutton starts blinking
NTutorial.Blink( { Type=BLINK_BTN_ROCKETS } )


ShowPopup

ShowPopup( { Text, Width, Height } ) : { Popup }

Shows a popup with text. Stopps the simulatioin. If the popup was closed a 'TutorialPopup'-event is fired.

Parameter table
Identifier | Data type | Values | Comment
Text | string | StringId from user_strings.res | Text
Width | unsigned int | n/a | Width of popup in pixel
Height | unsigned int | n/a | Highth of popup in pixel

Return table
Identifier | Data type | Values | Comment
Popup | unsigned int | n/a | Id of Popups (can be used in the 'TutorialPopup' event)

Example

V.Popup = NTutorial.ShowPopup( { Text="IDM_GLOBAL_5000_POPUP" } ).Popup


Add

Add( { Vector1, Vector2 } ) : { Vector }

Adds both vectors

Parameter table
Identifier | Data type | Values | Comment
Vector1 | table[3]:float | n/a | first vector
Vector1 | table[3]:float | n/a | second vector

Return table
Identifier | Data type | Values | Comment
Vector | table[3]:float | n/a | Vector1+Vector2

Example


GetPos

GetPos( { Area } ) : { Pos }

Returns a position in the specified area

Parameter table
Identifier | Data type | Values | Comment
Area | unsigned int | Spawn areas | Spawn areas without parameters

Return table
Identifier | Data type | Values | Comment
Pos | table[3]:float | n/a | absolute coordinates

Example

-- get a position behind the tradestation
V.Pos = {}V.Pos = NVector.GetPos( { Area = POSDESCR_TRADESTATION1  } ).Pos


SetMag

SetMag( { Vector, Mag } ) : { Vector }

Sets the length of a vector. Is 'Mag' not giben, the vector is normalized

Parameter table
Identifier | Data type | Values | Comment
Vector | table[3]:float | n/a | Vector
Mag | float | 0 < Mag | Length of the vector

Return table
Identifier | Data type | Values | Comment
Vector | table[3]:float | n/a | scaled version of 'Vector'

Example


Sub

Sub( { Vector1, Vector2 } ) : { Vector }

substracts vector2 from vector1

Parameter table
Identifier | Data type | Values | Comment
Vector1 | table[3]:float | n/a | first vector
Vector1 | table[3]:float | n/a | second vector

Return table
Identifier | Data type | Values | Comment
Vector | table[3]:float | n/a | Vector1-Vector2

Example


Create

Create( { Object|Position, Radius, Visible, Wing } ) : { Waypoint }

Creates a wapoint at the given coordinates or at an object (moving with it). If the waypoint is entered, a 'Waypoint'-Event is fired. Waypoints are not visible by default.

Parameter table
Identifier | Data type | Values | Comment
Object | unsigned int | CObjectHandle | Handlewert eines Objekts
Position | table[3]:float | n/a | Position
Radius | float | 0.0f < Radius | Trigger radius
Visible | bool | default=false | Waypoint is visible (true) or invisible (false)
Wing | bool | default=CWingHandle() | WingHandle.

Return table
Identifier | Data type | Values | Comment
Waypoint | unsigned int | CWaypointHandle | Handle of the waypoint

Example

-- Create an waypoint at a freighter
V.WP = NWaypoint.Create( { Object=V.Trader, Radius=300 } ).Waypoint

--and in space
V.WP = NWaypoint.Create( { Position={ 2000, 0, 0 }, Radius=2000, Visible=true } ).Waypoint


Show

Show( { Waypoint, Show } ) : {}

Changes the visibility state of a given waypoint

Parameter table
Identifier | Data type | Values | Comment
Waypoint | unsigned int | CWaypointHandle | Handle of waypoint
Show | bool | n/a | show (true) or hide it (false)

Return table
empty

Example

-- Create a waypoint and show it.
V.WP = NWaypoint.Create( { Position={ 2000, 0, 0 }, Radius=200 } ).Waypoint
NWaypoint.Show( { Waypoint=V.WP, Show=true } )


AddAction

AddAction( { Wing, List, First, Actions } ) : {}

This function adds an order to the actionlist of a wing.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Wing which receives the order
List | unsigned int | LIST_ACTIVE ..LIST_PLAYER | Identifier from the actionlist
First | unsigned int | n/a | if this parameter exists, the already existing actionlist is deleted
Actions | table[n]:Action | n/a | Table containing one or more actions

Return table
empty
Parameter table for Actions
Identifier | Data type | Values | Comment
Type | unsigned int | AI_ACTION_INACTIVE .. AI_ACTION_STANDARD | Type description of the action
Speed | float | 0.0f .. 5.0f | Speed in meters per timestep
Handle | unsigned int | CHandle | A handle value (used by some types of events)
Position | table[3]:float | n/a | absolute coordinate

Return table
empty
The actionlist which is used for special situations
Wert | Comment
LIST_ACTIVE | The list which is active at the moment
LIST_SHIELD | this list will be activated if a ship looses its shield
LIST_FIRST_SHIP | this list will be activated if the first ship of a wing was destroyed
LIST_HALF | this list will be activated if half of the wing was destroyed
LIST_LAST_SHIP | this list will be activated if the wing has only one ship left
LIST_NO_ENEMY | this list will be activated if the wing has no enemies left
LIST_PLAYER | this list will be activated if the wing becomes an enemy to the player

The list of possible actions of a wing
Wert | Parameter | Comment
AI_ACTION_INACTIVE | ohne | Wing is motionless and will not react to attacks
AI_ACTION_STATIC | ohne | wing is static but will react to attacks
AI_ACTION_WAIT | ohne | Wing is inactive until it gets an entry in its target list
AI_ACTION_ATTACK | If the handle is a StarShipHandle or a WingHandle, it is added to the enemy list | The wing attacks all enemies in its enemy list.
AI_ACTION_CONTATTACK | If the handle is a StarShipHandle or a WingHandle, it is added to the enemy list | like AI_ACTION_ANGRIFF, but the wing will look for another target from the AI-Group
AI_ACTION_POSITION1 | Speed matters. PosX, PosY, PosZ is the target position. | The wing moves to the given coordinates. Turrets are firing, but ships won't alter thier heading.
AI_ACTION_POSITION2 | Speed matters. PosX, PosY, PosZ is the target position. | The wing moves to the given coordinates. The wing will alter its heading
AI_ACTION_OBJECT1 | Speed matters. Handle is a SpaceObject | Wing moves to that object. Enemies will not attacked
AI_ACTION_OBJECT2 | Speed matters. Handle is a SpaceObject | Wing moves to that object. Enemies will be attacked
AI_ACTION_LAND | Handle is a SpaceObject with a hangar (station or cruiser) | Wing lands on that object if no enemies are near.
AI_ACTION_LANDNOW | Handle is a SpaceObjects with a hangar | Wing lands on that object, even if enemies are near.
AI_ACTION_CIRCLE | Speed matters. | Like AI_ACTION_WARTEN but the wing is circulating around the actual position. Gets the wing an enemy, circulating will be interupted
AI_ACTION_PATROL | Speed matters. PosX, PosY, PosZ are absolute positions. | Here 4 or more positions may follow. The wing moves to each position.
AI_ACTION_PROTECT | Handle is a WingHandle, Position a direction vector from the leader of given handle to the leader of the Wing. | one wing protect another. The wing follows the other in an standard distance
AI_ACTION_GUARD | Handle is a ContainerHandle | The wing protects a container.
AI_ACTION_PICKUP | Handle is a ContainerHandle | the wing recovers a container
AI_ACTION_DROP | Handle is a ContainerHandle | If Handle is a container this container is dropped, else all ships are dropping thier container
AI_ACTION_HYPERJUMP | Handle must be a CStarHandle if it is the players wing | The wing jumps into hyperspace. Is the player in it, he jumps with it to the given system (camera incl.) A mission wing consisting out of AI-shipa will be deleted (WING_DESTROYED is called)
AI_ACTION_HYPERJUMPNOW | Handle must be a CStarHandle, if it is the players wing. | like AI_ACTION_HYPERRAUM but no ships from the enemy list will be attacked.
AI_ACTION_BOSSCIRCLE | Position and speed matters | The wing circles around a position. Speed is taken as radius. This state doesn't end if an enemy is entered in its target list.
AI_ACTION_ENTRY | Handle is a CStarHandle or a CWingHandle. | Wing battles enemies near it. Arrives the wing in a system the next action will be started.
AI_ACTION_ESCORT | Position and speed matters. | The wing moves to a position. Little ships (even leaders) may leave the formation to attack enemies.
AI_ACTION_FOLLOWSHIP | Position and handle matters. | Handle must be a ship of another wing, which should be followed. Position defines the direction of the ship to the leader of the following wing.
AI_ACTION_POSATTACK | Targetposition matters. | The given 3D position is flown at and fired upon.
AI_ACTION_ACTIONTURRET | Handle will be entered into the enemy list. | ActionTurret will attack
AI_ACTION_DESTROYOBJ | Handle is a static CSpaceObject | Wing will move in front of the object and fire its primary weapons.
AI_ACTION_GETLIST | without | A new action from the action list should start
AI_ACTION_STANDARD | dependent from Wing | Standard-Ai of Wings is started
AI_ACTION_POLICESCAN | Speed and target position matters. | This order only works with wings created as WINGTYPE_POLICE ! Wing moves to a position. The player ship is scanned if it is near.
AI_ACTION_SKAA_ATTACK | Handle of a CStarShip | This order only works with wings created as WINGTYPE_SKAA ! The wing attacks the ship
AI_ACTION_SKAA_ACTIONTURRET | without | This order only works with wings created as WINGTYPE_SKAA ! if a CActionTurret is active, the target will be attacked. Other targets will be ignored.

Example

-- Wing shall move to a position at once and start circulating there.
NWing.AddAction( {Wing=V.WingId, List=LIST_ACTIVE, First=1,Actions={ {Type=AI_ACTION_POSITION1, Speed=1.2, Position={2039.0,5095.0,-5393.0} },{Type=AI_ACTION_KREISEN,Speed=1.2} }})

-- When the wing only has one ship left, make it drop all containers and jump away
NWing.AddAction( {Wing=V.WingId, List=LIST_LAST_SHIP, First=1,Actions={ {Type=AI_ACTION_ABWERFEN},{Type=AI_ACTION_HYPERRAUM, Handle=V.StarId} } } )


AddEnemy

AddEnemy( { Wing, Target, Priority } ) : {}

Insert a new enemy into the enemy list of that wing. Target can be a WingHandle or a StarShipHandle. If a wing is entered, all ships of that wing are added with a priority. If a ship is added, only that ship is added with a priority. Is a ship in a wing all ships get the standard priority of 0.2 is used. Priority influences the target selection of the wing ships.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Wing, getting a new enemy
Target | unsigned int | CWingHandle or CStarShipHandle | New Target
Priority | float | > 0.0f | Wigthing of enemies

Return table
empty

Example


Create

Create( { WingType, Number, Level, LevelOffset, Names, Race, PosType, Position|Object|Distance|FrontDir|UpDir } ) : { Wing, PosLeader }

Creates a wing and returns its handle

Parameter table
Identifier | Data type | Values | Comment
WingType | unsigned int | Wing types | Type of the wing
Number | unsigned int | 0 .. 11 | Number of ships in the wing, 0 creates a standard wing
Level | unsigned int | 0 .. 30 | Enemy level
LevelOffset | int | -30 .. 30 | Enemy level is calculated as Player level + level offset.
Names | table[n]:string | n/a | A field of StringIDs. Ship i gets name index i+1. If there is no name it gets the last name in the list.
Race | int | RACE_RANDOM or RACE_HUMAN .. RACE_SKAA | if RACE_RANDOM the automatic race distribution (cluster based) is used
PosType | unsigned int | Creation areas | Constant, defining the area
Position | table[3]:float | n/a | absolute position in space
FrontDir | table[3]:float | n/a | direction of Z-axis
UpDir | table[3]:float | n/a | direction of Y-axis
Object | unsigned int | CHandle | Handle of that object
Distance | float | n/a | Distance to the given wing

Return table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handlevalue of the created wing
Position | table[3]:float | n/a | Leader position

Example

-- Hunter in Interception area
V.Wing = NWing.Create( {WingType=WINGTYPE_HUNTER, Number=0, Level=3, Race=RACE_MORTHOK, PosType=POSDESCR_INTERCEPTION} ).Wing

-- Pirate freighter at a defined position
V.PirFreighter = NWing.Create( {WingType=WINGTYPE_PIRATEFREIGHTER, Number=1, PosType=POSDESCR_EXPLICIT, Position={250.0, -4000.0, 8000.0} } ).Wing

-- a pirate wing 500m aside a pirate freighter
V.Pirate = NWing.Create( {WingType=WINGTYPE_RAIDERS, Number=4, PosType=POSDESCR_WINGDISTANCE, Object=V.PirFreighter, Distance=500.0 } ).Wing


Define

Define( { WingType, Ships, Names, PosType, Position|Object|Distance|FrontDir|UpDir } ) : { Wing, PosLeader }

Creates a wing and returns its handle

Parameter table
Identifier | Data type | Values | Comment
WingType | unsigned int | Wing types | Type of wing. Needs to be given, if the wing needs to have an non missionAI AI.
Ships | table[n]:ShipDef | n/a | Description of the ship
Names | table[n]:string | n/a | A field of StringIDs. Ship i gets name index i+1. If there is no name it gets the last name in the list.
PosType | unsigned int | Creation areas | Constant, defining the area
Position | table[3]:float | n/a | absolute position in space
FrontDir | table[3]:float | n/a | direction of Z-axis
UpDir | table[3]:float | n/a | direction of Y-axis
Object | unsigned int | CHandle | Handle of that object
Distance | float | n/a | Distance to the given wing

Return table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of created wing
Position | table[3]:float | n/a | Leader position

Parameter table for ShipDef

Identifier | Data type | Values | Comment
ObjType | unsigned int | StarShip Types | Kind of created ship
ObjIndex | unsigned int | n/a | Index of ship in StarShip.ini
Level | unsigned int | 0 .. 30 | Enemy level
LevelOffset | int | -30 .. 30 | Enemy level is calculated as Player level + level offset.

Example

-- a human hunter wing will be created at the interception area
V.Wing = NWing.Define( { WingType=WINGTYPE_HUNTER, Ships={{ObjType=ST_WINGMAN, ObjIndex=0, LevelOffset=0}, {ObjType=ST_WINGMAN, ObjIndex=1, Level=4}}, PosType=POSDESCR_INTERCEPTION} ).Wing

-- a mixed mission wing at a defined position.
V.Wing = NWing.Define( { Ships={{ObjType=WINGTYPE_MILITARY, ObjIndex=2, LevelOffset=2}, {ObjType=ST_ST_MILITARYFIGHTER, ObjIndex=1, Level=2}}, PosType=POSDESCR_EXPLICIT,Position={1000.0,1000.0,0.0}, FrontDir={-1.0,-1.0,0.0} } ).Wing


Destroy

Destroy( { Wing } )

Destroys the given Wing. There is no WING_DESTROYED event fired!

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of Wing

Return table
empty

Example


ExecuteAi

ExecuteAi( { Wing } ) : {}

This order forces a wing to rechoose a new AiAction. In that way a Stop-order can be carried out at once.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a Wing

Return table
empty

Example

NWing.ExecuteAi( { Wing=Pirates.Wing } )


IsHostileShip

IsHostileShip( { Wing, Ship } ) : { IsEnemy }

It is checked, if an given ship is an enemy of the wing

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a Wing
Ship | unsigned int | CStarShipHandle | Id of a StarShips

Return table
Identifier | Data type | Values | Comment
Hostile | bool | n/a | is set, if the ship is in the enemy list.

Example


List

List( { Wing } ) : { ShipList }

Returns the ship handles of all ships in that wing.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a Wing

Return table
Identifier | Data type | Values | Comment
ShipList | table[n]:unsigned int | CStarShipHandle | Handle values of all ships in wing

Example


MakeHostile

MakeHostile( { Wing } ) : {}

The player becomes an enemy to that wing

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a Wings

Return table
empty

Example


NoEnemy

NoEnemy( { Wing } ) : {}

Clears the enemy list of that wing. If that order is used with a group AI it is possible that the wing starts looking for other enemies. If two groups are fighting each other, both groups have to get the NoEnemy order to stop fighting.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a wing

Return table
empty

Example


Place

Place( { Wing, Position, Front, LookAt, BaseObj } )

Platziert den Leader eines Wings an der angegebenen Position undAusrichtung und platziert alle weiteren Schiffe auf ihre Wingpositionen.Wird 'BaseObj' angegeben, sind 'LookAt' und 'Position' Koordinaten imBezugssystem von 'BaseObj'.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a wing
Position | table[3]:float | n/a | Position of wing leader
Front | table[3]:float | n/a | direction of wing leader
LookAt | table[3]:float or unsigned int | Vector or CObjectHandle | Position or objekt, for the camera look at
BaseObj | unsigned int | CObjectHandle | Object relating to 'Position' and 'LookAt'

Return table
empty

Example


SetFormation

SetFormation( { Wing, Formation } ) : {}

Defines a formation for a wing

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a wing
Formation | unsigned int | Index from WingInfo.ini | Index of formations

Return table
empty

Example


SetInvalidEnemy

SetInvalidEnemy( { Wing, TypeId, Set } ) : {}

This order allows or disallowes a shiptype as enemy of a wing

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Id of a Wings
TypeId | unsigned int | Ship types | ship type, which should be allowed or not allowed
Set | int | int | returns if a ship type may be an enemy. else TypeID is not allowed.

Return table
empty

Example

-- this pirate wing may attack other pirate wings.
-- the wing will not attack members of his own AI group
NWing.SetInvalidEnemy( { Wing=Pirates.Wing, TypeId=ST_PIRATESHIP, Set=0 } )

-- This piratewing is not allowed to attack the player
NWing.SetInvalidEnemy( { Wing=Pirates.Wing2, TypeId=ST_PLAYERSHIP } )


SetPlayerEntryPos

SetPlayerEntryPos( { Position, Front, Updir } ) : {}

If the players wing should enter a system at a different position than the hypergate. The position must be entered at the PREFADE-Event.

Parameter table
Identifier | Data type | Values | Comment
Position | table[3]:float | n/a | Position, where the wing should enter the system.
Front | table[3]:float | n/a | Direction, entering the system
Updir | table[3]:float | n/a | Up direction for the wing

Return table
empty

Example


Scripting events

Mission scripts in DSO are event-based. A script is only executed if an event was called which has an corresponding event-filter. These filters are automatically included if an event name is included in a transition.

If an event occures all missions, which have registert that event in a transition, will be executed. The transitions analyse the table of parameters, execute user code and put data in the returntable. After the return from the script to the c-program the event is handled by the program itself.

The transition contains 2 parameters - the datatable V from the mission and the datatable from the event, containing all information about itself.

Some events return values. This is done like at functions via a return-datatable, which contains named values.

The documentation uses following pattern
  • < Name of the Event > : < Parametertable > : < Returntable >
  • Object starting the event
  • Parametertable
  • Returntable
  • Examples
Italic names show optional parameters. In that case a default-parameter or default-range is shown after the descriptinon. If there is no entry all values of that datatype are valid. Explanations to the datatypes are shown under "Datatypes".


ActionCamEnd

ActionCamEnd : { Camera } : {}

A camera is about to be destroyed, the camera objects still exists though.

Trigger
Destruction of a camera which was created by the program or by a script.

Parameter table
Field identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the destroyed camera

Return table
empty

Example

{
    1.001, 1.007, "ActionCamEnd",
    function( V, Data )
        if V.Cam == Data.Camera then
            V.Cam = nil
        end
    end
}


ActionCamEnd

ActionCamStart : { Camera } : {}

A camera starts recording.

Trigger
On the program's side by setting of a new active camera.

Parameter table
Identifier | Data type | Values | Comment
Camera | unsigned int | CCameraHandle | Handle of the camera that is becoming active.

Return table
empty

Example

{
    1.001, 1.007, "ActionCamStart",
    function( V, Data )
        if V.Cam == Data.Camera then
            ...
        end
    end
}


Create

Canyon : { Event, Segment, Handle } : {}

An event has occurred within the canyon.

Trigger
The player is entering or leaving the canyon.
The player is moving through the canyon and switching the segment.
The player is passing through a force field.

Parameter table
Identifier | Data type | Values | Comment
Event | enum | CANYON_ENTER, CANYON_LEAVE, CANYON_SEGMENT, CANYON_TRIGGER | The event
Segment | unsigned int | n/a | The segment the player has now entered (Only applies to CANYON_SEGMENT events).
Handle | unsigned int | CStaticObjectHandle | Handle of the event-triggering object.

Return table
empty

Example

{	-- Player is switching the canyon segment
    1.001, 1.007, "Canyon", function( V, Data )
    if CANYON_SEGMENT == Data.Event then
        -- Is the player switching to segment 5?
        if 5 == Data.Segment then
            -- Create an enemy
            ...
        end
    end
end }


CommEnd

CommEnd : { Message } : {}

A radio message has ended.

Trigger
End of a radio message, created either by the program or by scripts.

Parameter table
Identifier Data type Values Comment Message unsigned int n/a ID of the message

Return table
empty

Example

{   -- Waiting for CommEnd
    1.001, 1.001, "CommEnd",
    function( V, Data )
        if Data.Message == V.Comm then
            V.TimerId = NMission.CreateTimer( { Time=3 } ).Timer
            V.Step = 1.002
        end
    end
}


Communication

Communication : { Type, Object } : {}

Events all around standard dialogues.

Trigger
The player has pressed the "communication" key
A dialog is being started via the TriggerDialog() command.
The player selects one of the options in a standard dialogue.

Parameter table
Identifier | Data type | Values | Comment
Type | enum | COMMTYPE_LANDING_FORBIDDEN, COMMTYPE_LANDING_DENIED, COMMTYPE_LANDING_GRANTED, COMMTYPE_LANDING_CLEARED, COMMTYPE_DLG_START | Type of response
Object | unsigned int | CObjectHandle | Handle value of the object involved in the dialogue.

Return table
Identifier | Data type | Values | Comment
BlockDlg | bool | n/a | If "CommType" was equal to "COMMTYPE_DLG_START" then a "BlockDlg" == true will prevent starting of the dialogue.
Object | unsigned int | CObjectHandle | Handle value of the object involved in the dialogue.


Dialog

Dialog : { Owner, Input } : { Text, Voice, Video, Inputs }

A dialogue between a player and another object is ongoing. The mission needs to provide texts and choices for replies. The "Inputs" list contains pairs of one StringId and one number. The number will be returned to the mission if this reply was chosen.

Trigger
The starting of a dialogue to which the mission has linked.

Parameter table
Identifier | Data type | Values | Comment
Owner | unsigned int | CObjectHandle | Handle des Dialogobjekts
Input | int | 0<=Input, -1==Input, -2==Input | Input index of the player, -1== start of the dialogue, -2==end of the dialogue

Return table
Identifier | Data type | Values | Comment
Text | string | StringId from the string database | text to display
Voice | string | Identifier of a stream resource from the "KlangErzeugerDefault.xml". | Stream to play
Video | string | n/a | Complete path leading to a *.bik video.
Inputs | table[n]:{ string, int } | N pairs of one StringId and one integer number | Choices for the player


MovieFinished : {} : {}

A cutscene has been played.

Trigger
The program triggers this event after finishing the video.

Parameter table
empty

Return table
empty


Achieved

Achieved : {} : { Timeout, Credits, Text, Keys }

The mission has been completed successfully. An info text will be displayed (default "Mission accomplished") and the accompanying jingle will be played. The mission will be put into status MSTATE_IDLE and no further events will be forwarded to the mission. If system shall be unlocked as a reward then the "keys" parameter should be used. Manual unlocking using NStarsystem.Unlock() will show the unlocked-message before "Mission accomplished" which should be avoided.

Trigger
Call from a script using NMission.SetState({ State = MSTATE_ACHIEVED })

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Timeout | int | n/a | Timeout of the mission in days; 0 == will be offered instantly, <0== will never be offered again
Credits | unsigned int | n/a | Amount of credits to transfer to the player
Text | string | StringId from the string database, default = <StringId of "Mission accomplished"> | Info text to display
Keys | table[n] : unsigned int | List of system numbers (0-399) | A list of all systems to unlock

Example

{   -- Mission successful, award a system key and do not offer the mission again
    0, nil, "Achieved",
    function( V, Data )
        NStar.StarUnlock( 19 )
        NPlayer.AddCredits( NPlayer.StandardReward() )
        return { Timeout=-1 }
    end
}


Create : {} : {}

A mission was created and is now active.

Trigger
Creation of the mission by the program itself or
call from script using NMission.Create()

Parameter table
empty

Return table
empty

Example

{   -- Mission was created
    nil, nil, "Create",
    function( V, Data )
        -- do something
    end
}


Destroy : {} : {}

The mission was destroyed and will be permanently removed after this call.

Trigger
Destruction of the mission by the program itself
As a result of the events "Achieved" or "Failed" with a supplied "Timeout" parameter of 0.
Call from a script using NMission.SetState({ State = MSTATE_ENDED })

Parameter table
empty

Return table
empty

Example

{   -- Cleaning up
    nil, nil, "Destroy",
    function( V, Data )
        -- Unmark these two systems
        NStar.SystemMissionTarget( V.System0, 0 )
        NStar.SystemMissionTarget( V.System1, 0 )
    end
}


Failed

Failed : {} : { Timeout, Text }

The mission has failed. An info text will be displayed (default "Mission failed") and an accompanying jingle will be played. The mission will be put into the state MSTATE_IDLE and no further events will be forwarded to the mission.

Trigger
Call from the script using NMission.SetState({ State = MSTATE_FAILED })

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Timeout | unsigned int | n/a | Timeout of the mission in days, 0==will be instantly offered again, -1==will never be offered again
Text | string | StringId from the string database, default = <StringId of "Mission failed"> | Info text to display

Example

{
    0, nil, "Failed", function( V, Data )
    if 100.0 == V.Step then
        return { Timeout = -1 }
    else
        return { Timeout = 0 }
    end
end }


Init

Init : {} : { Ready }

The mission is to be created. The handler for this event needs to check if all preconditions for creation are met. If so, it must return "Ready" with a value of "true" in its return table.

Trigger
Creation of the mission by the program.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Ready | bool | n/a | true, if the mission is allowed may be created

Example

{
    nil, nil, "Init", function( V, Data )
    local system = MissionLib.GetStarSystemId()
    if 12 == system
    or 13 == system
    or 14 == system
    or 15 == system then
        V.System0   = 16;
        V.System1   = 12;
        V.System2   = 17;
        V.Pirates = {}
        return { Ready=true }
    end
    return { Ready=false }
end }


MissionStart : {} : {}

The mission will finally be created.

Trigger
Starting up of the mission by the program
Call from a script using NMission.SetState( { State=MSTATE_RUNNING } )

Parameter table
empty

Return table
empty

Example

{   -- It's on!
    nil, nil, "MissionStart",
    function( V, Data )
        V.Step = 1.0
        Logic.SystemMissionTarget( V.System0 )
    end
}


SubType

Subtype : {} : { Subtype }

The program wants to retrieve the subtype of the mission. Usually only necessary for terminal missions.

Trigger
Creation of a mission by the program.

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Subtype | enum | SUBTYPE_TRANSPORT, SUBTYPE_HEADHUNT, SUBTYPE_PIRATES, SUBTYPE_SABOTAGE, SUBTYPE_PROTECT, SUBTYPE_RESCUE, SUBTYPE_POLITICAL | Subtype of the mission, used for selection and display in the mission terminal.

Example

{
    nil, nil, "Subtype",
    function( V, Data )
        return { Subtype=SUBTYPE_POLITICAL }
    end
}


Text

Text : { NPC } : { Header, Client, Text, Replace, Credits }

The program requests text. The return text can be different dependent from the internal state of the mission. If "Replace" contains a list of StringIds, these will be used to fill placeholders within "Text". Replacement will be done in the order of the "Replace" table where Replace[1] substitutes %1 in "Text".

Trigger
The player opens the mission terminal.
The player opens the logbook

Parameter table
Identifier | Data type | Values | Comment
NPC | unsigned int | CNPCHandle | Handle of an NPC if the text shall be delivered by one.

Return table
Identifier | Data type | Values | Comment
Header | string | StringId aus dem LokaTool | The headline
Client | string | StringId aus dem LokaTool | The contractor who offers the mission
Text | string | StringId aus dem LokaTool | Text to display
Replace | table[n]:string | Table with StringIds from the string database | These are optional fillers for placeholders in "Text"
Credits | unsigned int | default=StandardReward | displayed reward

Example

{   -- Show the logbook entry
    nil, nil, "Text", function( V, Data)
    if 1 > V.Step then
        return {
            Text = "IDM_HUMAN_003_LOG_CH01_0",
            Header = "IDM_HUMAN_003_HEADER",
            Client = "IDL_TRADER_02_0"..V.Combine,
            Replace =
            {
                "IDM_HUMAN_003_TADENITNAME",
                "ID_SYSTEMNAME_"..V.StartsystemId
            } }
    else
        return { Text = "IDM_HUMAN_003_LOG_CH01_1" }
    end
end }


Timer

Timer : {} : { Timer }

A previously created timer has run down.

Trigger
As a result of a timer event which was previously created by a script using NMission.CreateTimer().

Parameter table
Identifier | Data type | Values | Comment
Timer | unsigned int | CEventHandle | Handle of the timer event

Return table
empty

Example


Container

Container : { Container, Action, Ship } : {}

A container has been manipulated. If it was dropped then the Ship Id will be held in "Ship". This may also be a cargo drone of the player. Has the container been picked up by a drone then the Ship Id to which the drone belongs will be held in "Ship".

Trigger
Triggered by the program after manipulation of a container

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container
Ship | unsigned int | CStarShipHandle | CONTAINER_DROPPED: Ship which dropped the container. CONTAINER_TAKEN: Ship to which the container belongs
Action | enum | CONTAINER_TAKEN, CONTAINER_DROPPED, CONTAINER_DESTROYED, CONTAINER_METEROID | Action done to the container

Return table
empty


Waypoint

Waypoint : { Waypoint, Leaving, Ship, Wing } : {}

A waypoint was reached. The waypoint may not be deleted!

Trigger
The player is entering or leaving the triggering radius of a waypoint

Parameter table
Identifier | Data type | Values | Comment
Waypoint | unsigned int | CWaypointHandle | Handle of the waypoint
Leaving | bool | n/a | Player is leaving(true) or entering(false)
Ship | unsigned int | CStarShipHandle | The ship which triggered the waypoint event
Wing | unsigned int | CWingHandle | The wing of the triggering ship

Return table
empty


Artefact: {} : {}

The player has received an artifact

Trigger
The player has received an artifact

Parameter table
empty

Return table
empty

Example


Bar

Bar : { System, Enter } : {}

The player is entering or leaving a space station's bar (obsolete).

Trigger
Player clicks the "Bar" Button in the main hall
Player clicks the "Leave" Button in the bar

Parameter table
Identifier Data type Values Comment System unsigned int CStarHandle Handle of the space station's system Enter bool n/a Player is entering(true) or leaving(false)

Return table
empty


CriminalRecord

CriminalRecord : { System, Record } : {}

The system's criminal record of a player has changed.

Trigger
The player receives or loses crime points in a system.

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | CStarHandle | Handle of the system
Record | float | 0.0f < Record | Current score

Return table
empty


Equipment

Equipment: { Type, Level } : {}

The player is changing his ship equipment

Trigger
The player is buying a new piece of equipment

Parameter table
Identifier | Data type | Values | Comment
Type | enum | EQUIPMENT_AFTERBURNER, EQUIPMENT_CAPACITOR, EQUIPMENT_CARGO_COMPUTER, EQUIPMENT_GENERATOR, EQUIPMENT_HYPERDRIVE, EQUIPMENT_SCANNER, EQUIPMENT_SCANNER_JAMMER, EQUIPMENT_SHIELD_GENERATOR | Type of equipment
Level | unsigned int | n/a | Level of the piece of equipment

Return table
empty


Grab

Grab : { Container, HasGrabbed } : {}

A cargo drone has docked with a container OR the player is now able to pick up a container (by sending a drone).

Trigger
Drone is docking with the container
The container is close enough and a drone may be launched

Parameter table
Identifier | Data type | Values | Comment
Container | unsigned int | CContainerHandle | Handle of the container
HasGrabbed | bool | n/a | The player is now able to pick it up(false), the player has picked up(true)

Return table
empty


Hostile

Hostile : { Enemy } : {}

The player has just become hostile towards a wing

Trigger
Program-internal logic of the wing
Through manipulation of the enemy list of the wing

Parameter table
Identifier | Data type | Values | Comment
Enemy | unsigned int | CWingHandle | Handle of the wing which has become hostile

Return table
empty


Item

Item: {} : { Item }

The program is asking the mission for a special item which the player can use utilizing the "Use" key.

Trigger
The player is opening the use-screen

Parameter table
empty

Return table
Identifier | Data type | Values | Comment
Item | string | StringId from the string database | The name of the item to display


PlayerScanned

PlayerScanned: { illegal } : {}

The player is being scanned by the police. "illegal" is set to true if the player carries illegal goods on board and is being attacked therefore.

Trigger
A police ship has scanned the player

Parameter table
Identifier | Data type | Values | Comment
illegal | bool | n/a | Is true, if illegal goods were detected.

Return table
empty


Scan

Scan: { Target } : {}

The player is scanning a space object.

Trigger
The player is scanning a CSpaceObject

Parameter table
Identifier | Data type | Values | Comment
Target | unsigned int | CObjectHandle | Object being scanned

Return table
empty


Station

Station : { System, Enter } : {}

The player is landing on a space station or launching from it.

Trigger
The player is entering the hangar with a valid landing permit and will switch to inside view of the station.
The player is clicking the "Leave" button in the station's hall

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | CStarHandle | Handle of the system the station is in
Enter | bool | n/a | Player is entering(true) oder leaving(false)

Return table
empty


System

System : { System, State } : {}

The player is entering of leaving a star system

Trigger
By reaching a system via the hypergate (at various stages during entry, see below).
By entering hyperspace

Parameter table
Identifier | Data type | Values | Comment
System | unsigned int | CStarHandle | Handle of the system
State | enum | ENTER_PREFADE, ENTER_PRECAM, ENTER_POSTCAM, LEAVE_SYSTEM | The player is entering of leaving a system. ENTER_PREFADE,ENTER_PRECAM, ENTER_POSTCAM are different stages during entry of the system.

Return table
empty

Values for State
Wert | Comment
ENTER_PREFADE | Player is entering the system while the tunnel is still visible.
ENTER_PRECAM | The tunnel is now being shut down
ENTER_POSTCAM | The player has reassumed control of his ship
LEAVE_SYSTEM | The player is leaving the system


TargetSelect

TargetSelect : { Target } : {}

The player has selected a target

Trigger
The player is selecting a target using the target list or target selection keys.

Parameter table
Identifier | Data type | Values | Comment
Target | unsigned int | CObjectHandle | Handle value of the selected object

Return table
empty


Use : {} : {}

(preliminary) The player has used an item

Trigger
The player is activating the "use" key.

Parameter table
empty

Return table
empty

Example


Run : {} : {}

The simulation has begun a new time step. You should have good reasons to have your script handle this event, timers are often the better choice.

Trigger
Triggered by the program when calculating the new time step.

Parameter table
empty

Return table
empty


Shield

Shield : { Ship, Wing, Event, ShieldType } : {}

The shield of a ship reaches or drops below a certain threshold value.

Trigger
By the program when the shield status of any ship drops below one of the threshold values.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship
Wing | unsigned int | CWingHandle | Handle of the ship's wing
Event | enum | SHIELD_HALF, SHIELD_DOWN | Shield status
Shieldtype | enum | SHIELD_BACK, SHIELD_FRONT, SHIELD_BOTH | The affected shield

Return table
empty


StarShip

StarShip : { Ship, Event } : {}

Shield or hull status are dropping below a certain threshold. Watch the spelling: Star*S*hip!

Trigger
The ship was hit or rammed and one of the thresholds was reached.

The ship has landed in a hangar (and will be destroyed by the internal logic).

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship
Wing | unsigned int | CWingHandle | Handle of the ship's wing
Event | enum | see table below | Type of event

Return table
empty

Types of events described by parameter "Event"
Wert | Beschreibung
SHIP_SHIELD_50 | The shield status of the ship has dropped below 50%.
SHIP_SHIELD_25 | The shield status of the ship has dropped below 25%.
SHIP_SHIELD_0 | The shield status of the ship has dropped to 0% (This may be triggered on every hit once it was reached).
SHIP_HULL_75 | The hull status of the ship has dropped below 75%.
SHIP_HULL_50 | The hull status of the ship has dropped below 75%.
SHIP_HULL_25 | The hull status of the ship has dropped below 25%.
SHIP_HULL_10 | The hull status of the ship has dropped below 10%.
SHIP_LANDED | The ship has landed in a hangar(and will thereafter be destroyed)


StarshipDeath

StarshipDeath : { Ship } : {}

The hull condition of a ship reaches 0% and the death animation of the ship starts. Large ships will always play a death animation, small ships do so only occasionally

Trigger
By the program when the hull reaches 0%.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship

Return table
empty


StarshipDestroyed

StarshipDestroyed : { Ship, Wing, Killer } : {}

The hull condition of a ship was reduced to 0% and the ship is being destroyed. This will happen after an eventual death animation of the ship. This will NOT be called if the ship was deleted, for instance when the wing enters hyperspace.

Trigger
By the program, immediately before deletion of the ship.

Parameter table
Identifier | Data type | Values | Comment
Ship | unsigned int | CStarShipHandle | Handle of the ship
Wing | unsigned int | CWingHandle | Handle of the ship's wing
Killer | unsigned int | CStarShipHandle | Handle of the ship which scored the lethal hit (may also contain an invalid value).

Return table
empty


Tutorial

Tutorial : { Element } : {}

Specific elements of the game are being activated. These events were mainly used for the tutorials.

Trigger
The player is pressing certain keys, buttons, closing screens or doing other things.

Parameter table
Identifier | Data type | Values | Comment
Element | enum | TUTORIAL_ONCLICK_NAVMAP, TUTORIAL_ONCLICK_TARGETMAP, TUTORIAL_ONCLICK_HYPERJUMP, TUTORIAL_ONCLICK_CLUSTERMAP, TUTORIAL_ONCLICK_PLAYERCRUISER, TUTORIAL_ONCLOSE_NAVMAP, TUTORIAL_ONCLOSE_TARGETMAP, TUTORIAL_ONCLOSE_CLUSTERMAP, TUTORIAL_ONCLOSE_PLAYERCRUISER, TUTORIAL_ONHAS_HYPERJUMP, TUTORIAL_ONHAS_LANDING | Action of the player. TUTORIAL_ONCLICK_PLAYERCRUISER is an obsolete value. ONCLICK means opening and ONCLOSE closing of a screen. TUTORIAL_ONHAS_HYPERJUMP means the hyperdrive is fully loaded.

Return table
empty


TutorialPopup

TutorialPopup : { Popup } : {}

The tutorial popup was closed

Trigger
The player is closing one of the tutorial popups.

Parameter table
Identifier | Data type | Values | Comment
Popup | unsigned int | n/a | ID of the popup screen

Return table
empty


Wing

Wing : { Wing, Event } : {}

A wing has performed one of several actions or a special situation occurs. The "Event" parameter provides more information (see table below).

Trigger
A wing has performed one of several actions or a special situation occurs.
Will also be triggered when a wings enters hyperspace and is about to be deleted by the internal logic.

Parameter table
Identifier | Data type | Values | Comment
Wing | unsigned int | CWingHandle | Handle of the wing
Event | enum | WING_NO_TARGET, WING_DESTROYED, WING_TARGET_REACHED, WING_ENTER_SYSTEM.. | Type of event.

Return table
empty

Type table for the "Event" parameter
Value | Description
WING_NO_TARGET | The wing is out of targets to attack (It previously had targets).
WING_DESTROYED | The last ship of the wing was destroyed and the wing is about to be deleted.
WING_TARGET_REACHED | The wing has reached a previously assigned destination in space.
WING_ENTER_SYSTEM | All ships of the wing have entered the active star system.
WING_LEAVE_SYSTEM | All ships of the wing are about to leave the active star system.
WING_SHIP_SHIELDDOWN, | A ship of the wing has lost its shield (shield status 0%).
WING_SHIP_DESTROYED_1 | The wing has lost its first ship.
WING_SHIP_DESTROYED_2 | The wing has lost half of its ships.
WING_SHIP_DESTROYED_3 | The wing only has one ship remaining.
WING_SHIPS_LANDED | The last ship of the wing has landed in a hangar.
WING_FIRST_ENEMY | The enemy list of the wing was empty but now contains at least one enemy again.
WING_CARGO_GRABBED | The wing has finished its order to pick up a container. The container has not necessarily been picked up (The order may have been aborted).


CameraLib

Which camera is the right one?

Special Cameras like "Menace" should be used according to this document. It is necessary to try different cameras to find the optimal camera because it is depending on the game / purpose. This list contains proposals which camera is the right one for a special situation.
Situation | Camera | Parameter / Comment
Menace | MenaceWing / MenaceWingStrong / MenacePlayerWing | Camera is flying directly onto the specified Wing. The "Strong"-version is more dynamic. MenacePlayerWing tries to include the player in the camerapath, but the orientation is not optimal.
Dialog | TalkCamLeader / TalkCamFollower / TalkCamBoth | Camera is hovering infront of the "Talker". For longer conversation of a hunter to the player the FlyPara is the better choice (you should align both bevor). In some situations cameras like "ShowShip" or "ZoomAway" show better results.
Show special ships | ShowShip / BigBoy | Both circeling around a ship (parameter is a wing!). Adjust the zoom!
Show a frighter | ZoomAway | Camera moves from the cockpit to the right back away, so that the focus is on the cargo.
Show station | ShowStation | Shows great Objects, which shouldn't move.
Freighter (or hunter) dropping off cargo | ContainerDrop | Camera is infront of dropping ship and centers container
long monolog | FlyPara | Camera circulates the talking guy and then switches to the position right (in flightdirection) where the player should be located.
Artefact container | RewardContainer | Rotates the camera to an object.

Hints

Think about the 4 points, when using cameras:

  • If you use a nil in the returntable it can come to crashes. Look into the CameraLib!
  • Timing
    • It's no good idea to take away the players control while using cameras. You should not to often use the MenaceCam, because there is a danger showing - a danger the player wishes to eliminate and not to watch the enemy destroy his ship.
    • CommEnd - Especially dialogcams must be endet on this way. There are used with long durations, ending with the ending of the comm. Cameras on spline will become slow when the duration is big. Its better to use a "last camera" with a short duration to get the "Black out" and to end the camera with CommEnd.
  • Zoom - most of the cameras are adjusted to special shipsizes (a hunter or container). Therefore always check if the zoom is wrong. This can be used creativly, e.g. with a zoom of 100 you could make a wounderful circulation of the whole universe!
  • Crash - The function NCamera.Destroy({Camera=CamHandle}) destroys only the running camera, is there no camera running Darkstar will crash. Is another camera in the list, it wont be deleted. There is a trick to create a dummy camera with parameter immediate = True, and then to destroy this cam.


AlignPlayerToWing

Syntax

AlignPlayerToWing (WingId, Position)

Description
Starts this named camera sequence

Example
V.Camera = CameraLib.AlignPlayerToWing(V.Wing, V.Pos)


AlignWingToPlayer

Syntax

AlignWingToPlayer (WingId, Position)

Description
Starts this named camera sequence

Example
V.Camera = CameraLib.AlignWingToPlayer(V.Wing, V.Pos)


BigBoy

Syntax

BigBoy (WingId, Time)

Description
Camera does a flyby at "WingID" to show the size of the object. Duration is dependent on speed and size of the wingID.

Example
V.Camera = CameraLib.BigBoy(V.Wing, 20)


CamSequenz

Syntax

CamSequenz (WingID, CamNumber, WaitForCommEnd)

Description
Camera shows the targetwing from a fixed position.

Example
V.Camera = CameraLib.CamSequenz( V.TestWing, 0, 0 )


CloseUpWingLeader

Syntax

CloseUpWingLeader (WingId)

Description
Shows a closeup of the wing leader from behind (very near)

Example
V.Camera = CameraLib.CloseUpWingLeader(V.Wing)


ContainerDrop

Syntax

ContainerDrop (WingId, ContainerId, Time)

Description
Shows the ship (dropping the container) for a short time. After that the dropped container is shown.
Note! The container must be dropped manually in the function starting the camera.
Recomended duration: 10 seconds.

Example
V.Camera = CameraLib.ContainerDrop( V.TestWing, V.TestConti, 10 )


EnterCamPlayer

Syntax

EnterCamPlayer ()

Description
Camera flys into the playership

Example
V.Camera = CameraLib.EnterCamPlayer()


EnterCamWing

Syntax

EnterCamWing ((WingId, Time))

Description
Camera from the right position in front of the wing, turns to the left and enters the cockpit of the wing leader. Duration is dependent on ship size and speed.

Example
V.Camera = CameraLib.EnterCamWing(V.Wing, 20)


FlyPara

Syntax

FlyPara (WingId, Time)

Description
Left turn around the wing leader. Wingman are shown. Camera ends in the leaders ship.

Example
V.Camera = CameraLib.FlyPara(V.TestWing, 20)


FreighterHyperspace

Syntax

FreighterHyperspace (WingId)

Description
WingID will be followd until the hyperjump occurs.

Example
V.Camera = CameraLib.FreighterHyperspace(V.Wing)


getNewCameraPos_MetricBias

Syntax

getNewCameraPos_MetricBias (WingId, Position, bias)

Description
Returns coordinates for a relative camera position. Parameter1 is the camera target, parameter2 a position in space and parameter3 is an integer value (meters) defining the bias on the vector Parameter1-Parameter2.

Example
V.newPos = CameraLib.getNewCameraPos_MetricBias(V.Wing,V.old_pos,15)


getNewCameraPos_ParametricBias

Syntax

getNewCameraPos_ParametricBias (WingId, Position, bias)

Description
Returns coordinates for a relative camera position. Parameter1 is the camera target, parameter2 a position in space and parameter3 is an float value (multiplier) defining the bias on the vector Parameter1-Parameter2. A multiplier value 0 is the targetposition, 1 is the V.old_Pos value.

Example
V.newPos = CameraLib.getNewPos_ParametricBias(V.Wing,V.old_pos,0.5)


JoinCam

Syntax

JoinCam (WingId)

Description
If the player joins a wing, the camera flies a halve circle around the target wing, afterwards the wing is shown from a fixed position. Then the player ship enters the wing (shown from behind)

Example
V.Camera = CameraLib.JoinCam(V.WingId)


MenacePlayerWing

Syntax

MenacePlayerWing (WingId, Time)

Description
Shows the player from behind, then the WingID is focused. The camera flies past the WingID. After a cut the WingID is shown again. Recomended max. duration: >20 sec.

Example
V.Camera = CameraLib.MenacePlayerWing(V.Wing, 20)


MenaceWing

Syntax

MenaceWing (WingId, Time)

Description
Camera comes from the right directly on to the wing, turns to the left around the ship and brings the camera infront of the leaders cockpit. Recomended max. duration: 15 sec.

Example
V.Camera = CameraLib.MenaceWing(V.Wing, 20)


MenaceWingStrong

Syntax

MenaceWingStrong (WingId, Time)

Description
Camera flies fast onto the wing, past ahead and turns around to follow the wings leader. max. duration : 15 sec.

Example
V.Camera = CameraLib.MenaceWingStrong(V.Wing, 15)


PassBy

Syntax

PassBy (WingId, Time)

Description
Camera flies past the target. Duration is dependet from ships speed and size.

Example
V.Camera = CameraLib.PassBy(V.Wing, 20 )


PlanetenCam

Syntax

PlanetenCam (WingId, Position)

Description
Shows from different perspectivs the moving target until it is no longer visible. The last shot shows the origin of the target.

Example
V.Camera = CameraLib.PlanetenCam(V.Wing)


PSTotalBack

Syntax

PSTotalBack (WingId)

Description
Camera moves from the player ship to a target. Recomended duration: 100sec. Should be endet with CommEnd.

Example
V.Camera = CameraLib.PSTotalBack(V.Wing)


TalkCamBoth

Syntax

TalkCamBoth (WingId)

Description
Shows the target wing from a fixed position. Default duration: 100 sec. The camera must be destroyed manually with the NCamera.Destroy() command.

Example
V.Camera = CameraLib.TalkCamBoth(V.Wing)


TalkCamFollower

Syntax

TalkCamFollower (WingId)

Description
A fixed camera shows a wing flying away. Default duration: 100 sec. Must be ended with NCamera.Destroy().

Example
V.Camera = CameraLib.TalkCamFollower(V.Wing)


TalkCamLeader

Syntax

TalkCamLeader (WingId)

Description
Camera moves from left to right to show the wing leader. Default duratiom: 100 sec. Must be endet with NCamera.Destroy().

Example
V.Camera = CameraLib.TalkCamLeader(V.Wing)


TestSpline

Syntax

TestSpline (Number, Time, Zoom)

Description
uses a defines spline (number must be given between 0-23) Always targets to the player ship. Time and zoom are optional.

Example
x = TestSpline(23,10,1)


ZoomAway

Syntax

ZoomAway (WingId, Time)

Description
Camera zooms away from the front of the WingId. Recomended max. duration: < 20 sec.

Example
V.Camera = CameraLib.ZoomAway( V.Wing, 15 )


ZoomWingCam

Syntax

ZoomWingCam (WingId, Position)

Description
A short shot on the target wing, then a fixed camera shows the target wing. Default duration 100 sec. Will be ended with CommEnd.

Example
V.Camera = CameraLib.ZoomWingCam(V.WingId, V.Position)


GetObjectDistance

Syntax

GetObjectDistance (Obj1, Obj2)

Description
returns the distance between 2 objects. Returns nil if on parameter is nil.
Obj1 = Handle of object1.
Obj2 = Handle of object2.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
V.Con1=NContainer.Create({
    Type=CONTAINER_SPACE,
    Size=CONTAINER_SMALL,
    PosDesc=POSDESCR_TRADESTATION1
}).Container
V.Con2=NContainer.Create({
    Type=CONTAINER_SPACE,
    Size=CONTAINER_SMALL,
    PosDesc=POSDESCR_TRADESTATION2
}).Container
local _condist=MissionLib.GetObjectDistance( V.Con1, V.Con2 )


GetObjectType

Syntax

GetObjectType (Object)

Description
returns a table with the type of that object. An object can be a ship, a wing or an orbiter.

Rückgabetabelle
name of field, datatype, range of values, comments

Type String "Orbiter" and "Ship" means: Object is a ship or Orbiter.
ObjType CConst Ships, Orbiter returns a constant of the object.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
local wing = MissionLib.GetObjectType( V.TestWing )


GetChapterState

Syntax

GetChapterState (Mission, Chapter)

Description
Returns the state of the chapter

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
-- Last chapter must be finished
if "true" == MissionLib.GetChapterState( "IDM_HUMAN_003", 2 ) then
    return { Ready = true }
else
    return { Ready = false }
end


IsMissionDone

Syntax

IsMissionDone (MissionName)

Description
Returns true,if the missin is done

Example


IsMissionInRegister

Syntax

IsMissionInRegister (Mission)

Description
Test to see whether the mission was registered

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
-- last chapter must be done
if "true" == MissionLib.IsMissionInRegister( "IDM_XYZ") then
    -- Code for true
else
    -- Code for false
end


LogNewTask

Syntax

LogNewTask ()

Description
Shows the Message: "Mission obtained"

Example


LogStoryAchieved

Syntax

LogStoryAchieved ()

Description
creates the Message "Mission accomplished"

Example


LogUpdateStory()

Syntax

LogUpdateStory() ()

Description
creates the Message "New Mission target"

Example


LogUpdateTask

Syntax

LogUpdateTask ()

Description
creates the Message "Mission updated"

Example


RegisterMission

Syntax

RegisterMission (Mission)

Description
registers a Mission

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.RegisterMission("IDMXYZ")


SetChapterState

Syntax

SetChapterState (Mission, Chapter, Value)

Description
Sets the state of a chapter

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.SetChapterState("IDMXYZ", 1, "false")


SetMissionDone

Syntax

SetMissionDone (MissionName)

Description
Declares a mission as done. If you use 'SetMissionDone' and 'IsMissionDone' for long missionparts be sure not to start a mission again when the last part is done.

Example


UnregisterMission

Syntax

UnregisterMission (Mission)

Description
Removes a registered mission and all dependend data

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.UnregisterMission("IDMXYZ")


DropContainerFromList

Syntax

DropContainerFromList (Ship, ContainerList)

Description
Example


GetCargoList

Syntax

GetCargoList (maximum)

Description
Example


LoadCargo

Syntax

LoadCargo (Ship)

Description
Example


SetRandomCargo

Syntax

SetRandomCargo (table)

Description
Example


ContainerSQR

Syntax

ContainerSQR (Containersize, Pos, Count, Dist , Row ,Col)

Description
Creates a matrice of containers with parameters.
Containersize = Size
Pos = Position vector {}
Count = number of Containers
Dist = Distance between Containers
Row = number of rows
Col = number of colums

Note:
If Row and Col = 1 a queue of containers is created.
Example
Pos = {1,2,3}
V.ContainerList1 = MissionLib.ContainerSQR(CONTAINER_LARGE,Pos ,9,15,3,3)


GetSystemResearchStation

Syntax

GetSystemResearchStation ()

Description
Searches a researchstation in the actual system.
returns "nil" if the function fails
if nil == TradeStationHandle then
NDebug.Message( { Message="IDM_GLOBALSPACE_004 GetSystemResearchStation() failed" } )
end

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------

ResearchStationHandle = GetSystemResearchStation()


GetSystemTradeStation

Syntax

GetSystemTradeStation ()

Description
Searches the tradestation in the actual system.
returns "nil" if the function fails
if nil == TradeStationHandle then
NDebug.Message( { Message="IDM_GLOBALSPACE_004 GetSystemTradeStation() failed" } )
end

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------

TradeStationHandle = GetSystemTradeStation()


ListSystemOrbiter

Syntax

ListSystemOrbiter (OrbiterType)

Description
Lists all orbiters of the same type in tha actual system
Parameter
Constant

Description
ORBITTYPE_SUN | Sun of the System
ORBITTYPE_PLANET_TC | Tech-Planets
ORBITTYPE_PLANET_BG | Gasgigants
ORBITTYPE_PLANET_GR | Agriculturals
ORBITTYPE_MOON | Moons
ORBITTYPE_COMET | Comets
ORBITTYPE_METEORFIELD | Meteors
ORBITTYPE_DECO | Decorations

returns "nil" if the function fails
if nil == asteroidList[1] then
NDebug.Message( { Message="IDM_GLOBALSPACE_004 ListSystemOrbiter( ORBITTYPE_ASTEROID ) failed" } )
end

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------

local asteroidList{}

asteroidList = ListSystemOrbiter( ORBITTYPE_ASTEROID )


GetSystemHyperGate

Syntax

GetSystemHyperGate ()

Description
Searches the hypergate in the actual system.
returns "nil" if the function fails
if nil == systemHyperGate then
NDebug.Message( { Message="IDM_GLOBALSPACE_004 GetSystemHyperGate() failed" } )
end

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------

local systemHyperGate = GetSystemHyperGate()


AppendToTable

Syntax

AppendToTable (table, item)

Description
Adds an element as the last one in the array

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------


ConcatTables

Syntax

ConcatTables (table1, table2)

Description
Adds two arrays together and returns a resulting array. table1 is followed by table2.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
friends = { handle1, handle2, handle3 }
foes = { handle4, handle5, handle6 }
alltogether = ConcatTables( friends, foes )


CopyTable

Syntax

CopyTable (Table)

Description
returns a copy of a table

Example


GenerateRandomNumber

Syntax

GenerateRandomNumber (min.number, Factor)

Description
creates a random number.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
local zufallszahl = MissionLib.GenerateRandomNumber( 10, 4 )


GetVectorLength

Syntax

GetVectorLength (Vector)

Description
Returns the length of a 3D-vector
Vector = Table with 3 elements

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
-- Distance between 2 Objects
local _p1=NObject.GetPosition( { Object=Obj1 } ).Position
local _p2=NObject.GetPosition( { Object=Obj2 } ).Position
local _vec=NVector.Sub({ Vector1=_p1, Vector2=_p2 }).Vector
_dist=MissionLib.GetVectorLength( _vec )


IsInList

Syntax

IsInList (Element, List)

Description
Checks for an element in a list
returns an ID or "nil"

Example


IsListEmpty

Syntax

IsListEmpty (List)

Description
Checks if a list is empty
returns "true" or false

Example


RandomInteger

Syntax

RandomInteger (Min, Max)

Description
Returns a random integer value from a range of values [ Min, Max ]. The returned value can also be used as index for tables.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
local _random = MissionLib.RandomInteger( 2, 24 )
local _shipid = ships[ _random ]


SetShipNamesInWing

Syntax

SetShipNamesInWing (WingId)

Description
checks the race of the wing leader and renames all other ships with names from the race-names-list.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
V.Pirates = NWing.Create( {
   WingType = WINGTYPE_PIRATES,
   Number = 5,
   Level = nil,
   Race = RACE_RANDOM,
   PosType = POSDESCR_EXPLICIT, Position={2000.0, 8000.0, 1000.0} } ).Wing

MissionLib.SetShipNamesInWing( V.Pirates )


SetWingName

Syntax

SetWingName (WingId, NewName)

Description
Defines a name for a whole wing.
Paramter for NewName:
RANDOM
Only the leader gets a new name

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
V.Pirates = NWing.Create( {
   WingType = WINGTYPE_PIRATES,
   Number = 5,
   Level = nil,
   Race = RACE_RANDOM,
   PosType = POSDESCR_EXPLICIT, Position={2000.0, 8000.0, 1000.0} } ).Wing

MissionLib.SetWingName( V.Pirates, RANDOM )


WingSetAsTarget

Syntax

WingSetAsTarget (WingId)

Description
selects the wing leader as target
WingId
The id of the target wing.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
V.Pirates = NWing.Create( {
   WingType = WINGTYPE_PIRATES,
   Number = 5,
   Level = nil,
   Race = RACE_RANDOM,
   PosType = POSDESCR_EXPLICIT, Position={2000.0, 8000.0, 1000.0} } ).Wing

MissionLib.WingSetAsTarget( V.Pirates )


GetPlayerHandle

Syntax

GetPlayerHandle ()

Description
returns the handle of the players ship

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
V.Player = MissionLib.GetPlayerHandle()


GetPlayerPos

Syntax

GetPlayerPos ()

Description
returns the position of the player

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
local playerPos = {}
playerPos = MissionLib.GetPlayerPos()

local playerPosX = Pos[1]
local playerPosY = Pos[2]
local playerPosZ = Pos[3]


GetPlayerWing

Syntax

GetPlayerWing ()

Description
Returns the handle of the players wing

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------------------------------------------------------
V.PlayerWing = MissionLib.GetPlayerWing()


FindSystem

Syntax

FindSystem (tablePar)

Description
Looks for a system with given properties. returns id and handle of a found system. Uses the starfinder of the "Property System".

Parameter table for tablePar
Name of field | Datatype | Range of values | comments
param | unsigned int | Class of visibility | Kind of star system
active unsigned int != 0 ignores the actual system
should the actual system be ignored?
crime unsigned int ? Crime state of the system
economy | unsigned int | Economy | Economy of the system
faction | unsigned int | Fraction | Fraction of the system
gouvern | unsigned int | Government | Government of the system
orbiter | unsigned int | Orbiter Type | Orbiter Type
offset | unsigned int | [0..399] | value, for defining an ID bias
wealth | unsigned int | Wealth | Wealth of system
jump | unsigned int | [0, 1] | >0 does not look at systems not reachable with one hyperjump
Rückgabetabelle:
Name of field | Datatype | Range of values | comments
Found | boolean | false, true | true: A system was found
Id | unsigned int | [0..399] | Id of the system
Handle unsigned int ? Handle of the system

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------------------------------------------------------
local _results = MissionLib.FindSystem(
{
  active = 1,
  faction = FACTION_FEDERATION,
  param = STAR_UNLOCKED,
  offset = 2,
  wealth = WEALTH_WEALTHY,
})
local _systemid = _results.Id


FindSystemGroup

Syntax

FindSystemGroup (Systems)

Description
looks for a combination of n systems with special properties. return in 'found' the true value if a combination is found. The parameter Systems uses the same datastructure like FindSytem(table)
The algorithm:
It will be determined a set of n systems, every set with special properties. Then a combination with not-identical systems must be assembled. If we have 3 sets with 3 elemnts each, the following combinations are tested.

( 1, 1, 1 ),
( 2, 1, 1 ),
( 3, 1, 1 ),
( 1, 2, 1 ),
( 2, 2, 1 ),
( 3, 2, 1 ),
( 1, 3, 1 ),
( 2, 3, 1 ),
( 3, 3, 1 ),
( 1, 1, 2 ),
( 2, 1, 2 ),
( 3, 1, 2 ),
( 1, 2, 2 ),
( 2, 2, 2 ),
( 3, 2, 2 ),
( 1, 3, 2 ),
( 2, 3, 2 ),
( 3, 3, 2 ),
( 1, 1, 3 ),
( 2, 1, 3 ),
( 3, 1, 3 ),
( 1, 2, 3 ),
( 2, 2, 3 ),
( 3, 2, 3 ),
( 1, 3, 3 ),
( 2, 3, 3 ),
( 3, 3, 3 ),

Parameter table
Name of field | Datatype | Range of values | comments
param | unsigned int | Class of visibility | Kind of star system
active unsigned int != 0 ignores the actual system
should the actual system be ignored?
crime unsigned int ? Crime state of the system
economy | unsigned int | Economy | Economy of the system
faction | unsigned int | Fraction | Fraction of the system
gouvern | unsigned int | Government | Government of the system
orbiter | unsigned int | Orbiter Type | Orbiter Type
offset | unsigned int | [0..399] | value, for defining an ID bias
wealth | unsigned int | Wealth | Wealth of system
jump | unsigned int | [0, 1] | >0 does not look at systems not reachable with one hyperjump
Return table
Name of field | Datatype | Range of values | comments
Found | boolean | false, true | true: A system was found
Id | unsigned int | [0..399] | Id of the system
Handle unsigned int ? Handle of the system

Example
1. Usage

------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------------------------------------------------------
test = MissionLib.FindSystemGroup(
{
{
        param=STAR_UNLOCKED,
        faction=FACTION_FEDERATION,
        offset=2,
    },
    {
        param=STAR_UNLOCKED,
        faction=FACTION_INDEPENDENT,
        offset=5,
    },
    {
        param=STAR_UNLOCKED,
        faction=FACTION_INDEPENDENT,
        offset=5,
    },
})

2. Output

FindSystemGroup: Trying to find 3 Systems. (no script)
FindSystemGroup: Candidate #1: 3 candidates found. (no script)
FindSystemGroup: 	 #1: 8; (no script)
FindSystemGroup: 	 #2: 10; (no script)
FindSystemGroup: 	 #3: 9; (no script)
FindSystemGroup: Candidate #2: 3 candidates found. (no script)
FindSystemGroup: 	 #1: 7; (no script)
FindSystemGroup: 	 #2: 11; (no script)
FindSystemGroup: 	 #3: 4; (no script)
FindSystemGroup: Candidate #3: 3 candidates found. (no script)
FindSystemGroup: 	 #1: 7; (no script)
FindSystemGroup: 	 #2: 4; (no script)
FindSystemGroup: 	 #3: 11; (no script)
FindSystemGroup: Starting search in set 1. (no script)
FindSystemGroup: 	 8, 7, 7,  (no script)
FindSystemGroup: 	 10, 7, 7,  (no script)
FindSystemGroup: 	 9, 7, 7,  (no script)
FindSystemGroup: 	 8, 11, 7,  (no script)
FindSystemGroup: Success. Systems: (no script)
FindSystemGroup: 	 #1: Id = 8 (no script)
FindSystemGroup: 	 #2: Id = 11 (no script)
FindSystemGroup: 	 #3: Id = 7 (no script)


GetStarSystemHandle

Syntax

GetStarSystemHandle ()

Description
Returns the handle of the actual system

Example


GetStarSystemID

Syntax

GetStarSystemID ()

Description
Returns the SystemID of the actual system.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------

SystemId = MissionLib.GetSystemId()


GetStarSystemInfo

Syntax

GetStarSystemInfo (SystemId)

Description
Returns a table with informations to the enterd SystemID

Example
------------------------------[ Import ]--------------------------------------

source "lua/mission/MissionLib.lua"

------------------------------------------------------------------------------

local _starsysteminfo = MissionLib.GetStarSystemInfo( _systemid )

local _wealth = _starsysteminfo.wealth


GetShipCountInWing

Syntax

GetShipCountInWing (WingId)

Description
Returns the number of ships in a wing

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
local wingCount = MissionLib.GetShipCountInWing( WingId )


GetShipPos

Syntax

GetShipPos (ShipId)

Description
Gets the position of a special ship

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
local shipPos = {}
shipPos = MissionLib.GetShipPos( ShipId )

local shipPosX = Pos[1]
local shipPosY = Pos[2]
local shipPosZ = Pos[3]


GetWingLeader

Syntax

GetWingLeader (WingId)

Description
Returns the shiphandle of the wing leader.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

shipHandle= MissionLib.GetWingLeader( WingId )


GetWingMember

Syntax

GetWingMember (WingId, Index)

Description
Returns the handle of the ship from a wing member. Index=0 means the wing leader, >0 is a member of the wing.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

local _leader = MissionLib.GetWingMember( V.Wing1, 0 )
local _wingmen = {}
for i = 1, 10 do
    _wingmen[i]=MissionLib.GetWingMember( V.Wing1, i )
end


IsShipInWing

Syntax

IsShipInWing (Ship, Wing)

Description
Test if a ship is in a wing.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
local _bInWing
if ( MissionLib.IsShipInWing( V.PlayerHandle, V.HornblowerHandle ) ) then _bInWing = true end


SetWingName

Syntax

SetWingName (WingId, NewName)

Description
Gives a name to a whole wing

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
MissionLib.SetWingName( WingID, "NewName" )


WingExplode

Syntax

WingExplode (WingId)

Description
Wing starts spinning and explodes.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
MissionLib.WingExplode( WingId )


WingHyperJump

Syntax

WingHyperJump (WingId)

Description
Wing enters hyperspace.

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"

------------------------------[ Transitions ]---------------------------------
MissionLib.WingHyperJump( WingId )


WingAiActionAngriff

Syntax

WingAiActionAngriff (WingId, AimWingId, AddList)Beschreibung
WingAi Wrapper for AI_ACTION_ANGRIFF, Wing attacks another wing.
Parameter:
WingId
WingId of the attacker
AimWingId
WingId of the target wing
AddList
true Command is put into the order queue
false Command will be executed at once

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionAngriff( Wing1, Wing2, false )


WingAiActionAngriffPlayer

Syntax

WingAiActionAngriffPlayer (WingId, AddList)

Description
WingAi Wrapper for AI_ACTION_ANGRIFF, Wing attacks the player.
Parameter:
WingId
WingID of the attacker.
AddList
true Command is put into the order queue
false Command will be executed at once

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionAngriffPlayer( Wing, false )


WingAiActionFlyToPos

Syntax

WingAiActionFlyToPos (WingId, Pos, AddList)

Description
WingAi Wrapper.
Parameter:
WingId
WingID of a wing which should fly
Pos
Table with X, Y, Z values
AddList
true Command is put into the order queue
false Command will be executed at once

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionFlyToPos( WingId, Pos, AddList )


WingAiActionHyperJump

Syntax

WingAiActionHyperJump (WingId, AddList)

Description
WingAi Wrapper for jumping away in hyperspace.
Parameter:
WingId
WingID of the wing which should jump into hyperspace.
AddList
true Command is put into the order queue
false Command will be executed at once

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionHyperJump( Wing, false )


WingAiActionInaktiv

Syntax

WingAiActionInaktiv (WingId, AddList)

Description
WingAi Wrapper for AI_ACTION_INAKTIV.
Parameter:
WingId
WingID of the wing which shculd do nothing.
AddList
true Command is put into the order queue
false Command will be executed at once

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionInaktiv( Wing, false )


WingAiActionKreisen

Syntax

WingAiActionKreisen (WingId, AddList)

Description
WingAi Wrapper for AI_ACTION_KREISEN, circulating around a position.
Parameter:
WingId
WingID which should circulate around a position.
AddList
true Command is put into the order queue
false Command will be executed at once

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionKreisen( Wing, false )


WingAiActionSetEnemyBoss

Syntax

WingAiActionSetEnemyBoss (WingId)

Description
Wrapper for Ai, creates an enemy boss.
Parameter:
WingId

WingID of a wing which should be an enemy boss

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionSetEnemyBoss( Wing )


WingAiActionSetFriendlyBoss

Syntax

WingAiActionSetFriendlyBoss (WingId)

Description
Wrapper for Ai, creates a friendly boss.
Parameter:
WingId

WingID of a wing which should be an friendly boss

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionSetFriendlyBoss( Wing )


WingAiActionSetWingAsFriend

Syntax

WingAiActionSetWingAsFriend (WingId)

Description

All ships of that wing become friendly (RadarColorMap green)
WingId
WingID of a wing which should be friendly

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
MissionLib.WingAiActionSetWingAsFriend( V.Pirates )


WingAiActionSetWingLeaderAsFriend

Syntax

WingAiActionSetWingLeaderAsFriend (WingId)

Description
Wrapper for Ai, Wing becomes friendly to the player and can't attack him any longer.
Parameter:
WingId
WingID of a wing which leader should be friendly to the player

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Transitions ]---------------------------------
MissionLib.WingAiActionSetWingLeaderAsFriend( Wing )


WingAiActionSetWingLeaderNotAsFriend

Syntax

WingAiActionSetWingLeaderNotAsFriend (WingId)

Description
Wrapper für Ai, undo changes through MissionLib.WingAiActionSetWingAsFriend.

Example


WingAiActionSetWingRadarMapColorDefault

Syntax

WingAiActionSetWingRadarMapColorDefault (WingId)

Description
RadarMapColor will be reseted to default values
WingId
WingID of a wing

Example
------------------------------[ Import ]--------------------------------------
source "lua/mission/MissionLib.lua"
------------------------------[ Code ]----------------------------------------
MissionLib.WingAiActionSetWingRadarMapColorDefault( V.Pirates )


Scripting constants

Scripting events : constants

GUI

  • GUI_NAVMAP
  • GUI_TARGETVIEW
  • GUI_HYPERJUMP

Canyon

  • CST_ENTER
  • CST_ENTER_REVERSE
  • CST_HOVER
  • CST_HOVER_REVERSE
  • CST_ON_SPLINE
  • CST_ON_SPLINE_REVERSE
  • CST_LANDING
  • SPEED_DYNAMIC
  • SPEED_FIXED
  • SPLINE_PLAYER
  • SPLINE_AI_0
  • SPLINE_AI_1
  • SPLINE_AI_2
  • SPLINE_AI_3
  • SPLINE_OVERTURN
  • SPLINE_ENTER

Wing types

  • WINGTYPE_HUNTER
  • WINGTYPE_FREIGHTER100T
  • WINGTYPE_FREIGHTER200T
  • WINGTYPE_POLICE
  • WINGTYPE_MILITARY
  • WINGTYPE_CRUISER1
  • WINGTYPE_CRUISER2
  • WINGTYPE_WEAPONBASE
  • WINGTYPE_PIRATES
  • WINGTYPE_RAIDERS
  • WINGTYPE_PIRATEFREIGHTER

Wing status

  • WING_NO_TARGET
  • WING_DESTROYED
  • WING_TARGET_REACHED
  • WING_ENTER_SYSTEM

Communication

  • COMMTYPE_LANDING_CLEARED
  • COMMTYPE_LANDING_DENIED

Shield

  • SHIELD_BACK
  • SHIELD_FRONT
  • SHIELD_BOTH

Dialog

  • DIALOG_TYPE_1
  • DIALOG_TYPE_EIGHT
  • DIALOG_TYPE_TURN

Start positions

  • HYPERSPACE
  • HYPERNEAR
  • TRADESTATION
  • HANGAR
  • POSITION
  • FIGHTING
  • WINGDEST

Wing behavior

  • PATROUILLE
  • KILLER
  • PIRATE
  • JUMP
  • DOCK
  • PLAYERKILLER

Ship types

  • ST_PLAYERSHIP
  • ST_TRADERSHIP
  • ST_CONSUMPTION_SHUTTLE
  • ST_PRODUCTION_SHUTTLE
  • ST_POLICE
  • ST_PIRATESHIP
  • ST_WINGMAN
  • ST_CRUISER
  • ST_SKAADRONE
  • ST_MILITARYFIGHTER
  • ST_CARGODRONE
  • ST_WEAPONBASE
  • ST_PIRATEFREIGHTER
  • ST_SKAASWARM
  • ST_CANYONSHIP
  • ST_COMMSAT
  • ST_TRADERDRONE
  • ST_COLLECTOR_SHUTTLE
  • ST_SHIELDGEN

Objects types

  • OBJTYPE_ASTEROID
  • OBJTYPE_BASE
  • OBJTYPE_GATE
  • OBJTYPE_KOMET
  • OBJTYPE_METEOR
  • OBJTYPE_MOON
  • OBJTYPE_PLANETBG
  • OBJTYPE_PLANETGR
  • OBJTYPE_PLANETTC
  • OBJTYPE_SUN
  • OBJTYPE_STATION
  • SPACE_SUN
  • SPACE_PLANET
  • SPACE_SHIP
  • SPACE_STATION
  • SPACE_TAXI
  • SPACE_TRANSPORTER
  • SPACE_CARGO
  • SPACE_ROCKET
  • SPACE_PIRATE
  • SPACE_MINE
  • SPACE_POLICE
  • SPACE_PROJECTILE
  • SPACE_WARPGATE
  • SPACE_CRUISER
  • SPACE_EXPLOSION
  • SPACE_MILITARY
  • SPACE_HUNTER
  • SPACE_SKAADRONE
  • SPACE_ASTEROID
  • SPACE_METEROID
  • SPACE_RING
  • SPACE_CANYON
  • SPACE_CAMERA
  • SPACE_SPELL
  • SPACE_DEBRIS
  • SPACE_CARGODRONE
  • SPACE_TURRET
  • SPACE_WEAPONBASE
  • SPACE_SCAT
  • SPACE_WARPEFFECT
  • SPACE_DECORATION
  • SPACE_PIRATE_FREIGHTER
  • SPACE_SKAASWARM
  • SPACE_COMMSAT

Tutorial

  • TUTORIAL_ONCLICK_NAVMAP
  • TUTORIAL_ONCLICK_TARGETMAP
  • TUTORIAL_ONCLICK_HYPERJUMP
  • TUTORIAL_ONCLICK_CLUSTERMAP
  • TUTORIAL_ONCLICK_PLAYERCRUISER
  • TUTORIAL_ONCLOSE_NAVMAP
  • TUTORIAL_ONCLOSE_TARGETMAP
  • TUTORIAL_ONCLOSE_CLUSTERMAP
  • TUTORIAL_ONCLOSE_PLAYERCRUISER
  • BLINK_BTN_NAVMAP
  • BLINK_BTN_TARGETMAP
  • BLINK_BTN_COMMUNICATION
  • BLINK_BTN_LOGBUCH
  • BLINK_BTN_OPTIONS
  • BLINK_BTN_ROCKETS
  • BLINK_BTN_SPELLWEAPON
  • BLINK_BTN_SHIP

Artefact status

  • ARTEFACT_RECEIVED

Position types

Nearly all areas are located relativly to the position of the hypergate and the tradestation in a system. The tradestation is located on position (0,0,0), the hypergate is at (0,0,10000) [unit = meters]. We will use this vector (TS-HG) as orientation for all other areas, used in the game.

Value | Parameter | Comments
POSDESCR_PLAYERSHIP | -/- | Spherehull surrounding the playership (center), Diameter 2-4km
POSDESCR_INTERCEPTION | -/- | Spherehull with a diameter of 2-4km. The center of the sphere is located 4 km away, around the middle of TS-HG (0,0,5000).
POSDESCR_OFFSET | -/- | Sphere with a diameter of 3km. It is located 3km away, around a point 3km away of the hypergate on TS-HG (0,0,7000).
POSDESCR_ASTEROID | -/- | Sphere with a diameter of 0.5 km. Its center is 1km away from the middle of an asteroid on the opposite side to the tradestation. Are there more than one asteroid in the system, one asteroid is choosen randomly.
POSDESCR_TRADESTATION1 | -/- | Sphere with a diameter of 0.5 km. Its center is 1km away from the tradestationcenter on the opposite side to the hypergate (0,0,-1000).
POSDESCR_TRADESTATION2 | -/- | Spherehull around the tradestation with a diameter of 1-3 km.
POSDESCR_RESEARCHSTATION | -/- | Sphere with a diameter of 0.5 km. Its center is 1km away from the middle of a researchstation on the opposite side to the tradestation. Are there more than one researchstations in the system, one researchstation is choosen randomly.
POSDESCR_WELCOME | -/- | A cycle with a diameter of 100m. The center is located 100m in front of the dockinggate of the tradestation.
POSDESCR_METEROIDS | -/- | The center of a meteroid field (there can only be one field in a system).
POSDESCR_HANGAR | Object | Start from an object with a hangar
POSDESCR_WINGDISTANCE | Object and Distance | A position from a specified wing in space
POSDESCR_EXPLICIT | Position | A defined position in space
POSDESCR_HYPERSPACE | -/- | System will be entered through the hypergate
POSDESCR_HYPERSPACE_CRUISER | -/- | Cruisers may enter the system at any position

Container types

  • CONTAINER_ASTEROID
  • CONTAINER_SHIP
  • CONTAINER_SPACE
  • CONTAINER_POSITION

Container sizes

  • CONTAINER_SMALL
  • CONTAINER_MEDIUM
  • CONTAINER_LARGE

Container goods

  • GOODS_COALHYDRATES
  • GOODS_PROTEINS
  • GOODS_LIFEFORMS
  • GOODS_VEGFIBERS
  • GOODS_METALS
  • GOODS_PRECMETALS
  • GOODS_CRYSTALS
  • GOODS_ALLOYS
  • GOODS_MACHINERY
  • GOODS_ELECTRONICS
  • GOODS_COMPUTERS
  • GOODS_SHIPTECHS
  • GOODS_MEDICINE
  • GOODS_CHEMICALS
  • GOODS_LIQUOR
  • GOODS_FERTILIZER
  • GOODS_ENERGYCELLS
  • GOODS_FUELRODS
  • GOODS_ISOTOPES
  • GOODS_SUPERCONDUCTORS
  • GOODS_VIDEOGAMES
  • GOODS_LUXURIES
  • GOODS_ANDROIDS
  • GOODS_DRUGS
  • GOODS_MISSIONOBJECT

Classes of visibility

  • STAR_UNLOCKED: A system the player is allowed to enter
  • STAR_MISSION: A system reserved for a single mission. This mission is available in the actual system
  • STAR_SYSTEMKEY: A visible system. The key may be given in the actual system.
  • STAR_GANGSYSTEM A visible system with a pirate gang.

Races

  • RACE_HUMAN
  • RACE_MORLOK
  • RACE_RAPTOR
  • RACE_OCTO
  • RACE_WASP
  • RACE_THUL
  • RACE_SKAA

Goverments

  • GOVERN_ANARCHY
  • GOVERN_DICTATORSHIP
  • GOVERN_FEDERATION
  • GOVERN_DEMOCRACY
  • GOVERN_CONCERN
  • GOVERN_MONARCHY

Fractions

  • FACTION_FEDERATION
  • FACTION_REBELS
  • FACTION_INDEPENDENT

System economy

  • SYSTEM_AGRICULTURE
  • SYSTEM_INDUSTRY
  • SYSTEM_MINING
  • SYSTEM_PHARMACEUTICS
  • SYSTEM_RESEARCH
  • SYSTEM_SERVICE

System wealth

  • WEALTH_POOR
  • WEALTH_RICH
  • WEALTH_WEALTHY

Missionen status

  • MISSION_ACHIEVED
  • MISSION_ENDED
  • MISSION_FAILED
  • MISSION_NONE
  • MISSION_OFFERING
  • MISSION_RUNNING

Mission types

  • SUBTYPE_HEADHUNT
  • SUBTYPE_TRANSPORT
  • SUBTYPE_PIRATES
  • SUBTYPE_SABOTAGE
  • SUBTYPE_PROTECT
  • SUBTYPE_RESCUE
  • SUBTYPE_POLITICAL

Orbiter types

  • OBJTYPE_ASTEROID
  • OBJTYPE_BASE Tradestation
  • OBJTYPE_GATE
  • OBJTYPE_KOMET
  • OBJTYPE_METEOR
  • OBJTYPE_MOON
  • OBJTYPE_PLANETBG
  • OBJTYPE_PLANETGR
  • OBJTYPE_PLANETTC
  • OBJTYPE_SUN
  • OBJTYPE_STATION Researchstation
  • ORBITART_ANOMALIE