Spring - User contributions [en]

3DModels:Textures

2013-04-10T04:08:58Z

Spliff: /* Textures for S3O */

[[Engine_Development|Development]] < [[Game_and_Unit_development|Game Development]] < {{FULLPAGENAME}}

==Textures for S3O==

S3O has some tricky bits. One of them is learning to use the right texture formats to achieve your goals. Luckily for would-be content developers, Spring is very forgiving about image file-types, and allows users to make use of the TGA, PNG, BMP and DDS image file formats.

S3Os that are being rendered with Spring's ARB shaders (i.e., the default rendering pipeline) have two textures, each of which is supposed to be RGBA, not just RGB- i.e., 32-bit, not 24-bit. The alpha channel, which something many new modelers / painters aren't familiar with, has specific uses. If you don't know what an alpha channel is, please Google it and read a bit before continuing with this lesson.

===Texture1===

This texture is used to store the color values of the model (i.e., what people usually call the "skin") and the team-color values are stored in the alpha channel, as a grayscale, where white is pure team-color, black is none at all, and all gray values are in between. This is blended with the color values, reflective and glow values to arrive at a final color in the engine. Until you have more experience with graphics programming, it's enough to know that if you don't put any colors into your alpha channel, the model won't have team-color, and if you fill it with white, you will not see your colors at all.

===Texture2===

This is the "secondary" texture, but it is probably the most important, in terms of your final quality.

This texture uses RGBA, just like Texture1, but it uses each color channel indepedently, due to the way the ARB shader works. If you haven't learned to view the Channels in your images yet, this is where you should start learning, right now. To get the most out of this area of Spring (or for that matter, practically any game engine these days) it's important to understand how to work with image channels for precise control over the color values of any given pixel.

Green values are reflectivity. The more green in a given pixel, the more reflective it will be.

Red values are glow. The more red in a given pixel, the more glow it will have, overriding the light levels in a scene. A white Texture1 pixel with a totally red Texture2 pixel will always be completely white, no matter what.

Blue values do not have a use, in the standard ARB shader. There are variants of the ARB shader available, where the blue value does various things. These derivative versions of Spring's ARB shader code are Open Source, so please ask around if you want to know more about these, people will be happy to share them with you.

The alpha channel is one bit, if you're using Spring's default ARB shader. Black pixels == "clear", and will not be rendered at all. White pixels are "solid". This can be used to create "holes" in your models, etc.

===Texture Formats For S3O===

Spring supports TGA, PNG, and DDS.

TGA and PNG have no performance advantages, are rendered upside-down in [[upspring]] (which makes it hard to see if the final model is correct, without running the engine), and take up full texture RAM on the GPU. Neither format is recommended, but they are easier for newbies to use.

DDS is the preferred image format, and is what UpSpring was designed to use.

===General Guidelines For DDS Textures===

* It is recommended to use DXT5 or DXT3 compression for Texture 1, and DXT1 with alpha channel for Texture2
* Turn on mipmaps. You MUST make all of the mipmaps. Not one, not two, not four... all of them. This means when making a DDS, it may take a few moments to compress, especially if it's large. This is normal, do not be alarmed.
* If your texture is invisible ingame or is just plain black/white, make sure you have turned on Mipmaps, set a radius and height for your model in UpSpring, and not have pure black or white backgrounds (255,255,255)/(0,0,0), set them to anything other than those.
* DDS requires specific settings, in order to reduce compression artifacts and sharpen the mipmaps so that the resulting images look their best in Spring. This gives you much more control over quality than PNG or TGA, where the end-user's hardware determines what the mipmaps look like (which frequently will look a lot worse than DDS), but it requires some study.

[http://developer.nvidia.com/object/photoshop_dds_plugins.html However, if you have Photoshop, you can just get the nVidia DDS Plugin from here], and use Argh's DDS compression settings, which work well with DXT1, DXT3 and DXT5 (but are not yet optimized for DXT5 normalmaps). [http://www.wolfegames.com/TA_Section/Standard_DDS_Settings.7z Download that here.]

==Textures - Assimp Model Formats (DAE,MDL,MD3 and others except OBJ)==
Assimp is a library used by Spring to handle a large variety of common model formats. In general Assimp follows the same rules for textures as S3O models but there are some issues to be aware of - especially with regards to DDS textures.

Assimp supports a metadata file (<modelname>.lua or <modelname>.<model extension>.lua) in the same directory as your model. The file should return a lua table that will be hereafter refered to simply as 'metadata'.

'''Note 1:''' It's important to know that there are 2 seperate texture loading processes. DDS textures are passed directly from Spring to the nv_dds library (NVIDIA DDS Library). All other Assimp textures are handled by Spring's S30Texture and Bitmap classes which perform loading and editing tasks via the DevIL library. For content developers the primary distinction is that DDS images cannot be modified by Spring and as a consequence ''the metadata properties invertteamcolor and fliptextures have no effect on DDS.''

'''Note 2:''' Unlike S3O models the Assimp loader allows you to define relative paths to your texture in the metadata using the string keys tex1 and tex2.

'''Issue 1:''' DDS has different coordinates (y-axis flip) from other textures because it was designed for DirectX which is backwards from OpenGL and normal image orientation. Assimp can flip textures for you using fliptextures=true/false in your metadata. By default this value is false. This key has no effect on DDS however (See Note 1).

'''Issue 2:''' S3O textures use the alpha channel of tex1 for teamcolor however it treats opaque (0 alpha) as full teamcolor. This makes a normal JPG/PNG appear entirely as teamcolor and makes those textures hard to edit in normal tools. Assimp tries to correct this issue by inverting teamcolor automatically so "normal" textures work as expected. If you took a texture from an existing Spring model or created your texture following any existing S3O texture guide then it will be incorrect in Assimp UNLESS you create a metadata file with an invertteamcolor=false telling Assimp to leave it alone. If you create a texture/model from any other source it will just work. As far as Assimp (and common sense) is concerned existing Spring textures are busted and you should probably just invert your alpha channel in an image editor prior to moving content from S3O to Assimp. ''Be aware that DDS are not automatically inverted (or controlled by inverteamcolor) so PNG/JPG and DDS textures may be the inverse of each other for teamcolor (See Note 1)''. If you convert PNG->DDS your models may turn red until you invert your alpha in an image editor.

'''Issue 3:''' Assimp does not currently handle textures stored inside the model file or "material" properties like specular, diffuse defined in the model. If you want to use the textures stored in an existing model you should extract/export them to normal textures and set them up according to the method used by S3O.

'''Issue 4:''' Spring does not currently support per-node/per-piece textures or other multitexture arrangements. Your textures must be per-model and follow the rules for S3O (see above).

==Textures- 3DO (i.e., OTA game ports)==
Textures are stored in the UnitTextures directory of your game. They may be Windows .BMP format at 24 bit color depth, or a Targa .TGA file in 32 bit (alpha layer) color depth.

==Rules for textures==
OTA mods using 3DO models store their textures in a Texture Atlas. This is a single 2048 / 2048 image that is built by Spring automatically from the small images used as tiles in OTA. Thus, the total size of all of your 3DO textures cannot exceed 2048 / 2048. This is rarely a problem, if you're just porting an OTA mod.

===Logo Textures / Team Color===
In the case of logo textures, you must edit the file teamtex.txt in the UnitTextures/tatex directory (or in your game / mod, as it will overwrite Spring's values).

Just add the name of your texture to the list, without the "00". For example, if you wanted to add ArmLogo00.bmp to the team color list, you would put ArmLogo in the teamtex.txt file. The image must have only values in the Red, Blue and Alpha channels, to function correctly as teamcolor- the Green channel should be left black. So the resulting image will look "purple". If you are not experienced working with color channels, ask somebody for help, or read some tutorials.

===Reflections===
To make a texture reflect its environment, you must create a Targa file with an alpha layer with a program such as the [http://gimp-win.sourceforge.net/stable.html GIMP] or [http://www.adobe.com/products/tryadobe/main.jsp#product=39 Photoshop].

The procedure is the same as making team-color textures, but with two twists:

1. Don't name the file in the teamtex.txt file.

2. You can use all four channels- RGBA, for full colors and alpha- and the alpha layer's white / black values determine how reflective the object is. If white, that area is totally reflective. If black, it will not reflect the world at all. It should be noted that some image editors have trouble setting alpha layers to 100% and cause Spring to display the image as completely black, hence it is suggested you make it about 99%.

===Conversion from .GAF===
In Total Annihilation textures were stored in /Textures/*.gaf. If you're porting an old TA mods, there will be hundreds of textures to convert to Spring format. There is an easy way to automatically extract all the texture from all the .gaf into well named .bmp: Download [http://www.planetannihilation.com/bsr/downloads/GAFDump.zip GAF Dump]. Then run GAFDump.exe, from inside the folder your textures are, and with the '''-b''' commandline option.

To save yourself some more trouble, we strongly suggest that you use 3DOBleacher to remove all of the "shading" versions of the textures from the mod you're porting, as well. This will save a huge amount of space on the Texture Atlas and the final results will look a lot more professional in Spring. 3DOBleacher requires some reading and a lot of work to set up, however.

[[Category:3D Models]]

3DModels:Textures

2013-04-10T04:07:28Z

Spliff: Added breadcrumb

[[Engine_Development|Development]] < [[Game_and_Unit_development|Game Development]] < {{FULLPAGENAME}}

==Textures for S3O==

S3O, as the most modern file format for models in the Spring engine, has some tricky bits. One of them is learning to use the right texture formats to achieve your goals. Luckily for would-be content developers, Spring is very forgiving about image file-types, and allows users to make use of the TGA, PNG, BMP and DDS image file formats.

S3Os that are being rendered with Spring's ARB shaders (i.e., the default rendering pipeline) have two textures, each of which is supposed to be RGBA, not just RGB- i.e., 32-bit, not 24-bit. The alpha channel, which something many new modelers / painters aren't familiar with, has specific uses. If you don't know what an alpha channel is, please Google it and read a bit before continuing with this lesson.

===Texture1===

This texture is used to store the color values of the model (i.e., what people usually call the "skin") and the team-color values are stored in the alpha channel, as a grayscale, where white is pure team-color, black is none at all, and all gray values are in between. This is blended with the color values, reflective and glow values to arrive at a final color in the engine. Until you have more experience with graphics programming, it's enough to know that if you don't put any colors into your alpha channel, the model won't have team-color, and if you fill it with white, you will not see your colors at all.

===Texture2===

This is the "secondary" texture, but it is probably the most important, in terms of your final quality.

This texture uses RGBA, just like Texture1, but it uses each color channel indepedently, due to the way the ARB shader works. If you haven't learned to view the Channels in your images yet, this is where you should start learning, right now. To get the most out of this area of Spring (or for that matter, practically any game engine these days) it's important to understand how to work with image channels for precise control over the color values of any given pixel.

Green values are reflectivity. The more green in a given pixel, the more reflective it will be.

Red values are glow. The more red in a given pixel, the more glow it will have, overriding the light levels in a scene. A white Texture1 pixel with a totally red Texture2 pixel will always be completely white, no matter what.

Blue values do not have a use, in the standard ARB shader. There are variants of the ARB shader available, where the blue value does various things. These derivative versions of Spring's ARB shader code are Open Source, so please ask around if you want to know more about these, people will be happy to share them with you.

The alpha channel is one bit, if you're using Spring's default ARB shader. Black pixels == "clear", and will not be rendered at all. White pixels are "solid". This can be used to create "holes" in your models, etc.

===Texture Formats For S3O===

Spring supports TGA, PNG, and DDS.

TGA and PNG have no performance advantages, are rendered upside-down in [[upspring]] (which makes it hard to see if the final model is correct, without running the engine), and take up full texture RAM on the GPU. Neither format is recommended, but they are easier for newbies to use.

DDS is the preferred image format, and is what UpSpring was designed to use.

===General Guidelines For DDS Textures===

* It is recommended to use DXT5 or DXT3 compression for Texture 1, and DXT1 with alpha channel for Texture2
* Turn on mipmaps. You MUST make all of the mipmaps. Not one, not two, not four... all of them. This means when making a DDS, it may take a few moments to compress, especially if it's large. This is normal, do not be alarmed.
* If your texture is invisible ingame or is just plain black/white, make sure you have turned on Mipmaps, set a radius and height for your model in UpSpring, and not have pure black or white backgrounds (255,255,255)/(0,0,0), set them to anything other than those.
* DDS requires specific settings, in order to reduce compression artifacts and sharpen the mipmaps so that the resulting images look their best in Spring. This gives you much more control over quality than PNG or TGA, where the end-user's hardware determines what the mipmaps look like (which frequently will look a lot worse than DDS), but it requires some study.

[http://developer.nvidia.com/object/photoshop_dds_plugins.html However, if you have Photoshop, you can just get the nVidia DDS Plugin from here], and use Argh's DDS compression settings, which work well with DXT1, DXT3 and DXT5 (but are not yet optimized for DXT5 normalmaps). [http://www.wolfegames.com/TA_Section/Standard_DDS_Settings.7z Download that here.]

==Textures - Assimp Model Formats (DAE,MDL,MD3 and others except OBJ)==
Assimp is a library used by Spring to handle a large variety of common model formats. In general Assimp follows the same rules for textures as S3O models but there are some issues to be aware of - especially with regards to DDS textures.

Assimp supports a metadata file (<modelname>.lua or <modelname>.<model extension>.lua) in the same directory as your model. The file should return a lua table that will be hereafter refered to simply as 'metadata'.

'''Note 1:''' It's important to know that there are 2 seperate texture loading processes. DDS textures are passed directly from Spring to the nv_dds library (NVIDIA DDS Library). All other Assimp textures are handled by Spring's S30Texture and Bitmap classes which perform loading and editing tasks via the DevIL library. For content developers the primary distinction is that DDS images cannot be modified by Spring and as a consequence ''the metadata properties invertteamcolor and fliptextures have no effect on DDS.''

'''Note 2:''' Unlike S3O models the Assimp loader allows you to define relative paths to your texture in the metadata using the string keys tex1 and tex2.

'''Issue 1:''' DDS has different coordinates (y-axis flip) from other textures because it was designed for DirectX which is backwards from OpenGL and normal image orientation. Assimp can flip textures for you using fliptextures=true/false in your metadata. By default this value is false. This key has no effect on DDS however (See Note 1).

'''Issue 2:''' S3O textures use the alpha channel of tex1 for teamcolor however it treats opaque (0 alpha) as full teamcolor. This makes a normal JPG/PNG appear entirely as teamcolor and makes those textures hard to edit in normal tools. Assimp tries to correct this issue by inverting teamcolor automatically so "normal" textures work as expected. If you took a texture from an existing Spring model or created your texture following any existing S3O texture guide then it will be incorrect in Assimp UNLESS you create a metadata file with an invertteamcolor=false telling Assimp to leave it alone. If you create a texture/model from any other source it will just work. As far as Assimp (and common sense) is concerned existing Spring textures are busted and you should probably just invert your alpha channel in an image editor prior to moving content from S3O to Assimp. ''Be aware that DDS are not automatically inverted (or controlled by inverteamcolor) so PNG/JPG and DDS textures may be the inverse of each other for teamcolor (See Note 1)''. If you convert PNG->DDS your models may turn red until you invert your alpha in an image editor.

'''Issue 3:''' Assimp does not currently handle textures stored inside the model file or "material" properties like specular, diffuse defined in the model. If you want to use the textures stored in an existing model you should extract/export them to normal textures and set them up according to the method used by S3O.

'''Issue 4:''' Spring does not currently support per-node/per-piece textures or other multitexture arrangements. Your textures must be per-model and follow the rules for S3O (see above).

==Textures- 3DO (i.e., OTA game ports)==
Textures are stored in the UnitTextures directory of your game. They may be Windows .BMP format at 24 bit color depth, or a Targa .TGA file in 32 bit (alpha layer) color depth.

==Rules for textures==
OTA mods using 3DO models store their textures in a Texture Atlas. This is a single 2048 / 2048 image that is built by Spring automatically from the small images used as tiles in OTA. Thus, the total size of all of your 3DO textures cannot exceed 2048 / 2048. This is rarely a problem, if you're just porting an OTA mod.

===Logo Textures / Team Color===
In the case of logo textures, you must edit the file teamtex.txt in the UnitTextures/tatex directory (or in your game / mod, as it will overwrite Spring's values).

Just add the name of your texture to the list, without the "00". For example, if you wanted to add ArmLogo00.bmp to the team color list, you would put ArmLogo in the teamtex.txt file. The image must have only values in the Red, Blue and Alpha channels, to function correctly as teamcolor- the Green channel should be left black. So the resulting image will look "purple". If you are not experienced working with color channels, ask somebody for help, or read some tutorials.

===Reflections===
To make a texture reflect its environment, you must create a Targa file with an alpha layer with a program such as the [http://gimp-win.sourceforge.net/stable.html GIMP] or [http://www.adobe.com/products/tryadobe/main.jsp#product=39 Photoshop].

The procedure is the same as making team-color textures, but with two twists:

1. Don't name the file in the teamtex.txt file.

2. You can use all four channels- RGBA, for full colors and alpha- and the alpha layer's white / black values determine how reflective the object is. If white, that area is totally reflective. If black, it will not reflect the world at all. It should be noted that some image editors have trouble setting alpha layers to 100% and cause Spring to display the image as completely black, hence it is suggested you make it about 99%.

===Conversion from .GAF===
In Total Annihilation textures were stored in /Textures/*.gaf. If you're porting an old TA mods, there will be hundreds of textures to convert to Spring format. There is an easy way to automatically extract all the texture from all the .gaf into well named .bmp: Download [http://www.planetannihilation.com/bsr/downloads/GAFDump.zip GAF Dump]. Then run GAFDump.exe, from inside the folder your textures are, and with the '''-b''' commandline option.

To save yourself some more trouble, we strongly suggest that you use 3DOBleacher to remove all of the "shading" versions of the textures from the mod you're porting, as well. This will save a huge amount of space on the Texture Atlas and the final results will look a lot more professional in Spring. 3DOBleacher requires some reading and a lot of work to set up, however.

[[Category:3D Models]]

Assimp

2013-04-10T03:55:52Z

Spliff: /* Assimp Textures */

[[Engine_Development|Development]] < [[Game_and_Unit_development|Game Development]] < {{FULLPAGENAME}}

=Assimp=
Open Asset Import Library (short name: Assimp) is used in Spring for loading a number of model formats including Collada & 3ds (currently obj is parsed by a different codepaths).

What Spring supports in its Assimp renderer:
* extended metafile (<code>%modelfilename%.lua</code> next to the modefile)
* still uses tex1 & tex2 texture system of S3O (same shader as S3O)
* 2nd texcoord
* loading of the texture filepaths from the model (don't have to be in <code>unittextures/</code>)
* when texture filepaths aren't included in the model, it searches for <code>%modelfilename%.*</code> & <code>%modelfilename%2.*</code> in <code>unittextures/</code>
* special modelpieces `SpringHeight` & `SpringRadius`

=Assimp Textures=
See [[Units:Textures]] (Assimp Section)

=Blender Workflow Tutorial=
This is a stub containing a simple outline of a Blender workflow. Disclaimer: I'm no modeling expert, there may be a better way to do this.

<table>
<tr>
<td valign="top">'''1)''' Open an existing Blender model or import a different format through the File menu (File > Import).</td>
</tr>
<tr>
<td valign="top">'''2)''' In the 3D view, at the top right, there will be a '+' icon. click this </td>
<td> [[File:3-12-2013 5-02-21 PM.pngâ€Žâ€Ž|secret panel]]</td>
</tr>
<tr>
<td valign="top">'''3)''' In that panel, select Display > Shading > GLSL </td>
<td>[[File:3-12-2013 5-02-04 PM.pngâ€Žâ€Ž|display settings]]</td>
</tr>
<tr>
<td valign="top">'''4)''' Make sure you have a lamp in your scene while in this mode or your model will be dark.
</td>
<td> [[File:3-12-2013_5-11-14_PM.pngâ€Žâ€Ž|blend light source]]</td>
</tr>
<tr>
<td valign="top">'''5)''' Applying texture:
## In the UV/Image editor, click the image icon (Tooltip: Browse Image to be linked) to select your texture. If it's not there, click on Image > Open Image to browse for it.
## In the 3D View, select (right-click) your object and hit Tab to enter Mesh Mode.
## Hit A to select all your faces.
## In the 3D View, hit A to select all the faces there and select your image with the image icon. Assuming there's a UVMap, you should see your texture.
## If you don't see any faces you'll need to add the UVMap to a new texture:
### In the Properties view click on Textures (checkerboard icon).
### Click on Add New Texture (plus icon).
### Select Type = Image or Movie.
### Under Image, click on the image icon and choose your image file.
### Under Mapping, select Coordinates = UV.
### Under Influence > Diffuse, check Color and make sure it's 1.00.
## To add a normalmap:
### Repeat steps 5.1 to 5.5.
### Under Image Sampling, check Normal Map.
### Under Influence > Geometry, check Normal. Make sure it.s 1.00.
## You'll need to do this for each piece.</td>
</tr>
<tr>
<td valign="top">'''7)''' Piece hierarchy:
## Select piece A, hold shift and select piece B. Hit Ctrl+P and it will make piece A a child of piece B.
## Make sure all the pieces are descending from one single piece.
# Setting piece origins:
## Select a piece.
## Place the 3D cursor where you want the origin to be (left-click).
## Click on Object > Transform > Origin to 3D Cursor.
## You can now rotate your pieces:
### Click on the dropdown "Pivot Center for Rotation/Scaling" and select Individual Origins.
### Rotate.
## Repeat this for all your pieces.
# Save your model.
# Select all the pieces of your model, ignore the lamp.
# Click on File > Export > Collada.
# Check "Export Only Selected" and export.
# The dae file will be used as your object.</td>
</tr>
</table>

[[Category:3D Models]]

3DModels:Textures

2013-04-10T03:49:01Z

Spliff: /* Textures- Assimp added*/

==Textures for S3O==

S3O, as the most modern file format for models in the Spring engine, has some tricky bits. One of them is learning to use the right texture formats to achieve your goals. Luckily for would-be content developers, Spring is very forgiving about image file-types, and allows users to make use of the TGA, PNG, BMP and DDS image file formats.

S3Os that are being rendered with Spring's ARB shaders (i.e., the default rendering pipeline) have two textures, each of which is supposed to be RGBA, not just RGB- i.e., 32-bit, not 24-bit. The alpha channel, which something many new modelers / painters aren't familiar with, has specific uses. If you don't know what an alpha channel is, please Google it and read a bit before continuing with this lesson.

===Texture1===

This texture is used to store the color values of the model (i.e., what people usually call the "skin") and the team-color values are stored in the alpha channel, as a grayscale, where white is pure team-color, black is none at all, and all gray values are in between. This is blended with the color values, reflective and glow values to arrive at a final color in the engine. Until you have more experience with graphics programming, it's enough to know that if you don't put any colors into your alpha channel, the model won't have team-color, and if you fill it with white, you will not see your colors at all.

===Texture2===

This is the "secondary" texture, but it is probably the most important, in terms of your final quality.

This texture uses RGBA, just like Texture1, but it uses each color channel indepedently, due to the way the ARB shader works. If you haven't learned to view the Channels in your images yet, this is where you should start learning, right now. To get the most out of this area of Spring (or for that matter, practically any game engine these days) it's important to understand how to work with image channels for precise control over the color values of any given pixel.

Green values are reflectivity. The more green in a given pixel, the more reflective it will be.

Red values are glow. The more red in a given pixel, the more glow it will have, overriding the light levels in a scene. A white Texture1 pixel with a totally red Texture2 pixel will always be completely white, no matter what.

Blue values do not have a use, in the standard ARB shader. There are variants of the ARB shader available, where the blue value does various things. These derivative versions of Spring's ARB shader code are Open Source, so please ask around if you want to know more about these, people will be happy to share them with you.

The alpha channel is one bit, if you're using Spring's default ARB shader. Black pixels == "clear", and will not be rendered at all. White pixels are "solid". This can be used to create "holes" in your models, etc.

===Texture Formats For S3O===

Spring supports TGA, PNG, and DDS.

TGA and PNG have no performance advantages, are rendered upside-down in [[upspring]] (which makes it hard to see if the final model is correct, without running the engine), and take up full texture RAM on the GPU. Neither format is recommended, but they are easier for newbies to use.

DDS is the preferred image format, and is what UpSpring was designed to use.

===General Guidelines For DDS Textures===

* It is recommended to use DXT5 or DXT3 compression for Texture 1, and DXT1 with alpha channel for Texture2
* Turn on mipmaps. You MUST make all of the mipmaps. Not one, not two, not four... all of them. This means when making a DDS, it may take a few moments to compress, especially if it's large. This is normal, do not be alarmed.
* If your texture is invisible ingame or is just plain black/white, make sure you have turned on Mipmaps, set a radius and height for your model in UpSpring, and not have pure black or white backgrounds (255,255,255)/(0,0,0), set them to anything other than those.
* DDS requires specific settings, in order to reduce compression artifacts and sharpen the mipmaps so that the resulting images look their best in Spring. This gives you much more control over quality than PNG or TGA, where the end-user's hardware determines what the mipmaps look like (which frequently will look a lot worse than DDS), but it requires some study.

[http://developer.nvidia.com/object/photoshop_dds_plugins.html However, if you have Photoshop, you can just get the nVidia DDS Plugin from here], and use Argh's DDS compression settings, which work well with DXT1, DXT3 and DXT5 (but are not yet optimized for DXT5 normalmaps). [http://www.wolfegames.com/TA_Section/Standard_DDS_Settings.7z Download that here.]

==Textures - Assimp Model Formats (DAE,MDL,MD3 and others except OBJ)==
Assimp is a library used by Spring to handle a large variety of common model formats. In general Assimp follows the same rules for textures as S3O models but there are some issues to be aware of - especially with regards to DDS textures.

Assimp supports a metadata file (<modelname>.lua or <modelname>.<model extension>.lua) in the same directory as your model. The file should return a lua table that will be hereafter refered to simply as 'metadata'.

'''Note 1:''' It's important to know that there are 2 seperate texture loading processes. DDS textures are passed directly from Spring to the nv_dds library (NVIDIA DDS Library). All other Assimp textures are handled by Spring's S30Texture and Bitmap classes which perform loading and editing tasks via the DevIL library. For content developers the primary distinction is that DDS images cannot be modified by Spring and as a consequence ''the metadata properties invertteamcolor and fliptextures have no effect on DDS.''

'''Note 2:''' Unlike S3O models the Assimp loader allows you to define relative paths to your texture in the metadata using the string keys tex1 and tex2.

'''Issue 1:''' DDS has different coordinates (y-axis flip) from other textures because it was designed for DirectX which is backwards from OpenGL and normal image orientation. Assimp can flip textures for you using fliptextures=true/false in your metadata. By default this value is false. This key has no effect on DDS however (See Note 1).

'''Issue 2:''' S3O textures use the alpha channel of tex1 for teamcolor however it treats opaque (0 alpha) as full teamcolor. This makes a normal JPG/PNG appear entirely as teamcolor and makes those textures hard to edit in normal tools. Assimp tries to correct this issue by inverting teamcolor automatically so "normal" textures work as expected. If you took a texture from an existing Spring model or created your texture following any existing S3O texture guide then it will be incorrect in Assimp UNLESS you create a metadata file with an invertteamcolor=false telling Assimp to leave it alone. If you create a texture/model from any other source it will just work. As far as Assimp (and common sense) is concerned existing Spring textures are busted and you should probably just invert your alpha channel in an image editor prior to moving content from S3O to Assimp. ''Be aware that DDS are not automatically inverted (or controlled by inverteamcolor) so PNG/JPG and DDS textures may be the inverse of each other for teamcolor (See Note 1)''. If you convert PNG->DDS your models may turn red until you invert your alpha in an image editor.

'''Issue 3:''' Assimp does not currently handle textures stored inside the model file or "material" properties like specular, diffuse defined in the model. If you want to use the textures stored in an existing model you should extract/export them to normal textures and set them up according to the method used by S3O.

'''Issue 4:''' Spring does not currently support per-node/per-piece textures or other multitexture arrangements. Your textures must be per-model and follow the rules for S3O (see above).

==Textures- 3DO (i.e., OTA game ports)==
Textures are stored in the UnitTextures directory of your game. They may be Windows .BMP format at 24 bit color depth, or a Targa .TGA file in 32 bit (alpha layer) color depth.

==Rules for textures==
OTA mods using 3DO models store their textures in a Texture Atlas. This is a single 2048 / 2048 image that is built by Spring automatically from the small images used as tiles in OTA. Thus, the total size of all of your 3DO textures cannot exceed 2048 / 2048. This is rarely a problem, if you're just porting an OTA mod.

===Logo Textures / Team Color===
In the case of logo textures, you must edit the file teamtex.txt in the UnitTextures/tatex directory (or in your game / mod, as it will overwrite Spring's values).

Just add the name of your texture to the list, without the "00". For example, if you wanted to add ArmLogo00.bmp to the team color list, you would put ArmLogo in the teamtex.txt file. The image must have only values in the Red, Blue and Alpha channels, to function correctly as teamcolor- the Green channel should be left black. So the resulting image will look "purple". If you are not experienced working with color channels, ask somebody for help, or read some tutorials.

===Reflections===
To make a texture reflect its environment, you must create a Targa file with an alpha layer with a program such as the [http://gimp-win.sourceforge.net/stable.html GIMP] or [http://www.adobe.com/products/tryadobe/main.jsp#product=39 Photoshop].

The procedure is the same as making team-color textures, but with two twists:

1. Don't name the file in the teamtex.txt file.

2. You can use all four channels- RGBA, for full colors and alpha- and the alpha layer's white / black values determine how reflective the object is. If white, that area is totally reflective. If black, it will not reflect the world at all. It should be noted that some image editors have trouble setting alpha layers to 100% and cause Spring to display the image as completely black, hence it is suggested you make it about 99%.

===Conversion from .GAF===
In Total Annihilation textures were stored in /Textures/*.gaf. If you're porting an old TA mods, there will be hundreds of textures to convert to Spring format. There is an easy way to automatically extract all the texture from all the .gaf into well named .bmp: Download [http://www.planetannihilation.com/bsr/downloads/GAFDump.zip GAF Dump]. Then run GAFDump.exe, from inside the folder your textures are, and with the '''-b''' commandline option.

To save yourself some more trouble, we strongly suggest that you use 3DOBleacher to remove all of the "shading" versions of the textures from the mod you're porting, as well. This will save a huge amount of space on the Texture Atlas and the final results will look a lot more professional in Spring. 3DOBleacher requires some reading and a lot of work to set up, however.

[[Category:3D Models]]

Assimp

2013-04-10T02:58:47Z

Spliff: /* Assimp */

[[Engine_Development|Development]] < [[Game_and_Unit_development|Game Development]] < {{FULLPAGENAME}}

=Assimp=
Open Asset Import Library (short name: Assimp) is used in Spring for loading a number of model formats including Collada & 3ds (currently obj is parsed by a different codepaths).

What Spring supports in its Assimp renderer:
* extended metafile (<code>%modelfilename%.lua</code> next to the modefile)
* still uses tex1 & tex2 texture system of S3O (same shader as S3O)
* 2nd texcoord
* loading of the texture filepaths from the model (don't have to be in <code>unittextures/</code>)
* when texture filepaths aren't included in the model, it searches for <code>%modelfilename%.*</code> & <code>%modelfilename%2.*</code> in <code>unittextures/</code>
* special modelpieces `SpringHeight` & `SpringRadius`

=Assimp Textures=
See textures page (Assimp Section)

=Blender Workflow Tutorial=
This is a stub containing a simple outline of a Blender workflow. Disclaimer: I'm no modeling expert, there may be a better way to do this.

<table>
<tr>
<td valign="top">'''1)''' Open an existing Blender model or import a different format through the File menu (File > Import).</td>
</tr>
<tr>
<td valign="top">'''2)''' In the 3D view, at the top right, there will be a '+' icon. click this </td>
<td> [[File:3-12-2013 5-02-21 PM.pngâ€Žâ€Ž|secret panel]]</td>
</tr>
<tr>
<td valign="top">'''3)''' In that panel, select Display > Shading > GLSL </td>
<td>[[File:3-12-2013 5-02-04 PM.pngâ€Žâ€Ž|display settings]]</td>
</tr>
<tr>
<td valign="top">'''4)''' Make sure you have a lamp in your scene while in this mode or your model will be dark.
</td>
<td> [[File:3-12-2013_5-11-14_PM.pngâ€Žâ€Ž|blend light source]]</td>
</tr>
<tr>
<td valign="top">'''5)''' Applying texture:
## In the UV/Image editor, click the image icon (Tooltip: Browse Image to be linked) to select your texture. If it's not there, click on Image > Open Image to browse for it.
## In the 3D View, select (right-click) your object and hit Tab to enter Mesh Mode.
## Hit A to select all your faces.
## In the 3D View, hit A to select all the faces there and select your image with the image icon. Assuming there's a UVMap, you should see your texture.
## If you don't see any faces you'll need to add the UVMap to a new texture:
### In the Properties view click on Textures (checkerboard icon).
### Click on Add New Texture (plus icon).
### Select Type = Image or Movie.
### Under Image, click on the image icon and choose your image file.
### Under Mapping, select Coordinates = UV.
### Under Influence > Diffuse, check Color and make sure it's 1.00.
## To add a normalmap:
### Repeat steps 5.1 to 5.5.
### Under Image Sampling, check Normal Map.
### Under Influence > Geometry, check Normal. Make sure it.s 1.00.
## You'll need to do this for each piece.</td>
</tr>
<tr>
<td valign="top">'''7)''' Piece hierarchy:
## Select piece A, hold shift and select piece B. Hit Ctrl+P and it will make piece A a child of piece B.
## Make sure all the pieces are descending from one single piece.
# Setting piece origins:
## Select a piece.
## Place the 3D cursor where you want the origin to be (left-click).
## Click on Object > Transform > Origin to 3D Cursor.
## You can now rotate your pieces:
### Click on the dropdown "Pivot Center for Rotation/Scaling" and select Individual Origins.
### Rotate.
## Repeat this for all your pieces.
# Save your model.
# Select all the pieces of your model, ignore the lamp.
# Click on File > Export > Collada.
# Check "Export Only Selected" and export.
# The dae file will be used as your object.</td>
</tr>
</table>

[[Category:3D Models]]

Modinfo.lua

2011-11-15T12:14:06Z

Spliff: Removed version from name in examples and clarify format of dependencies

==Location==
<code>modinfo.lua</code> is a file in the root directory of a Spring Game.

==Purpose==
The purpose of this file is to define a Spring content package as a game or game content archive. It is read both by the multiplayer lobbies and the engine itself.

==Source==
The engine source code which parses the data from this file is viewable here: {{sourcelink|file=rts/System/FileSystem/ArchiveScanner.cpp}}

==Details==
The following tags are read, all are strings unless otherwise specified:
* <code>name</code> - The name displayed in the lobby or via Spring.exe, <code>version</code> is automatically appended. [http://springrts.com/phpbb/viewtopic.php?f=14&t=25927 Don't put the version into the name!]

* <code>shortName</code> - A short representation of the package name, usually an acronym of the above.

* <code>version</code> - The version of this package. Can be any text you like but preferably not blank. It's also best if the version increments numerically so players know which version is newer.

* <code>mutator</code> - String. Is the package an official release or a mutator?

* <code>game</code> - What game is this package based on? This is subtly different from the <code>name</code> attribute. Consider that a main game archive and a mutator would have the same game, but different name values.

* <code>shortGame</code> - Again an acronym representing the above.

* <code>description</code> - A description of this content package.

* <code>modtype</code> - What kind of content package is this? 1 for a game or mutator, 0 for a hidden base content file. Maps use 3 in [[mapinfo.lua]].

* <code>depend</code> - A table of other content packages, referenced by <code>name + version</code>, not their filename, which this package depends on. Spring will load them if they are present, or throw an error if they are missing. This is used by mutators to depend on main game file and by all games to depend on base content files. New games may particularly want to depend on <code>'Spring Cursors'</code> (provided as <code>cursors.sdz</code> in the Spring <code>base</code> directory) if they do not yet have their own [[MouseCursors|custom cursors]].

* <code>replace</code> - A table of content packages, again referenced by <code>name + version</code>, that this package is meant to replace. For example if you have a base content package with your game music, you may wish to replace it with an updated version later on without having to modify the <code>modinfo.lua</code> of all packages which <code>depend</code> on it. This is not usually used to update main game archives, however, as players may wish to continue playing a previous version.

==Examples==
===Main Game file===
<code><pre>
local modinfo = {
name = "My Awesome Spring Game",
shortName = "MASG",
game = "My Awesome Spring Game",
shortGame = "MASG",
mutator = "Official",
version = "v1.0",
description = "An awesome game I made with units",
url = "http://www.linktomyawesomegame.com/",
modtype = 1,
}

return modinfo
</pre></code>

===Mutator===
A mutator depends on the main game file, but does not replace it, it will usually have a different <code>name</code> and <code>shortName</code> but the same <code>game</code> and <code>shortGame</code> values as the main game file. It should still have a <code>modtype</code> of 1.

<code><pre>
local modinfo = {
name = "My Awesome Spring Game Mutator",
shortName = "MASGM",
game = "My Awesome Spring Game",
shortGame = "MASG",
mutator = "Double Speed Mutator",
version = "v1.0",
description = "An awesome mutator I made for MASG",
url = "http://www.linktomyawesomegame.com/",
modtype = 1,
depend = {
"My Awesome Spring Game v1.0",
}
}

return modinfo
</pre></code>

===Base Content===
Base content is a hidden, unplayable content package which is depended on by your game. For example you might include music in a hidden content package so that it was not updated with the main game files. It must have a <code>modtype</code> of 0. The following example is from <code>springcontent.sdz</code>, which is automatically loaded by Spring for all games.

<code><pre>
local modinfo = {
name = "Spring content",
version = "v1",
description = "Mods can depend on this archive to get all the spring content",
modtype = 0,
depend = {
"Spring Bitmaps v1"
},
}

return modinfo
</pre></code>

[[Category:Game development]]
[[Category:gamedata]]

===Further reading===
Forum thread: ''Please fix:games contain version in "name" tag (modinfo.lua)'' 
http://springrts.com/phpbb/viewtopic.php?f=14&t=25927

Building Spring on Linux

2011-02-21T04:38:59Z

Spliff: /* Ubuntu */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and either scons and python2.5-dev or cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===
<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread1.40-dev libboost-regex1.40-dev libboost-system1.40-dev \
libboost-program-options1.40-dev libboost-signals1.40-dev

# alternatively, you can try ...
sudo apt-get build-dep spring
</pre></code>

... and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
cmake .
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>/usr</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=/usr .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

== Using Scons ==
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

 
{{Finalizing_linux_install}}

 
{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Building Spring on Linux

2011-02-21T04:36:07Z

Spliff: /* Ubuntu */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and either scons and python2.5-dev or cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===

<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread1.40-dev libboost-regex1.40-dev libboost-system1.40-dev \
libboost-program-options1.40-dev libboost-signals1.40-dev
</pre></code>

Alternatively, you can try
<code><pre>
sudo apt-get build-dep spring
</pre></code>

and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
cmake .
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>/usr</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=/usr .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

== Using Scons ==
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

 
{{Finalizing_linux_install}}

 
{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Building Spring on Linux

2011-02-21T04:18:28Z

Spliff: /* Ubuntu */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and either scons and python2.5-dev or cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===

<code><pre>
apt-get install build-essential cmake cmake-gui git libglew-dev libsdl-dev \
libdevil-dev libopenal-dev libogg-dev libvorbis-dev libfreetype6-dev \
p7zip-full libxcursor-dev libboost-thread1.40-dev libboost-regex1.40-dev \
libboost-program-options1.40-dev libboost-signals1.40-dev \
libboost-system1.40-dev
</pre></code>

Alternatively, you can try
<code><pre>
sudo apt-get build-dep spring
</pre></code>

and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
cmake .
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>/usr</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=/usr .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

== Using Scons ==
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

 
{{Finalizing_linux_install}}

 
{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Building Spring on Linux

2011-02-21T04:17:28Z

Spliff: /* Ubuntu */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and either scons and python2.5-dev or cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===

<code><pre>
apt-get install build-essential cmake cmake-gui git libglew-dev libsdl-dev \
libdevil-dev libopenal-dev libogg-dev libvorbis-dev libfreetype6-dev \
p7zip-full libboost-thread1.40-dev libboost-regex1.40-dev \
libboost-program-options1.40-dev libboost-signals1.40-dev \
libboost-system1.40-dev
</pre></code>

Alternatively, you can try
<code><pre>
sudo apt-get build-dep spring
</pre></code>

and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
cmake .
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>/usr</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=/usr .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

== Using Scons ==
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

 
{{Finalizing_linux_install}}

 
{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

FAQ:trouble

2010-10-07T11:23:04Z

Spliff: Updated driconf details

[[Category:FAQ]]

=Troubleshooting=

==Network: My buddy can not connect to a game I've opened. What can we do?==
The engine uses UDP port 8452 by default, which can be changed in the lobby. If you are behind a router, and are having problems hosting, try forwarding the correct port and also make sure the firewall is not blocking it. If you do not know what a port or a firewall is, use a relay host instead: when hosting a game, tick the check-box labeled "Use relayhost".

Note that Spring engine will not connect to already running game, even if lobby client allows it.

==Graphics: I am having really bad framerates (fps) on my dual core! What am I doing wrong?==
This error is sometimes reported by people having multicore-CPUs. To solve this, you could try to restrict it to run on one core. Download the file from http://www.robpol86.com/pages/imagecfg.php follow the instructions, and force the spring exe file (spring.exe) to run on one core.

Installing the latest processor drivers and Windows hotfixes for your system may also help.

Also you may try multithreaded version of Spring, which can be downloaded from [[OtherDownloads|here]].

==Graphics: I am having really bad framerates (fps) on my brand new nVidia graphics card! What am I doing wrong?==
Turn off 'threaded optimizations' for Spring in the nVidia control panel.

==Graphics: I use an ATI or Intel graphic card on Linux with Open-Source drivers, and the map is all white! Is there a solution?==
Due to patents S3TC texture support is disabled by default. To enable it you need the tool driconf (note, you no longer require libdxtn):

<code>
$ sudo apt-get install libgl1-mesa-dev driconf 
$ driconf 
</code>

On the "Image Quality" tab activate "Enable S3TC texture compression even if software support is not available".

[http://springrts.com/phpbb/viewtopic.php?f=20&t=20809 Related forum thread].

==Graphics: I've got the most recent drivers and the game crashes in atioglxx.dll...?==
As of Spring 0.80.5, use only basic or dynamic water. Bump water with disabled shore waves should also work. Reflective or refractive water will make the game crash after 15-20 minutes due to a memory leak.

Spring 0.81.2 and/or Catalyst 10.2 drivers should fix this problem.

==Graphics: I've got a notebook and official AMD ATI drivers refuse to install, what to do?==
Use [http://www.driverheaven.net/modtool.php ATI Mobility Modder] or unofficial drivers - DNA or Omega. Use [http://google.com Google] or get them from [http://downloads.guru3d.com/Videocards----ATI-Catalyst-(Modified)_c24.html guru3d].

==Graphics: UI disapears after 5-10 mins of play on old ATI videocards==
In cmdcolors.txt, simply comment out or remove the following lines:
stipplePattern 0xffcc
stippleFactor 1
stippleSpeed 1.0
The problem detected on:
* ATI Radeon X3200 with latest drivers ([http://springrts.com/phpbb/viewtopic.php?f=11&t=20817 ref])
* ATI Radeon 9500 with Omega drivers 3.8.442 ([http://springrts.com/phpbb/viewtopic.php?f=11&t=23526 ref])

==Graphics: How to Alt-Tab out of full-screen on Linux?==
Play windowed with ''/grabinput'', or [http://springrts.com/phpbb/viewtopic.php?p=449972#p449972 use devilspie].

==Sound: I am having sound problems under Linux! What can i do?==
In more then 90% of the cases, this is caused by pulseaudio. You can safely remove pulseaudio from your system. To do this, open your favorite package manager (eg. Synaptic under Ubuntu), and search for packages with "pulse" in their name. From these, keep only the ones whichs name starts with "lib", and remove all others.

==Misc: I have a problem that is not described here! What can i do?==
There is a number of things you can do, among these are:
* Search in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum], and ask if you can not find a suiting topic.
* Look at the [[Gentoo_install#Linux_specific_Troubleshooting|Linux only FAQ]].
* Ask for help in the lobby in a suiting channel, eg: #springlobby, #de, #fr, #ai, #main
* Ask the FAQ-Bot in the lobby in channel #springlobby. To get a list of topics, write ''!faqlist'' and then use ''!faq <topic-name>'' to get the help text. For example, try ''!faq rename''.

Building Spring on Windows

2010-09-15T10:18:13Z

Spliff: Added details on tools and libraries file mirror

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}
{{#css:
code * {margin:inherit;}
}}
= Get the Source Code =
{{Obtaining_The_Source_Code}}

= Essential Tools and Libraries =
If you are new to programming for open-source projects on Windows you'll quickly discover it can often be difficult to find the right software and dependencies. To aid you in your journey you will find stable versions of most of the tools and libraries listed below on [http://www.warriorhut.org/spring this mirror]. Use them if you have trouble finding what you need below.

If you have trouble opening any of the archives please install the application 7zip as it supports all of the archive formats in common use (it's in the tools/archiving subdirectory).

= Compiling on Windows =
For other platforms see [[Building spring]].

==Install MinGW==
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

===Getting MinGW===
Compiling Spring in MinGW requires GCC 4.x
There are 2 different packages the official one and the TDM (experimental) builds.
====Official 4.4.0 (recommended)====
(Note: you can't override an existing old TDM enviroment with these, you first have to uninstall TDM, else you will get some "undefined ... SJLJ_xyz" linking errors!)

Get it here: [http://sourceforge.net/projects/mingw/files/ official MinGW]

You have to get MinGW as a bunch of separate packages, as the downloader does not support installing gcc 4.4.0 yet, which is needed to compile spring successfully.

minimum packages:
* MinGW Runtime - ''mingwrt (dev & dll. - version 3.17 recommended, 3.18+ will cause a "multiple definition of _tls_used" linker error)''
* MinGW API for MS-Windows - ''w32api (dev)''
* GNU Binutils - ''binutils (bin)''
* GCC 4 - ''gcc-core (bin & dll)''
* GCC 4 - ''gcc-c++ (bin & dll)''
* GCC 4 - ''pthreads (dll)''
* GCC 4 - ''mpfr (dll)''
* GCC 4 - ''gmp (dll)''
instead of the five above mentioned GCC packages (17MB), you could also get it in a single archive instead (60MB):
* GCC 4 - ''full (bin)''
if you do not have an other make system in place, get this in addition:
* GNU Make - ''mingw32-make''
if you want to debug, you will want this as well:
* GNU Source-Level Debugger - ''gdb (version 6.8-3 or later)''
Extract all the packages to a common dir, eg. ''C:/MinGW/'', and then the environment vars:
* <code>''MINGDIR=C:/MinGW''</code>
* <code>''PATH=%PATH%;%MINGDIR%\bin''</code>

You also need some Spring dependencies, prepackaged in the '''mingwlibs''' archive.

You can get it here ('''Download Source''' button, or use ''git''):
* [http://github.com/spring/mingwlibs/tree/boost_1.42.0_mingw_4.4.2 '''mingwlibs''' for MinGW GCC 4.4 or newer]
* [http://github.com/spring/mingwlibs '''mingwlibs''' for MinGW GCC 4.3 or older]
(Note: TDM builds need a different package!)

====TDM Builds (alternative)====
Get it here: [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Get at least the following packages:
* mingw-runtime
* core
* c++
* binutils
* win32api
In the case you use the old SJLJ exception handling you need this: [http://jobjol.nl/1102 v19 of the MinGW library package].
If you use the new Dwarf2 handling use the mingwlibs package for the official GCC from above.

... or get aegis "portable" TDM mingw 4.4.1 from [http://aegis.eat-peet.net/MinGW.7z here]. Just extract it to ''C:/''.

===MinGW Setup===
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''MINGDIR'' option to CMake in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.
*[http://www.cmake.org/files/v2.6/cmake-2.6.2-win32-x86.exe CMake 2.6 installer]

= Compiling with cmake =
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* run the <code>''cmake-gui''</code> and select a source and a build directory
* configure and follow the instructions, and adjust variables to your needs (defaults are OK)
* press '''Generate'''
* open a console (''cmd.exe''), ''cd'' into your build directory, and run: <code>''mingw32-make install-spring''</code>

=Compiling with scons=
Install the following programs (you don'T need cmake in this case):
*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]

==Quick instructions==
* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=Visual Studio 8 (2005)=
(possibly the free Express Edition)

* Install the [http://cloud.github.com/downloads/spring/spring/spring-vc8libs-v5.7z vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories.
** Note that the most recent version of Platform SDK is called [http://www.microsoft.com/downloads/details.aspx?FamilyID=c17ba869-9671-4330-a63e-1fd44e0e2505&displaylang=en Windows SDK].
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

== Errors ==
* ...\Windows\v6.0A\include\shlwapi.h(196) : error C2061: syntax error : identifier 'PCUITEMID_CHILD' - wrong version of Platform SDK is used; go to Tools >> Options >> >> Projects and Solutions >> VC++ Directories and move the one that's causing this problem all the way down.

=Visual Studio 9 (2008)=
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

or update your Visual Studio using your Windows Update.

For the rest the Visual Studio 8 instructions should apply, mostly. You probably won't need to add Windows SDK path references as they should be present by default.

You need the [http://cloud.github.com/downloads/spring/spring/spring-vc9libs-v4.7z vclibs for VS2008], and not the ones for Visual Studio 2005. The installation procedure is the same though.

Be aware that the project file isn't updated nearly as frequently as it should, so it's best to use the .vcproj file from VS8 build and VS2008 will automatically update it.

=General Visual Studio Notes=
So far the following aspects of Spring don't function properly or don't function at all when compiled with Visual Studio:
*Your VS build won't sync with GCC builds in multiplayer mode (currently being worked on)
*Any external AI crashes immediatley at start, LUA AI works though
[[Category:Compiling]]

Lua UnsyncedCtrl

2009-10-07T09:44:38Z

Spliff: explained (needs ModUICtrl)

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

NOTE: Entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users springsettings.cfg. It is enabled by default so you generally don't need to care.

= UI =
'''Spring.SetLastMessagePosition'''
( number x, number y, number z ) -> nil

= Ingame Console =
'''Spring.Echo'''
( arg1 [, arg2 [, ... ] ] ) -> nil

Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

'''Spring.SendCommands''' (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil

== GUI ==
'''Spring.SetActiveCommand''' (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
'''Spring.ForceLayoutUpdate''' (needs ModUICtrl)
( ) -> nil
'''Spring.SetDrawSelectionInfo''' disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil

== Mouse ==
'''Spring.SetMouseCursor''' (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
'''Spring.WarpMouse''' (needs ModUICtrl)
( number x, number y ) -> nil

== LOS Colors ==
'''Spring.SetLosViewColors''' (needs ModUICtrl)
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil

== SendMessage ==
'''Spring.SendMessage'''
( string "message" ) -> nil
'''Spring.SendMessageToPlayer'''
( number playerID, string "message" ) -> nil
'''Spring.SendMessageToTeam'''
( number teamID, string "message" ) -> nil
'''Spring.SendMessageToAllyTeam'''
( number allyID, string "message" ) -> nil
'''Spring.SendMessageToSpectators'''
( string "message" ) -> nil

== Markers ==
'''Spring.MarkerAddPoint''' (needs ModUICtrl)
( number x, number y, number z [, string text = ""] ) -> nil
'''Spring.MarkerAddLine''' (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
'''Spring.MarkerErasePosition''' (needs ModUICtrl)
( number x, number y, number z ) -> nil

= Sounds =
'''Spring.PlaySoundFile'''
( string "soundfile" [, number volume
[, number x, number y, number z ] ] ) -> nil | boolean
Plays WAV or OGG sounds. By default, the soundfile is expected to be in the "Sounds" folder.
'''Spring.PlaySoundStream'''
( string "oggfile" [, number volume = 1.0
[, number x, number y, number z ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. Note: you may only play _ONE_ stream at a time. If another stream is playing and you try to start a second one the call will fail, and silence will result. 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream is running. Since only one may play at any time (see above), this can be used as an interrupt.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

'''Spring.SendLuaUIMsg''' (needs ModUICtrl)
( string message, string mode ) -> nil
possible modes are: "s"/"specs" & "a"/"allies"
'''Spring.SendLuaGaiaMsg''' (needs ModUICtrl)
( string message ) -> nil
'''Spring.SendLuaRulesMsg''' (needs ModUICtrl)
( string message ) -> nil

= Units =
== Unit Selection ==
'''Spring.SelectUnitMap'''
( { [unitID] = anything, ...} [,boolean append] ) -> nil
'''Spring.SelectUnitArray'''
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil

'''Spring.GetDrawSelectionInfo'''
( boolean drawSelectionInfo ) -> nil

== Unit Group ==
'''Spring.SetUnitGroup''' (needs ModUICtrl)
( number unitID, number groupID ) -> nil

== Give Order ==
'''Spring.GiveOrder''' gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnit''' (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitMap''' (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitMap''' (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true

'''Spring.SetBuildFacing'''
( int Facing ) -> nil

'''Spring.SetBuildSpacing'''
( int Spacing ) -> nil

== Unit NoDraw,NoSelect,NoMinimap ==
'''Spring.SetUnitNoDraw''' LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
'''Spring.SetUnitNoSelect''' LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
'''Spring.SetUnitNoMinimap''' LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil

= GUI =
'''Spring.SetDrawSky'''
( boolean drawSky ) -> nil
'''Spring.SetDrawWater'''
( boolean drawWater ) -> nil
'''Spring.SetDrawGround'''
( boolean drawGround ) -> nil

'''Spring.DrawUnitCommands'''
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil

'''Spring.SetTeamColor'''
( number teamID, number r, number g, number b ) -> nil

'''Spring.AssignMouseCursor''' default hotspot is center!
( string "cmdName", string "iconFileName"
[, boolean overwrite [, boolean hotSpotTopLeft] ] ) -> nil | boolean
'''Spring.ReplaceMouseCursor''' default hotspot is center!
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft] ) -> nil | boolean

'''Spring.SetCustomCommandDrawData''' register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdIconID | string iconname | nil,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil | true

= Sharing =
'''Spring.SetShareLevel''' note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
'''Spring.ShareResources''' (needs ModUICtrl)
( number teamID, string "units" ) -> nil
( number teamID, string "metal" | "energy", number amount ) -> nil

= UnitDef RadarIcons & BuildPics =
'''Spring.AddUnitIcon''' (needs ModUICtrl)
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] ) -> nil | boolean
'''Spring.FreeUnitIcon''' (needs ModUICtrl)
( string iconName ) -> nil | boolean
'''Spring.SetUnitDefIcon''' (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
'''Spring.SetUnitDefImage''' (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil

= Camera =
'''Spring.SetCameraState'''
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState.

'''Spring.SetCameraTarget'''
( number x, number z, number y [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

'''Spring.SetCameraOffset''' (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil

= (Virtual-)FileSystem =
'''Spring.ExtractModArchiveFile'''
( string modfile ) -> boolean
'''Spring.CreateDir''' (needs ModUICtrl)
( number path ) -> nil | boolean

= Engine Config =
The following functions read the engine configs saved in .springrc, springsettings.cfg or what ever your os prefers.

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value ) -> nil

= Make Font =
'''Spring.MakeFont''' (needs ModUICtrl)
( [string inputFile], table options ) -> nil | boolean
options = {
outName = string,
inData = string,
height = number,
texWidth = number,
minChar = number,
maxChar = number,
outlineMode = number,
outlineRadius = number,
outlineWeight = number,
padding = number,
stuffing = number,
debug = number,
}

= World Primitives =
outdated! use opengl api instead!

'''Spring.AddWorldIcon'''
( number cmdID, number x, number y, number z ) -> nil
'''Spring.AddWorldText'''
( string "text", number x, number y, number z ) -> nil
'''Spring.AddWorldUnit'''
( number unitDefID,
number x, number y, number z,
number team, number facing) -> nil

= Misc =

'''Spring.Restart''' (0.79+)
( string commandline_args, string startscript ) -> if this call returns, something went wrong
commandline_args are commandline arguments passed to spring executable

startscript is the CONTENT of the script.txt spring should use to start (if empty, no startscript is added, you can still point spring to your custom script.txt when you add the filepath to commandline_args

Lua SyncedRead

2009-09-19T17:09:39Z

Spliff: /* Ground Informations */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

== Game ==
=== Special TeamID Variables ===
(those special TeamIDs are not supported by all functions) 
'''Spring.ALL_UNITS''' 
'''Spring.MY_UNITS''' 
'''Spring.ALLY_UNITS''' 
'''Spring.ENEMY_UNITS'''

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

=== GameStates ===
'''Spring.IsGodModeEnabled'''
( ) -> boolean
'''Spring.IsCheatingEnabled'''
( ) -> boolean
'''Spring.IsDevLuaEnabled'''
( ) -> boolean
'''Spring.IsEditDefsEnabled'''
( ) -> boolean
'''Spring.AreHelperAIsEnabled'''
( ) -> boolean
'''Spring.FixedAllies'''
( ) -> nil | boolean

'''Spring.IsGameOver'''
( ) -> boolean

=== Rules ===
Those functions allow to save data per Game,Team and Unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
'''Spring.GetRulesInfoMap'''
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number index | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> { [rule1] = number value1, [rule2] = number value2, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [rule1] = number value1, [rule2] = number value2, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [rule1] = number value1, [rule2] = number value2, ... }

=== Mod-/Map-Options ===
'''Spring.GetModOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }
'''Spring.GetMapOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

=== Vectors ===
'''Spring.GetWind'''
( ) -> number dirX, number dirY, number dirZ,
number strength, number normDirX, number normDirY, number normDirZ

'''Spring.GetHeadingFromVector'''
( number x, number z ) -> number heading
'''Spring.GetVectorFromHeading'''
( number heading ) -> number x, number z

== Sides/Factions ==
'''Spring.GetSideData'''
( string sideName ) -> nil | string startUnit, string caseSensitiveSideName
( number sideID ) -> nil | string sideName, string startUnit, string caseSensitiveSideName
( ) -> { [1] = { sideName=string,caseName=string,startUnit=string}, [2] = .., .. }

== Teams ==
=== StartBoxes/StartPositions ===
'''Spring.GetAllyTeamStartBox'''
( number allyID ) -> nil | number xmin, number zmin, number xmax, number zmax
'''Spring.GetTeamStartPosition'''
( number teamID ) -> nil | number x, number y, number z

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

'''Spring.GetPlayerInfo'''
( number playerID ) ->
nil | string "name", (in synced code this is "SYNCED_NONAME"!)
boolean active,
boolean spectator,
number teamID,
number allyTeamID,
number pingTime,
number cpuUsage,
string country,
number rank
table customPlayerKeys
'''Spring.GetPlayerControlledUnit'''
( number playerID ) -> nil | number unitID

'''Spring.GetAllyTeamInfo'''
( number allyteamID ) -> nil | table customTeamKeys

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamNum,
number leader,
boolean isDead,
boolean isAiTeam,
string "side",
number allyTeam
table customTeamKeys
'''Spring.GetTeamResources'''
( number teamID, string "metal" | "energy" ) ->
nil | number currentLevel,
number storage,
number pull,
number income,
number expense,
number share,
number sent,
number received
'''Spring.GetTeamUnitStats'''
( number teamID ) ->
nil | number killed,
number died,
number capturedBy,
number capturedFrom,
number received,
number sent
'''Spring.GetTeamStatsHistory'''
( number teamID, number startTime, number endTime ) ->
{
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}
'''Spring.GetTeamLuaAI'''
( number teamID ) -> string "luaAI"

=== Teams/PlayersAllied ===
'''Spring.AreTeamsAllied'''
( number teamID1, number teamID2 ) -> nil | boolean
'''Spring.ArePlayersAllied'''
( number playerID1, number playerID2 ) -> nil | boolean

== Units ==
=== GetUnits ===
'''Spring.GetAllUnits'''
( ) -> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetTeamUnits'''
( number teamID ) -> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitsSorted'''
( number teamID ) -> nil |
unitDefTable = {
[number unitDefID] = { [1] = [number unitID], etc... },
etc...
}
'''Spring.GetTeamUnitsCounts'''
( number teamID ) -> nil | countTable = { [number unitDefID] = count, etc... }
'''Spring.GetTeamUnitsByDefs'''
( number teamID, number unitDefID | { number unitDefID1, ... } )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitDefCount'''
( number teamID, number unitDefID ) -> nil | number count
'''Spring.GetTeamUnitCount'''
( number teamID ) -> nil | number count

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }

plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0


'''Spring.GetUnitNearestAlly'''
( number unitID [, number range ] ) -> nil | number unitID
'''Spring.GetUnitNearestEnemy'''
( number unitID [, number range [, bool useLOS]] ) -> nil | number unitID

=== Unit Informations ===
'''Spring.ValidUnitID'''
( number unitID ) -> boolean
'''Spring.GetUnitIsDead'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitTooltip'''
( number unitID ) -> nil | string tooltip
'''Spring.GetUnitDefID'''
( number unitID ) -> nil | number unitDefID
'''Spring.GetUnitTeam'''
( number unitID ) -> nil | number teamID
'''Spring.GetUnitAllyTeam'''
( number unitID ) -> nil | number allyID
'''Spring.GetUnitLineage'''
( number unitID ) -> nil | number lineage | number lineage, boolean lineageIsRoot
'''Spring.GetUnitNeutral'''
( number unitID ) -> nil | boolean neutral
'''Spring.GetUnitHealth'''
( number unitID ) -> nil | number health, number maxHealth, number paralyzeDamage,
number captureProgress, number buildProgress
'''Spring.GetUnitArmored'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
returns the center position of the unit (midpos).

'''Spring.GetUnitBasePosition'''
( number unitID ) -> nil | number x, number y, number z
returns the bottom of the unit.

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
possible types are: airLos, radar, sonar, seismic, radarJammer & sonarJammer
'''Spring.GetUnitLosState''' raw is only available in gadgets
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' (returns the distance of 2 units)
( number unitID1, number unitID2 [, boolean 2D ] ) -> nil | number distance
'''Spring.GetUnitDefDimensions'''
( number unitDefID ) -> nil |
{
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}
'''Spring.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame,
number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
tag can be:
"reloadState" | "reloadTime" | "accuracy" | "sprayAngle" |
"range" | "projectileSpeed" | "burst" | "burstRate" | "projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
Returns piece position in unit space

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
Broken (returns reverse direction in piece space for pieces with >= 2 vertices, and returns (1,1,1) for pieces with < 2 vertices)

'''Spring.GetUnitPieceMatrix'''
( number unitID, number piece ) -> { [1] = number, ... , [16] = number }
'''Spring.GetUnitPieceList'''
( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }
'''Spring.GetUnitPieceMap'''
( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }
'''Spring.GetUnitPieceInfo'''
( number unitID, number piece ) -> {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
}
'''Spring.GetUnitScriptPiece'''
( number unitID [, number scriptPiece ] )
-> nil | { scriptPieceNum = number modelPieceNum } | number modelPieceNum

This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get via Cob2Lua a pieceID you have to translate it with this function. Btw the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized.

=== CommandQueues ===

'''Spring.GetUnitCommands'''
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean
}
}, ...
}

'''Spring.GetCommandQueue''' (same as Spring.GetUnitCommands)
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' (cleans the buildqueue of things the unit can't build itself)
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean
}
}, ...
}
'''Spring.GetFactoryCounts''' (used to get the buildqueue of a factory, seems screwed o_O)
( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
[2] = { [number unitDefID | number -cmdID] = number count }, ...
}

=== Command Descriptions/Buttons ===
'''Spring.GetUnitCmdDescs'''
( number unitID [, number startIndex [, number endIndex ] ] ) -> nil | {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}
'''Spring.FindUnitCmdDesc'''
( number unitID, number cmdID ) -> nil | number index

== Features ==
=== GetFeatures ===
'''Spring.GetFeaturesInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }
'''Spring.GetFeatureList''' NOTE: this is not really required, now all FeatureDefs are pre-loaded

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
=== Ground Informations ===
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundNormal'''
( number x, number z ) -> number x, number y, number z
'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

=== Test Building ===
'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != 0 then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos'''
( number unitDefID, number x, number y, number z ) -> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilePosition'''
( number projectileID ) --> px, py, pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) --> vx, vy, vz

Lua SyncedRead

2009-09-19T17:08:43Z

Spliff: /* Ground Informations */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

== Game ==
=== Special TeamID Variables ===
(those special TeamIDs are not supported by all functions) 
'''Spring.ALL_UNITS''' 
'''Spring.MY_UNITS''' 
'''Spring.ALLY_UNITS''' 
'''Spring.ENEMY_UNITS'''

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

=== GameStates ===
'''Spring.IsGodModeEnabled'''
( ) -> boolean
'''Spring.IsCheatingEnabled'''
( ) -> boolean
'''Spring.IsDevLuaEnabled'''
( ) -> boolean
'''Spring.IsEditDefsEnabled'''
( ) -> boolean
'''Spring.AreHelperAIsEnabled'''
( ) -> boolean
'''Spring.FixedAllies'''
( ) -> nil | boolean

'''Spring.IsGameOver'''
( ) -> boolean

=== Rules ===
Those functions allow to save data per Game,Team and Unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
'''Spring.GetRulesInfoMap'''
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number index | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> { [rule1] = number value1, [rule2] = number value2, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [rule1] = number value1, [rule2] = number value2, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [rule1] = number value1, [rule2] = number value2, ... }

=== Mod-/Map-Options ===
'''Spring.GetModOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }
'''Spring.GetMapOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

=== Vectors ===
'''Spring.GetWind'''
( ) -> number dirX, number dirY, number dirZ,
number strength, number normDirX, number normDirY, number normDirZ

'''Spring.GetHeadingFromVector'''
( number x, number z ) -> number heading
'''Spring.GetVectorFromHeading'''
( number heading ) -> number x, number z

== Sides/Factions ==
'''Spring.GetSideData'''
( string sideName ) -> nil | string startUnit, string caseSensitiveSideName
( number sideID ) -> nil | string sideName, string startUnit, string caseSensitiveSideName
( ) -> { [1] = { sideName=string,caseName=string,startUnit=string}, [2] = .., .. }

== Teams ==
=== StartBoxes/StartPositions ===
'''Spring.GetAllyTeamStartBox'''
( number allyID ) -> nil | number xmin, number zmin, number xmax, number zmax
'''Spring.GetTeamStartPosition'''
( number teamID ) -> nil | number x, number y, number z

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

'''Spring.GetPlayerInfo'''
( number playerID ) ->
nil | string "name", (in synced code this is "SYNCED_NONAME"!)
boolean active,
boolean spectator,
number teamID,
number allyTeamID,
number pingTime,
number cpuUsage,
string country,
number rank
table customPlayerKeys
'''Spring.GetPlayerControlledUnit'''
( number playerID ) -> nil | number unitID

'''Spring.GetAllyTeamInfo'''
( number allyteamID ) -> nil | table customTeamKeys

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamNum,
number leader,
boolean isDead,
boolean isAiTeam,
string "side",
number allyTeam
table customTeamKeys
'''Spring.GetTeamResources'''
( number teamID, string "metal" | "energy" ) ->
nil | number currentLevel,
number storage,
number pull,
number income,
number expense,
number share,
number sent,
number received
'''Spring.GetTeamUnitStats'''
( number teamID ) ->
nil | number killed,
number died,
number capturedBy,
number capturedFrom,
number received,
number sent
'''Spring.GetTeamStatsHistory'''
( number teamID, number startTime, number endTime ) ->
{
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}
'''Spring.GetTeamLuaAI'''
( number teamID ) -> string "luaAI"

=== Teams/PlayersAllied ===
'''Spring.AreTeamsAllied'''
( number teamID1, number teamID2 ) -> nil | boolean
'''Spring.ArePlayersAllied'''
( number playerID1, number playerID2 ) -> nil | boolean

== Units ==
=== GetUnits ===
'''Spring.GetAllUnits'''
( ) -> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetTeamUnits'''
( number teamID ) -> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitsSorted'''
( number teamID ) -> nil |
unitDefTable = {
[number unitDefID] = { [1] = [number unitID], etc... },
etc...
}
'''Spring.GetTeamUnitsCounts'''
( number teamID ) -> nil | countTable = { [number unitDefID] = count, etc... }
'''Spring.GetTeamUnitsByDefs'''
( number teamID, number unitDefID | { number unitDefID1, ... } )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitDefCount'''
( number teamID, number unitDefID ) -> nil | number count
'''Spring.GetTeamUnitCount'''
( number teamID ) -> nil | number count

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }

plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0


'''Spring.GetUnitNearestAlly'''
( number unitID [, number range ] ) -> nil | number unitID
'''Spring.GetUnitNearestEnemy'''
( number unitID [, number range [, bool useLOS]] ) -> nil | number unitID

=== Unit Informations ===
'''Spring.ValidUnitID'''
( number unitID ) -> boolean
'''Spring.GetUnitIsDead'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitTooltip'''
( number unitID ) -> nil | string tooltip
'''Spring.GetUnitDefID'''
( number unitID ) -> nil | number unitDefID
'''Spring.GetUnitTeam'''
( number unitID ) -> nil | number teamID
'''Spring.GetUnitAllyTeam'''
( number unitID ) -> nil | number allyID
'''Spring.GetUnitLineage'''
( number unitID ) -> nil | number lineage | number lineage, boolean lineageIsRoot
'''Spring.GetUnitNeutral'''
( number unitID ) -> nil | boolean neutral
'''Spring.GetUnitHealth'''
( number unitID ) -> nil | number health, number maxHealth, number paralyzeDamage,
number captureProgress, number buildProgress
'''Spring.GetUnitArmored'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
returns the center position of the unit (midpos).

'''Spring.GetUnitBasePosition'''
( number unitID ) -> nil | number x, number y, number z
returns the bottom of the unit.

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
possible types are: airLos, radar, sonar, seismic, radarJammer & sonarJammer
'''Spring.GetUnitLosState''' raw is only available in gadgets
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' (returns the distance of 2 units)
( number unitID1, number unitID2 [, boolean 2D ] ) -> nil | number distance
'''Spring.GetUnitDefDimensions'''
( number unitDefID ) -> nil |
{
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}
'''Spring.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame,
number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
tag can be:
"reloadState" | "reloadTime" | "accuracy" | "sprayAngle" |
"range" | "projectileSpeed" | "burst" | "burstRate" | "projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
Returns piece position in unit space

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
Broken (returns reverse direction in piece space for pieces with >= 2 vertices, and returns (1,1,1) for pieces with < 2 vertices)

'''Spring.GetUnitPieceMatrix'''
( number unitID, number piece ) -> { [1] = number, ... , [16] = number }
'''Spring.GetUnitPieceList'''
( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }
'''Spring.GetUnitPieceMap'''
( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }
'''Spring.GetUnitPieceInfo'''
( number unitID, number piece ) -> {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
}
'''Spring.GetUnitScriptPiece'''
( number unitID [, number scriptPiece ] )
-> nil | { scriptPieceNum = number modelPieceNum } | number modelPieceNum

This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get via Cob2Lua a pieceID you have to translate it with this function. Btw the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized.

=== CommandQueues ===

'''Spring.GetUnitCommands'''
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean
}
}, ...
}

'''Spring.GetCommandQueue''' (same as Spring.GetUnitCommands)
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' (cleans the buildqueue of things the unit can't build itself)
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean
}
}, ...
}
'''Spring.GetFactoryCounts''' (used to get the buildqueue of a factory, seems screwed o_O)
( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
[2] = { [number unitDefID | number -cmdID] = number count }, ...
}

=== Command Descriptions/Buttons ===
'''Spring.GetUnitCmdDescs'''
( number unitID [, number startIndex [, number endIndex ] ] ) -> nil | {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}
'''Spring.FindUnitCmdDesc'''
( number unitID, number cmdID ) -> nil | number index

== Features ==
=== GetFeatures ===
'''Spring.GetFeaturesInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }
'''Spring.GetFeatureList''' NOTE: this is not really required, now all FeatureDefs are pre-loaded

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
=== Ground Informations ===
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundNormal'''
( number x, number z ) -> number x, number y, number z
'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

=== Test Building ===
'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != 0 then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos'''
( number unitDefID, number x, number y, number z ) -> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilePosition'''
( number projectileID ) --> px, py, pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) --> vx, vy, vz

Troubleshooting linux

2009-02-14T02:19:24Z

Spliff: added advice to run cmake twice

= Troubleshooting =

== Ingame ==

=== LuaUI Crash Ingame ===

This issue is caused by a memory corruption bug in spring. It will be fixed in version after 0.76b1. Ubuntu packages include the fix. '''Workaround: disable ground decals.'''

LuaUI can crash during game, because some lua script you use has a bug. 0.75 should be resistant to this problem, but 0.74b3 is not. After crash, you won't see the bottom left tooltip box and top right resource bar anymore. Fear not, help is near:

<code><pre>
/resbar 1
/tooltip 1
</pre></code>

These might not be necessary in 0.75 anymore at all.

Also, you won't be able to change the build menu page with mouse anymore, but keys , and . do the trick.

LuaUI can also be restarted after it crashed. Often this does the trick and it works fine the rest of the game:

<code><pre>
/luaui reload
</pre></code>

=== Mouse is slow in fullscreen mode ===

Run:
<code><pre>
echo '# Slow fullscreen cursor fix for Spring' >> ~/.xsessionrc
echo 'SDL_MOUSE_RELATIVE=0' >> ~/.xsessionrc
echo 'export SDL_MOUSE_RELATIVE' >> ~/.xsessionrc
</pre></code>
And log out and log in again.

The mouse should now be as fast as in windowed mode.

=== Rotating Buildings Ingame ===

You can rotate a building before you give the build order, but the keys that do this don't work in linux by default for some users. Issue the following commands in the beginning of the game:

<code><pre>
/bind keycodex buildfacing inc
/bind keycodey buildfacing dec
</pre></code>

Keycodex and keycodey above are just placeholders. What you want to write depends on which key you want to use. To see what keycodes any keys have, do:

<code><pre>
/keydebug yes
</pre></code>

And then hit the keys you want to use, and spring prints the keycodes in the message buffer.

TODO: add information on how to save the settings so that they work the next time you start spring.

=== Map is White ===

If the whole map is only shades of white and grey, there is a problem with your display driver. Maybe your gpu is very old and does not support some needed opengl feature. For example I had this problem with matrox g550 but not with some very old geforce.

=== Sound is Choppy ===

If the engine sound is very broken or choppy sounding, and you hear some noise or crackling, you need to update OpenAL. Spring needs at least OpenAL Soft with version 1.6 to sound good, by this time all major distribution have it in their repository, so installing it should be easy (if it isn't installed by default).

== Startup ==

=== Missing Default Cursor ===

This or any similar error of not being able to find a specific file are usually because the mod you are using needs ota content, download & install as explained [[SetupGuide#OTA_Content|earlier in this document]].

=== sounds/button9.wav "cant find wav file" ===

Same problem as above.

=== could not open file: gamedata/defs.lua ===

Make sure your ~/spring does not contain an outdated version of base/springcontent.sdz because a new version of this file is distributed with spring.
If you do, just remove it.

=== Couldnt find matching GLX visual ===

Reduce anti aliasing.

=== GL_ARB_texture_compression not found ===

This can be an issue with your gpu drivers. The drivers you are using do not support a feature that is required to run spring. You might have better luck with the closed source official drivers of nvidia or amd cards. If your gpu itself is really old, this might not help.

Try to update your gfx drivers, either with the one from your distributions package-manager, of with the original one from your gfx vendor. Also be sure hardware acceleration is enabled, tutorials on how to do this can be found in most of the distributions forums / wikis / etc.

=== OpenAL Segfault ===

See -> Sound is Choppy.

=== Desync in game ===

If you start a network game with other players, and you get sync error messages in game, your lobby version may be too old. It does not support the new protocol so it does not set the options on spring correctly, and desyncs at game start.

== Compiletime ==

=== hpiutil2 error with cmake ===
make[1]: *** [rts/lib/CMakeFiles/hpiutil2.dir/all] Error 2
make: *** [all] Error 2

Run cmake TWICE. It doesn't always work properly on the first run.

=== invalid use of ILvoid / ALCvoid ===

During compiling, if you get a lot of the following errors:

<code><pre>
/usr/include/IL/il.h:497: error: '<anonymous>' has incomplete type
/usr/include/IL/il.h:497: error: invalid use of 'ILvoid'
</pre></code>

This happens because the version of libdevil-dev you have installed is not compatible with gcc version 4.2 and newer.

You should upgrade your libdevil-dev to fix this issue. However, in some distributions (at least gentoo), the fixed package has the SAME version number as the older unfixed package, so you might actually need to remove your current libdevil-dev package completely and reinstall it.

this is an issue that can be better hacked [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=9278 there]. while the packages aren't fixed for their maintainers, you will need to do nasty things, like that:

<code><pre>
//typedef void ALCvoid;
#define ALCvoid void
</pre></code>

== Network Setup ==

Usually you don't need to do any network setup whatsoever, because the lobbies take care of nat traversal with firewall hole punching, but if you need to know the topology, it goes like this:

Host needs to enable incoming udp to port 8452, and outgoing replies to those.
Non-host players need to enable outgoing udp, and incoming replies to those.
So basically only non-host players initiate "connections", and only the server listens on a well-known port.

== If You Still Have Problems ==

Join either IRC chat in #taspring on Freenode or #sy on QuakeNet, or ask for help in the lobby channels #sy or #springlobby.

However, generic linux problems not really related to installing this should be asked elsewhere.

Prepare to list your distribution, which installation method you used, and what exactly is the error. Don't ask if people are around or not, just go straight to business and tell all details, for maximizing your chances of getting help.

== IRC ==

# #taspring @ FreeNode
# #sy @ QuakeNet

== Asking For Help ==

Ok so you need human help. This is how '''NOT''' to do it:

<code><pre>
15:54 -!- **** [n=****@*] has joined #taspring
15:54 < ****> Hi, i have a problem with compiling spring on debian
15:54 < ****> can anyone help me?
15:57 -!- **** [n=****@*] has quit [Client Quit]
</pre></code>

Don't ask to ask, instead go straight to business by stating the exact problem you have, and giving all necessary information. What you were trying to achieve, how did you try to do it, what happened and what did you expect to happen.

Then WAIT for someone to notice you.

Building Spring Cross Compiled

2009-02-14T02:06:15Z

Spliff:

Cross-compiling allows you to build for other platforms than the machine you are building on. You can, for example, compile Windows 32-bit binaries on a Linux 64-bit machine.

= Obtaining the Source =

{{Obtaining_The_Source_Code}}

= CMake cross compiling =

== Setting up the cross compiler ==

I have only done this on Gentoo (instructions [http://en.gentoo-wiki.com/wiki/Crossdev here] or [http://psas.pdx.edu/GentooCrossCompilerHowto/ here]).

There is also a general cross-compiler for linux [http://www.profv.de/mingw_cross_env/ here]

== Getting Spring's libraries ==

'''If Win32 (mingw32) is your target:'''
Auswaschbar has helpfully uploaded all win32 dependencies [http://spring.jobjol.nl/show_file.php?id=1102 here]. Unpack with 7zip to a directory of your choice (or use the one I recommend below).

== Setting up your directories ==
Here is my recommended layout

<pre>
~/spring-xcompile/ (or wherever you want to put it all)
___ spring/ (the spring source)
___ win32/ (your target platform)
_______ build/ (the build files for your target will go here)
_______ final/ (the compiled binaries and libs will be installed here)
_______ libs/ (the target libraries you just downloaded, ie: mingw32libs_v13)
_______ win32.cmake (see below)
</pre>

== Create your cmake toolchain ==

* Create the toolchain file:

>> pico "~/spring-xcompile/win32/win32.cmake"

=== Example toolchain file ===
An example should be self-explanatory:
<pre>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

# the spring mingw32 dependencies
SET(MINGWLIBS ~/spring-xcompile/win32/libs)

# the path that make install will use to put the final binaries
SET(CMAKE_INSTALL_PREFIX ~/spring-xcompile/win32/final)
</pre>

Pass this with "-DCMAKE_TOOLCHAIN_FILE=~/spring-xcompile/win32/win32.cmake" to cmake or select it in the gui to make a cross-compilation (see below).

=== Some Options Explained ===
* MINGWLIBS: directory where the [http://spring.jobjol.nl/show_file.php?id=1102 MinGW library package] is (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

=== Further reference ===
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

== Run CMake ==

=== The GUI method ===
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

=== The commandline method ===

* cd to build directory

>> cd ~user/spring-xcompile/win32/build

* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>

* IMPORTANT: depending on your settings you may need to run this command twice. It can't hurt so I recommend doing it anyway.

>> cmake "~user/spring-xcompile/spring" "-DCMAKE_TOOLCHAIN_FILE=~user/spring-xcompile/win32/win32.cmake"

* run "make" and "make install"

>> make && make install DESTDIR=~user/spring-xcompile/win32/final

== Package Maintainers Note: ==
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

= SCons cross compiling =

configure:
<pre>
MINGDIR=/usr/i586-mingw32msvc \
MINGWLIBS=${MINGWLIBS_DIR} \
CC=i586-mingw32msvc-gcc \
CXX=i586-mingw32msvc-g++ \
scons configure platform=windows debug=DEBUG2 \
mingwlibsdir=${MINGWLIBS_DIR} \
builddir="${BUILD_DIR}" \
prefix="${INSTALL_DIR}" \
datadir="." \
bindir="." \
libdir="."
</pre>

make install:
<pre>
MINGDIR=/usr/i586-mingw32msvc \
CC=i586-mingw32msvc-gcc \
CXX=i586-mingw32msvc-g++ \
scons install \
builddir="${BUILD_DIR}"
</pre>

Building Spring on Linux

2009-02-14T02:03:38Z

Spliff: now using get source template

== Build From Source on Linux ==
For other platforms see [[Building spring|Building Spring]]

If prefer to use your distributions package system, refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning: You might encounter sync errors in online play if you are not using the exact same version of the compiler and same compiler settings as used for prebuilt packages! (Applies to GCC <4.0)'''

For 0.77b5 these are: TODO add them here.

<div style="clear:both"></div>

== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

== Get Dependencies ==

You will need to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this. The scons configure will whine if you forget something, but it does not check if you remembered to install zip, even though you still need it.

==== Debian ====

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
that Spring 0.77b5 depends on the boost libraries version 1.34.* and won't
work on lower versions. (updated libboost-serialization-dev, and libvorbis-dev dependencies for 0.76b1)

Also, on 64-bit be sure to build against devIl 1.6.8-rc2 or higher, 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install scons build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev libboost-dev
sudo aptitude install libboost-thread-dev libboost-regex-dev libdevil-dev
sudo aptitude install libboost-serialization-dev python2.5-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev
</pre></code>

==== Gentoo ====
This has been tested to work with a clean install of gentoo 2007.0:

<code><pre>
emerge dev-util/scons \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal =dev-lang/python-2.4\* media-libs/glew dev-libs/boost
emerge media-libs/devil app-arch/zip media-libs/libogg
</pre></code>

==== Fedora ====

On Fedora 8, these dependencies should be sufficient:

<code><pre>
yum install scons boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel java-1.7.0-icedtea-devel libvorbis-devel
</pre></code>

Fedora 9 has issues with 0.76b1, because it uses GCC 4.3 which changed a few compilation warnings into errors. However, the [http://spring.clan-sy.com/phpbb/viewtopic.php?f=20&t=12802 inofficial Linux installer] may work for you (it installs a precompiled binary).

== Build And Install ==

The build will spew out warnings like the following, which you can safely ignore:

<code><pre>
warning: division by zero
warning: 'q' may be used uninitialized in this function
</pre></code>
==== Using Scons ====
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

=== Using CMake (2.6 or newer) ===
Configure and build:

<code><pre>
cmake .
make
</pre></code>

Install:

<code><pre>
make install
</pre></code>

Your paths are: Spring executable in <code>/usr/local/games/spring</code> and
read-only data in <code>/usr/local/share/games/spring</code>.

{{Finalizing_linux_install}}

{{Linux_tips}}

{{Troubleshooting_linux}}

Building spring

2009-02-14T02:00:02Z

Spliff: getting source info changed to a template

=Building Spring=

== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

== Compiling ==
* [[Building Spring on Windows|Windows]]
* [[Building Spring on Linux|Linux]]
* [[Building Spring on MacOSX|MacOSX]]
* [[Building Spring Cross Compiled|Cross-compiler]]
* [[Building Spring on Buildbot|Buildbot]].

If you are using Linux and prefer to use your distributions package system, refer to the Linux [[SetupGuide]].

[[Category:Compiling]]

Building Spring on Windows

2009-02-14T01:57:22Z

Spliff:

== Get the Source Code ==
{{Obtaining_The_Source_Code}}

== Compiling on Windows ==
For other platforms see [[Building spring]].

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

TODO: The cmake instructions were for linux. Add instructions for windows users.

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Building Spring on Windows

2009-02-14T01:56:46Z

Spliff: added getting source template

== Get the Source Code ==
{{Obtaining_The_Source_Code}}

== Compiling on Windows ==
For other platforms and obtaining the source code see [[Building spring]].

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

TODO: The cmake instructions were for linux. Add instructions for windows users.

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Template:Obtaining The Source Code

2009-02-14T01:55:11Z

Spliff: Obtaining The Source Code moved to Template:Obtaining The Source Code: made into a template

''' Latest Release (For playing Spring online) '''

[http://spring.clan-sy.com/download.php Download]

This code is the same as that used to build the last public release. It is required you use this version of the code to play against others online, or de-syncs will occur.

''' Development Sources from Git (Bleeding-edge, unstable code for Development and Testing) '''

Our GIT repository can be cloned from git://github.com/spring/spring.git.

For serious developers. This will also allow you to make a patch out of the changes you make to the code, and send it to one of the developers with repository access.

Assuming the GIT-commandline client is installed, you can clone the repository with
<code>git clone git://github.com/spring/spring.git</code>
and update it with
<code>git pull</code>

Obtaining The Source Code

2009-02-14T01:55:11Z

Spliff: Obtaining The Source Code moved to Template:Obtaining The Source Code: made into a template

#REDIRECT [[Template:Obtaining The Source Code]]

Template:Obtaining The Source Code

2009-02-14T01:52:14Z

Spliff: Template page for obtaining Spring source

Linux Page

2009-02-11T10:35:45Z

Spliff: White text on very light blue backgrounds ??!! Good one idiot!

{|border="0" cellpadding="4" cellspacing="10" width="100%"
|width="100%" valign="top" style="border: 1px #aaa solid;"|
This is for all using Linux, NetBSD, MacOSX, or any other variant of Unix)
|}

{|border="0" cellpadding="4" cellspacing="10" width="100%"
|width="33%" valign="top" style="border: 1px #aaa solid;"|
===Installation===
'''[[SetupGuide]]''' - Guide for getting Spring to run on Linux. 
'''[[Linux multiplayer games]]''' - Basic information starting a multiplayer game with several Linux clients. 

|width="33%" valign="top" style="border: 1px #aaa solid;"|

===Linux Lobbies===
'''Active'''

'''[http://spring.clan-sy.com/phpbb/viewtopic.php?t=10371 Spring Lobby]''' Multiplatform C++/wxWidgets lobby by tc- and semi 
'''[[AFLobby]]''' A java lobby written by AF 
'''[[TASClient_with_Wine]]''' The Windows delphi lobby by Betalord running via wine/cedega 

'''InActive'''

'''[[Unity Lobby]]''' A python GTK lobby by Hollowsoul 
'''[[Omni]]''' The original python lobby by Ace 
'''[[Orakios Client]]''' A java client written by Orakio 

|width="33%" valign="top" style="border: 1px #aaa solid;"|

===Misc===
'''[[Spring guide!]]''' 
'''[[Spring on MacOSX]]''' 
'''[[Spring for RTS Players]]''' 
'''[[Mods, and their strategies/tactics]]''' 
|}

''' [[Main_Page|<- Back to Main page]]'''

Building Spring on Linux

2009-02-04T22:18:35Z

Spliff: some links, tidy up

== Build From Source on Linux ==
For other platforms see [[Building spring|Building Spring]]

If prefer to use your distributions package system, refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning: You might encounter sync errors in online play if you are not using the exact same version of the compiler and same compiler settings as used for prebuilt packages! (Applies to GCC <4.0)'''

For 0.77b5 these are: TODO add them here.

<div style="clear:both"></div>

== Get Source ==

You can either download the source as a tarball (recommended; v. 0.77b5) or get it from the subversion repository. Either way, the result is the same.

=== Tarball ===

<code><pre>
cd /usr/local/src # or /var/tmp, or whatever
wget http://planetspring.free.fr/spring/src/spring_0.77b5-spring_0.77b5_src.tar.bz2
tar xjf spring_0.77b2-spring_0.77b5_src.tar.bz2
cd spring_0.77b5
</pre></code>

'''NOTE: The .zip release is for windows only. Linux users have to get .bz2 like shown above.'''

=== Subversion ===

<code><pre>
aptitude install subversion # if you are not on debian, figure it out
svn co https://spring.clan-sy.com/svn/spring/tags/spring_0.77b5 \
/usr/local/src/spring_0.77b5
cd /usr/local/src/spring_0.77b5
</pre></code>

If the above subversion host happens to be down (which is unlikely since you're reading this wiki page now), you can try the following hourly updated mirror (replace the svn co line above with the following line):
<code><pre>
svn co svn://caspring.org:3691/tags/spring_0.77b5 \
/usr/local/src/spring_0.77b5
</pre></code>

=== Dependencies ===

You will need to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this. The scons configure will whine if you forget something, but it does not check if you remembered to install zip, even though you still need it.

==== Debian ====

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
that Spring 0.77b5 depends on the boost libraries version 1.34.* and won't
work on lower versions. (updated libboost-serialization-dev, and libvorbis-dev dependencies for 0.76b1)

Also, on 64-bit be sure to build against devIl 1.6.8-rc2 or higher, 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install scons build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev libboost-dev
sudo aptitude install libboost-thread-dev libboost-regex-dev libdevil-dev
sudo aptitude install libboost-serialization-dev python2.5-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev
</pre></code>

==== Gentoo ====
This has been tested to work with a clean install of gentoo 2007.0:

<code><pre>
emerge dev-util/scons \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal =dev-lang/python-2.4\* media-libs/glew dev-libs/boost
emerge media-libs/devil app-arch/zip media-libs/libogg
</pre></code>

==== Fedora ====

On Fedora 8, these dependencies should be sufficient:

<code><pre>
yum install scons boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel java-1.7.0-icedtea-devel libvorbis-devel
</pre></code>

Fedora 9 has issues with 0.76b1, because it uses GCC 4.3 which changed a few compilation warnings into errors. However, the [http://spring.clan-sy.com/phpbb/viewtopic.php?f=20&t=12802 inofficial Linux installer] may work for you (it installs a precompiled binary).

== Build And Install ==

The build will spew out warnings like the following, which you can safely ignore:

<code><pre>
warning: division by zero
warning: 'q' may be used uninitialized in this function
</pre></code>
==== Using Scons ====
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

=== Using CMake (2.6 or newer) ===
Configure and build:

<code><pre>
cmake .
make
</pre></code>

Install:

<code><pre>
make install
</pre></code>

Your paths are: Spring executable in <code>/usr/local/games/spring</code> and
read-only data in <code>/usr/local/share/games/spring</code>.

{{Finalizing_linux_install}}

{{Linux_tips}}

{{Troubleshooting_linux}}

Building Spring Cross Compiled

2009-02-04T22:08:14Z

Spliff:

= Building Spring on a Cross-Compiler =

Cross-compiling allows you to build for other platforms than the machine you are building on. You can, for example, compile Windows 32-bit binaries on a Linux 64-bit machine.

== Setting up the cross compiler ==

I have only done this on Gentoo (instructions [http://en.gentoo-wiki.com/wiki/Crossdev here] or [http://psas.pdx.edu/GentooCrossCompilerHowto/ here]).

There is also a general cross-compiler for linux [http://www.profv.de/mingw_cross_env/ here]

== Getting Spring's libraries ==

'''If Win32 (mingw32) is your target:'''
Auswaschbar has helpfully uploaded all win32 dependencies [http://spring.jobjol.nl/show_file.php?id=1102 here]. Unpack with 7zip to a directory of your choice (or use the one I recommend below).

== Setting up your directories ==
Here is my recommended layout

<pre>
~/spring-xcompile/ (or wherever you want to put it all)
___ spring/ (the spring source)
___ win32/ (your target platform)
_______ build/ (the build files for your target will go here)
_______ final/ (the compiled binaries and libs will be installed here)
_______ libs/ (the target libraries you just downloaded, ie: mingw32libs_v13)
_______ win32.cmake (see below)
</pre>

== Create your cmake toolchain ==

* Create the toolchain file:

>> pico "~/spring-xcompile/win32/win32.cmake"

=== Example toolchain file ===
An example should be self-explanatory:
<pre>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

# the spring mingw32 dependencies
SET(MINGWLIBS ~/spring-xcompile/win32/libs)

# the path that make install will use to put the final binaries
SET(CMAKE_INSTALL_PREFIX ~/spring-xcompile/win32/final)
</pre>

Pass this with "-DCMAKE_TOOLCHAIN_FILE=~/spring-xcompile/win32/win32.cmake" to cmake or select it in the gui to make a cross-compilation (see below).

=== Some Options Explained ===
* MINGWLIBS: directory where the [http://spring.jobjol.nl/show_file.php?id=1102 MinGW library package] is (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

=== Further reference ===
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

== Run CMake ==

=== The GUI method ===
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

=== The commandline method ===

* cd to build directory

>> cd ~user/spring-xcompile/win32/build

* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>

* IMPORTANT: depending on your settings you may need to run this command twice. It can't hurt so I recommend doing it anyway.

>> cmake "~user/spring-xcompile/spring" "-DCMAKE_TOOLCHAIN_FILE=~user/spring-xcompile/win32/win32.cmake"

* run "make" and "make install"

>> make && make install DESTDIR=~user/spring-xcompile/win32/final

== Package Maintainers Note: ==
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

Building Spring Cross Compiled

2009-02-04T22:07:13Z

Spliff: Cross-compiling instructions

= Building Spring on a Cross-Compiler =

Cross-compiling allows you to build for other platforms than the machine you are building on. You can, for example, compile Windows 32-bit binaries on a Linux 64-bit machine.

== Setting up the cross compiler ==

I have only done this on Gentoo (instructions [http://en.gentoo-wiki.com/wiki/Crossdev here] or [http://psas.pdx.edu/GentooCrossCompilerHowto/ here]).

There is also a general cross-compiler for linux [http://www.profv.de/mingw_cross_env/ here]

== Getting Spring's libraries ==

'''If Win32 (mingw32) is your target:'''
Auswaschbar has helpfully uploaded all win32 dependencies [http://spring.jobjol.nl/show_file.php?id=1102 here]. Unpack with 7zip to a directory of your choice (or use the one I recommend below).

== Setting up your directories ==
Here is my recommended layout

<pre>
~/spring-xcompile/ (or wherever you want to put it all)
___ spring/ (the spring source)
___ win32/ (your target platform)
_______ build/ (the build files for your target will go here)
_______ final/ (the compiled binaries and libs will be installed here)
_______ libs/ (the target libraries you just downloaded, ie: mingw32libs_v13)
_______ win32.cmake (see below)
</pre>

== Create your cmake toolchain ==

* Create the toolchain file:

>> pico "~/spring-xcompile/win32/win32.cmake"

=== Example toolchain file ===
An example should be self-explanatory:
<pre>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

# the spring mingw32 dependencies
SET(MINGWLIBS ~/spring-xcompile/win32/libs)

# the path that make install will use to put the final binaries
SET(CMAKE_INSTALL_PREFIX ~/spring-xcompile/win32/final)
</pre>

Pass this with "-DCMAKE_TOOLCHAIN_FILE=~/spring-xcompile/win32/win32.cmake" to cmake or select it in the gui to make a cross-compilation (see below).

=== Some Options Explained ===
* MINGWLIBS: directory where the [http://spring.jobjol.nl/show_file.php?id=1102 MinGW library package] is (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

=== Further reference ===
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

== Run CMake ==

=== The GUI method ===
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

=== The commandline method ===

* cd to build directory

>> cd ~user/spring-xcompile/win32/build

* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>

* IMPORTANT: depending on your settings you may need to run this command twice. It can't hurt so I recommend doing it anyway.

>> cmake "~user/spring-xcompile/spring" "-DCMAKE_TOOLCHAIN_FILE=~user/spring-xcompile/win32/win32.cmake"

* run "make" and "make install"

>> make && make install DESTDIR=~user/spring-xcompile/win32/final

== PACKAGE MAINTAINERS: ==
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

Building Spring on Windows

2009-02-04T21:36:14Z

Spliff: more cmake cleanup

Building Spring on Windows

2009-02-04T21:32:53Z

Spliff: removed cmake command-line method since it is linux only

== Compiling on Windows ==
For other platforms and obtaining the source code see [[Building spring]].

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

==== The GUI method ====
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Building Spring on Linux

2009-02-04T21:04:40Z

Spliff: Build from source moved to Building Spring on Linux: To make clear these are linux instructions as each platform now has it's own build page.

== Build From Source ==

'''You might encounter sync errors in online play if you are not using the exact same version of the compiler and same compiler settings as used for prebuilt packages! (Applies to GCC <4.0)'''

For 0.77b5 these are: TODO add them here.

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

<div style="clear:both"></div>

=== Get Source ===

You can either download the source as a tarball (recommended; v. 0.77b5) or get it from the subversion repository. Either way, the result is the same.

==== Tarball ====

<code><pre>
cd /usr/local/src # or /var/tmp, or whatever
wget http://planetspring.free.fr/spring/src/spring_0.77b5-spring_0.77b5_src.tar.bz2
tar xjf spring_0.77b2-spring_0.77b5_src.tar.bz2
cd spring_0.77b5
</pre></code>

'''NOTE: The .zip release is for windows only. Linux users have to get .bz2 like shown above.'''

==== Subversion ====

<code><pre>
aptitude install subversion # if you are not on debian, figure it out
svn co https://spring.clan-sy.com/svn/spring/tags/spring_0.77b5 \
/usr/local/src/spring_0.77b5
cd /usr/local/src/spring_0.77b5
</pre></code>

If the above subversion host happens to be down (which is unlikely since you're reading this wiki page now), you can try the following hourly updated mirror (replace the svn co line above with the following line):
<code><pre>
svn co svn://caspring.org:3691/tags/spring_0.77b5 \
/usr/local/src/spring_0.77b5
</pre></code>

=== Dependencies ===

You will need to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this. The scons configure will whine if you forget something, but it does not check if you remembered to install zip, even though you still need it.

==== Debian ====

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
that Spring 0.77b5 depends on the boost libraries version 1.34.* and won't
work on lower versions. (updated libboost-serialization-dev, and libvorbis-dev dependencies for 0.76b1)

Also, on 64-bit be sure to build against devIl 1.6.8-rc2 or higher, 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install scons build-essential zlib1g-dev libfreetype6-dev
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev libboost-dev
sudo aptitude install libboost-thread-dev libboost-regex-dev libdevil-dev
sudo aptitude install libboost-serialization-dev python2.5-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev
</pre></code>

==== Gentoo ====
This has been tested to work with a clean install of gentoo 2007.0:

<code><pre>
emerge dev-util/scons \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal =dev-lang/python-2.4\* media-libs/glew dev-libs/boost
emerge media-libs/devil app-arch/zip media-libs/libogg
</pre></code>

==== Fedora ====

On Fedora 8, these dependencies should be sufficient:

<code><pre>
yum install scons boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel java-1.7.0-icedtea-devel libvorbis-devel
</pre></code>

Fedora 9 has issues with 0.76b1, because it uses GCC 4.3 which changed a few compilation warnings into errors. However, the [http://spring.clan-sy.com/phpbb/viewtopic.php?f=20&t=12802 inofficial Linux installer] may work for you (it installs a precompiled binary).

=== Build And Install ===

The build will spew out warnings like the following, which you can safely ignore:

<code><pre>
warning: division by zero
warning: 'q' may be used uninitialized in this function
</pre></code>
==== Using Scons ====
Configure and build:

<code><pre>
scons configure
scons
</pre></code>

Install:

<code><pre>
scons install
</pre></code>

==== Using CMake (2.6 or newer) ====
Configure and build:

<code><pre>
cmake .
make
</pre></code>

Install:

<code><pre>
make install
</pre></code>

Your paths are: Spring executable in <code>/usr/local/games/spring</code> and
read-only data in <code>/usr/local/share/games/spring</code>.

{{Finalizing_linux_install}}

{{Linux_tips}}

{{Troubleshooting_linux}}

Build from source

2009-02-04T21:04:40Z

Spliff: Build from source moved to Building Spring on Linux: To make clear these are linux instructions as each platform now has it's own build page.

#REDIRECT [[Building Spring on Linux]]

Building Spring on Windows

2009-02-04T20:56:51Z

Spliff:

== Compiling on Windows ==
For other platforms and obtaining the source code see [[Building spring]].

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

==== The GUI method ====
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

==== The commandline method ====
Only works with the linux version of cmake, and is easiely scriptable.
* cd to (and/or create) build directory where temporary files are stored
* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>
* depending on your settings you may need to run "cmake ..." twice
* run "make" and "make install"
* PACKAGE MAINTAINERS:
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

==== Some Options Explained ====
* MINGWLIBS: directory where the [http://jobjol.nl/1626 v12 of the MinGW library package is] (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

==== The toolchain file ====
An example should be self-explainatory:
<code>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

SET(MINGWLIBS /home/karl/spring/mingwlibs_v12)</code>
Pass this with "-DCMAKE_TOOLCHAIN_FILE=/your/toolchain/file" to cmake or select it in the gui to make a cross-compilation.

==== Further reference ====
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Building Spring on Windows

2009-02-04T20:55:47Z

Spliff: added link to other platforms and obtaining source code

== Compiling on Windows ==
For other platforms and obtaining the source code see [[Building Spring]].

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

==== The GUI method ====
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

==== The commandline method ====
Only works with the linux version of cmake, and is easiely scriptable.
* cd to (and/or create) build directory where temporary files are stored
* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>
* depending on your settings you may need to run "cmake ..." twice
* run "make" and "make install"
* PACKAGE MAINTAINERS:
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

==== Some Options Explained ====
* MINGWLIBS: directory where the [http://jobjol.nl/1626 v12 of the MinGW library package is] (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

==== The toolchain file ====
An example should be self-explainatory:
<code>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

SET(MINGWLIBS /home/karl/spring/mingwlibs_v12)</code>
Pass this with "-DCMAKE_TOOLCHAIN_FILE=/your/toolchain/file" to cmake or select it in the gui to make a cross-compilation.

==== Further reference ====
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Building Spring on Windows

2009-02-04T20:53:16Z

Spliff: moved from Building_spring

== Compiling on Windows ==

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

==== The GUI method ====
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

==== The commandline method ====
Only works with the linux version of cmake, and is easiely scriptable.
* cd to (and/or create) build directory where temporary files are stored
* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>
* depending on your settings you may need to run "cmake ..." twice
* run "make" and "make install"
* PACKAGE MAINTAINERS:
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

==== Some Options Explained ====
* MINGWLIBS: directory where the [http://jobjol.nl/1626 v12 of the MinGW library package is] (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

==== The toolchain file ====
An example should be self-explainatory:
<code>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

SET(MINGWLIBS /home/karl/spring/mingwlibs_v12)</code>
Pass this with "-DCMAKE_TOOLCHAIN_FILE=/your/toolchain/file" to cmake or select it in the gui to make a cross-compilation.

==== Further reference ====
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Building spring

2009-02-04T20:52:20Z

Spliff: moved windows build instructions to Building_Spring_on_Windows

Development:Main

2009-02-04T20:46:35Z

Spliff: differenciated compiling and development pages

{|border="0" cellpadding="4" cellspacing="10" width="100%"
|width="500px" valign="top"|

'''[[Building spring|Building/Compiling the Spring Engine]]'''

How to build Spring from source. 
[[Building Spring on Windows|Windows]], [[Building Spring on Linux|Linux]], [[Building Spring on MacOSX|MacOSX]], [[Building Spring Cross Compiled|Cross-compiler]] or [[Building Spring on Buildbot|Buildbot]].

'''[[Getting_Started_Development|Spring Engine Development]]'''

Information regarding contributing to the source code of Spring.

'''[[Mod_and_Unit_development#Mod_development|Game Development And Unit Creation]]'''

Lots of links to valuable Articles and forum threads regarding Mod/Unit Development.

'''[[Map_development|Map Development]]'''

Tutorials and other useful information for creating maps.

'''[[Lua Scripting]]'''

Information regarding the use of the supplementary Lua scripting language for Widgets and beyond...

'''[[Map, Mod, And Unit Development Programs|Content Development Programs]]'''

Links to all kind of useful programs.

'''[[Mission development]]'''

Help on writing campaigns, demos and missions using Lua.

'''[[AI|AI Development]]'''

Lots of information about developing Skirmish, Unit and Group AIs for Spring.

'''[[Linux_Page |Linux and Mac OS]]'''

Mac OSX / NetBSD / Solaris / Linux / Cross-platform information.

'''[[Monthly Topic Rotation]]'''

Generally related to development of the engine or particular mods. Read before posting on the forums.

'''[[General Resources]]'''

Usable textures, sounds and code snippets by the community, for the community.

'''[[Associated Development Groups]]'''

Teams, Forums and Groups associated with Spring content and code development.

|width="250px" valign="top"|
{|width="100%"
| style="background: #41545c; padding:5px; border: 1px #aaa solid;"|
'''[http://spring.clan-sy.com/phpbb/viewforum.php?f=12 Development forums]'''

Look at the development forums for ongoing progress and discussion
|}

{|width="100%"
| style="background: #41545c; padding:5px; border: 1px #aaa solid;"|
'''[http://spring.clan-sy.com/mantis/ Report Bugs/Submit a Patch]'''

Submit patches and bug reports here
|}

{|width="100%"
| style="background: #41545c; padding:5px; border: 1px #aaa solid;"|
'''Commit Mailing List'''

View svn commits in your email as they happen
|}

|}

Development:Main

2009-02-04T20:41:17Z

Spliff:

{|border="0" cellpadding="4" cellspacing="10" width="100%"
|width="500px" valign="top"|
'''[[Building spring|Building/Compiling the Spring Engine]]'''

Information regarding the source code of Spring.

'''[[Building spring|Building/Compiling the Spring Engine]]'''

How to build Spring from source. 
[[Building Spring on Windows|Windows]], [[Building Spring on Linux|Linux]], [[Building Spring on MacOSX|MacOSX]], [[Building Spring Cross Compiled|Cross-compiler]] or [[Building Spring on Buildbot|Buildbot]].

'''[[Mod_and_Unit_development#Mod_development|Game Development And Unit Creation]]'''

Lots of links to valuable Articles and forum threads regarding Mod/Unit Development.

'''[[Map_development|Map Development]]'''

Tutorials and other useful information for creating maps.

'''[[Lua Scripting]]'''

Information regarding the use of the supplementary Lua scripting language for Widgets and beyond...

'''[[Map, Mod, And Unit Development Programs|Content Development Programs]]'''

Links to all kind of useful programs.

'''[[Mission development]]'''

Help on writing campaigns, demos and missions using Lua.

'''[[AI|AI Development]]'''

Lots of information about developing Skirmish, Unit and Group AIs for Spring.

'''[[Linux_Page |Linux and Mac OS]]'''

Mac OSX / NetBSD / Solaris / Linux / Cross-platform information.

'''[[Monthly Topic Rotation]]'''

Generally related to development of the engine or particular mods. Read before posting on the forums.

'''[[General Resources]]'''

Usable textures, sounds and code snippets by the community, for the community.

'''[[Associated Development Groups]]'''

Teams, Forums and Groups associated with Spring content and code development.

|width="250px" valign="top"|
{|width="100%"
| style="background: #41545c; padding:5px; border: 1px #aaa solid;"|
'''[http://spring.clan-sy.com/phpbb/viewforum.php?f=12 Development forums]'''

Look at the development forums for ongoing progress and discussion
|}

{|width="100%"
| style="background: #41545c; padding:5px; border: 1px #aaa solid;"|
'''[http://spring.clan-sy.com/mantis/ Report Bugs/Submit a Patch]'''

Submit patches and bug reports here
|}

{|width="100%"
| style="background: #41545c; padding:5px; border: 1px #aaa solid;"|
'''Commit Mailing List'''

View svn commits in your email as they happen
|}

|}

Development:Getting Started

2009-02-04T20:31:26Z

Spliff: Moved from Building_Spring

=Starting Spring Development=
'''NOTE: Outlined below is information on assisting with the development of the Spring source itself. For information about developing a mod (units, widgets, maps, etc.) see the [[Mod_and_Unit_development]] page.'''

'''Even if you are developing a mod, it is highly recommended that you get the engine source. Engine source + full text search: DO IT.'''

==Overview==
To start development, you will need:
#To read the [[Coding_Standards]]
#The latest version of the source
#A good code manipulation program
#Compiling your modified source (see instructions above)

==Learning C++==
You will need to know C++ to modify or understand Spring's source code. If you are interested in learning C++, see [[Learning_CPP]]

However please note that badly designed code (code created by a C++ novice for example), even if working will likely not be included in the spring code. Spring is a large project, and therefore it is necessary to stay away from hack jobs and create general solutions to problems.

==Keep track what others do==
If you develop with others, you need to know what they do. You can browse the source [http://github.com/spring/spring/tree/master at our github-page], and there is a [http://github.com/feeds/spring/commits/spring/master commit newsfeed].

==Source Code Documentation==
A good place to start is [http://buildbot.no-ip.org/~buildbot/spring/doxygen the source code documentation].

An explanation on how the code is executed in game can be found in the [[Spring Engine Code]]
page.

==Development Guidelines==
Before starting to make modifications to the source, take a look at the [[development guidelines]] which outlines some important things to think about. To find something interesting to work on, look at [[SpringEngineTODO]]. You can also check the list of [[whois doing what]] to see what others are doing. If you do edit the code, please add [[Doxygen style comments]] to the code, which will then enhance the source code documentation.

==How to get your code included==
If you create something that you think should be included in the official source tree, you can report a "bug" in [http://spring.clan-sy.com/mantis/ mantis, our BTS]. Add your patch as attachment, and put "[patch]" in front of the subject, so it is easy for us to separate patches from bugs.

It's also considered standard practice to post one's modifications in the [http://spring.clan-sy.com/phpbb/viewforum.php?f=12 development forum] and get feedback.

==Spring Engine TODO list==
There is a TODO list for developers who want to contribute to the engine itself:
[[SpringEngineTODO]]. There is also a [http://spring.clan-sy.com/phpbb/viewforum.php?f=21 feature request forum], which may give you some ideas. Don't be overwhelmed by the sheer number of (silly) requests though!

==Development links==
* [http://planetspring.free.fr/spring/ Automatic installer builds (crosscompiled, mingw)]
* [http://spring.jobjol.nl/show_file.php?id=860 Spring base content files]
* [http://developer.berlios.de/projects/taspring-linux BerliOS project page (OLD)]
* [http://spring.clan-sy.com/mantis Bug Tracking System]
* [http://buildbot.no-ip.org:8010/ Buildbot]
* [https://lists.berlios.de/mailman/listinfo/taspring-linux-commit Commit mailing list]
* [http://spring.clan-sy.com/dl/spring-vc8libs.exe Development libraries for Visual Studio 2005]
* [http://spring.jobjol.nl/show_file.php?id=1102 Development libraries for MinGW]
* [http://sourceforge.net/projects/springrts SourceForge project page (OLD)]
* [http://buildbot.no-ip.org/~buildbot/spring/stacktraceTranslator.php StackTrace Translator]
* [https://spring.clan-sy.com/svn/spring/trunk/ Old Subversion repository]
* [http://spring.clan-sy.com/dl/docs/unitsync/group__unitsync__api.html Unitsync API docs]

Building spring

2009-02-04T20:23:57Z

Spliff: moved development section to own page

=Building Spring=

==Obtaining the Source==
Our GIT repository can be cloned from git://github.com/spring/spring.git.

Another option is to manually [http://spring.clan-sy.com/download.php download] it along with the latest released version of the game. However, for serious developers, a better way would be to download the source straight from the GIT repository. This will also allow you to make a patch out of the changes you make to the code, and send it to one of the developers with repository access.

Assuming the GIT-commandline client is installed, you can clone the repository with
<code>git clone git://github.com/spring/spring.git</code>
and update it with
<code>git pull</code>

== Compiling on Linux ==
If you are using Linux, refer to the [[SetupGuide]] to build Spring and get it running.

== Compiling on Windows ==

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

====Getting MinGW====

Compiling in MinGW requires GCC 4.x which is only available in experimental builds. [http://www.tdragon.net/recentgcc/ TDM's experimental MinGW]

Previous versions of this document suggested using [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks] for their included MinGW. They both come with MinGW 3.4 which no longer compiles a fully working Spring.exe. If you want to use Dev-C++ or Codeblocks, you can install the experimental MinGW build over the one that's included.

Get at least the following packages:
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://jobjol.nl/1102 v13 of the MinGW library package] if you have MinGW .

====MinGW Setup====
There are two ways to setup the MinGL libraries:

''1.'' Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
*/spring/
*/spring/installer
*/spring/rts
*/spring/... other dirs
*/spring/mingwlibs

''2.'' Install the package somewhere else (preferably outside of the source tree), and pass its location with the ''mingwlibsdir'' option to SCons in the configure step (see further down, in the quick instructions).

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-212.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-1.1.0.win32.exe Scons 1.1.0 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

====Quick instructions====

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environment...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)

==== The GUI method ====
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

==== The commandline method ====
Only works with the linux version of cmake, and is easiely scriptable.
* cd to (and/or create) build directory where temporary files are stored
* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>
* depending on your settings you may need to run "cmake ..." twice
* run "make" and "make install"
* PACKAGE MAINTAINERS:
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

==== Some Options Explained ====
* MINGWLIBS: directory where the [http://jobjol.nl/1626 v12 of the MinGW library package is] (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

==== The toolchain file ====
An example should be self-explainatory:
<code>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

SET(MINGWLIBS /home/karl/spring/mingwlibs_v12)</code>
Pass this with "-DCMAKE_TOOLCHAIN_FILE=/your/toolchain/file" to cmake or select it in the gui to make a cross-compilation.

==== Further reference ====
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://spring.clan-sy.com/dl/spring-vc8libs.exe vclibs library package]. You need to install this in the /spring directory from the SVN checkout or the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

[[Category:Compiling]]

Building spring

2009-02-03T09:36:11Z

Spliff: Major cleanup. This page was a freakin mess!

Gentoo install

2009-01-26T17:39:50Z

Spliff:

== Installation ==

This is for version 0.77b5.

 

An overlay to use with layman is provided. If gentoo overlays and/or layman are new to you, [http://overlays.gentoo.org/ read about them], as they are an essential part of gentoo.

This example assumes you never used layman before. If it's not your first time, you hopefully know what to do.

<code><pre>
### install layman (with git support)
echo "app-portage/layman git" >> /etc/portage/package.use
emerge layman
echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf

### add spring overlay to layman
layman -f -a Spring -o \
'http://www.springlobby.info/overlay/?p=springlobby.git;a=blob_plain;f=overlays.xml;hb=HEAD'

### allow installation of unstable versions
echo "games-strategy/spring ~x86" >> /etc/portage/package.keywords
echo "games-util/springlobby ~x86" >> /etc/portage/package.keywords

### install game and lobby
emerge spring springlobby
</pre></code>

=== Upgrading ===

<code><pre>
### update the repository and check for new versions
layman -S

### upgrade existing installations
emerge -u spring springlobby
</pre></code>

Your paths are: Spring executable in <code>/usr/games/bin/spring</code> and
read-only data in <code>/usr/share/games/spring</code>.

= Finalizing installation =

Now you have Spring installed along with SpringLobby. You are now ready to start springlobby for the first time.

=== Maps & Mods ===

Since Spring is only an engine, you need to download games/mods for it, and the maps that go with those games.

Springlobby will automatically do this for you using bittorrent when you attempt to join a game with a map or mod that you don't currently have.

If you want to download it manually or browse existing maps, there are several easy to use websites - here are some:
*[http://spring.jobjol.nl/subcategory.php?id=1 SpringFiles]
*[http://spring-portal.com/ Spring-Portal]
*[http://www.darkstars.co.uk/downloads/index.php?dir=spring Darkstars]

Pick any of those sites, download a map or mod, and then double click it. This will move it to your Spring folder using the spring map/mod installer program. If you wish to move maps/mods by hand, they are located under ~/.spring/maps/ or ~/.spring/mods/ (if the folder doesn't exist - create it). Don't unpack the file in any way though, just download and save it. Reload your maps/mods in Springlobby, (Tools -> Reload maps/mods) and they will be ready to use.

These sites also may provide other neat things like lua widgets, epic replays, AI bots (for playing offline or to team up on with a freind). Generally the installation requires you to download the file and place it in the appropriate folder in your ~/.spring directory. (you may have to create the folder)

Hint: If you know the map name you want, there is a Search function provided in those websites. Just write a part of the name, like one word, and you'll easily find the map you were looking for - this is helpful later on.

==== BA (Balanced Annihilation) ====

A popular mod to get started with is Balanced Annihilation (BA) 6.21. Please note that before you can run it though, you'll need to download the OTA content - read the section below on how to get that.

==== CA (Complete Annihilation) ====

A new mod with better models, graphical effects, and a different take on gameplay is the CA mod - get it [http://trac.caspring.org/wiki/CAInstaller here].

==== OTA Content ====

If you want to play mods based on Total Annihilation, for example XTA, AA, BA, or CA then you have to do the following:

<code><pre>
emerge games-strategy/spring-ota-content
</pre></code>

Note that you need to own a copy of Total Annihilation, to download this file legally.
Mods that do not require this file are at least NanoBlobs, Kernel Panic and Expand & Exterminate

{{Linux_tips}}

{{Troubleshooting_linux}}

Building Spring on Linux

2009-01-26T15:22:45Z

Spliff:

Development:Main

2008-09-08T17:28:52Z

Spliff:

'''NOTE: Outlined below is information on assisting with the development of the Spring source itself. For information about developing a mod (units, widgets, maps, etc.) see the [[Mod Development]] page.'''

Below you can find information on how to work with the Spring source in the current mainline (Windows platform) if you like to work on another platform (Linux & Mac) please look at the bottem of this page under "Multiplatform development"

==Starting Development==
To start development, you will need
#To read the [[Coding_Standards]]
#The latest version of the source
#A good code manipulation program
#Compiling your modified source

== Keep track what others do ==
If you develop with others, you need to know what they do. We have [http://spring.clan-sy.com/fisheye/ fisheye], a very handy SVN helper, and [http://spring.clan-sy.com/websvn/ WebSVN] running on the server.

===Source Code Documentation===
A good place to start is [http://buildbot.no-ip.org/~buildbot/spring/doxygen the source code documentation].

An explanation on how the code is executed in game can be found in the [[Spring Engine Code]]
page.

==Obtaining the Source==
The latest SVN is at: [https://spring.clan-sy.com/svn/spring https://spring.clan-sy.com/svn/spring] 
A hourly updated read-only mirror is available at: svn://caspring.org:3691/

Another option is to manually [http://spring.clan-sy.com/download.php download] it along with the latest released version of the game. However, for serious developers, a better way would be to download the source straight from the subversion (SVN) repository. This will also allow you to make a patch out of the changes you make to the code, and send it to one of the developers with SVN access.

Windows SVN clients : [http://subversion.tigris.org Subversion] (Win32-Console),
[http://www.syntevo.com/smartsvn/index.jsp SmartSVN] (Java) and [http://tortoisesvn.tigris.org TortoiseSVN] (MSI).

Assuming that you are using the Subversion svn client you can download the latest SVN source with one of the following commands:

<code>svn.exe checkout https://spring.clan-sy.com/svn/spring/trunk 
svn.exe checkout svn://caspring.org:3691/trunk</code>

It will create a trunk subdirectory in the directory from where you ran it, which will contain the source code root directory which will be later referred to as /spring

If you're using Git rather than SVN, you need to initialize local repository and fetch using:

<code>git-svn clone https://spring.clan-sy.com/svn/spring
</code>

(this may take a while)

To update your local repository, use:

<code>git-svn fetch https://spring.clan-sy.com/svn/spring
</code>

==Learning C++==
You will need to know C++ to modify or understand Spring's source code. If you are interested in learning C++, see [[Learning_CPP]]

However please note that badly designed code (code created by a C++ novice for example), even if working will likely not be included in the spring code. Spring is a large project, and therefore it is necessary to stay away from hack jobs and create general solutions to problems.

==Setting up your development environment==
You have either to use the SCons build system that is multi platform, or use Microsoft Visual Studio for building spring. See also [[Development_IDEs]] for some more background information about the IDE to choose.

===Visual Studio 8 (2005)===
(possibly the free Express Edition)

* Install the [http://xta.wolfgame.org/SimBase/vclibs.7z vclibs library package]. You need to install this in the /spring directory from the SVN checkout the zipped source. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/vclibs
* Install the [http://msdn.microsoft.com/directx/sdk/ DirectX SDK]
* Install the PlatformSDK. I got away with unchecking the parts of the PlatformSDK that were obviously not related (IIS, web stuff). Makes for a smaller download. Make '''sure''' the Platform SDK and DirectX SDK are in the VS search/include directories:
* After installing them, open Visual C++. Click Tools >> Options >> Projects and Solutions >> VC++ Directories. Add these entries to the corresponding sections (paths just a reference, yours may be different):
**Include files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Include
***$(ProgramFiles)\Microsoft Platform SDK\include
**Library files:
***$(ProgramFiles)\Microsoft DirectX SDK (August 2007)\Lib\x86 (Might need \x64 on a 64-bit platform, I don't know.)
***$(ProgramFiles)\Microsoft Platform SDK\lib
* Open the solution. /spring/rts/build/vstudio8/rts.sln
* Start building (usually you want to select the release/no debug build, debug is really too slow and is used only when you really know what you want to test)
* Select the working directory in the project properties, otherwise spring will not work correctly

===Visual Studio 9 (2008)===
(possibly the free Express Edition)

Not yet fully working as far as I know; you need at least this hotfix from Microsoft though:

http://support.microsoft.com/kb/946040

For the rest the Visual Studio 8 instructions should apply, mostly.

===SCONS/MinGW===
Code::Blocks and Dev C++ use MinGW too, so if you are using one of these IDEs, you'll want to follow these instructions too.

'''Getting the compiler'''

You can compile spring either with MinGW version 3 or 4. MinGW 4.2.1 is used for spring release builds (cross compiled on Linux). Therefore, version 4 is recommended.

''MinGW 3''

If you do not have MinGW installed yet, the easiest way to get it, is to install it together with one of the two IDEs [http://downloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2_setup.exe Dev-C++] or [http://downloads.sourceforge.net/codeblocks/codeblocks-8.02mingw-setup.exe Code::Blocks]. They both come with MinGW 3.4, which still compiles spring correctly (June 2008). Use [http://spring.clan-sy.com/dl/spring-mingwlibs-v10.exe v10 of the MinGW library package] if you have MinGW 3.

''MinGW 4 (recommended)''

If you don't yet have it, go to [http://sf.net/project/showfiles.php?group_id=2435 the MinGW download page], and get at least the following packages (MinGW 4.3.0):
* mingw-runtime
* core
* c++
* java (if MinGW 4.3.1 is out yet, you dont need this)
* binutils
* win32api
Use [http://spring.jobjol.nl/show_file.php?id=1102 v11 of the MinGW library package] if you have MinGW 4.

'''Compiling spring'''

Make sure you install the MinGW library package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
**/spring/
**/spring/installer
**/spring/rts
**/spring/... other dirs
**/spring/mingwlibs

These programs are a must have if you want to compile Spring with MinGW, so install them now, if you don't have them already.

*[http://www.python.org/ftp/python/2.5.1/python-2.5.1.msi Python 2.5 installer]
*[http://downloads.sourceforge.net/pywin32/pywin32-210.win32-py2.5.exe Python 2.5 win32 extensions installer]
*[http://prdownloads.sourceforge.net/scons/scons-0.96.96.win32.exe Scons 0.96 installer]
*[http://www.cmake.org/files/v2.6/cmake-2.6.0-win32-x86.exe CMake 2.6 installer]

Oh, and quick instructions:

* Grab and install the above programs.
* Make sure C:\Python25, C:\Python25\Scripts and C:\Dev-Cpp\bin are in your PATH environment variable. Set environment variables by: Start -> Settings -> Control Panel -> System -> Advanced -> Environment variables (for Windows XP).
* Make sure a MINGDIR environment variable with value C:\Dev-Cpp exists. (change paths where appropriate.)
* Checkout the Spring SVN repository, following the instructions above in obtaining source. (TODO:link)
* Open a console (Start -> Run -> cmd.exe -> Run), cd \where you checked it out in the previous step, if you checked it out on a different drive make sure to change drives with DriveLetter:<enter> first.
* Type scons configure<enter>. Refer to scons --help for options which can be passed to scons configure. Gotchas:
** If you get an error message starting with "EOFError: : env = Environement...", try deleting the file build/scons_signatures.dblite
** If you get an error message stating "ImportError: No module named win32file:", you have probably not installed the python-win32-extensions.
** If all proceeds as intended you will see a message similar to: "Everything seems OK. Run `scons' now to build."
* Type scons<enter> to start the compilation.
** If you have Delphi installed and get an error message that the commandline params "--no-print-directory" & "-C" aren't supported, then you should remove the Delphi dirs from your PATH variable, because scons tried to run the delphi's make.exe instead of using mingw32-make. (this will cause that streflop can't be build!)
* Wait for the compilation to finish, this may take a while.
* Copy datafiles and stuff from official Spring installation to the /spring/game directory (where spring.exe is located, after the compilation finished.)
* Copy missing DLLs from mingwlibs/dll.
* Start developing.

If you are using Linux, refer to the [[SetupGuide]] to build Spring and get it running.

=== CMake/GCC ===
Currently the CMake scripts are not capable of generating Visual Studio project files, so CMake can only be used for gcc compiling.

* Install CMake (must be at least version 2.6.0) from either www.cmake.org or through your distributions package manager
* get the source code (from svn, tarballs...)
==== The GUI method ====
CMake offers a nice Qt4 gui to ease the following steps (to use the gui explained here, cmake must be at least version 2.6.1). Doing so should be straightforward:
* select source directory
* select (and/or create) build directory where temporary files are stored
* hit configure button
* choose your build type:
** Unix makefile if you are using linux and want to compile linux executables
** mingw makefiles if you are working on windows
** Unix makefile with cross compiler setup to cross-compile mingw32 executables, you have to select the toolchain file you want to use (see below)
* configure variables to your need (move the mouse over the options and read the tooltip for further informations on them and or see Section "Options")
* push generate button
* open commandline and do "make" and "make install"

==== The commandline method ====
Only works with the linux version of cmake, and is easiely scriptable.
* cd to (and/or create) build directory where temporary files are stored
* "cmake <path to source tree> <options>" where:
** <path to source tree> is the path to the spring source directory
** <options> are defined like "-D<option name>=<value>
* depending on your settings you may need to run "cmake ..." twice
* run "make" and "make install"
* PACKAGE MAINTAINERS:
** doing "make install DESTDIR=/some/path" will install spring in the specified place, putting files in subdirectories like configured. This may be helpfull when making packages so spring don'T get installed on your system for real (see also CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ#Does_CMake.27s_.22make_install.22_support_DESTDIR.3F]]).
** You need to update the mime database (update-mime-database) and the kde database (kbuildsycoca) after installing to make the system aware of the newly installed mime types and desktop shortcuts.

==== Some Options Explained ====
* MINGWLIBS: directory where the [http://spring.jobjol.nl/show_file.php?id=1102 v11 of the MinGW library package is] (only needed when compiling with mingw)
* CMAKE_BUILD_TYPE: either RELEASE, DEBUG, DEBUG2, DEBUG3 which compiler options to use
* CMAKE_INSTALL_PREFIX: installation prefix (defaults to /usr/local) defines the base directory for installing
* DATADIR, LIBDIR, BINDIR: where to install data, libraries or binaries (relative paths are based on CMAKE_INSTALL_PREFIX, absolute paths are absolute (DESTDIR is still respected))
* APPLICATIONS_DIR, MIME_DIR, PIXMAPS_DIR: where to install freedesktop-files (icons, mime-types and application-description)

==== The toolchain file ====
An example should be self-explainatory:
<code>
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)

# which compilers to use for C and C++
SET(CMAKE_C_COMPILER i686-mingw32-gcc)
SET(CMAKE_CXX_COMPILER i686-mingw32-g++)

# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/i686-mingw32)

SET(MINGWLIBS /home/karl/spring/mingwlibs_v11)</code>
Pass this with "-DCMAKE_TOOLCHAIN_FILE=/your/toolchain/file" to cmake or select it in the gui to make a cross-compilation.

==== Further reference ====
* CMake FAQ [[http://www.vtk.org/Wiki/CMake_FAQ]]
* man CMake
* the CMake documentation (long!) [[http://www.cmake.org/HTML/cmake-2.6.html]]

==Development Suggestions==
Before starting to make modifications to the source, take a look at the [[development guidelines]] which outlines some important things to think about. To find something interesting to work on, look at the list of [[example projects]]. You can also check the list of [[whois doing what]] to see what others are doing. If you do edit the code, please add [[Doxygen style comments]] to the code, which will then enhance the source code documentation.

==How to get your code included==
If you create something that you think should be included in the official source tree, you can report a "bug" in [http://spring.clan-sy.com/mantis/ mantis, our BTS]. Add your patch as attachment, and put "[patch]" in front of the subject, so it is easy for us to separate patches from bugs.

It's also considered standard practice to post one's modifications in the [http://spring.clan-sy.com/phpbb/viewforum.php?f=12 development forum] and get feedback.

==Spring Engine TODO list==
There is a TODO list for developers who want to contribute to the engine itself:
[[SpringEngineTODO]]. There is also a [http://spring.clan-sy.com/phpbb/viewforum.php?f=21 feature request forum], which may give you some ideas. Don't be overwhelmed by the sheer number of (silly) requests though!

==Development links==
* [http://planetspring.free.fr/spring/ Automatic installer builds (crosscompiled, mingw)]
* [http://spring.jobjol.nl/show_file.php?id=860 Spring base content files]
* [http://developer.berlios.de/projects/taspring-linux BerliOS project page (OLD)]
* [http://spring.clan-sy.com/mantis Bug Tracking System]
* [http://buildbot.no-ip.org:8010/ Buildbot]
* [https://lists.berlios.de/mailman/listinfo/taspring-linux-commit Commit mailing list]
* [http://spring.clan-sy.com/dl/spring-vc8libs.exe Development libraries for Visual Studio 2005]
* [http://www.unknown-files.net/spring/3839/mingwlibsv10/ Development libraries for MinGW]
* [http://lolut.utbm.info/cgi-bin/mailman/listinfo/taspring-linux Developers mailing list (practically dead, use this forum instead) (DOWN)]
* [http://buildbot.no-ip.org/~buildbot/spring/doxygen Doxygen pages of the latest source (regenerated nightly)]
* [http://spring.clan-sy.com/fisheye Fisheye interface to SVN]
* [http://sourceforge.net/projects/springrts SourceForge project page (OLD)]
* [http://buildbot.no-ip.org/~buildbot/spring/stacktraceTranslator.php StackTrace Translator]
* [https://spring.clan-sy.com/svn/spring/trunk/ Subversion repository]
* [http://spring.clan-sy.com/websvn/listing.php?repname=spring&path=%2F&sc=0 WebSVN]
* [http://spring.clan-sy.com/websvn/log.php?repname=spring&path=%2F&rev=0&sc=0&isdir=1 WebSVN link to "development log"]
* [http://spring.clan-sy.com/websvn/filedetails.php?repname=spring&path=%2Ftrunk%2FDocumentation%2Fchangelog.txt&rev=0&sc=0 WebSVN link to the most recent changelog.txt]

[[Category:Development]] [[Category:Source development]]