PioneerWiki - User contributions [en]

3DS Max

2013-01-09T14:11:47Z

ImTheFish: /* Empty nodes */

'''3DS Max'''

I recommend reading the [[Model system]] page first as most of whats there is still relevant when it comes to creating content for pioneer this is just whats different in 3DS Max.

== '''Scale''' ==

1 unit in 3DS Max is equal to 1 meter in Pioneer. Putting a "person sized" (~1.8 units tall) box next to your model should also help with getting the scale right.

== '''Orientation''' ==

Max uses different axis orientation to Blender and pioneer and there are a few ways to deal with this but changing the direction of your model so the front is facing the back just before export is probably the easiest.

[[File:OrientationTop.png]]

== '''.OBJ Export''' ==

This is probably the easiest format to export your model in but lacks the ability to hold empty nodes for things like thrusters and cant store any animations so this is best to use for things like collision meshes

[[File:ExportObj.png]]

A basic setup of the .OBJ options

[[File:ObjOptions.png]]

== '''.DAE Export''' ==

The .DAE format is a bit more complicated but can store all the things that the .Obj cant

[[File:ExportDae.png]]

As you can see there are alot more options to play with but this setup works with both thrusters and animations

[[File:DaeOptions.png]]

When exporting thrusters and other empty nodes you will get a warning but this is not a problem and can be turned off in the options

[[File:DaeWarnings.png]]

== '''Empty nodes''' ==

Things like thrusters use empty nodes that can be created using 'Helper Objects'. The best one i have found is the 'Point' helper.

[[File:ThrusterObjects.png]]

Once the object is placed you will want to set its orientation and scale, when setting the scale the object can seem to get very large very quickly while not gaining much size in the model viewer but the size of the object can be changed in max without effecting the scale by using the 'Size' option for the object. The orientation is simple just rotate the top to face the way you want the thruster to point.

[[File:ThrusterOrientation.png]]

When using these to place labels the writing is placed along the X axis facing out to the Z axis with the Y axis at the top

And remember that the node is placed at the center of the helper object and is scaled out from there

3DS Max

2013-01-09T14:10:21Z

ImTheFish:

'''3DS Max'''

I recommend reading the [[Model system]] page first as most of whats there is still relevant when it comes to creating content for pioneer this is just whats different in 3DS Max.

== '''Scale''' ==

1 unit in 3DS Max is equal to 1 meter in Pioneer. Putting a "person sized" (~1.8 units tall) box next to your model should also help with getting the scale right.

== '''Orientation''' ==

Max uses different axis orientation to Blender and pioneer and there are a few ways to deal with this but changing the direction of your model so the front is facing the back just before export is probably the easiest.

[[File:OrientationTop.png]]

== '''.OBJ Export''' ==

This is probably the easiest format to export your model in but lacks the ability to hold empty nodes for things like thrusters and cant store any animations so this is best to use for things like collision meshes

[[File:ExportObj.png]]

A basic setup of the .OBJ options

[[File:ObjOptions.png]]

== '''.DAE Export''' ==

The .DAE format is a bit more complicated but can store all the things that the .Obj cant

[[File:ExportDae.png]]

As you can see there are alot more options to play with but this setup works with both thrusters and animations

[[File:DaeOptions.png]]

When exporting thrusters and other empty nodes you will get a warning but this is not a problem and can be turned off in the options

[[File:DaeWarnings.png]]

== '''Empty nodes''' ==

Things like thrusters use empty nodes that can be created using 'Helper Objects'. The best one i have found is the 'Point' helper.

[[File:ThrusterObjects.png]]

Once the object is placed you will want to set its orientation and scale, when setting the scale the object can seem to get very large very quickly while not gaining much size in the model viewer but the size of the object can be changed in max without effecting the scale by using the 'Size' option for the object. The orientation is simple just rotate the top to face the way you want the thruster to point.
[[File:ThrusterOrientation.png]]

When using these to place labels the writing is placed along the X axis facing out to the Z axis with the Y axis at the top

And remember that the node is placed at the center of the helper object and is scaled out from there

3DS Max

2013-01-03T09:49:22Z

ImTheFish: /* Empty nodes */

'''3DS Max'''

I recommend reading the [[Model system]] page first as most of whats there is still relevant when it comes to creating content for pioneer this is just whats different in 3DS Max.

== '''Orientation''' ==

Max uses different axis orientation to Blender and pioneer and there are a few ways to deal with this but changing the direction of your model so the front is facing the back just before export is probably the easiest.

[[File:OrientationTop.png]]

== '''.OBJ Export''' ==

This is probably the easiest format to export your model in but lacks the ability to hold empty nodes for things like thrusters and cant store any animations so this is best to use for things like collision meshes

[[File:ExportObj.png]]

A basic setup of the .OBJ options

[[File:ObjOptions.png]]

== '''.DAE Export''' ==

The .DAE format is a bit more complicated but can store all the things that the .Obj cant

[[File:ExportDae.png]]

As you can see there are alot more options to play with but this setup works with both thrusters and animations

[[File:DaeOptions.png]]

When exporting thrusters and other empty nodes you will get a warning but this is not a problem and can be turned off in the options

[[File:DaeWarnings.png]]

== '''Empty nodes''' ==

Things like thrusters use empty nodes that can be created using 'Helper Objects'. The best one i have found is the 'Point' helper.

[[File:ThrusterObjects.png]]

Once the object is placed you will want to set its orientation and scale, when setting the scale the object can seem to get very large very quickly while not gaining much size in the model viewer but the size of the object can be changed in max without effecting the scale by using the 'Size' option for the object. The orientation is simple just rotate the top to face the way you want the thruster to point.
[[File:ThrusterOrientation.png]]

When using these to place labels the writing is placed along the X axis facing out to the Z axis with the Y axis at the top

And remember that the node is placed at the center of the helper object and is scaled out from there

Model system

2013-01-02T15:35:12Z

ImTheFish: /* 3DS Max */

== Overview ==

tl;dr: a simple scenegraph-based approach that has nothing to do with the old system or Lua, focus is on easy importing, supports some animation.

== Importing models ==

The import system theoretically supports [http://assimp.sourceforge.net/main_features_formats.html many different formats] but you are expected to use only some:

* When node structure, node names and animations matter, use '''Collada (.dae).'''
* For static geometry, such as buildings, OBJ is recommended, this may allow for some optimizations

The only officially tested 3D modelling program at the moment is [http://www.blender.org/ Blender 2.64]. For blender, a quick checklist is:

* Coordinates: X right, Y forward, Z up
* Always generate UV coordinates for the model
* Versions downloaded from blender.org support Collada out of the box, while the version distributed with some Linux distros doesn't

The [[Model viewer]] is supplied with the game.

=== Model definition file ===

Models must be placed under '''data/models'''

To define a model, create a simple <code>name_here.model</code> text file along with your exported meshes:

#Comments can be written like this
#Define all used materials first
Material some-material
tex_diff some_texture.png
diffuse 0.8 0.7 0.7

#Meshes to be imported into this model, should be in the current folder
#Mixing different formats should be OK
mesh part1.obj
mesh part2.obj

== Materials ==

Only material names are imported from 3D models, to set material properties use a small definition like this:

material CobraI_body
tex_diff CobraI_diff.png
tex_glow CobraI_emit.png
tex_spec CobraI_spec.png
diffuse 1.0 1.0 1.0
specular 1.0 1.0 1.0
shininess 150

=== Material properties ===

{| class="wikitable"
|-
| material || Name. Mandatory! Note, some exporters modify the names from what is visible in the modeling program, for example the Blender 2.6 Collada exporter adds "-material" to each name. You'll have to use this final name. If in doubt, note that both .obj and .dae files are human readable, and you can find the assigned names in them with a text editor.
|-
| diffuse|| Diffuse colour RGB. Default white.
|-
| specular|| Colour of specular highlights, RGB. Default white. Set to black to disable highlights.
|-
| emissive|| Self-illumination colour, RGB. Default black.
|-
| shininess|| Sharpness/size of specular highlights, 0 - 200. Default 200.
|-
| opacity|| 0-100, controls transparency of the material. A node with a material opacity less than 100 is treated as transparent, otherwise opaque.
|-
| tex_diff || Diffuse texture, file name (in the same folder). If you don't specify this, a white dummy texture is generated.
|-
| tex_glow||Self-illumination texture, overrides emissive colour parameter. Default none.
|-
| tex_spec||Specular highlight colour/intensity texture. Default none. Multiplied by specular colour parameter, so set it to white to leave control entirely to the texture.
|-
| use_patterns||yes/no. This material will use the pattern/colour system. Read more below. Default no.
|}

[[File:newmodel_specularmap.png]]
Flat specular lighting improved by a specular map

[[File:newmodel_glowmap.png]]
A model lit only by the self-illumination texture

=== Patterns ===

A system to mark customizable color areas on a model without splitting it to separate materials.

Patterns are small grayscale textures placed in the model folder, named pattern*.png. Using gray or white colour you can mark the areas tinted by one of the customizable colours (black marks unaffected areas). The colours are set by the game (faction-specific ship colours, shipyard UI for the player).

The system has several limitations: it is not meant to do fine details, transitioning from one color to another is sharp and it works best with white/light textures. You'll have to experiment.

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

Meshes can be grouped into detail levels using the <code>lod pixelsize</code> directive:

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

A detail level will be picked if the approximate size of the model on screen is less than <code>pixelsize</code> (for the highest level it does not matter as long as it's larger than the others). Use the modelviewer to find optimal sizes.

You may specify any number of detail levels in any order, they will be sorted according to size.

== Animations ==

Position, rotation and scale keyframe animation is supported. Since the Blender 2.6 Collada exporter cannot export multiple animations in one file, you will have to put it all in one timeline and split it at the import stage (this is also the only reliable way to get named animations). An animation is defined after all the meshes in format <code>anim name startframe endframe</code>:

anim gear_down 0 10
anim something_else 12 25

Note, Collada uses seconds instead of frame numbers. For the conversion to work, you should create the animations at '''24FPS'''.

The game will recognize animations by name, the list of supported animations is to be decided.

There is no animation blending, so two animations shouldn't be directly controlling the same node.

== Attachments ==

Models may have special "tag point" nodes where other models may be attached. You may define a tag point in Blender by placing an Empty object and giving it one of the predefined names.

The system is meant for attaching equipment: guns, cargo pods, turrets...

Example: A generic gun model attached to a point "tag_gun_right":

[[File:newmodel_tagpoints01.png]]

The actual list of available names has not been determined yet.

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes. For more control, you can import a custom mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

Decals are meant for customizable insignia on spaceships and changing advertisements on space stations. Up to four unique decals are available for a model (multiple identical decals are allowed). Place a piece of geometry, usually a flat quad, with proper UV coordinates and name it decal_01, 02, 03 or 04. The game will then use a special material on the geometry, or make it invisible if no decal is to be used.

[[File:newmodel_decals01.png]]

== Labels ==

Dynamic 3D labels are meant for naming ships and space stations. Put an empty node in the model and give it a name beginning with "label". The text is set by the game at runtime if supported.

Node scale can be used as usual but the text is not constrained to the node bounds or anything like that, so some trial will be required.

You can use multiple label nodes but they will all show the same text.

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). Certain lights will blink when a ship's landing gear is down. This feature is not complete as it needs more support in the game.

=== Thrusters ===

Thrusters are marked with dummy objects. In Blender, create an "Empty" object and point its Z-axis (change the object display type to "arrows" or "single arrow" to visualize this) where the thruster should point. Thruster size is taken from the object scale. Begin the object name with either <code>thruster</code> or <code>thruster_linear</code> so the importer can recognize them (linear thrusters light up only when moving up/down/left/right/forward/backward, not when turning).

== Internals ==

You can find some testcase models at git://github.com/Luomu/newmodels.git.

The internal scene graph consists of several of these nodes:

{| class="wikitable"
|-
| Node|| Base class. A node can have a name and one or more parents.
|-
| Group|| A group is a Node that can have several children.
|-
| MatrixTransform|| A Group that applies a transformation to its child nodes when rendering.
|-
| StaticGeometry|| Contains one or more StaticMeshes.
|-
| LOD|| Detail level control node, picks one of the child nodes based on the approximate size of the model on screen.
|-
| ModelNode || Can be used to attach another Model as a submodel. Use case: dynamic equipment on ships.
|-
| More!||Some marginal nodes that exist at the moment are:

* Thruster: spaceship thruster
* Billboard: can be used for light sprites (navlights on ships)
* Label3D: dynamic 2d text, meant for labeling ships
|}

MatrixTransform nodes are the most commonly used, if a geometry is rotated or scaled it will be parented to a MatrixTransform. A simple form of instancing can be achieved by adding a geometry as the child of several separate MatrixTransforms.

During rendering, the graph is traversed twice. Once for opaque objects, and once for transparent objects (which includes decals, thrusters). The model system does not perform any depth sorting, this improvement job needs to be done elsewhere.

=== Animations ===

An animation consists of Channels. Each channel controls one node (always a MatrixTransform) and has a list of position and rotation Keys. Each key has a time and value. Keys are always linearly interpolated.

At first the animations had proper play/pause/loop functionality but right now it is not so. Animation progress (and fun things like serialization) needs to be controlled directly by whatever feature uses the animation (see: landing gear).

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

[[Category:Art]]

3DS Max

2013-01-02T15:33:09Z

ImTheFish:

'''3DS Max'''

I recommend reading the [[Model system]] page first as most of whats there is still relevant when it comes to creating content for pioneer this is just whats different in 3DS Max.

== '''Orientation''' ==

Max uses different axis orientation to Blender and pioneer and there are a few ways to deal with this but changing the direction of your model so the front is facing the back just before export is probably the easiest.

[[File:OrientationTop.png]]

== '''.OBJ Export''' ==

This is probably the easiest format to export your model in but lacks the ability to hold empty nodes for things like thrusters and cant store any animations so this is best to use for things like collision meshes

[[File:ExportObj.png]]

A basic setup of the .OBJ options

[[File:ObjOptions.png]]

== '''.DAE Export''' ==

The .DAE format is a bit more complicated but can store all the things that the .Obj cant

[[File:ExportDae.png]]

As you can see there are alot more options to play with but this setup works with both thrusters and animations

[[File:DaeOptions.png]]

When exporting thrusters and other empty nodes you will get a warning but this is not a problem and can be turned off in the options

[[File:DaeWarnings.png]]

== '''Empty nodes''' ==

Things like thrusters use empty nodes that can be created using 'Helper Objects'. The best one i have found is the 'Point' helper.

[[File:ThrusterObjects.png]]

Once the object is placed you will want to set its orientation and scale, when setting the scale the object can seem to get very large very quickly while not gaining much size in the model viewer but the size of the object can be changed in max without effecting the scale by using the 'Size' option for the object. The orientation is simple just rotate the top to face the way you want the thruster to point.
[[File:ThrusterOrientation.png]]

And remember that the node is placed at the center of the helper object and is scaled out from there

Pioneer Wiki

2013-01-02T15:31:17Z

ImTheFish: /* Content Creation */

Pioneer is a space adventure game set in the milkyway galaxy at the turn of the 31st century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

* [http://pioneerspacesim.net/download Download Pioneer] for Windows, Linux and Mac OSX

* [http://sourceforge.net/projects/pioneerspacesim/files/nightly/ Development Builds] (warning, may be more unstable than a release)

----

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting started|How to get started]].

And write a nice front page and get rid of this, ok? :)

----
{|width=100%
|width="33%" style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top"|
===Community===
* [http://pioneerspacesim.net/ Pioneer Space Sim Homepage]
* [http://pioneerspacesim.net/forum Forums]
* [[FAQ]]
* [[Keyboard and mouse controls]]
* [http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter
* [[Media Coverage]]
|width="33%" style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top"|

===Content Creation===
* [[Mods]]
* [[Introduction to Mission Scripting]]
** [[Interacting with the game: Event-based programming]]
** [[Interacting with the player: BBS forms]]
** [[Surviving a reload]]
* [http://eatenbyagrue.org/f/pioneer/codedoc/ Lua API Reference]
* Modeling
** [[Model system]]
** [[Model viewer]]
** [[Transitioning to the new model system]]
** [[3DS Max]]
* [[Music]]
* [[Sound Effects]]
* [[Translations]]
|width="33%" style="background:#fff3f3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top"|

===Development===
* [[Design Scope|Game Scope]]
* [[Getting Started with Development]]
** [[Using git and GitHub]] (work in progress)
** [[Core Team]]
* [[Development Model]]
* [[Design_Workflow|Design and Project Management Workflow]]
|}

Pioneer is brung to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

3DS Max

2013-01-02T15:29:51Z

ImTheFish: Created page with "'''3DS Max''' I recommend reading the Model_System page as most of whats there is still relevant when it comes to creating content for pioneer this is just whats different in 3D..."

'''3DS Max'''

I recommend reading the Model_System page as most of whats there is still relevant when it comes to creating content for pioneer this is just whats different in 3DS Max.

== '''Orientation''' ==

Max uses different axis orientation to Blender and pioneer and there are a few ways to deal with this but changing the direction of your model so the front is facing the back just before export is probably the easiest.

[[File:OrientationTop.png]]

== '''.OBJ Export''' ==

This is probably the easiest format to export your model in but lacks the ability to hold empty nodes for things like thrusters and cant store any animations so this is best to use for things like collision meshes

[[File:ExportObj.png]]

A basic setup of the .OBJ options

[[File:ObjOptions.png]]

== '''.DAE Export''' ==

The .DAE format is a bit more complicated but can store all the things that the .Obj cant

[[File:ExportDae.png]]

As you can see there are alot more options to play with but this setup works with both thrusters and animations

[[File:DaeOptions.png]]

When exporting thrusters and other empty nodes you will get a warning but this is not a problem and can be turned off in the options

[[File:DaeWarnings.png]]

== '''Empty nodes''' ==

Things like thrusters use empty nodes that can be created using 'Helper Objects'. The best one i have found is the 'Point' helper.

[[File:ThrusterObjects.png]]

Once the object is placed you will want to set its orientation and scale, when setting the scale the object can seem to get very large very quickly while not gaining much size in the model viewer but the size of the object can be changed in max without effecting the scale by using the 'Size' option for the object. The orientation is simple just rotate the top to face the way you want the thruster to point.
[[File:ThrusterOrientation.png]]

And remember that the node is placed at the center of the helper object and is scaled out from there

File:ThrusterOrientation.png

2013-01-02T15:21:43Z

ImTheFish: orientation of the thrusters

orientation of the thrusters

File:ThrusterObjects.png

2013-01-02T15:13:10Z

ImTheFish: the point helper in 3ds max

the point helper in 3ds max

File:DaeWarnings.png

2013-01-02T15:09:07Z

ImTheFish: warnings generated in max when exporting thrusters

warnings generated in max when exporting thrusters

File:DaeOptions.png

2013-01-02T14:58:24Z

ImTheFish: uploaded a new version of "File:DaeOptions.png"

export options for .DAE in 3ds max

File:DaeOptions.png

2013-01-02T14:57:17Z

ImTheFish: export options for .DAE in 3ds max

export options for .DAE in 3ds max

File:ExportDae.png

2013-01-02T14:53:27Z

ImTheFish: uploaded a new version of "File:ExportDae.png"

Export .Dae in max

File:ExportDae.png

2013-01-02T14:52:14Z

ImTheFish: Export .Dae in max

Export .Dae in max

File:ObjOptions.png

2013-01-02T14:42:48Z

ImTheFish: quick look at the .obj options that worked for me

quick look at the .obj options that worked for me

File:ExportObj.png

2013-01-02T14:36:15Z

ImTheFish: uploaded a new version of "File:ExportObj.png"

export options for .obj part 1

File:ExportObj.png

2013-01-02T14:34:41Z

ImTheFish: export options for .obj part 1

export options for .obj part 1

File:OrientationTop.png

2013-01-02T14:23:10Z

ImTheFish: uploaded a new version of "File:OrientationTop.png"

orientation of a ship in max from the top

File:OrientationTop.png

2013-01-02T14:19:57Z

ImTheFish: orientation of a ship in max from the top

orientation of a ship in max from the top

Model system

2012-12-24T01:49:55Z

ImTheFish: /* 3DS Max */

== Overview ==

tl;dr: a simple scenegraph-based approach that has nothing to do with the old system or Lua, focus is on easy importing, supports some animation.

== Importing models ==

The import system theoretically supports [http://assimp.sourceforge.net/main_features_formats.html many different formats] but you are expected to use only some:

* When node structure, node names and animations matter, use '''Collada (.dae)'''
* For static geometry, such as buildings, OBJ is recommended, this may allow for some optimizations

The only officially tested 3D modelling program at the moment is [http://www.blender.org/ Blender 2.64]. For blender, a quick checklist is:

* Coordinates: X right, Y forward, Z up
* Always generate UV coordinates for the model

The [[Model viewer]] is supplied with the game.

=== Model definition file ===

Models must be placed under '''data/models'''

To define a model, create a simple <code>name_here.model</code> text file along with your exported meshes:

#Comments can be written like this
#Define all used materials first
Material some-material
tex_diff some_texture.png
diffuse 0.8 0.7 0.7

#Meshes to be imported into this model, should be in the current folder
#Mixing different formats should be OK
mesh part1.obj
mesh part2.obj

== Materials ==

Only material names are imported from 3D models, to set material properties use a small definition like this:

material CobraI_body
tex_diff CobraI_diff.png
tex_glow CobraI_emit.png
tex_spec CobraI_spec.png
diffuse 1.0 1.0 1.0
specular 1.0 1.0 1.0
shininess 150

=== Material properties ===

{| class="wikitable"
|-
| material || Name. Mandatory! Note, some exporters modify the names from what is visible in the modeling program, for example the Blender 2.6 Collada exporter adds "-material" to each name. You'll have to use this final name.
|-
| diffuse|| Diffuse colour RGB. Default white.
|-
| specular|| Colour of specular highlights, RGB. Default white. Set to black to disable highlights.
|-
| emissive|| Self-illumination colour, RGB. Default black.
|-
| shininess|| Sharpness/size of specular highlights, 0 - 200. Default 200.
|-
| opacity|| 0-100, controls transparency of the material. A node with a material opacity less than 100 is treated as transparent, otherwise opaque.
|-
| tex_diff || Diffuse texture, file name (in the same folder). If you don't specify this, a white dummy texture is generated.
|-
| tex_glow||Self-illumination texture, overrides emissive colour parameter. Default none.
|-
| tex_spec||Specular highlight colour/intensity texture. Default none. Multiplied by specular colour parameter, so set it to white to leave control entirely to the texture.
|-
| use_patterns||yes/no. This material will use the pattern/colour system. Read more below. Default no.
|}

[[File:newmodel_specularmap.png]]
Flat specular lighting improved by a specular map

[[File:newmodel_glowmap.png]]
A model lit only by the self-illumination texture

=== Patterns ===

A system to mark customizable color areas on a model without splitting it to separate materials.

Patterns are small grayscale textures placed in the model folder, named pattern*.png. Using gray or white colour you can mark the areas tinted by one of the customizable colours (black marks unaffected areas). The colours are set by the game (faction-specific ship colours, shipyard UI for the player).

The system has several limitations: it is not meant to do fine details, transitioning from one color to another is sharp and it works best with white/light textures. You'll have to experiment.

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

Meshes can be grouped into detail levels using the <code>lod pixelsize</code> directive:

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

A detail level will be picked if the approximate size of the model on screen is less than <code>pixelsize</code> (for the highest level it does not matter as long as it's larger than the others). Use the modelviewer to find optimal sizes.

You may specify any number of detail levels in any order, they will be sorted according to size.

== Animations ==

Position, rotation and scale keyframe animation is supported. Since the Blender 2.6 Collada exporter cannot export multiple animations in one file, you will have to put it all in one timeline and split it at the import stage (this is also the only reliable way to get named animations). An animation is defined after all the meshes in format <code>anim name startframe endframe</code>:

anim gear_down 0 10
anim something_else 12 25

Note, Collada uses seconds instead of frame numbers. For the conversion to work, you should create the animations at '''24FPS'''.

The game will recognize animations by name, the list of supported animations is to be decided.

There is no animation blending, so two animations shouldn't be directly controlling the same node.

== Attachments ==

Models may have special "tag point" nodes where other models may be attached. You may define a tag point in Blender by placing an Empty object and giving it one of the predefined names.

The system is meant for attaching equipment: guns, cargo pods, turrets...

Example: A generic gun model attached to a point "tag_gun_right":

[[File:newmodel_tagpoints01.png]]

The actual list of available names has not been determined yet.

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes. For more control, you can import a custom mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

Decals are meant for customizable insignia on spaceships and changing advertisements on space stations. Up to four unique decals are available for a model (multiple identical decals are allowed). Place a piece of geometry, usually a flat quad, with proper UV coordinates and name it decal_01, 02, 03 or 04. The game will then use a special material on the geometry, or make it invisible if no decal is to be used.

[[File:newmodel_decals01.png]]

== Labels ==

Dynamic 3D labels are meant for naming ships and space stations. Put an empty node in the model and give it a name beginning with "label". The text is set by the game at runtime if supported.

Node scale can be used as usual but the text is not constrained to the node bounds or anything like that, so some trial will be required.

You can use multiple label nodes but they will all show the same text.

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). Certain lights will blink when a ship's landing gear is down. This feature is not complete as it needs more support in the game.

=== Thrusters ===

Thrusters are marked with dummy objects. In Blender, create an "Empty" object and point its Z-axis (change the object display type to "arrows" or "single arrow" to visualize this) where the thruster should point. Thruster size is taken from the object scale. Begin the object name with either <code>thruster</code> or <code>thruster_linear</code> so the importer can recognize them (linear thrusters light up only when moving up/down/left/right/forward/backward, not when turning).

== Internals ==

You can find some testcase models at git://github.com/Luomu/newmodels.git.

The internal scene graph consists of several of these nodes:

{| class="wikitable"
|-
| Node|| Base class. A node can have a name and one or more parents.
|-
| Group|| A group is a Node that can have several children.
|-
| MatrixTransform|| A Group that applies a transformation to its child nodes when rendering.
|-
| StaticGeometry|| Contains one or more StaticMeshes.
|-
| LOD|| Detail level control node, picks one of the child nodes based on the approximate size of the model on screen.
|-
| ModelNode || Can be used to attach another Model as a submodel. Use case: dynamic equipment on ships.
|-
| More!||Some marginal nodes that exist at the moment are:

* Thruster: spaceship thruster
* Billboard: can be used for light sprites (navlights on ships)
* Label3D: dynamic 2d text, meant for labeling ships
|}

MatrixTransform nodes are the most commonly used, if a geometry is rotated or scaled it will be parented to a MatrixTransform. A simple form of instancing can be achieved by adding a geometry as the child of several separate MatrixTransforms.

During rendering, the graph is traversed twice. Once for opaque objects, and once for transparent objects (which includes decals, thrusters). The model system does not perform any depth sorting, this improvement job needs to be done elsewhere.

=== Animations ===

An animation consists of Channels. Each channel controls one node (always a MatrixTransform) and has a list of position and rotation Keys. Each key has a time and value. Keys are always linearly interpolated.

At first the animations had proper play/pause/loop functionality but right now it is not so. Animation progress (and fun things like serialization) needs to be controlled directly by whatever feature uses the animation (see: landing gear).

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

== 3DS Max ==

in 3DS Max an empty node can be created using a point helper found in the helper objects section

[[Category:Art]]

Model viewer

2012-12-23T10:42:43Z

ImTheFish:

To enter modelviewer mode, launch the game with:

pioneer -mv <optional model name>

''OSX Only:'' Hold down the Option key while clicking on the pioneer.app icon to launch the model viewer instead of the game.

In windows an easy way to open the model viewer is to create a shortcut to pioneer.exe then add '-mv shipname' to the end of the target in the shortcut properties (without the ' ), then you only have to run the shortcut to load the model viewer.

= Hotkeys =

Esc: Quit

Tab: Toggle UI

PrintScr: Screenshot

Space: Reset camera view + thruster sliders

G: Cycle grid mode

R: Randomize colour sliders

Z: Toggle wireframe mode

Camera view presets are like Blender:

* Numpad 1 - Front view
* Ctrl+Numpad - Rear view
* Numpad 3 - Right view
* Ctrl+Numpad 3 - Left view
* Numpad 7 - Top view
* Ctrl+Numpad 7 - Bottom view
* Numpad2/4/6/8: Rotate view

[[Category:Art]]

Model system

2012-12-21T23:43:28Z

ImTheFish: small update with some 3DS Max info

== Overview ==

tl;dr: a simple scenegraph-based approach that has nothing to do with the old system or Lua, focus is on easy importing, supports some animation.

== Importing models ==

The import system theoretically supports [http://assimp.sourceforge.net/main_features_formats.html many different formats] but you are expected to use only some:

* When node structure, node names and animations matter, use '''Collada (.dae)'''
* For static geometry, such as buildings, OBJ is recommended, this may allow for some optimizations

The only officially tested 3D modelling program at the moment is [http://www.blender.org/ Blender 2.64]. For blender, a quick checklist is:

* Coordinates: X right, Y forward, Z up
* Always generate UV coordinates for the model

The [[Model viewer]] is supplied with the game.

=== Model definition file ===

Models must be placed under '''data/models'''

To define a model, create a simple <code>name_here.model</code> text file along with your exported meshes:

#Comments can be written like this
#Define all used materials first
Material some-material
tex_diff some_texture.png
diffuse 0.8 0.7 0.7

#Meshes to be imported into this model, should be in the current folder
#Mixing different formats should be OK
mesh part1.obj
mesh part2.obj

== Materials ==

Only material names are imported from 3D models, to set material properties use a small definition like this:

material CobraI_body
tex_diff CobraI_diff.png
tex_glow CobraI_emit.png
tex_spec CobraI_spec.png
diffuse 1.0 1.0 1.0
specular 1.0 1.0 1.0
shininess 150

=== Material properties ===

{| class="wikitable"
|-
| material || Name. Mandatory! Note, some exporters modify the names from what is visible in the modeling program, for example the Blender 2.6 Collada exporter adds "-material" to each name. You'll have to use this final name.
|-
| diffuse|| Diffuse colour RGB. Default white.
|-
| specular|| Colour of specular highlights, RGB. Default white. Set to black to disable highlights.
|-
| emissive|| Self-illumination colour, RGB. Default black.
|-
| shininess|| Sharpness/size of specular highlights, 0 - 200. Default 200.
|-
| opacity|| 0-100, controls transparency of the material. A node with a material opacity less than 100 is treated as transparent, otherwise opaque.
|-
| tex_diff || Diffuse texture, file name (in the same folder). If you don't specify this, a white dummy texture is generated.
|-
| tex_glow||Self-illumination texture, overrides emissive colour parameter. Default none.
|-
| tex_spec||Specular highlight colour/intensity texture. Default none. Multiplied by specular colour parameter, so set it to white to leave control entirely to the texture.
|-
| use_patterns||yes/no. This material will use the pattern/colour system. Read more below. Default no.
|}

[[File:newmodel_specularmap.png]]
Flat specular lighting improved by a specular map

[[File:newmodel_glowmap.png]]
A model lit only by the self-illumination texture

=== Patterns ===

A system to mark customizable color areas on a model without splitting it to separate materials.

Patterns are small grayscale textures placed in the model folder, named pattern*.png. Using gray or white colour you can mark the areas tinted by one of the customizable colours (black marks unaffected areas). The colours are set by the game (faction-specific ship colours, shipyard UI for the player).

The system has several limitations: it is not meant to do fine details, transitioning from one color to another is sharp and it works best with white/light textures. You'll have to experiment.

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

Meshes can be grouped into detail levels using the <code>lod pixelsize</code> directive:

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

A detail level will be picked if the approximate size of the model on screen is less than <code>pixelsize</code> (for the highest level it does not matter as long as it's larger than the others). Use the modelviewer to find optimal sizes.

You may specify any number of detail levels in any order, they will be sorted according to size.

== Animations ==

Position, rotation and scale keyframe animation is supported. Since the Blender 2.6 Collada exporter cannot export multiple animations in one file, you will have to put it all in one timeline and split it at the import stage (this is also the only reliable way to get named animations). An animation is defined after all the meshes in format <code>anim name startframe endframe</code>:

anim gear_down 0 10
anim something_else 12 25

Note, Collada uses seconds instead of frame numbers. For the conversion to work, you should create the animations at '''24FPS'''.

The game will recognize animations by name, the list of supported animations is to be decided.

There is no animation blending, so two animations shouldn't be directly controlling the same node.

== Attachments ==

Models may have special "tag point" nodes where other models may be attached. You may define a tag point in Blender by placing an Empty object and giving it one of the predefined names.

The system is meant for attaching equipment: guns, cargo pods, turrets...

Example: A generic gun model attached to a point "tag_gun_right":

[[File:newmodel_tagpoints01.png]]

The actual list of available names has not been determined yet.

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes. For more control, you can import a custom mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

Decals are meant for customizable insignia on spaceships and changing advertisements on space stations. Up to four unique decals are available for a model (multiple identical decals are allowed). Place a piece of geometry, usually a flat quad, with proper UV coordinates and name it decal_01, 02, 03 or 04. The game will then use a special material on the geometry, or make it invisible if no decal is to be used.

[[File:newmodel_decals01.png]]

== Labels ==

Dynamic 3D labels are meant for naming ships and space stations. Put an empty node in the model and give it a name beginning with "label". The text is set by the game at runtime if supported.

Node scale can be used as usual but the text is not constrained to the node bounds or anything like that, so some trial will be required.

You can use multiple label nodes but they will all show the same text.

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). Certain lights will blink when a ship's landing gear is down. This feature is not complete as it needs more support in the game.

=== Thrusters ===

Thrusters are marked with dummy objects. In Blender, create an "Empty" object and point its Z-axis (change the object display type to "arrows" or "single arrow" to visualize this) where the thruster should point. Thruster size is taken from the object scale. Begin the object name with either <code>thruster</code> or <code>thruster_linear</code> so the importer can recognize them (linear thrusters light up only when moving up/down/left/right/forward/backward, not when turning).

== Internals ==

You can find some testcase models at git://github.com/Luomu/newmodels.git.

The internal scene graph consists of several of these nodes:

{| class="wikitable"
|-
| Node|| Base class. A node can have a name and one or more parents.
|-
| Group|| A group is a Node that can have several children.
|-
| MatrixTransform|| A Group that applies a transformation to its child nodes when rendering.
|-
| StaticGeometry|| Contains one or more StaticMeshes.
|-
| LOD|| Detail level control node, picks one of the child nodes based on the approximate size of the model on screen.
|-
| ModelNode || Can be used to attach another Model as a submodel. Use case: dynamic equipment on ships.
|-
| More!||Some marginal nodes that exist at the moment are:

* Thruster: spaceship thruster
* Billboard: can be used for light sprites (navlights on ships)
* Label3D: dynamic 2d text, meant for labeling ships
|}

MatrixTransform nodes are the most commonly used, if a geometry is rotated or scaled it will be parented to a MatrixTransform. A simple form of instancing can be achieved by adding a geometry as the child of several separate MatrixTransforms.

During rendering, the graph is traversed twice. Once for opaque objects, and once for transparent objects (which includes decals, thrusters). The model system does not perform any depth sorting, this improvement job needs to be done elsewhere.

=== Animations ===

An animation consists of Channels. Each channel controls one node (always a MatrixTransform) and has a list of position and rotation Keys. Each key has a time and value. Keys are always linearly interpolated.

At first the animations had proper play/pause/loop functionality but right now it is not so. Animation progress (and fun things like serialization) needs to be controlled directly by whatever feature uses the animation (see: landing gear).

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

== 3DS Max ==

in 3DS Max an empty node can be created using a dummy object found in the helper objects section

[[Category:Art]]

Interacting with the player: BBS forms

2012-11-18T18:44:36Z

ImTheFish:

The bulletin board system is currently the only place where real dialogue between a script and the player can take place. Bulletin boards can exist within any <code>SpaceStation</code> in the current system. They are created in a station the first time that a ship is either spawned, or lands, in that station. They continue to exist until the player leaves the system or quits the game. They are not saved in saved games, although a saved game contains information about which ones did exist.

When a bulletin board is created, the <code>onCreateBB</code> event is triggered, and passes the <code>SpaceStation</code> body in which that bulletin board was created. There is an exception to this: The event is not triggered after loading a game for those bulletin boards which, having existed at the time of saving, are re-created. The consequences of this will be covered later (see "[[Surviving a reload]]").

There are two components to any mission's entry on a bulletin board: The advert and the form. The advert is the part that is displayed on the main bulletin board list, along with all the other entries. The form is the part that appears on screen when the player clicks the advert's button.

==Internationalization==

It is important that scripters are familiar with the Translations library (scroll down to "Lua module translation"). A list of <code>Translate:Add()</code> calls are usually placed in a file named <code>Languages.lua</code> and kept in the same subdirectory as the script that needs them.

This is by convention only; all translations, regardless of filename, are available to all scripts, and it would technically be perfectly possible to recycle the translated strings provided by another script. In order to keep the workload as simple as possible for translators, however, we do prefer the convention to be followed.

The script itself makes use of translated strings by getting the translator function and using it to translate strings by token. So, if the <code>Languages.lua</code> file contained this:

Translate:Add({
English = {
['Please, help me!'] = 'Please, help me!',
},
Deutsch = {
['Please, help me!'] = 'Bitte, hilf mir!',
},
})

then in the main script, you would first get the translator function:

local t = Translate:GetTranslator()

where <code>t</code> could be any other convenient name, in the event that you already have a variable named <code>t</code>. Once you have your translator, you can simply use it to translate by giving it the key:

Comms.ImportantMessage(t('Please, help me!'))

This would put "''Please, help me!''" on the screens of English players, and "''Bitter, hilf mir!''" on the screens of German players.

The translator is fully documented in the codedoc. For the remainder of the document, I shall be using string literals. This is for clarity only; all custom scripts should be fully translatable if they are intended to be included with the game.

==The BBS advert==

Adverts are placed onto a BBS by calling the station's <code>AddAdvert()</code> method, once the bulletin board has been created. Depending on the nature of your script, you might want to always place one advert on every station (as seen with the Breakdowns & Servicing script), or you might want to place an arbitrary number of adverts on a given station (as seen with deliveries, or assassinations).

The opportunities to add an advert are presented by two events. <code>onCreateBB</code> is the obvious one; there is also <code>onUpdateBB</code>, which is called for all existing bulletin boards in the current system, approximately once every hour or two. The actual interval is not particularly predictable.

The <code>AddAdvert()</code> method takes three arguments. The first is the text that will appear on the advert. The second is the function that will be called when the player clicks the advert. The third is optional, and is a function that can be called when the advert is deleted for any reason.

<code>AddAdvert()</code> returns a reference number, which can subsequently be used to remove the advert using <code>RemoveAdvert()</code>.

It's the job of the scripter to decide how many, if any, adverts to add to a bulletin board when <code>onCreateBB</code> is triggered, and whether to add or remove any when <code>onUpdateBB</code> is triggered. Tests could include the population of the system, the type of starport or the type of planet. In the future, tests will be able to include the government type of the system.

One important thing to bear in mind is that the script cannot query a bulletin boad to find out what adverts already exist. Each script must carefully track each advert that it has created if it is to have any control over how long they remain, and to be able to re-create them after a reload.

Here is an example of adding an advert. The effect of clicking the advert is simply to send a message to the player console with the name of the station. The advert is only added if the station is in space. There is no mission here; I am simply illustrating the mechanics of adding the advert.

local onCreateBB = function (station)

-- This function can be in any scope that's visible when AddAdvert() is called
local sendStationName = function ()
Comms.ImportantMessage(station.label)
end

if station.type == 'STARPORT_ORBITAL' then
station:AddAdvert('Need the name of this station?',sendStationName)
end
end

Event.Register("onCreateBB", onCreateBB)

This code will create an advert:

[[File:interact.bbsad.1.png]]

Looking at the image, you will notice that my advert has appeared at a completely arbitrary location on the bulletin board. There is no way to specify the location, and no way to determine it.

Clicking on the advert causes this to happen:

[[File:interact.bbsad.2.png]]

Even though the only thing our function did was to send a message to the console (visible at the bottom), you can see that Pioneer automatically created a form for our advert. The only control is the "Go back" button, and the name and face are defaulted to that which was displayed on the main bulletin board.

==The BBS form==

Once the player has clicked on an advert, they are presented with a form. Each advert has only one form. The content of the form is added by the script, and can be modified at any time. It consists of a title, a face, a message and zero or more clickable options.

The form itself is passed to the function specified in the <code>SpaceStation.AddAdvert()</code> method. In the example above, that function would be <code>sendStationName()</code>, which simply ignored any parameters sent to it. This resulted in the form being blank.

The form object which is passed to this function has methods for adding the content. <code>SetTitle()</code> and <code>SetMessage()</code> each accept a string. <code>SetFace()</code> takes a table of information which defines the photofit face on the left. <code>AddOption()</code> adds clickable options with buttons. <code>Clear()</code> removes the Message and Options, but preserves the Title and Face, while <code>Close()</code> acts the same way as the "Go back" button.

The following example doesn't have any clickable options, but does have a customized form:

local populateForm = function (form)
local facedata = {
name = "Bob",
female = true,
title = "Lorry driver",
}

form:SetTitle('This appears above the face picture')
form:SetFace(facedata)
form:SetMessage([[This is the main message.

It is normally a multi-line string.]])
end

local onCreateBB = function (station)
station:AddAdvert('This appears in the advert list',populateForm)
end

Event.Register("onCreateBB", onCreateBB)

As before, an advert was created:

[[File:interact.bbsad.3.png]]

Randomly, it has appeared at the top of the list.

Clicking on the advert causes this to happen:

[[File:interact.bbsad.4.png]]

Now we can see that <code>populateForm</code> was called, and it successfully filled the form with content. All of the face options were optional; if they aren't provided, Pioneer will choose random values. I have left out a couple of options here; it's wise to specify them all, because after a saved game is loaded, it's the script's job to make sure that the same face appears (see "[[Surviving a reload]]").

==Adding options to the form==

In the example above, I created a function named <code>populateForm()</code> which was run when the advert button was clicked. That's not the only time it can be run; it is also run whenever options on its form are clicked.

To make use of this, it is passed two additional parameters, both of which <code>populateForm()</code> ignored. The first parameter is the form object, the second is the advert's unique reference and the third is the number of the option that was clicked. Because it handles all chat events, by convention we instead name this function <code>onChat()</code>, which is how it shall be named from now on.

The previous example did not store or use the value returned by <code>AddAdvert()</code>. It is this value which is sent as the second parameter; very useful if your script adds several adverts, each of which might have slightly differently worded content.

When the advert was clicked in the main bulletin board list, it was passed the value <code>0</code> as the option.

Form options are declared like this:

form:AddOption('I am option one',1)
form:AddOption('I am option two',2)

These options will appear with the specified caption, and will call <code>onChat()</code>, which will receive the form object, the advert reference and the number that was specified after the caption in <code>AddOption()</code>.

The codedoc has a brilliant example of a complete onChat, which I will reproduce here:

local onChat = function (form, ref, option)
form:Clear()

-- option 0 is called when the form is first activated from the
-- bulletin board
if option == 0 then

form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Yellow", 3)
form:AddOption("Blue", 4)
form:AddOption("Hang up.", -1)

return
end

-- option 1 - red
if option == 1 then
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Hang up.", -1)
return
end

-- option 2 - green
if option == 2 then
form:SetMessage("Ahh green, the colour of trees.")
form:AddOption("Hang up.", -1)
return
end

-- option 3 - yellow
if option == 3 then
form:SetMessage("Ahh yellow, the colour of the sun.")
form:AddOption("Hang up.", -1)
return
end

-- option 4 - blue
if option == 4 then
form:SetMessage("Ahh blue, the colour of the ocean.")
form:AddOption("Hang up.", -1)
return
end

-- only option left is -1, hang up
form:Close()
end

Here, every time <code>onChat()</code> is called, regardless of the specified option, the form is cleared. The option is checked, and the relevant content is added to the form. Any other functions can be called from here, and this is how the script gets input from the player.

An alternative format might be this:

local onChat = function (form, ref, option)
form:Clear()

local options = {
[0] = function ()
form:SetTitle("Favourite colour")
form:SetMessage("What's your favourite colour?")

form:AddOption("Red", 1)
form:AddOption("Green", 2)
form:AddOption("Yellow", 3)
form:AddOption("Blue", 4)
form:AddOption("Hang up.", -1)
end,
[1] = function ()
form:SetMessage("Ahh red, the colour of raspberries.")
form:AddOption("Hang up.", -1)
end,
[2] = function ()
form:SetMessage("Ahh green, the colour of trees.")
form:AddOption("Hang up.", -1)
end,
[3] = function ()
form:SetMessage("Ahh yellow, the colour of the sun.")
form:AddOption("Hang up.", -1)
end,
[4] = function ()
form:SetMessage("Ahh blue, the colour of the ocean.")
form:AddOption("Hang up.", -1)
end,
[-1] = function ()
form:Close()
end
}
options[option]()
end

==The player's mission list==

Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity.

The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab.

The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>AddMission()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. So, it usually looks a little like <code>ref = Game.player:AddMission(table_of_info)</code>.

In practice, it might look more like this:

local mission_storage={}

table.insert(mission_storage,Game.player:AddMission({
type = "Fetch beer",
client = "Bert Beerbreath",
due = Game.time + 600, -- ten minutes' time
reward = 10,
location = Game.player.frameBody.path, -- here, basically
status = 'ACTIVE'
}))

table.insert(mission_storage,Game.player:AddMission({
type = "Fetch curry",
client = "Curt Curryface",
due = Game.time + 900, -- fifteen minutes' time
reward = 5,
location = Game.player.frameBody.path,
status = 'ACTIVE'
}))

I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here.

This creates visible missions on the mission screen:

[[File:interact.misscrn.1.png]]

These missions will remain exactly like that forever, unless a script explicitly makes changes. There is no automatic logic, and no automatic removal. Your script must keep track of them. In this example, I have the references in the <code>mission_storage</code> table.

The <code>UpdateMission()</code> method allows a script to alter any detail. The status can be <code>'ACTIVE'</code>,<code>'FAILED'</code> or <code>'COMPLETED'</code>. I'm going to change the status of the first mission to <code>'COMPLETED'</code>.

Game.player:UpdateMission(mission_storage[1],{status='COMPLETED'})

The updated information can be a partial table. The unspecified members will remain unchanged:

[[File:interact.misscrn.2.png]]

The <code>GetMission()</code> method allows a script to read data from a mission, if the script has the reference. It returns a table with that information. Here, I'm going to add ten minutes to the deadline of the second mission:

local due_date = Game.player:GetMission(mission_storage[2]).due
Game.player:UpdateMission(mission_storage[2],{due = due_date + 600})

The result:

[[File:interact.misscrn.3.png]]

The <code>RemoveMission()</code> method allows a script to remove a mission. Here I remove the completed one:

Game.player:RemoveMission(mission_storage[1])
table.remove(mission_storage,1)

And here it isn't:

[[File:interact.misscrn.4.png]]

==Mission flavours==

A script can define a mission, and then place many instances of it onto many bulletin boards. A script that introduces many instances should provide some variety; it would harm immersion if all delivery missions were worded identically, for example.

To introduce variety, we can use tables, which contain all of the lines needed for bulletin board forms, messages and so forth. It's then a simple matter to use a similar, but differently worded, table to make the same misison appear different. A flavour might look like this:

{
title = "Shill bidder wanted for auction",
greeting = "Hi there. Want to earn some quick cash?",
yesplease = "Sure. What do you need me to do?",
nothanks = "No, ta - this looks a bit shady.",
}

An alternative flavour might look like this:

{
title = "Help me win an auction.",
greeting = "Hello. I'll pay you to place fake bids for me. Interested?",
yesplease = "Yes, I like to live dangerously.",
nothanks = "No thanks; I'd rather not get arrested for fraud.",
}

Ideally, we just need a table with as many of these as we can be bothered to write, then select one at random.

There are issues with translation, though. Because flavours are often full of colloquial language, and can feature several ways of saying basically the same thing, translating them all word-for-word is not necessarily productive. To this end, the Translate system features a pair of methods which can ease the handling of flavours, especially in different languages.

The <code>Translate:AddFlavour()</code> method allows a flavour to be added, and marked as being of a specific language. By convention, these statements would appear in the script's <code>Languages.lua</code> file so that translators could see them and be inspired to write some in other languages. The method takes three arguments. The first is the language of the flavour, as a string. The second is a name, so that the <code>Translate</code> class can give flavours back to the correct script. The third is the flavour table itself. If my script was named <code>TestModule</code>, I might define the two flavours above in my <code>Languages.lua</code> as follows:

Translate:AddFlavour('English','TestModule',{
title = "Shill bidder wanted for auction",
greeting = "Hi there. Want to earn some quick cash?",
yesplease = "Sure. What do you need me to do?",
nothanks = "No, ta - this looks a bit shady.",
})

Translate:AddFlavour('English','TestModule',{
title = "Help me win an auction.",
greeting = "Hello. I'll pay you to place fake bids for me. Interested?",
yesplease = "Yes, I like to live dangerously.",
nothanks = "No thanks; I'd rather not get arrested for fraud.",
})

As an added benefit, <code>Translate:AddFlavour()</code> checks all flavour tables for uniformity. It does this by comparing all of the table's keys with that of the first English flavour that was specified; a technical consequence of this is that an English flavour needs to come first in your <code>Languages.lua</code> file, otherwise Pioneer will give you an error.

To fetch the flavours into your script, use <code>Translate.GetFlavours()</code>. It takes a single argument, which is the module name that was specified in <code>AddFlavour()</code>'s second parameter. It doesn't matter to <code>Translate</code> how many flavours there are in each language, or whether it's an equal number. If my current language is not English, and there are no flavours in that language, English flavours will be used instead. If there is only one flavour in my language, I will only see that one variety.

The following example will select a random flavour from my flavour tables.

local all_flavours = Translate:GetFlavours('TestModule')
local flavour = all_flavours[Engine.rand:Integer(1,#all_flavours)]

<code>GetFlavours()</code> returns a table of flavours. The second line of code generates a random number between 1 and the number of flavours in that table, and returns that flavour from the table. After this, <code>flavour.title</code> will either be <code>"Shill bidder wanted for auction"</code> or <code>"Help me win an auction."</code>. Adding more flavours means more variety.

==Maintaining immersion==

Fictionally, of course, this bulletin board is visible to any and all ships that dock at the space station, not just the player. It is important that bulletin board missions are not all scaled to the capabilities of the player. Delivery missions with unreasonable deadlines should not be ruled out. Neither should cargo missions requiring much more cargo space than the player's ship has, or combat missions for which the player is completely unqualified.

These missions should deal with the player gracefully; either allowing them to fail, and providing consequences, or preventing them from being given the mission.

It's also important, if your script serves many instances of a mission, to periodically clear away bulletin board adverts and place new ones. Not just those with obvious time constraints, but any others; the assumption that the player should make is that perhaps some other character has taken these missions.