PioneerWiki - User contributions [en]

Building with Code::Blocks

2014-02-23T18:38:29Z

Luomu:

These are instructions for building Pioneer for '''Windows''' using the '''Code::Blocks''' IDE, with GCC as the compiler.

== Compiler and IDE ==

First, acquire C::B: http://www.codeblocks.org/. Version 13.12 is verified to work.

Then, you will need a compiler toolchain. Install the '''32-bit''' TDM-GCC bundle from: http://tdm-gcc.tdragon.net/. You may add the bin/ directory to your PATH but that is not necessary.

You may use other distributions (http://sourceforge.net/projects/mingwbuilds/, http://mingw-w64.sourceforge.net/) but then you most likely cannot use the prebuilt dependencies package.

In C::B, open Settings->Compiler..., selected compiler should be GNU GCC compiler. On tab "Toolchain executables" the paths should be:

* Compiler's install directory: C:\TDM-GCC-32 (or wherever you put it)
* C compiler: mingw32-gcc.exe
* C++ compiler: mingw32-g++.exe
* Linker for dynamic libs: mingw32-g++.exe
* Linker for static libs: ar.exe
* Resource compiler: windres.exe
* Make program: mingw32-make.exe

Also, in Settings->Debugger you can set the path to C:\TDM-GCC-32\bin\gdb.exe for debugging to work.

== Premake4 ==

[http://industriousone.com/premake Premake4] is used to generate the C::B project file. The latest release 4.3 might work, but here is a more recent executable built from the premake-stable branch:

https://dl.dropboxusercontent.com/u/95790686/premake4.zip

TODO: put this in pioneer-thirdparty repository

== Third-party dependencies package ==

If you use TDM-GCC32 to compile, you can use this package with prebuilt dependencies (SDL, Assimp, libPNG etc.). Otherwise you have to gather your own dependencies.

https://dl.dropboxusercontent.com/u/95790686/pioneer-cb-deps.7z

Extract it to your preferred location, and copy the .dll files to the Pioneer directory.

TODO: put this in pioneer-thirdparty repository

== Building the game ==

Open command prompt and go to pioneer/win32/codeblocks. Generate the project file:

<pre>
premake4.exe --thirdparty=D:/Dev/mingw32 codeblocks
</pre>

Substitute the correct location for the third-party deps root folder, using forward slashes. Using --thirdparty is optional if you set the correct include and lib paths in C::B settings.

Pioneer.cbp is generated in the build/ subdirectory, open it in C::B and build the pioneer subproject. The executables are placed in the pioneer root directory. Copy the .dlls from the third-party dependencies before running for the first time.

You need to regenerate the project every time a source file is added or removed. The generated project will not be committed to the repository.

== Extra options for the premake script ==

<pre>
--thirdparty=[location], Folder where the third-party deps are extracted
--noconsole, Don't open a console window when running the game.
--release-symbols, Include debug symbols in release build. Makes debugging possible, results in a larger executable.
</pre>

== Known issues ==

* Plenty of warnings from contrib header files.
* Starting the build for the entire workspace does not give the correct build order. Launch the build for the pioneer subproject instead.

Building with Code::Blocks

2014-02-23T16:52:20Z

Luomu: Created page with "These are instructions for building Pioneer for '''Windows''' using the '''Code::Blocks''' IDE, with GCC as the compiler. First, acquire C::B: http://www.codeblocks.org/. Ver..."

These are instructions for building Pioneer for '''Windows''' using the '''Code::Blocks''' IDE, with GCC as the compiler.

First, acquire C::B: http://www.codeblocks.org/. Version 13.12 is verified to work.

Then, you will need a compiler toolchain. Install the '''32-bit''' TDM-GCC bundle from: http://tdm-gcc.tdragon.net/. You may add the bin/ directory to your PATH but that is not necessary.

You may use other distributions (http://sourceforge.net/projects/mingwbuilds/, http://mingw-w64.sourceforge.net/) but then you most likely cannot use the prebuilt dependencies package.

In C::B, open Settings->Compiler..., selected compiler should be GNU GCC compiler. On tab "Toolchain executables" the paths should be:

* Compiler's install directory: C:\TDM-GCC-32 (or wherever you put it)
* C compiler: mingw32-gcc.exe
* C++ compiler: mingw32-g++.exe
* Linker for dynamic libs: mingw32-g++.exe
* Linker for static libs: ar.exe
* Resource compiler: windres.exe
* Make program: mingw32-make.exe

Also, in Settings->Debugger you can set the path to C:\TDM-GCC-32\bin\gdb.exe for debugging to work.

[http://industriousone.com/premake Premake4] is used to generate the C::B project file. Link here.

Third-party dependencies package.

Open command prompt and go to pioneer/win32/codeblocks. Generate the project file:

<pre>
premake4.exe --thirdparty=D:/Dev/mingw32 codeblocks
</pre>

Substitute the correct location for the third-party deps root folder, using forward slashes. Using --thirdparty is optional if you set the correct include and lib paths in C::B settings.

Pioneer.cbp is generated in the build/ subdirectory, open it in C::B and build the pioneer subproject. The executables are placed in the pioneer root directory. Copy the .dlls from the third-party dependencies before running for the first time.

== Extra options for the premake script ==

== Known issues ==

* Plenty of warnings from contrib header files.
* Starting the build for the entire workspace does not give the correct build order. Launch the build for the pioneer subproject instead.

Pioneer Wiki

2013-10-17T13:10:20Z

Luomu: /* Content Creation */

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

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)
* [http://pioneerwiki.com/wiki/Category:Manufacturers Manufacturers] (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]]
** [[Model QA Checklist]]
** 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__

Model QA Checklist

2013-10-17T13:09:26Z

Luomu: Created page with "== Are the source files available? == They should be put to the asset repository. == Does the model have detail levels? == LODs should be included in every model. The numbe..."

== Are the source files available? ==

They should be put to the asset repository.

== Does the model have detail levels? ==

LODs should be included in every model. The number depends on the case. For ships 2-3, for stations and buildings 3-4.

== Does the model have a proper collision mesh? ==

All models must have a collision mesh, and it should be very low detail (<100 triangles).

== Does the model have a large number of geometry nodes? ==

One geometry node equals one drawcall. All static geometry should be combined into one node (or one per material).

Some day the importer may provide optimization options, but until it does modelers must merge geometry before exporting.

== Does the model have many materials? ==

Geometries with different materials will be drawn separately. Identical materials should be merged together.

== Does an animation have a large number of keyframes? ==

Some exporters have the option to resample the timeline, creating new keyframes at set intervals. If almost every frame is a keyframe, the file size will increase quickly.

== Does the model have large secondary texture maps (glow, specular, patterns) ==

Glowmaps usually don't have much detail, so they should be half or quarter size of the main texture. Patterns should never be very large.

== Do .png textures include an unnecessary alpha channel? ==

Opaque textures don't need to be 32-bit. With Photoshop this mistake is easy to make, so flatten the image before saving.

Roadmap

2013-06-30T19:28:09Z

Luomu:

== 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
* Missions and station interface
** Redesign the bulletin board to allow filtering and searching (e.g., adverts have tags, as shown in this old mock-up: http://i.imgur.com/HJH9L.png)
** Centralise bulletin board within the station interface (ie, everything else hangs off the bulletin board; the BB is basically the station-wide-web)
** Replace the "standard" commodity market with multiple traders/shops advertising on the BB
** Replace the "standard" ship equipment and servicing screens with mechanics advertising on the BB
** Replace the "standard" ship purchase screen with specialist shops advertising on the BB, plus also individual pilots posting ship-for-sale and ship-wanted adverts
** Allow player to buy some types of ship equipment as cargo and have it fitted elsewhere
* 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)
* Ship to ship docking

Roadmap

2013-06-13T13:13:36Z

Luomu: /* More proposed stuff */

== Version 1.0 ==

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)

2013-01-13T17:15:13Z

Luomu:

Model system

2013-01-06T14:22:26Z

Luomu: Update specular exponent value

== 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||yes/no. This material will use the pattern/colour system. Read more below. Default no.
|}

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

[[Category:Art]]

Model system

2012-12-15T15:36:39Z

Luomu: /* Importing models */

== Overview ==

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

== Importing models ==

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

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

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

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

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

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

[[Category:Art]]

Model system

2012-12-15T15:36:15Z

Luomu: /* Importing models */

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

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

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

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

[[Category:Art]]

Model system

2012-12-15T15:06:05Z

Luomu: /* Export settings */

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

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

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

=== Export settings ===

Collada (.dae) export settings for Blender 2.6:

[[File:newmodel_exportsettings01.png]]

[[Category:Art]]

File:Newmodel exportsettings01.png

2012-12-15T15:05:34Z

Luomu:

Model system

2012-12-15T15:05:18Z

Luomu:

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

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

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

=== Export settings ===

[[File:newmodel_exportsettings01.png]]

[[Category:Art]]

Model system

2012-12-15T04:25:33Z

Luomu: viewer note

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

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

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

[[Category:Art]]

Model system

2012-12-15T04:20:35Z

Luomu:

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

The model viewer is supplied with the game. See [[Newmodelviewer]].

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

[[Category:Art]]

User:Luomu

2012-12-15T04:20:23Z

Luomu:

= .plan =

Hello! I do things for Pioneer. Not as much as I would like to.

You may catch me at:

* github.com/Luomu
* irc: kko_

== Scratchpad ==

=== New systems that need to be developed ===

Lots of them :)

* Model cache system so geometry is converted only once
* Lua API
* System to handle attachments
** Tag points may be rotated in code to implement target tracking guns
* System to handle spaceship logos, station advertisements and shipyard UI to customize your ship
** It should be possible to add ship insignia by dropping a .png in your user folder, without saves breaking if you later remove that .png
* UI to paint your ship and a system to give faction-appropriate colour schemes to NPC ships
* Building sets
* Update collision system to handle animation (just updating BB should be enough)
* Separate space station docking scripts from the old models
* There is no good way to define parameters for certain triangles (geomflags in LMR). The main use case is to mark landing pads, this will be doable with a named node.
* etc

=== Graph dump ===

Below, an actual model test_meteor (two LODs, animated landing gear, several ship thrusters)

Group - test_meteor
LOD
Group - 10
MatrixTransform - Scene
MatrixTransform - Meteor_Low
StaticGeometry - Meteor_Low_mesh
Group - 1000
Group
MatrixTransform - Scene
MatrixTransform - Meteor_Hi
StaticGeometry - Meteor_Hi_mesh
MatrixTransform
Thruster - thruster_linear_rear_001
MatrixTransform
Thruster - thruster_right_001
MatrixTransform
Thruster - thruster_top_001
MatrixTransform
Thruster - thruster_right_000
MatrixTransform
Thruster - thruster_left_001
MatrixTransform
Thruster - thruster_left_002
MatrixTransform
Thruster - thruster_linear_rear_000
MatrixTransform
Thruster - thruster_top_000
MatrixTransform
Thruster - thruster_wing_001
MatrixTransform
Thruster - thruster_wing_000
MatrixTransform
Thruster - thruster_wing_002
MatrixTransform - decal_01
StaticGeometry - decal_01_mesh
Group
MatrixTransform - Root
MatrixTransform - LandingGear
StaticGeometry - LandingGear_mesh
MatrixTransform - tag_gun_left
MatrixTransform - tag_gun_right

Optimization potential: unanimated geometry should be pre-translated at loading phase to get rid of some MatrixTransforms.

Question: you might notice tag_gun_left and right are attached to the model root node. They have been pre-transformed to make the positions absolute. It's done this way since if a tag is defined on each LOD it can practically have several positions. This is a bit stupid since now they are outside of the LOD node. Should tags be kept in their original locations in the structure (then model->FindTag will potentially return more than one)?

User:Luomu

2012-12-15T04:17:24Z

Luomu:

Model system

2012-12-15T04:16:50Z

Luomu: Removed todo

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

The model viewer is supplied with the game. See [[Newmodelviewer]].

=== Model definition file ===

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

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

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

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

== Materials ==

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

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

=== Material properties ===

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

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

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

=== Patterns ===

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

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

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

[[File:newmodel_patterns_asp.png]]

== Detail levels ==

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

lod 100
mesh hull_low.dae

lod 200
mesh hull_med.dae

lod 1000
mesh hull_hi.dae
mesh landing_gear.dae

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

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

== Animations ==

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

anim gear_down 0 10
anim something_else 12 25

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

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

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

== Attachments ==

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

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

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

[[File:newmodel_tagpoints01.png]]

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

== Collisions ==

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

collision collision.obj

This will be global for all detail levels.

[[File:newmodel_collmesh01.png]]

== Decals ==

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

[[File:newmodel_decals01.png]]

== Labels ==

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

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

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

[[File:newmodel_labels01.png]]

== Minor features ==

=== Billboard lights ===

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

=== Thrusters ===

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

== Internals ==

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

The internal scene graph consists of several of these nodes:

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

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

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

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

=== Animations ===

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

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

=== Graph dump ===

Below, an actual model test_meteor (two LODs, animated landing gear, several ship thrusters)

Group - test_meteor
LOD
Group - 10
MatrixTransform - Scene
MatrixTransform - Meteor_Low
StaticGeometry - Meteor_Low_mesh
Group - 1000
Group
MatrixTransform - Scene
MatrixTransform - Meteor_Hi
StaticGeometry - Meteor_Hi_mesh
MatrixTransform
Thruster - thruster_linear_rear_001
MatrixTransform
Thruster - thruster_right_001
MatrixTransform
Thruster - thruster_top_001
MatrixTransform
Thruster - thruster_right_000
MatrixTransform
Thruster - thruster_left_001
MatrixTransform
Thruster - thruster_left_002
MatrixTransform
Thruster - thruster_linear_rear_000
MatrixTransform
Thruster - thruster_top_000
MatrixTransform
Thruster - thruster_wing_001
MatrixTransform
Thruster - thruster_wing_000
MatrixTransform
Thruster - thruster_wing_002
MatrixTransform - decal_01
StaticGeometry - decal_01_mesh
Group
MatrixTransform - Root
MatrixTransform - LandingGear
StaticGeometry - LandingGear_mesh
MatrixTransform - tag_gun_left
MatrixTransform - tag_gun_right

Optimization potential: unanimated geometry should be pre-translated at loading phase to get rid of some MatrixTransforms.

Question: you might notice tag_gun_left and right are attached to the model root node. They have been pre-transformed to make the positions absolute. It's done this way since if a tag is defined on each LOD it can practically have several positions. This is a bit stupid since now they are outside of the LOD node. Should tags be kept in their original locations in the structure (then model->FindTag will potentially return more than one)?

[[Category:Art]]

Model viewer

2012-12-12T03:13:45Z

Luomu: moved Newmodelviewer to Model viewer

To enter modelviewer mode, launch the game with:

pioneer -mv <optional model name>

= Hotkeys =

Esc: Quit

Tab: Toggle UI

PrintScr: Screenshot

Space: Reset camera view + thruster sliders

G: Cycle grid mode

R: Randomize colour sliders

Z: Toggle wireframe mode

Camera view presets are like Blender:

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

[[Category:Art]]

Newmodelviewer

2012-12-12T03:13:45Z

Luomu: moved Newmodelviewer to Model viewer

#REDIRECT [[Model viewer]]

Power Use in Ships

2012-11-14T14:14:10Z

Luomu: moved Idea Power Use in Ships to Power Use in Ships

Idea Power Use in Ships

2012-11-14T14:14:10Z

Luomu: moved Idea Power Use in Ships to Power Use in Ships

#REDIRECT [[Power Use in Ships]]

Escape Capsules

2012-11-14T14:14:02Z

Luomu: moved Idea Escape Capsules to Escape Capsules