PioneerWiki - User contributions [en]

ServerAgent

2015-02-03T07:37:43Z

RobN: Created page with "The ServerAgent is an '''experimental''' feature that allows Pioneer scripts to make calls to an API server. Out of the box its disabled and not used by any of the stock modul..."

The ServerAgent is an '''experimental''' feature that allows Pioneer scripts to make calls to an API server. Out of the box its disabled and not used by any of the stock modules. That will change once we gain experience with it.

== Enabling the agent ==

To enable the agent, you need to edit your <tt>config.ini</tt> and set two parameters:

* <tt>EnableServerAgent=1</tt>
* <tt>ServerEndpoint=http://somewhere/api</tt>

Obviously, you'll need the URL of an API server.

== Using the agent ==

The agent has one method:

ServerAgent.Call(method, params, successCallback, failureCallback)

The arguments are:

* <tt>method</tt>: string, name of the remote method to call
* <tt>params</tt>: (optional) arbitrary data, converted to JSON and sent to the server
* <tt>successCallback</tt>: (optional) function called on successful return from the server. Passed any data returned from the server
* <tt>failureCallback</tt>: (optional) function called on failure. Passed an error message

<tt>ServerAgent.Call()</tt> returns immediately. If there is already a call being processed, calls are queued.

== Writing a server ==

Servers will receive a HTTP POST request against the endpoint URL like this:

POST /api/method HTTP/1.1
User-Agent: PioneerServerAgent/git.0f09618
Content-Type: application/json

{"foo":"bar"}

The `params` argument to `ServerAgent.Call()` is JSON-encoded and sent in the request body.

The server should return something like:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 14

{"baz":"quux"}

The result body is JSON-decoded and passed to the `successCallback`.

This style of server is trivially implemented in just about any programming language. A sample server is available at https://github.com/robn/pioneer-apiserver/blob/master/pioneer-apiserver.psgi

Translations

2014-03-03T00:10:15Z

RobN: /* For mod developers */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository unless you've checked it with a core developer first and it has a good reason.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an table of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex. [http://json.org/string.gif Here] is a useful chart showing how characters are interpreted.

If you're submitting code that requires a new language you should only include <tt>en.json</tt>. Please tag @robn or @johnbartholomew in your pull request so they can create a new resource in Transifex and make sure a language update is done at merge. If you don't do this then you'll break the game for non-English users.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Model debug flags

2014-02-01T11:47:03Z

RobN: Created page with "The model system can be instructed to draw models with extra information visible, such as the collision mesh, tag locations, etc. The same information that is available in the..."

The model system can be instructed to draw models with extra information visible, such as the collision mesh, tag locations, etc. The same information that is available in the modelviewer is also available in-game. Here's how to activate it via the console.

== Getting a model reference ==

You need to get a reference to a model into the console environment. Every model-based physical body (that is anything inheriting from <tt>ModelBody</tt>: ships, spacestations, cargo, missiles) has a <tt>model</tt> attribute attached. For the player, that's available as:

<pre>model = Game.player.model</pre>

For other models, the easiest way to get a reference to the body is to target the object and then obtain the navtarget or combat target from the player:

<pre>model = Game.player:GetNavTarget().model
model = Game.player:GetCombatTarget().model</pre>

== Set debug flags ==

Once you've got a model reference, pass a list of the flags you want to enable to its <code>SetDebugFlags()</code> method:

<pre>model:SetDebugFlags({"BBOX","COLLMESH"})</pre>

To disable all flags, pass an empty list:

<pre>model:SetDebugFlags({})</pre>

== Available flags ==

=== BBOX - Bounding box ===

Displays the axis-aligned bounding box of the model. This includes the shield mesh, even if its not currently on screen. The bounding box is used for early collision culling and body size estimates.

[[File:Model-debug-bbox.png|800x500px]]

=== COLLMESH - Collision mesh ===

Displays the collision mesh of the model. Also shows special collision-based surfaces (such as docking surfaces).

[[File:Model-debug-collmesh.png|800x500px]]

[[File:Model-debug-collmesh-station.png|800x500px]]

=== WIREFRAME - Wireframe mode ===

Draws the model in wireframe. This can result in a performance hit on complex modes.

[[File:Model-debug-wireframe.png|800x500px]]

=== TAGS - Show model tags ===

Draws an axis indicator at any <tt>tag_</tt> points defined on the model.

[[File:Model-debug-tags.png|800x500px]]

=== DOCKING - Show docking positions ===

Draws an axis indicator at docking points defined on the model (typically a station). Currently the points are drawn quite small, making them difficult to see from a distance.

[[File:Model-debug-docking-station.png|800x500px]]

File:Model-debug-wireframe.png

2014-02-01T11:37:03Z

RobN:

File:Model-debug-tags.png

2014-02-01T11:36:32Z

RobN:

File:Model-debug-docking-station.png

2014-02-01T11:36:17Z

RobN:

File:Model-debug-collmesh-station.png

2014-02-01T11:36:16Z

RobN:

File:Model-debug-collmesh.png

2014-02-01T11:36:00Z

RobN:

File:Model-debug-bbox.png

2014-02-01T11:35:05Z

RobN:

Model system

2014-01-29T11:39:38Z

RobN: /* Tag points */

== 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 - 128. Default 100.
|-
| 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||This material will use the pattern/colour system. Read more below.
|-
| unlit||No lighting, diffuse value can still be used to tint the result
|-
| two_sided||Self-explanatory, however normals on the other side are not automatically inversed (no good way to do this) so the usefulness is limited
|-
| alpha_test||Pixels with alpha value < 0.5 are discarded, this is good for fences and such. It produces sharp edges but the geometry does not need to be sorted.
|}

[[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 value ranges are:
* 0-63: not affecting (black)
* 64-127: first color (dark gray)
* 128-191: second color (mid gray)
* 192-255: third color (light gray/white)
You can set all three channels to these in RGB, or only the L channel in HSL (Hue, Saturation, Level) to get the needed gray.

The alpha channel of the pattern defines it's transparency. It can be used for gradual changes from colored to blank, but not for gradients between different gray ranges. Useful for showing wear on the pattern, or coloring some parts more lightly. Alpha channel can be created by using a layer mask.

Antialiasing (which generates small gradients) can cause artifacts, especially at black-white boundaries. To avoid it, try lowering the contrast on problematic places. Even different grays can be used from the same range, they will indicate the same color.

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 radius 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]]

Tag points have not been fully implemented. If you want to use this feature, please content the devs.

=== Tag points ===

As at 29 January 2014.

{| class="wikitable"
|-
| tag_camera_front tag_camera_rear tag_camera_left tag_camera_right tag_camera_top tag_camera_bottom
|| Position and orientation for the six internal view cameras. X "left", Y "up", Z "out" of the ship (in the direction the camera is facing). If one is missing, tag_camera will be used with its orientation adjusted for the appropriate direction. Camera tag scaling should be 1 on all three axes to avoid glitches.
|-
| tag_camera || Fallback for the specific camera tags. Useful if you don't want to specify all points. Defaults to the ship origin.
|-
| tag_gunmount_N || Gun positions, X "left", Y "up", Z "out" of the ship (in the fire direction). Note at this time, only N = 0 or 1 will work, and they correspond to "front" and "rear" guns in the UI. The "max_lasers" ship definition field still takes precedence (ie if max_lasers = 1, tag_gunmount_1 will never be used). Defaults to the ship origin.
|-
| tag_landing || A point at the lowest point of the ship with gear extended. Used during landing to make sure the ship sits at the right place on the surface. Defaults to the lowest point in the ships AABB, which is usually unsuitable because it includes the shield mesh.
|-
|}

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes.

For more control, name objects with the prefix "collision_" and they will be added to form a collision mesh (these objects will not be visible geometry, and the bounding box will not be generated).

Note, these names are reserved for station collision trigger surfaces:

* collision_pad1
* collision_pad2
* collision_pad3
* collision_pad4

You can also import a separate mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

The collision meshis separate from all detail levels, so it should be only defined once.

[[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 ==

Note, these special nodes are only imported from the most detailed LOD, there is no need to duplicate them. They are rendered outside the detail level system.

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). This feature will be more customizable someday, but for now the following name prefixes are recognized:

* navlight_red: blinking red light, with ships when landing gear is down, with stations constantly
* navlight_green: blinking green light when landing gear is down
any other navlight_ is blue, on when landing gear is down.
* space stations, navlight_pad<number> lights change according to landing pad reservation status

=== 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]]

Model system

2014-01-29T11:39:17Z

RobN: /* Tag points */

== 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 - 128. Default 100.
|-
| 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||This material will use the pattern/colour system. Read more below.
|-
| unlit||No lighting, diffuse value can still be used to tint the result
|-
| two_sided||Self-explanatory, however normals on the other side are not automatically inversed (no good way to do this) so the usefulness is limited
|-
| alpha_test||Pixels with alpha value < 0.5 are discarded, this is good for fences and such. It produces sharp edges but the geometry does not need to be sorted.
|}

[[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 value ranges are:
* 0-63: not affecting (black)
* 64-127: first color (dark gray)
* 128-191: second color (mid gray)
* 192-255: third color (light gray/white)
You can set all three channels to these in RGB, or only the L channel in HSL (Hue, Saturation, Level) to get the needed gray.

The alpha channel of the pattern defines it's transparency. It can be used for gradual changes from colored to blank, but not for gradients between different gray ranges. Useful for showing wear on the pattern, or coloring some parts more lightly. Alpha channel can be created by using a layer mask.

Antialiasing (which generates small gradients) can cause artifacts, especially at black-white boundaries. To avoid it, try lowering the contrast on problematic places. Even different grays can be used from the same range, they will indicate the same color.

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 radius 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]]

Tag points have not been fully implemented. If you want to use this feature, please content the devs.

=== Tag points ===

As at 23 September 2013.

{| class="wikitable"
|-
| tag_camera_front tag_camera_rear tag_camera_left tag_camera_right tag_camera_top tag_camera_bottom
|| Position and orientation for the six internal view cameras. X "left", Y "up", Z "out" of the ship (in the direction the camera is facing). If one is missing, tag_camera will be used with its orientation adjusted for the appropriate direction. Camera tag scaling should be 1 on all three axes to avoid glitches.
|-
| tag_camera || Fallback for the specific camera tags. Useful if you don't want to specify all points. Defaults to the ship origin.
|-
| tag_gunmount_N || Gun positions, X "left", Y "up", Z "out" of the ship (in the fire direction). Note at this time, only N = 0 or 1 will work, and they correspond to "front" and "rear" guns in the UI. The "max_lasers" ship definition field still takes precedence (ie if max_lasers = 1, tag_gunmount_1 will never be used). Defaults to the ship origin.
|-
| tag_landing || A point at the lowest point of the ship with gear extended. Used during landing to make sure the ship sits at the right place on the surface. Defaults to the lowest point in the ships AABB, which is usually unsuitable because it includes the shield mesh.
|-
|}

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes.

For more control, name objects with the prefix "collision_" and they will be added to form a collision mesh (these objects will not be visible geometry, and the bounding box will not be generated).

Note, these names are reserved for station collision trigger surfaces:

* collision_pad1
* collision_pad2
* collision_pad3
* collision_pad4

You can also import a separate mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

The collision meshis separate from all detail levels, so it should be only defined once.

[[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 ==

Note, these special nodes are only imported from the most detailed LOD, there is no need to duplicate them. They are rendered outside the detail level system.

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). This feature will be more customizable someday, but for now the following name prefixes are recognized:

* navlight_red: blinking red light, with ships when landing gear is down, with stations constantly
* navlight_green: blinking green light when landing gear is down
any other navlight_ is blue, on when landing gear is down.
* space stations, navlight_pad<number> lights change according to landing pad reservation status

=== 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]]

Code style

2014-01-21T02:54:43Z

RobN: /* Licensing */

This page describes some of the code style used in Pioneer. Its probably incomplete, but it should be correct. If you see something in the code that doesn't match what's described here, this guide takes precedence (and please submit a patch to fix it!)

== Licensing ==

Engine and Lua code is [http://www.gnu.org/licenses/gpl.html GPL 3]. Assets (include Lua-based data files like ship defs) are [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3]

Include these two lines at the top of each file (suitably commented):

Copyright © 2008-2014 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2014 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

* Hard tabs, 4-space aligned.
* Inner spaces after tabs to align arguments on multiple lines, etc

== Constants ==

* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible

== Name style ==

* Classes: FooBar
* Methods: FooBar
* Class members: m_fooBar
* Static members: s_fooBar
* Constants (defines and <tt>static const</tt>): FOO_BAR

Names should generally be chosen for what the thing represents. It shouldn't have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). Just name it so its crystal clear what it is.

(Exception: member variables have a <tt>m_</tt> or <tt>s_</tt> to disambiguate them from local names and to match C++ conventions).

There's also a few abbreviated names that are commonly used throughout the codebase, eg <tt>Renderer *r</tt>, <tt>lua_State *l</tt>, etc. Try to prefer them where appropriate.

== Include guards ==

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

* Ship.h
#ifndef SHIP_H

* WorldView.h
#ifndef WORLDVIEW_H

* graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

Avoid assigning explicit integer values. Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable). If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

Code review

2014-01-15T12:24:44Z

RobN:

== Why do code review? ==

Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good quality, is consistent with the rest of the codebase and takes Pioneer in the direction that the community wants it to go.

== When does it happen? ==

Code review can happen at any time, whenever you like. For small items of work it will get at least one review when it is submitted for inclusion (via a pull request). For a large development you may wish to find to someone to review your code periodically, to make sure you're on the right track. If you're starting to feel a bit unsure about what you're doing, that's probably a good time to ask someone!

You don't have to do this of course, but be aware that the reviewers don't particularly being asked to review hundreds or thousands of lines of code changes that appear out of nowhere. You face a good chance of having your code rejected outright or ignored completely, and that sucks. So if you're going to do something massive, at least check in at the start to make sure someone knows about it.

== Who can review code? ==

Anyone that wants to! Anyone can use the review tools on Github to read and comment on code while its under development or test pull requests.

In the case of a pull request, someone with commit access needs to do the final sign-off (typically, but not necessarily, at the same time as merging). If you don't have commit access you can still help make life easier for that person by leaving comments and working with the original submitter.

== I have commit access, does my code need to be reviewed? ==

No, you have commit access for a reason - you've proven that you can be trusted to be a good steward for the project. You should feel free to change whatever you want or need to, but as you do you should be considering all the points normally covered by a review. Self-review, if you like.

That said, no person is an island. Be sure to ask for help if you need it, even if its just a feeling that something isn't right.

== What gets reviewed? ==

Every single change is a candidate for review, no matter how small. Most review will happen in a pull request, but you can be reviewing code by reading the commit history or even by reading code as you're working on it.

Here are some good things to look out for:

* Bugs, logical errors, mathematical errors, typos (any simple, isolated code error). These are easy. If you find a bug during testing or by looking at the code, either fix it or tell the submitter to fix it. It's easy because everyone agrees that bugs need to be fixed.

* Uncertainty about some code logic or behaviour ("Is this maths right?" "Did the submitter intend this weird behaviour?"). These are easy: Ask the submitter (obviously). Explanatory comments are usually the "fix" here.

* Code style errors (braces, whitespace, naming conventions, etc). Same as bugs: fix it, or tell the submitter fix it. Not everyone agrees about the importance of code style, or perhaps even what style we should be using (particularly since the existing codebase is not totally consistent), but we have a [[Code_style|code style guide]] and we want everything to conform to it. If there is some aspect of style not covered by the code style guide on the wiki, amend the guide and tell the submitter to fix their style. Yes, style is subjective, and it's not the submitter's fault that they didn't use the "correct" style, since it may not have been clear what was the "correct" style when they made the PR, but its not worth arguing about - the time and energy to discuss it costs more than just fixing the code.

* Messy git history. Fix it or ignore it. The trouble with telling the submitter to fix it is that many of our contributors don't have enough confidence wth git to do it right and the ones that do tend not to submit messy histories in the first place. So its not worth arguing about. Just do the best you can to keep your own history tidy, but if its not working out don't stress too much about. If you really need help, talk to someone that can drive Git well; they can help you out.

* Game design uncertainty ("Do we want this feature?", "Do we want it to behave this way?"). For the most part you should choose what you think is best. You should be paying attention to what the other developers and the players are asking for and be aware of what other developments are happening, and from there be able to make a reasonable decision. If you don't know, ask someone who does. But remember that you should not reject an idea simply because you prefer it a different way. Of course your opinion matters, but try to balance everyone's needs as much as possible. (This is hard. Please ask for help).

* Code structure problems ("We want the feature, but not implemented like this"). Structural problems can take a significant effort to fix and they make future code maintenance harder. They're the ones that often end up needing to be ripped out or rewritten later. The difficulty is that its often a ridiculous amount of effort to do something the "right" way, especially if it relates to a very old piece of code. The rule of thumb then is to permit mess if its necessary, but do the best you can to keep it contained. Remember that you're now adding to the cleanup work that someone else will have to do in the future.

== Merging looks hard, do I have to? ==

No. You can still review code without having to do the merge yourself. If you're not confident enough with git to do the merge properly, please ask someone who can. Mention that your code review is done and you're happy with it and they will merge it without any fuss.

Commit access

2014-01-15T12:22:43Z

RobN:

== What is commit access? ==

Having commit access means you have the ability to push code directly to the main Pioneer repository.

== How do I get commit access? ==

Usually, just by asking. If you're known to the other committers to be someone who can be trusted to be a good steward of the project (usually shown by the quality of previous contributions) then you'll be given access to push to the repository. This is deliberately a subjective measure, but rest assured, the bar is set pretty low. Its mostly just a check to make sure you aren't going to do something stupid.

In some circumstances you might be offered commit access. The same bar is set there. It usually happens when the other committers finds themselves thinking "this person would be a good committer".

== What do I need to know when pushing? ==

There's a few things that are special to the way we work that you need to know about.

=== Code style ===

We have a [[Code_style|code style guide]]. Learn it, love it. There's almost certainly something in there you'll hate, because we all have different opions on code style. Don't argue, just use it - its what we've got!

=== Code review ===

Read the page about the [[Code_review|code review process]]. You're expected to be reviewing your own code according to the guildlines set out there, and you're encouraged to find another person to review your code if its particularly large or complex. Read that page for more info about that.

There is no obligation for commiters to review other people's work, but it would be very helpful if you could. If everyone is involved, then the total workload on any individual remains small, giving everyone time to work on their code.

=== Update the changelog ===

[https://github.com/pioneerspacesim/pioneer/blob/master/Changelog.txt Changelog.txt] is where we track the history of the project. Each time you make a change, add a brief description of it to the Changelog. Include the Github issue or pull request number if it has one. The description should be something that is understandable by players. Choose an appropriate category, start a new month header at the start of the month, and preserve the existing formatting. Have a look through the history to get a feel for how it works.

=== Don't break the build ===

Pioneer is regularly built by an autobuild script, sometimes as often as once per day. This is done using the Makefile/autotools system (all platforms). You must take care to ensure that everything that lands on the master branch builds correctly with the autotools/GCC build. This could be a problem for Windows-based developers using MSVC; please do the best you can and ask for help if you need it.

Development team

2014-01-15T12:17:18Z

RobN: /* AUTHORS */

This page lists a few of the people that work on Pioneer, and their roles. If you need help with with a particular part of the game, or code or asset development, you should be able to find the right person here.

== Who's who? ==

Some of our people, and what they know about. These aren't necessarily owners of these areas, but they definitely know lots about it and you should talk to them before you start.

* Robert Norris (robn): all of the code, project admin, website, everything
* John Bartholomew (jpab): all of the code, project admin, everything

Add your name and details if you consider yourself an expert in one or more areas and you'd like to make yourself available.

== Project admin ==

There's a bunch of administrative stuff that needs to be done in a project like this. Things like looking after the repository and commit rights, the build machines, various support services (eg Transifex), managing the money, paying for domain registration and hosting, that sort of thing. That's handled quietly by robn and jpab. Yell at one of us if you have any questions.

== AUTHORS ==

We list everyone that has ever contributed to the project (even a single-character tweak) in the [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt AUTHORS.txt] file.

Development team

2014-01-15T12:16:51Z

RobN: /* AUTHORS */

This page lists a few of the people that work on Pioneer, and their roles. If you need help with with a particular part of the game, or code or asset development, you should be able to find the right person here.

== Who's who? ==

Some of our people, and what they know about. These aren't necessarily owners of these areas, but they definitely know lots about it and you should talk to them before you start.

* Robert Norris (robn): all of the code, project admin, website, everything
* John Bartholomew (jpab): all of the code, project admin, everything

Add your name and details if you consider yourself an expert in one or more areas and you'd like to make yourself available.

== Project admin ==

There's a bunch of administrative stuff that needs to be done in a project like this. Things like looking after the repository and commit rights, the build machines, various support services (eg Transifex), managing the money, paying for domain registration and hosting, that sort of thing. That's handled quietly by robn and jpab. Yell at one of us if you have any questions.

== AUTHORS ==

We list everyone that has ever contributed to the project (even a single-character tweak) in the [][[https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt AUTHORS.txt]] file.

Development team

2014-01-15T12:16:27Z

RobN: /* AUTHORS */

Development team

2014-01-15T12:16:05Z

RobN: /* AUTHORS */

This page lists a few of the people that work on Pioneer, and their roles. If you need help with with a particular part of the game, or code or asset development, you should be able to find the right person here.

== Who's who? ==

Some of our people, and what they know about. These aren't necessarily owners of these areas, but they definitely know lots about it and you should talk to them before you start.

* Robert Norris (robn): all of the code, project admin, website, everything
* John Bartholomew (jpab): all of the code, project admin, everything

Add your name and details if you consider yourself an expert in one or more areas and you'd like to make yourself available.

== Project admin ==

There's a bunch of administrative stuff that needs to be done in a project like this. Things like looking after the repository and commit rights, the build machines, various support services (eg Transifex), managing the money, paying for domain registration and hosting, that sort of thing. That's handled quietly by robn and jpab. Yell at one of us if you have any questions.

== AUTHORS ==

We list everyone that has ever contributed to the project (even a single-character tweak) in the [[https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt|AUTHORS.txt]] file.

Development team

2014-01-15T12:14:41Z

RobN: Created page with "This page lists a few of the people that work on Pioneer, and their roles. If you need help with with a particular part of the game, or code or asset development, you should b..."

This page lists a few of the people that work on Pioneer, and their roles. If you need help with with a particular part of the game, or code or asset development, you should be able to find the right person here.

== Who's who? ==

Some of our people, and what they know about. These aren't necessarily owners of these areas, but they definitely know lots about it and you should talk to them before you start.

* Robert Norris (robn): all of the code, project admin, website, everything
* John Bartholomew (jpab): all of the code, project admin, everything

Add your name and details if you consider yourself an expert in one or more areas and you'd like to make yourself available.

== Project admin ==

There's a bunch of administrative stuff that needs to be done in a project like this. Things like looking after the repository and commit rights, the build machines, various support services (eg Transifex), managing the money, paying for domain registration and hosting, that sort of thing. That's handled quietly by robn and jpab. Yell at one of us if you have any questions.

== AUTHORS ==

We list everyone that has ever contributed to the project (even a single-character tweak) in the [[AUTHORS.txt|https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt]] file.

Commit access

2014-01-15T11:58:16Z

RobN: Created page with "== What is commit access? == Having commit access means you have the ability to push code directly to the main Pioneer repository. Its expected that anyone with commit acces..."

== What is commit access? ==

Having commit access means you have the ability to push code directly to the main Pioneer repository.

Its expected that anyone with commit access is trusted and responsible. As such, committers don't need to formally go through the [[Code_review|code review process]] (though you should still be thinking about it; there's some good ideas in there).

== How do I get commit access? ==

Usually, just by asking. If you're known to the other committers to be someone who can be trusted to be a good steward of the project (usually shown by the quality of previous contributions) then you'll be given access to push to the repository. This is deliberately a subjective measure, but rest assured, the bar is set pretty low. Its mostly just a check to make sure you aren't going to do something stupid.

In some circumstances you might be offered commit access. The same bar is set there. It usually happens when the other committers finds themselves thinking "this person would be a good committer".

== What do I need to know when pushing? ==

There's a few things that are special to the way we work that you need to know about.

=== Code style ===

We have a [[Code_style|code style guide]]. Learn it, love it. There's almost certainly something in there you'll hate, because we all have different opions on code style. Don't argue, just use it - its what we've got!

=== Code review ===

Read the page about the [[Code_review|code review process]]. As a committer it doesn't directly apply to you, but there's good information about the types of problems that you should be looking for in your code before you push it.

=== Update the changelog ===

Changelog.txt is where we track the history of the project. Each time you make a change, add a brief description of it to the Changelog. Include the Github issue or pull request number if it has one. The description should be something that is understandable by players. Choose an appropriate category, start a new month header at the start of the month, and preserve the existing formatting. Have a look through the history to get a feel for how it works.

=== Don't break the build ===

Pioneer is regularly built by an autobuild script, sometimes as often as once per day. This is done using the Makefile/autotools system (all platforms). You must take care to ensure that everything that lands on the master branch builds correctly with the autotools/GCC build. This could be a problem for Windows-based developers using GCC; please do the best you can and ask for help if you need it.

Code review

2014-01-15T11:37:17Z

RobN: /* What gets reviewed? */

Code review

2014-01-15T11:35:17Z

RobN: /* What gets reviewed? */

== Why do code review? ==

Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good quality, is consistent with the rest of the codebase and takes Pioneer in the direction that the community wants it to go.

== When does it happen? ==

Code review can happen at any time, whenever you like. For small items of work it will get at least one review when it is submitted for inclusion (via a pull request). For a large development you may wish to find to someone to review your code periodically, to make sure you're on the right track. If you're starting to feel a bit unsure about what you're doing, that's probably a good time to ask someone!

You don't have to do this of course, but be aware that the reviewers don't particularly being asked to review hundreds or thousands of lines of code changes that appear out of nowhere. You face a good chance of having your code rejected outright or ignored completely, and that sucks. So if you're going to do something massive, at least check in at the start to make sure someone knows about it.

== Who can review code? ==

Anyone that wants to! Anyone can use the review tools on Github to read and comment on code while its under development or test pull requests.

In the case of a pull request, someone with commit access needs to do the final sign-off (typically, but not necessarily, at the same time as merging). If you don't have commit access you can still help make life easier for that person by leaving comments and working with the original submitter.

== I have commit access, does my code need to be reviewed? ==

No, you have commit access for a reason - you've proven that you can be trusted to be a good steward for the project. You should feel free to change whatever you want or need to, but as you do you should be considering all the points normally covered by a review. Self-review, if you like.

That said, no person is an island. Be sure to ask for help if you need it, even if its just a feeling that something isn't right.

== What gets reviewed? ==

Every single change is a candidate for review, no matter how small. Most review will happen in a pull request, but you can be reviewing code by reading the commit history or even by reading code as you're working on it.

Here are some good things to look out for:

* Bugs, logical errors, mathematical errors, typos (any simple, isolated code error). These are easy. If you find a bug during testing or by looking at the code, either fix it or tell the submitter to fix it. It's easy because everyone agrees that bugs need to be fixed.

* Uncertainty about some code logic or behaviour ("Is this maths right?" "Did the submitter intend this weird behaviour?"). These are easy: Ask the submitter (obviously). Explanatory comments are usually the "fix" here.

* Code style errors (braces, whitespace, naming conventions, etc). Same as bugs: fix it, or tell the submitter fix it. Not everyone agrees about the importance of code style, or perhaps even what style we should be using (particularly since the existing codebase is not totally consistent), but we have a [[Code_style code style guide]] and we want everything to conform to it. If there is some aspect of style not covered by the code style guide on the wiki, amend the guide and tell the submitter to fix their style. Yes, style is subjective, and it's not the submitter's fault that they didn't use the "correct" style, since it may not have been clear what was the "correct" style when they made the PR, but its not worth arguing about - the time and energy to discuss it costs more than just fixing the code.

* Messy git history. Fix it or ignore it. The trouble with telling the submitter to fix it is that many of our contributors don't have enough confidence wth git to do it right and the ones that do tend not to submit messy histories in the first place. So its not worth arguing about. Just do the best you can to keep your own history tidy, but if its not working out don't stress too much about. If you really need help, talk to someone that can drive Git well; they can help you out.

* Game design uncertainty ("Do we want this feature?", "Do we want it to behave this way?"). For the most part you should choose what you think is best. You should be paying attention to what the other developers and the players are asking for and be aware of what other developments are happening, and from there be able to make a reasonable decision. If you don't know, ask someone who does. But remember that you should not reject an idea simply because you prefer it a different way. Of course your opinion matters, but try to balance everyone's needs as much as possible. (This is hard. Please ask for help).

* Code structure problems ("We want the feature, but not implemented like this"). Structural problems can take a significant effort to fix and they make future code maintenance harder. They're the ones that often end up needing to be ripped out or rewritten later. The difficulty is that its often a ridiculous amount of effort to do something the "right" way, especially if it relates to a very old piece of code. The rule of thumb then is to permit mess if its necessary, but do the best you can to keep it contained. Remember that you're now adding to the cleanup work that someone else will have to do in the future.

Code review

2014-01-15T11:34:22Z

RobN:

== Why do code review? ==

Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good quality, is consistent with the rest of the codebase and takes Pioneer in the direction that the community wants it to go.

== When does it happen? ==

Code review can happen at any time, whenever you like. For small items of work it will get at least one review when it is submitted for inclusion (via a pull request). For a large development you may wish to find to someone to review your code periodically, to make sure you're on the right track. If you're starting to feel a bit unsure about what you're doing, that's probably a good time to ask someone!

You don't have to do this of course, but be aware that the reviewers don't particularly being asked to review hundreds or thousands of lines of code changes that appear out of nowhere. You face a good chance of having your code rejected outright or ignored completely, and that sucks. So if you're going to do something massive, at least check in at the start to make sure someone knows about it.

== Who can review code? ==

Anyone that wants to! Anyone can use the review tools on Github to read and comment on code while its under development or test pull requests.

In the case of a pull request, someone with commit access needs to do the final sign-off (typically, but not necessarily, at the same time as merging). If you don't have commit access you can still help make life easier for that person by leaving comments and working with the original submitter.

== I have commit access, does my code need to be reviewed? ==

No, you have commit access for a reason - you've proven that you can be trusted to be a good steward for the project. You should feel free to change whatever you want or need to, but as you do you should be considering all the points normally covered by a review. Self-review, if you like.

That said, no person is an island. Be sure to ask for help if you need it, even if its just a feeling that something isn't right.

== What gets reviewed? ==

Every single change is a candidate for review, no matter how small. Most review will happen in a pull request, but you can be reviewing code by reading the commit history or even by reading code as you're working on it.

Here are some good things to look out for:

* Bugs, logical errors, mathematical errors, typos (any simple, isolated code error). These are easy. If you find a bug during testing or by looking at the code, either fix it or tell the submitter to fix it. It's easy because everyone agrees that bugs need to be fixed.

* Uncertainty about some code logic or behaviour ("Is this maths right?" "Did the submitter intend this weird behaviour?"). These are easy: Ask the submitter (obviously). Explanatory comments are usually the "fix" here.

* Code style errors (braces, whitespace, naming conventions, etc). Same as bugs: fix it, or tell the submitter fix it. Not everyone agrees about the importance of code style, or perhaps even what style we should be using (particularly since the existing codebase is not totally consistent), but we have a [Code_style code style guide] and we want everything to conform to it. If there is some aspect of style not covered by the code style guide on the wiki, amend the guide and tell the submitter to fix their style. Yes, style is subjective, and it's not the submitter's fault that they didn't use the "correct" style, since it may not have been clear what was the "correct" style when they made the PR, but its not worth arguing about - the time and energy to discuss it costs more than just fixing the code.

* Messy git history. Fix it or ignore it. The trouble with telling the submitter to fix it is that many of our contributors don't have enough confidence wth git to do it right and the ones that do tend not to submit messy histories in the first place. So its not worth arguing about. Just do the best you can to keep your own history tidy, but if its not working out don't stress too much about. If you really need help, talk to someone that can drive Git well; they can help you out.

* Game design uncertainty ("Do we want this feature?", "Do we want it to behave this way?"). For the most part you should choose what you think is best. You should be paying attention to what the other developers and the players are asking for and be aware of what other developments are happening, and from there be able to make a reasonable decision. If you don't know, ask someone who does. But remember that you should not reject an idea simply because you prefer it a different way. Of course your opinion matters, but try to balance everyone's needs as much as possible. (This is hard. Please ask for help).

* Code structure problems ("We want the feature, but not implemented like this"). Structural problems can take a significant effort to fix and they make future code maintenance harder. They're the ones that often end up needing to be ripped out or rewritten later. The difficulty is that its often a ridiculous amount of effort to do something the "right" way, especially if it relates to a very old piece of code. The rule of thumb then is to permit mess if its necessary, but do the best you can to keep it contained. Remember that you're now adding to the cleanup work that someone else will have to do in the future.

Code review

2014-01-15T10:17:58Z

RobN:

== Why do code review? ==

Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good quality, is consistent with the rest of the codebase and takes Pioneer in the direction that the community wants it to go.

== When does it happen? ==

Code review can happy at any time, whenever you like. For small items of work it will get at least one review when it is submitted for inclusion (via a pull request). For a large development you may wish to find to someone to review your code periodically, to make sure you're on the right track. If you're starting to feel a bit unsure about what you're doing, that's probably a good time to ask someone!

You don't have to do this of course, but be aware that the reviewers don't particularly being asked to review hundreds or thousands of lines of code changes that appear out of nowhere. You face a good chance of having your code rejected outright or ignored completely, and that sucks. So if you're going to do something massive, at least check in at the start to make sure someone knows about it.

== Who can review code? ==

Anyone that wants to! Anyone can use the review tools on Github to read and comment on code while its under development or test pull requests.

In the case of a pull request, someone with commit access needs to do the final sign-off (typically, but not necessarily, at the same time as merging). If you don't have commit access you can still help make life easier for that person by leaving comments and working with the original submitter.

== I have commit access, does my code need to be reviewed? ==

No, you have commit access for a reason - you've proven that you can be trusted to be a good steward for the project. You should feel free to change whatever you want or need to, but as you do you should be considering all the points normally covered by a review. Self-review, if you like.

That said, no person is an island. Be sure to ask for help if you need it, even if its just a feeling that something isn't right.

== What gets reviewed? ==

Every single change is a candidate for review, no matter how small. Most review will happen in a pull request, but you can be reviewing code by reading the commit history or even by reading code as you're working on it.

Here are some good things to look out for:

* Bugs, logical errors, mathematical errors, typos (any simple, isolated code error). These are easy. If you find a bug during testing or by looking at the code, either fix it or tell the submitter to fix it. It's easy because everyone agrees that bugs need to be fixed.

* Uncertainty about some code logic or behaviour ("Is this maths right?" "Did the submitter intend this weird behaviour?"). These are easy: Ask the submitter (obviously). Explanatory comments are usually the "fix" here.

* Code style errors (braces, whitespace, naming conventions, etc). Same as bugs: fix it, or tell the submitter fix it. Not everyone agrees about the importance of code style, or perhaps even what style we should be using (particularly since the existing codebase is not totally consistent), but we have a code style guide and we want everything to conform to it. If there is some aspect of style not covered by the code style guide on the wiki, amend the guide and tell the submitter to fix their style. Yes, style is subjective, and it's not the submitter's fault that they didn't use the "correct" style, since it may not have been clear what was the "correct" style when they made the PR, but its not worth arguing about - the time and energy to discuss it costs more than just fixing the code.

* Messy git history. Fix it or ignore it. The trouble with telling the submitter to fix it is that many of our contributors don't have enough confidence wth git to do it right and the ones that do tend not to submit messy histories in the first place. So its not worth arguing about. Just do the best you can to keep your own history tidy, but if its not working out don't stress too much about. If you really need help, talk to someone that can drive Git well; they can help you out.

* Game design uncertainty ("Do we want this feature?", "Do we want it to behave this way?"). For the most part you should choose what you think is best. You should be paying attention to what the other developers and the players are asking for and be aware of what other developments are happening, and from there be able to make a reasonable decision. If you don't know, ask someone who does. But remember that you should not reject an idea simply because you prefer it a different way. Of course your opinion matters, but try to balance everyone's needs as much as possible. (This is hard. Please ask for help).

* Code structure problems ("We want the feature, but not implemented like this"). Structural problems can take a significant effort to fix and they make future code maintenance harder. They're the ones that often end up needing to be ripped out or rewritten later. The difficulty is that its often a ridiculous amount of effort to do something the "right" way, especially if it relates to a very old piece of code. The rule of thumb then is to permit mess if its necessary, but do the best you can to keep it contained. Remember that you're now adding to the cleanup work that someone else will have to do in the future.

Code review

2014-01-15T10:17:17Z

RobN: Created page with "== Why do code review? Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good..."

== Why do code review?

Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good quality, is consistent with the rest of the codebase and takes Pioneer in the direction that the community wants it to go.

== When does it happen?

Code review can happy at any time, whenever you like. For small items of work it will get at least one review when it is submitted for inclusion (via a pull request). For a large development you may wish to find to someone to review your code periodically, to make sure you're on the right track. If you're starting to feel a bit unsure about what you're doing, that's probably a good time to ask someone!

You don't have to do this of course, but be aware that the reviewers don't particularly being asked to review hundreds or thousands of lines of code changes that appear out of nowhere. You face a good chance of having your code rejected outright or ignored completely, and that sucks. So if you're going to do something massive, at least check in at the start to make sure someone knows about it.

== Who can review code?

Anyone that wants to! Anyone can use the review tools on Github to read and comment on code while its under development or test pull requests.

In the case of a pull request, someone with commit access needs to do the final sign-off (typically, but not necessarily, at the same time as merging). If you don't have commit access you can still help make life easier for that person by leaving comments and working with the original submitter.

== I have commit access, does my code need to be reviewed?

No, you have commit access for a reason - you've proven that you can be trusted to be a good steward for the project. You should feel free to change whatever you want or need to, but as you do you should be considering all the points normally covered by a review. Self-review, if you like.

That said, no person is an island. Be sure to ask for help if you need it, even if its just a feeling that something isn't right.

== What gets reviewed?

Every single change is a candidate for review, no matter how small. Most review will happen in a pull request, but you can be reviewing code by reading the commit history or even by reading code as you're working on it.

== Here are some good things to look out for:

* Bugs, logical errors, mathematical errors, typos (any simple, isolated code error). These are easy. If you find a bug during testing or by looking at the code, either fix it or tell the submitter to fix it. It's easy because everyone agrees that bugs need to be fixed.

* Uncertainty about some code logic or behaviour ("Is this maths right?" "Did the submitter intend this weird behaviour?"). These are easy: Ask the submitter (obviously). Explanatory comments are usually the "fix" here.

* Code style errors (braces, whitespace, naming conventions, etc). Same as bugs: fix it, or tell the submitter fix it. Not everyone agrees about the importance of code style, or perhaps even what style we should be using (particularly since the existing codebase is not totally consistent), but we have a code style guide and we want everything to conform to it. If there is some aspect of style not covered by the code style guide on the wiki, amend the guide and tell the submitter to fix their style. Yes, style is subjective, and it's not the submitter's fault that they didn't use the "correct" style, since it may not have been clear what was the "correct" style when they made the PR, but its not worth arguing about - the time and energy to discuss it costs more than just fixing the code.

* Messy git history. Fix it or ignore it. The trouble with telling the submitter to fix it is that many of our contributors don't have enough confidence wth git to do it right and the ones that do tend not to submit messy histories in the first place. So its not worth arguing about. Just do the best you can to keep your own history tidy, but if its not working out don't stress too much about. If you really need help, talk to someone that can drive Git well; they can help you out.

* Game design uncertainty ("Do we want this feature?", "Do we want it to behave this way?"). For the most part you should choose what you think is best. You should be paying attention to what the other developers and the players are asking for and be aware of what other developments are happening, and from there be able to make a reasonable decision. If you don't know, ask someone who does. But remember that you should not reject an idea simply because you prefer it a different way. Of course your opinion matters, but try to balance everyone's needs as much as possible. (This is hard. Please ask for help).

* Code structure problems ("We want the feature, but not implemented like this"). Structural problems can take a significant effort to fix and they make future code maintenance harder. They're the ones that often end up needing to be ripped out or rewritten later. The difficulty is that its often a ridiculous amount of effort to do something the "right" way, especially if it relates to a very old piece of code. The rule of thumb then is to permit mess if its necessary, but do the best you can to keep it contained. Remember that you're now adding to the cleanup work that someone else will have to do in the future.

Translations

2014-01-07T06:22:33Z

RobN: /* For mod developers */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository unless you've checked it with a core developer first and it has a good reason.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an table of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex.

If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include <tt>en.json</tt> in your patch.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Translations

2014-01-07T06:22:02Z

RobN: /* For mod developers */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository unless you've checked it with a core developer first and it has a good reason.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an tables of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex.

If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include <tt>en.json</tt> in your patch.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Translations

2014-01-07T06:12:42Z

RobN: /* For translators */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an tables of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex.

If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include <tt>en.json</tt> in your patch.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Media Coverage

2014-01-02T21:10:42Z

RobN:

The following websites or publications have mentioned or featured Pioneer.

* [http://www.cnet.com.au/amazing-dad-builds-his-son-a-spaceship-simulator-339343918.htm CNET Australia] article about a "real" space ship simulator than runs Pioneer.
* [http://www.bbc.co.uk/news/technology-20165344 BBC] article about funding for the new Elite game mentions Pioneer in a list of alternatives.
* [http://www.rockpapershotgun.com/2011/12/06/back-to-frontier-pioneer/ Rock Paper Shotgun] interviews the development team.
* [http://github.com/blog/1228-game-bytes-2/ Github Game Bytes] blog entry featuring Pioneer.
* [http://www.pcgamer.com/2014/01/01/ten-top-fan-remade-classics-you-can-play-for-free-right-now/ PC Gamer] include Pioneer in their list of top game remakes.

Mods

2013-12-30T02:37:01Z

RobN: /* List of known Mods */

== Available Mods ==

=== How to install Mods ===

Since Alpha 22, Pioneer has had support for modding. This is done by allowing core game data to be added to or given preference by data in your userdir (that is, <code>'My Docs/Pioneer/mods'</code> for Windows, <code>'~/.pioneer/mods'</code> for Linux, and <code>'~/Library/Application Support/Pioneer/mods'</code> for OSX).

Once you have downloaded a mod, you simply place the .zip file in the /mods folder described above. There is no need to extract the files.

If a file in a .zip is identically named with one found in the Main pioneer/data directory, the version in the .zip will be used. You can use this fact to easily modify the core game files of Pioneer

This method can be used for any file under the main Pioneer/data directory and applies to ships, buildings and stations, systems, music, fonts, textures, whatever.

However, there are still some mods not packaged in the mod format (.zip). Overtime these are being repackaged by members of the Pioneer community, but in case you have a mod that is not in the correct format then the data in these style of mods must be placed in the correct folder within your main Pioneer/data directory and not in the mods directory described above. But be warned, make a back up of the files you are about to overwrite as this can not be undone and if you do want to return to a 'vanilla' Pioneer, you will have to re-install Pioneer.

== List of known Mods ==

Overtime all the mods here can also be found on the Pioneer Mods page at sourceforge https://sourceforge.net/projects/modsforpioneer/files/Alpha%2030%20mods/

{| class="wikitable"
|+Current known Mod Packages
|-
!Mod Name
!Mod Description
!Author(s)
!Version
!Tested with Pioneer*
!Size
!Download link
|-
|Graveyard
|Example of bundling multiple files in a mod. Adds a custom system "Graveyard" (up and to the right of Sol) and a script that does something when you jump there.
|[[User:RobN|RobN]]
|1.0
|20131229
|1kb
|[http://eatenbyagrue.org/f/pioneer/graveyard.zip graveyard.zip]
|-
|RedSol
|Example of replacing a core file. Replaces the system def for Sol with one that has a red star.
|[[User:RobN|RobN]]
|1.0
|Alpha22
|1kb
|[http://eatenbyagrue.org/f/pioneer/redsol.zip redsol.zip]
|-
|Moon Heightmap
|Higher res heightmap which replaces the 2mb default heightmap.
|Ae-2222
|1.0
|Alpha26-30
|33Mb
|[http://wikisend.com/download/359748/moon-hi-res-heightmap.zip moon-hi-res-heightmap.zip]
|-
|Apollo LEM Lunar orbit save file for Alpha26
|Low fuel LEM landing challenge (-w- cargo to jettison) 3 saves with Lunar lander in unpowered orbit over moon with low fuel(requires HighRes.Moon_Apollo.LEM.a26Mod)
|[[User:baobobafet|baobobafet]]
|1.0
|Alpha26
|520kb
|[http://www.mediafire.com/?sy5d6i4n8vz10c4]
|-
|Interstellar Shuttle 1700
|Adds a modified version of the standard shuttle to the ship roster with hyperdrive capability, ecm, missile, cargo/fuel scoop options and more cargo space.(includes a new shuttle skin and solar array for bottom of existing standard shuttle (readme inside zip file)
|[[User:baobobafet|baobobafet]]
|1.3
|Alpha 30
|3560kb
|[http://www.mediafire.com/?46ci6m4677y5wg3]
|-
|I,S. Shuttle 1700
|see above ^
|[[User:baobobafet|baobobafet]]
|1.1
|Alpha27 & 28
|3560kb
|[http://www.mediafire.com/?xw5ns1xprj8wmju]
|-
|Enterprise 1701a (static ship)
|Replaces the Long Range Cruiser (static Ship) with the NCC 1701a "Enterprise" at realistic scale. (readme inside zip file)
|[[User:baobobafet|baobobafet]]
|1.2
|Alpha 30
|1.78mb
|[http://www.mediafire.com/?g4ng4dk46kdns8v]
|-
|Enterprise 1701a static
|see above ^
|[[User:baobobafet|baobobafet]]
|1.1
|Alpha 27 & 28
|1.78mb
|[http://www.mediafire.com/?008oidsj5cro9v6]
|-
|-
|Enterprise 1701a static
|see above ^
|[[User:baobobafet|baobobafet]]
|1.1
|Alpha 27 & 28
|1.78mb
|[http://www.mediafire.com/?008oidsj5cro9v6]
|-
|Ship Decals Mod 256x256
|This is version 4.0 - includes 8 ship decals. IMAGE here: http://img708.imageshack.us/img708/7146/decalsversion4.png
|[[User:baobobafet|baobobafet]]
|4.0
|Alpha 27-30
|3mb
|[http://www.mediafire.com/?14bchs29dn06nn2]
|-
|-
|-
|Controller Templates
|Not really a Mod - This is for people who have - or are familiar with either Xpadder, 3D Pro Joystick or the G-13 Gameboard. Extreme 3D Pro Joystick Xpadder profile and G-13 gameboard Basic Template - printable key & joystick button reference. Version 3 (More info see above)
|[[User:baobobafet|baobobafet]]
|3.0
|Most Alphas up to 26
|4490kb
|[https://docs.google.com/open?id=0B5dK9aniVGUnM09GRU1qVFJWemM] [http://www.mediafire.com/?ncnh6bpdvna34n2]
|-
|-
|3DPro Joystick Profile
|This is an update supporting the new view keys, for Extreme 3D Pro Joystick Xpadder profile with Template - printable joystick button reference. Version 5 (see pic: http://imageshack.us/a/img822/864/ztf.png )
|[[User:baobobafet|baobobafet]]
|5.0
|Alphas after 28 (all current versions)
|2.31mb
|[http://www.mediafire.com/?btgkn3sjx0ianuu]
|-
|-
|Pioneer default keyboard reference
|In pdf printable format(see PNG pic: http://img203.imageshack.us/img203/2079/5dh.png )
|[[User:baobobafet|baobobafet]]
|v201305.93bao
|Alphas after 28(all current versions)
|7.3mb
|[http://www.mediafire.com/?y5a2sapya7vfhhr]
|}

*'' Version number represents what the module was tested/built against. There is no guarantee that it will work for later versions.''

== List of known Mod Compilations ==

{| class="wikitable"
|+Current known Mod Compilation Packages
|-
!Mod Name
!Mod Description
!Author(s)
!Version
!Tested with Pioneer*
!Size
!Download link
|-
|HiRes Moon & Apollo LEM Mod
|High res Moon heightmap & flyable Apollo Eagle Lander with docs & nav maps.
|contrib by Ae-2222 & [[User:baobobafet|baobobafet]]
|2.0
|Alpha 30
|35.3Mb
|[https://docs.google.com/open?id=0B4TOJEZxkYiVUGZqVklKVEE0WUE]
|
|}

*'' Version number represents what the module compilation was tested/built against. There is no guarantee that it will work for later versions.''

'''''The who/when/where for mod storage/testing/package compilation is still to be established. As with all things concerning Pioneer it is up to interested parties to resolve this. There is the beginnings of a discussion on the [[Talk:Mods|discussion page]] as not everyone is on the mailing list yet (another could be started on a specific task page if anyone wants to). You need to register to edit pages and contribute.'''''

== Creating A New Ship Mod ==
This is in response to the couple of people who are interested in doing art, perhaps even leading the direction it can go in.

For programmers there's a path which involves creating a GitHub account, forking the Pioneer repository, creating branches, configuring remotes, making commits and submitting Pull Requests.

For Artists and scripters there's another way which is hopefully preferrable for everyone!

To follow this "tutorial" you'll need at least a way of creating ".zip" files, on Windows I use the 7-zip program.

This example is being written for Windows but the ideas are broadly transferrable even if the exact file paths and locations aren't.

=== MyFirstShip mod ===
There's links to a few existing mods above but they're very simple things:
* They're just zip files containing some directories and files,
* Their contents are "Added" to Pioneer unless replace something like a script, ship, texture, etc,
* They use the same directory structure as Pioneer.
The example that most players are enthusiastic about is adding a new ship which is the first step on the long road to a total conversion!

To start with we want to make this task easy for ourselves so lets try the following to create a "mod" called "myfirstship":
* Go to wherever you've extracted your Pioneer download to,
* Open the folder "data" and look down the folder names as there's two we're interested in,
** "ships" and "models",
* open the "ships" folder,
** copy and rename the file "wave.lua" to "myfirstship.lua",
** open the file in a text editor and change the following lines like so
*** from: name='Wave Heavy Hypersonic Fighter'
*** from: model='wave',
*** To: name='My First Ship Tutorial'
*** To: model='myfirstship',
*** save your changes to the "myfirstship.lua" file,
*** now go back up to the data folder,
* open the "models" folder, then the "ships" folder,
** copy and rename the folder "wave" to "myfirstship",
** open the "myfirstship" folder,
*** rename the file "wave.model" to "myfirstships.model",
Now run Pioneer with the parameter "-mv myfirstship" so the command line should look like "pioneer.exe -mv myfirstship" this will open it in the modelviewer mode so you can see if everything has worked.

If you run Pioneer as usual then you should be able to go to the ship yard and buy your very own "My First Ship Tutorial" spaceship. Of course it will look like the Wave heavy Hypersonic Fighter, and it will handle like it and be like it in every possible way because it's a perfect copy of it

If you want to make it look different so it's easier to spot then a quick thing you can do is edit the texture "wave.png" in your "/data/models/ships/myfirstship/" folder, perhaps just paint the white a bright red or something which will make it easy to tell that you've changed it.

Obviously we're not done turning all this effort into a mod yet, we've just copied a ship definition ("myfirstship.lua") and the model data for it.

So lets open a new folder window (if on Windows) and:
* Create a new folder somewhere you won't lose it, "My Documents" for windows users or the home folder on Linux etc, call it "tutorial" this time (to avoid confusion),
* In this folder create two more called "ships" and "models",
* With the "models" folder create another folder called "ships",
* by now you should have something that looks like:
** /tutorial/ships/
** /tutorial/models/ships/
* now you're going to _move_ the "myfirstships.lua" file you edited earlier out of the "/pioneer/data/ships/" into the folder "/tutorial/ships/" folder,
* next you must _move_ the folder "myfirstship" from "/pioneer/data/models/ships/" to "/tutorial/models/ships/",
* now create a "readme.txt" file in the "tutorial" folder and add your name to it for now,
* Add everything inside the "tutorial" folder to a zip archive - to do this with 7-zip just selected everything inside the tutorial folder, right-click, open the 7-zip submenu and choose the "Add to archive",
* Make sure that you choose to use "zip" compression and call the archive "myfirstship.zip".
* Finally, put the file "myfirstship.zip" into the "mods" directory - this IS NOT usually where you extracted the Pioneer download.
** On Windows it will be in a folder under your "My Documents"/"Documents" directory for example:
*** "/My Documents/Pioneer/mods/"
* Now double check that you really did MOVE the files and folders, i.e; go back to where you first copied the wave files and folders and make sure that there aren't any "myfirsthip" files or folder there because they should now all be inside the zip file (and safely backed up in the "tutorial" folder).
** The reason this step is important is that you might have made a mistake with the zipping process and the mod is actually now broken, however it will look like it works because the original files are still being found by Pioneer in it's own data directory.
* Finally, the mod should have been packaged up into a zip, it should be in the "mods" directory, and you've made sure the Pioneer data folder is clean.
* Run Pioneer and make sure your mod works.

There are many steps that take just a second or two and lots of bits you can skip once you know what you're doing.

You can have as many ships within a single mod as you like, this technique just gives you a copy of the Wave to edit and play with.

You can, and should, replace it with your own mesh and edit the parameters it uses for thrust and equipment etc.

=== So how does this get my ships into the Pioneer download? ===
Easy, you create your mod, test it, try it out, share it via this forums download area so that others can play it, respond to criticisms to improve it and then ask the Core Team to include it in the main distribution.

This is basically the same process that we go through for programmers submissions but without having to understand Git and GitHub.

It's also more direct to players and fans of the game who often use several mods together to make Pioneer play how they want it too.

Code style

2013-12-10T09:17:56Z

RobN: /* Name style */

This page describes some of the code style used in Pioneer. Its probably incomplete, but it should be correct. If you see something in the code that doesn't match what's described here, this guide takes precedence (and please submit a patch to fix it!)

== Licensing ==

Engine and Lua code is [http://www.gnu.org/licenses/gpl.html GPL 3]. Assets (include Lua-based data files like ship defs) are [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3]

Include these two lines at the top of each file (suitably commented):

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

* Hard tabs, 4-space aligned.
* Inner spaces after tabs to align arguments on multiple lines, etc

== Constants ==

* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible

== Name style ==

* Classes: FooBar
* Methods: FooBar
* Class members: m_fooBar
* Static members: s_fooBar
* Constants (defines and <tt>static const</tt>): FOO_BAR

Names should generally be chosen for what the thing represents. It shouldn't have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). Just name it so its crystal clear what it is.

(Exception: member variables have a <tt>m_</tt> or <tt>s_</tt> to disambiguate them from local names and to match C++ conventions).

There's also a few abbreviated names that are commonly used throughout the codebase, eg <tt>Renderer *r</tt>, <tt>lua_State *l</tt>, etc. Try to prefer them where appropriate.

== Include guards ==

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

* Ship.h
#ifndef SHIP_H

* WorldView.h
#ifndef WORLDVIEW_H

* graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

Avoid assigning explicit integer values. Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable). If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

Code style

2013-12-10T09:16:01Z

RobN: /* Name style */

This page describes some of the code style used in Pioneer. Its probably incomplete, but it should be correct. If you see something in the code that doesn't match what's described here, this guide takes precedence (and please submit a patch to fix it!)

== Licensing ==

Engine and Lua code is [http://www.gnu.org/licenses/gpl.html GPL 3]. Assets (include Lua-based data files like ship defs) are [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3]

Include these two lines at the top of each file (suitably commented):

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

* Hard tabs, 4-space aligned.
* Inner spaces after tabs to align arguments on multiple lines, etc

== Constants ==

* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible

== Name style ==

* Classes: FooBar
* Methods: FooBar
* Class members: m_fooBar
* Static members: s_fooBar
* Constants: FOO_BAR

Names should generally be chosen for what the thing represents. It shouldn't have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). Just name it so its crystal clear what it is.

There's also a few abbreviated names that are commonly used throughout the codebase, eg <tt>Renderer *r</tt>, <tt>lua_State *l</tt>, etc. Try to prefer them where appropriate.

== Include guards ==

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

* Ship.h
#ifndef SHIP_H

* WorldView.h
#ifndef WORLDVIEW_H

* graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

Avoid assigning explicit integer values. Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable). If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

Translations

2013-11-03T01:39:32Z

RobN: /* For translators */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo once per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an tables of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex.

If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include <tt>en.json</tt> in your patch.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Translations

2013-11-03T00:57:56Z

RobN:

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo once per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - an tables of tokens as keys, with values of a table with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex.

If you're submitting code that requires a new language resource, please make a note of it in your pull request, and only include <tt>en.json</tt> in your patch.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Model system

2013-09-24T13:15:52Z

RobN: /* Tag points */

== 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 - 128. Default 100.
|-
| 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||This material will use the pattern/colour system. Read more below.
|-
| unlit||No lighting, diffuse value can still be used to tint the result
|-
| two_sided||Self-explanatory, however normals on the other side are not automatically inversed (no good way to do this) so the usefulness is limited
|-
| alpha_test||Pixels with alpha value < 0.5 are discarded, this is good for fences and such. It produces sharp edges but the geometry does not need to be sorted.
|}

[[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 value ranges are:
* 0-63: not affecting (black)
* 64-127: first color (dark gray)
* 128-191: second color (mid gray)
* 192-255: third color (light gray/white)
You can set all three channels to these in RGB, or only the L channel in HSL (Hue, Saturation, Level) to get the needed gray.

Antialiasing (which generates small gradients) can cause artifacts, especially at black-white boundaries. To avoid it, try lowering the contrast on problematic places. Even different grays can be used from the same range, they will indicate the same color.

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 radius 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]]

Tag points have not been fully implemented. If you want to use this feature, please content the devs.

=== Tag points ===

As at 23 September 2013.

{| class="wikitable"
|-
| tag_camera_front tag_camera_rear tag_camera_left tag_camera_right tag_camera_top tag_camera_bottom
|| Position and orientation for the six internal view cameras. X right, Y down, Z "out" of the ship (in the direction the camera is facing). If one is missing, tag_camera will be used with its orientation adjusted for the appropriate direction.
|-
| tag_camera || Fallback for the specific camera tags. Useful if you don't want to specify all points. Defaults to the ship origin.
|-
| tag_gunmount_N || Gun positions, X right, Y down, Z "out" of the ship (in the fire direction). Note at this time, only N = 0 or 1 will work, and they correspond to "front" and "rear" guns in the UI. The "max_lasers" ship definition field still takes precedence (ie if max_lasers = 1, tag_gunmount_1 will never be used). Defaults to the ship origin.
|-
|}

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes.

For more control, name objects with the prefix "collision_" and they will be added to form a collision mesh (these objects will not be visible geometry, and the bounding box will not be generated).

Note, these names are reserved for station collision trigger surfaces:

* collision_pad1
* collision_pad2
* collision_pad3
* collision_pad4

You can also import a separate mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

The collision meshis separate from all detail levels, so it should be only defined once.

[[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 ==

Note, these special nodes are only imported from the most detailed LOD, there is no need to duplicate them. They are rendered outside the detail level system.

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). This feature will be more customizable someday, but for now the following name prefixes are recognized:

* navlight_red: blinking red light, with ships when landing gear is down, with stations constantly
* navlight_green: blinking green light when landing gear is down
any other navlight_ is blue, on when landing gear is down.
* space stations, navlight_pad<number> lights change according to landing pad reservation status

=== 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]]

Model system

2013-09-24T13:10:50Z

RobN: /* Tag points */

== 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 - 128. Default 100.
|-
| 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||This material will use the pattern/colour system. Read more below.
|-
| unlit||No lighting, diffuse value can still be used to tint the result
|-
| two_sided||Self-explanatory, however normals on the other side are not automatically inversed (no good way to do this) so the usefulness is limited
|-
| alpha_test||Pixels with alpha value < 0.5 are discarded, this is good for fences and such. It produces sharp edges but the geometry does not need to be sorted.
|}

[[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 value ranges are:
* 0-63: not affecting (black)
* 64-127: first color (dark gray)
* 128-191: second color (mid gray)
* 192-255: third color (light gray/white)
You can set all three channels to these in RGB, or only the L channel in HSL (Hue, Saturation, Level) to get the needed gray.

Antialiasing (which generates small gradients) can cause artifacts, especially at black-white boundaries. To avoid it, try lowering the contrast on problematic places. Even different grays can be used from the same range, they will indicate the same color.

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 radius 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]]

Tag points have not been fully implemented. If you want to use this feature, please content the devs.

=== Tag points ===

As at 23 September 2013.

{| class="wikitable"
|-
| tag_camera_front tag_camera_rear tag_camera_left tag_camera_right tag_camera_top tag_camera_bottom
|| Position and orientation for the six internal view cameras. X right, Y down, Z "out" of the ship (in the direction the camera is facing). If one is missing, tag_camera will be used with its orientation adjusted for the appropriate direction.
|-
| tag_camera || Fallback for the specific camera tags. Useful if you don't want to specify all points. Defaults to the ship origin.
|-
| tag_gunpoint_N || Gun positions, X right, Y down, Z "out" of the ship (in the fire direction). Note at this time, only N = 0 or 1 will work, and they correspond to "front" and "rear" guns in the UI. The "max_lasers" ship definition field still takes precedence (ie if max_lasers = 1, tag_gunpoint_1 will never be used). Defaults to the ship origin.
|-
|}

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes.

For more control, name objects with the prefix "collision_" and they will be added to form a collision mesh (these objects will not be visible geometry, and the bounding box will not be generated).

Note, these names are reserved for station collision trigger surfaces:

* collision_pad1
* collision_pad2
* collision_pad3
* collision_pad4

You can also import a separate mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

The collision meshis separate from all detail levels, so it should be only defined once.

[[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 ==

Note, these special nodes are only imported from the most detailed LOD, there is no need to duplicate them. They are rendered outside the detail level system.

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). This feature will be more customizable someday, but for now the following name prefixes are recognized:

* navlight_red: blinking red light, with ships when landing gear is down, with stations constantly
* navlight_green: blinking green light when landing gear is down
any other navlight_ is blue, on when landing gear is down.
* space stations, navlight_pad<number> lights change according to landing pad reservation status

=== 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]]

Model system

2013-09-23T00:10:58Z

RobN:

== 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 - 128. Default 100.
|-
| 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||This material will use the pattern/colour system. Read more below.
|-
| unlit||No lighting, diffuse value can still be used to tint the result
|-
| two_sided||Self-explanatory, however normals on the other side are not automatically inversed (no good way to do this) so the usefulness is limited
|-
| alpha_test||Pixels with alpha value < 0.5 are discarded, this is good for fences and such. It produces sharp edges but the geometry does not need to be sorted.
|}

[[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 value ranges are:
* 0-63: not affecting (black)
* 64-127: first color (dark gray)
* 128-191: second color (mid gray)
* 192-255: third color (light gray/white)
You can set all three channels to these in RGB, or only the L channel in HSL (Hue, Saturation, Level) to get the needed gray.

Antialiasing (which generates small gradients) can cause artifacts, especially at black-white boundaries. To avoid it, try lowering the contrast on problematic places. Even different grays can be used from the same range, they will indicate the same color.

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 radius 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]]

Tag points have not been fully implemented. If you want to use this feature, please content the devs.

=== Tag points ===

As at 23 September 2013.

{| class="wikitable"
|-
| tag_camera_front tag_camera_rear tag_camera_left tag_camera_right tag_camera_top tag_camera_bottom
|| Position and orientation for the six internal view cameras. X left, Y up, Z "out" of the ship (in the direction the camera is facing). If one is missing, tag_camera will be used with its orientation adjusted for the appropriate direction.
|-
| tag_camera || Fallback for the specific camera tags. Useful if you don't want to specify all points. Defaults to the ship origin.
|-
| tag_gunpoint_N || Gun positions, X left, Y up, Z "out" of the ship (in the fire direction). Note at this time, only N = 0 or 1 will work, and they correspond to "front" and "rear" guns in the UI. The "max_lasers" ship definition field still takes precedence (ie if max_lasers = 1, tag_gunpoint_1 will never be used). Defaults to the ship origin.
|-
|}

== Collisions ==

By default, the collision mesh of a model is the bounding box of all the meshes.

For more control, name objects with the prefix "collision_" and they will be added to form a collision mesh (these objects will not be visible geometry, and the bounding box will not be generated).

Note, these names are reserved for station collision trigger surfaces:

* collision_pad1
* collision_pad2
* collision_pad3
* collision_pad4

You can also import a separate mesh using the <code>collision</code> directive in the model definition:

collision collision.obj

The collision meshis separate from all detail levels, so it should be only defined once.

[[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 ==

Note, these special nodes are only imported from the most detailed LOD, there is no need to duplicate them. They are rendered outside the detail level system.

=== Billboard lights ===

Simple light sprites placed using empty nodes with special naming (navlight_*). This feature will be more customizable someday, but for now the following name prefixes are recognized:

* navlight_red: blinking red light, with ships when landing gear is down, with stations constantly
* navlight_green: blinking green light when landing gear is down
any other navlight_ is blue, on when landing gear is down.
* space stations, navlight_pad<number> lights change according to landing pad reservation status

=== 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]]

Natrix

2013-08-17T10:47:34Z

RobN: /* Description */

{{Infobox_Ship
|name= Natrix
|type= Starter
|image = [[File:Natrixshape.png|center|300px]][[File:Natrix.png|center|300px]]
|manufacturer = OPLI-Barnard Inc.
|forward_thrust = 124e5
|reverse_thrust = 21e5
|up_thrust = 21e5
|down_thrust = 21e5
|left_thrust = 21e5
|right_thrust = 21e5
|angular_thrust = 195e5
|gun_mounts = 1
|max_atmoshield = 0
|max_cargo = 40
|max_laser = 1
|max_missile = 0
|max_cargoscoop = 0
|max_fuelscoop = 0
|max_engine = yes
|min_crew = 1
|max_crew = 1
|capacity = 40
|hull_mass = 15
|fuel_tank_mass = 36
|effective_exhaust_velocity = 62143e3
|price = 50000
|hyperdrive_class = 2
}}

==Description==

The Natrix is a small multi-role craft. As a cheap vessel with limited cargo space, it is most often used by first-time pilots hoping to eke out a living as interstellar traders. The more ambitious often hope to begin with this small craft, and earn their fortune over time. A few may even hope to abandon the trading life, in search of some grand interstellar adventure.

[[Category:Ships]]

Pioneer Wiki

2013-07-04T08:47:20Z

RobN:

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.

If you are new to pioneer you may want to know [[How to start| how to start]].

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

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

----
{|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]
* [http://webchat.freenode.net/?channels=#pioneer Pioneer Space Sim on IRC]
* [http://pioneerspacesim.net/+ Pioneer Space Sim] on Google+
* [http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter
----
* [[Tutorials]](Outdated and WIP)
* [[Keyboard and mouse controls]]
* [[FAQ]]
* [[Media Coverage]]

|width="33%" style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top"|
===The Pioneer universe===
* [[Story]]
* [http://pioneerwiki.com/wiki/Category:Ships Ships] (work in progress)
* [[Places of interest]]
|}

{|width=100%
|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]]
** [[Lua-based equipment]] (NOT YET MERGED!)
** [[Surviving a reload]]
* [http://eatenbyagrue.org/f/pioneer/codedoc/ Lua API Reference]
* Ships and stations
** [[Making your first ship]]
** [[Creating Ships and Stations]]
* Models
** [[Model system]]
** [[Model viewer]]
** [[Transitioning to the new model system]]
** Making models
*** [[Textures]]
*** [[Transparency]]
*** [[Optimising geometry]]
*** [[Modelling stations]]
** [[3DS Max]]
** [[:Category:Blender|Blender]]
*** [[Blender Tips]]
*** [[UV coordinates in Blender]]
*** [[Asteroids and rocks in Blender]]
*** [[Scripting Blender]]
** [[:Category:GIMP|GIMP]]
*** [[GIMP Tips]]
*** [[Cutaway panels in GIMP]]
* [[Music]]
* [[Sound Effects]]
* [[Translations]]
* [[Licensing]]

|width="33%" style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top"|

===Development===
* [[Design Scope|Game Scope]]
* [[Getting Started with Development]]
** [[How to communicate]]
** [[Using git and GitHub]] (work in progress)
** [[Core Team]]
* [[Development Model]]
* [[Design_Workflow|Design and Project Management Workflow]]
* [https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
|}

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]

__NOTOC__

Code style

2013-07-02T23:00:28Z

RobN: /* Enum types */

This page describes some of the code style used in Pioneer. Its probably incomplete, but it should be correct. If you see something in the code that doesn't match what's described here, this guide takes precedence (and please submit a patch to fix it!)

== Licensing ==

Engine and Lua code is [http://www.gnu.org/licenses/gpl.html GPL 3]. Assets (include Lua-based data files like ship defs) are [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3]

Include these two lines at the top of each file (suitably commented):

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

* Hard tabs, 4-space aligned.
* Inner spaces after tabs to align arguments on multiple lines, etc

== Constants ==

* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible

== Name style ==

* Classes: FooBar
* Methods: FooBar
* Class members: m_fooBar
* Static members: s_fooBar
* Constants: FOO_BAR

== Include guards ==

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

* Ship.h
#ifndef SHIP_H

* WorldView.h
#ifndef WORLDVIEW_H

* graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

Avoid assigning explicit integer values. Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable). If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

Code style

2013-07-02T22:59:59Z

RobN:

This page describes some of the code style used in Pioneer. Its probably incomplete, but it should be correct. If you see something in the code that doesn't match what's described here, this guide takes precedence (and please submit a patch to fix it!)

== Licensing ==

Engine and Lua code is [http://www.gnu.org/licenses/gpl.html GPL 3]. Assets (include Lua-based data files like ship defs) are [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3]

Include these two lines at the top of each file (suitably commented):

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2013 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

* Hard tabs, 4-space aligned.
* Inner spaces after tabs to align arguments on multiple lines, etc

== Constants ==

* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible

== Name style ==

* Classes: FooBar
* Methods: FooBar
* Class members: m_fooBar
* Static members: s_fooBar
* Constants: FOO_BAR

== Include guards ==

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

* Ship.h
#ifndef SHIP_H

* WorldView.h
#ifndef WORLDVIEW_H

* graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

Avoid assigning explicit integer values. Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable). If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

Code style

2013-07-02T02:46:30Z

RobN:

Roadmap

2013-06-28T11:55:46Z

RobN:

== First milestone ==

Basically we want external interfaces to be stable.

* New save file format
* Separate Player from Ship (breaks Lua)
* Turn Missiles into guided Projectiles
* Lua equipment
* Module manifest
* Convert to new UI (but not redesigned HUD)
* JSON data files (ship defs)
* Starsystem generation rewrite (plus custom systems)

== Second milestone ==

Gameplay stuff, redesigned UI. Dunno yet.

== Older stuff ==

Pioneer version 1.0 will be the first "stable" release. This will not be the final state of the game: development will continue, particularly adding a lot more content and game-play features, but features present in version 1.0 are expected to be supported for a long time.

Things that must be done before we can release version 1.0:

'''''Warning:''' This list is incomplete - and under active discussion so subject to change''
=== Technical features ===
* The save system will be changed to allow future versions to be made without breaking all prior saved games.
* Equipment control will be moved to Lua.
* All user-interface will be converted to use the new-ui system and be driven by Lua.
* Star system generation will be rewritten to allow partially custom systems, and to allow some types of changes to be made without having knock-on effects through the entire galaxy or system.

=== Gameplay features ===
* Military progression / treason.
* Something like the Scout missions the walterar has done, exploration jobs.
* No hypersace from in atmosphere / or too close to a planet surface.
* In-system hyperspace jumps to make assassination missions and piracy actually possible.
* Alternatively a Fast-As-Light drive, Shadmar has taken a hacked one I (fluffyfreak) wrote and updated it for Paragon.

=== More proposed stuff ===

From [[User:Luomu|Luomu]] ([[User talk:Luomu|talk]]) 17:09, 1 May 2013 (PDT)

* New, fault tolerant save system: this is the most important thing ever
* Rewrite the HUD
** Gather a list of components before doing any visual design
* Controls
** New input system: do we need one, or can the current one be fixed?
** Current problems: conflicting binds, cannot bind multiple inputs per action
** Remove rarely used buttons?
* Camera
** Add chase camera, padlock
* Weapons
** goals: allow more than just laser bolts (beams, missiles), auto-tracking guns and turrets
** rewrite, basically
** turn missiles into guided projectiles instead of ships
** conflicts with lua trade goods/equipment?
* Star views and navigation
** combine system (orbit) view into star map
** maybe other streamlining as well?
** bookmarks, travel log
* Separate Player from Ships
** to enable shuttlecraft and remote drones
** must be done during alpha, not sensible afterwards (breaks modules)
* Hitpoints: use generic HP value instead of mass
* Cargo: use kg instead of tons
* AI
** needs more higher level stuff like basic self preservation, modules must not have to implement their own (like tradeships...)
** formations, anyone?
* Ship visual customization
* Space stations
** external docking
** traffic rules (don't allow modules to let ships idle forever)
* JSON for data files (ship defs etc)

Code style

2013-06-27T21:16:45Z

RobN:

== Tabs & spacing ==

* Hard tabs, 4-space aligned.
* Inner spaces after tabs to align arguments on multiple lines, etc

== Constants ==

* Prefer <tt>static const</tt> over <tt>#define</tt> wherever possible

== Name style ==

* Classes: FooBar
* Methods: FooBar
* Class members: m_fooBar
* Static members: s_fooBar
* Constants: FOO_BAR

Code style

2013-06-26T22:41:01Z

RobN: Created page with "== Tabs & spacing == * Hard tabs, 4-space aligned. * Inner spaces after tabs to align arguments on multiple lines, etc == Constants == * Prefer <tt>static const</tt> over <..."

Media Coverage

2013-04-16T00:03:39Z

RobN:

Asset List

2013-02-12T11:06:34Z

RobN:

A list of models that we have/want/need in the core game.

== Ships ==

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Shuttle || Small shuttlecraft for in-system trips, package deliveries, etc. Not hyperspace-capable. || ip_shuttle || Needs to be replaced or converted from LMR
|-
| Starter || Small multirole craft, capable of hyperspace and atmospheric flight. || natrix || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/2033 #2033]
|-
| Medium || Medium/large multirole craft, for cargo runs, exploration, etc. || lanner, wave || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1957 #1957] [https://github.com/pioneerspacesim/pioneer/pull/2022 #2022]
|-
| Freighter || Large hyperspace-capable cargo ship || dsminer || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/2023 #2023]
|-
| Fighter || Small, fast short-range fighter, not hyperspace-capable. For use by police/pirates. || kanara || '''In progress''' [https://github.com/pioneerspacesim/pioneer/pull/2037 #2037]
|-
| Bulk || Enormous supply ship, for positioning near stations (and later convoys etc). Non-playable || lrc, lynx || Needs to be replaced or converted from LMR
|}

== Stations ==

Surface and spacestations.

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Orbital || Ring-type space station with internal docking space for four ships. || big_crappy_spacestation || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1964 #1964], updates in progress [https://github.com/pioneerspacesim/pioneer/pull/2046 #2046]
|-
| Surface || Open-air surface station with four 100x100m landing pads || ground_station_4 || Placeholder. Needs conversion from LMR or recreation. See [https://github.com/pioneerspacesim/pioneer/pull/1932 #1932]
|}

== Buildings ==

== Others ==

{| class="wikitable"
|-
!Type
!Purpose
|-
| Cargo container || A generic container, should be well visible
|-
| Gun || Ship weapon model, used for all types for now
|-
| Missile launcher || Weapon model attached to ships that carry missiles
|-
| Missile || Fired missile model, used for all types
|}

[[Category:Art]]

Asset List

2013-02-04T03:40:22Z

RobN: /* Ships */

A list of models that we have/want/need in the core game.

== Ships ==

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Shuttle || Small shuttlecraft for in-system trips, package deliveries, etc. Not hyperspace-capable. || ip_shuttle || Needs to be replaced or converted from LMR
|-
| Starter || Small multirole craft, capable of hyperspace and atmospheric flight. || natrix || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/2033 #2033]
|-
| Medium || Medium/large multirole craft, for cargo runs, exploration, etc. || lanner, wave || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1957 #1957] [https://github.com/pioneerspacesim/pioneer/pull/2022 #2022]
|-
| Freighter || Large hyperspace-capable cargo ship || dsminer || '''Done''' Needs to be replaced or converted from LMR
|-
| Fighter || Small, fast short-range fighter, not hyperspace-capable. For use by police/pirates. || talon? || Needs to be replaced or converted from LMR
|-
| Bulk || Enormous supply ship, for positioning near stations (and later convoys etc). Non-playable || lrc, lynx || Needs to be replaced or converted from LMR
|}

== Stations ==

Surface and spacestations.

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Orbital || Ring-type space station with internal docking space for four ships. || big_crappy_spacestation || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1964 #1964]
|-
| Surface || Open-air surface station with four 100x100m landing pads || ground_station_4 || Placeholder. Needs conversion from LMR or recreation. See [https://github.com/pioneerspacesim/pioneer/pull/1932 #1932]
|}

== Buildings ==

== Others ==

{| class="wikitable"
|-
!Type
!Purpose
|-
| Cargo container || A generic container, should be well visible
|-
| Gun || Ship weapon model, used for all types for now
|-
| Missile launcher || Weapon model attached to ships that carry missiles
|-
| Missile || Fired missile model, used for all types
|}

[[Category:Art]]

Asset List

2013-02-04T03:39:50Z

RobN: /* Ships */

A list of models that we have/want/need in the core game.

== Ships ==

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Shuttle || Small shuttlecraft for in-system trips, package deliveries, etc. Not hyperspace-capable. || ip_shuttle || Needs to be replaced or converted from LMR
|-
| Starter || Small multirole craft, capable of hyperspace and atmospheric flight. || natrix || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/2033 #2033]
|-
| Medium || Medium/large multirole craft, for cargo runs, exploration, etc. || lanner, wave || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1957 #1957]
[https://github.com/pioneerspacesim/pioneer/pull/2022 #2022]|-
| Freighter || Large hyperspace-capable cargo ship || dsminer || '''Done''' Needs to be replaced or converted from LMR
|-
| Fighter || Small, fast short-range fighter, not hyperspace-capable. For use by police/pirates. || talon? || Needs to be replaced or converted from LMR
|-
| Bulk || Enormous supply ship, for positioning near stations (and later convoys etc). Non-playable || lrc, lynx || Needs to be replaced or converted from LMR
|}

== Stations ==

Surface and spacestations.

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Orbital || Ring-type space station with internal docking space for four ships. || big_crappy_spacestation || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1964 #1964]
|-
| Surface || Open-air surface station with four 100x100m landing pads || ground_station_4 || Placeholder. Needs conversion from LMR or recreation. See [https://github.com/pioneerspacesim/pioneer/pull/1932 #1932]
|}

== Buildings ==

== Others ==

{| class="wikitable"
|-
!Type
!Purpose
|-
| Cargo container || A generic container, should be well visible
|-
| Gun || Ship weapon model, used for all types for now
|-
| Missile launcher || Weapon model attached to ships that carry missiles
|-
| Missile || Fired missile model, used for all types
|}

[[Category:Art]]

Asset List

2013-02-04T03:37:26Z

RobN: /* Stations */

A list of models that we have/want/need in the core game.

== Ships ==

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Shuttle || Small shuttlecraft for in-system trips, package deliveries, etc. Not hyperspace-capable. || ip_shuttle || Needs to be replaced or converted from LMR
|-
| Starter || Small multirole craft, capable of hyperspace and atmospheric flight. || eagle_lrf || Needs to be replaced or converted from LMR
|-
| Medium || Medium/large multirole craft, for cargo runs, exploration, etc. || lanner || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1957 #1957]
|-
| Freighter || Large hyperspace-capable cargo ship || caribou? hammerhead? || Needs to be replaced or converted from LMR
|-
| Fighter || Small, fast short-range fighter, not hyperspace-capable. For use by police/pirates. || talon? || Needs to be replaced or converted from LMR
|-
| Bulk || Enormous supply ship, for positioning near stations (and later convoys etc). Non-playable || lrc, lynx || Needs to be replaced or converted from LMR
|}

== Stations ==

Surface and spacestations.

{| class="wikitable"
|-
!Type
!Purpose
!Model
!Status
|-
| Orbital || Ring-type space station with internal docking space for four ships. || big_crappy_spacestation || '''Done''' [https://github.com/pioneerspacesim/pioneer/pull/1964 #1964]
|-
| Surface || Open-air surface station with four 100x100m landing pads || ground_station_4 || Placeholder. Needs conversion from LMR or recreation. See [https://github.com/pioneerspacesim/pioneer/pull/1932 #1932]
|}

== Buildings ==

== Others ==

{| class="wikitable"
|-
!Type
!Purpose
|-
| Cargo container || A generic container, should be well visible
|-
| Gun || Ship weapon model, used for all types for now
|-
| Missile launcher || Weapon model attached to ships that carry missiles
|-
| Missile || Fired missile model, used for all types
|}

[[Category:Art]]