Spring - User contributions [en]

Kernel Panic

2023-03-07T05:31:53Z

Visionm:

<center>[http://timblokdijk.nl/spring/Kernel%20Panic/logo/kernel0_hd.png https://springrts.com/mediawiki/images/f/fc/Kernel_Panic_Alpha_Title_Half.png]</center>

==Overview:==

''For the latest news and/or assistance, try the [http://springrts.com/phpbb/viewforum.php?f=43'''KP forum'''] or go to #kp when you log onto the lobby.''

'''Kernel Panic''' is a game about computers. Systems, Hackers and Networks wage war in a matrix of DOOM! The only constraints are time and space; unlike other real time strategy games, no resource economy exists in KP.

All units are free in this game, every factory built will be spamming units at all times. You can build more factories, but only on pre-defined areas (geothermal vents). All that remains is pure strategy and tactics.

KP makes for a frantically fast-paced, action-oriented game, with a very unique graphical style.

----

==Download links:==

Current Version of Kernel Panic is 4.9

* <u>Newcomers:</u>
** If you run '''Windows''' (2000,XP,Vista,7,8,10):
*** Here you can get a complete installer:
**** https://web.archive.org/web/20230203212632/http://zwzsg.ddns.net/kp/installers/Kernel_Panic_4.9_Including_Spring_105.0_Installer39.exe
**** Mod DB mirror: https://www.moddb.com/games/kernel-panic/downloads/kernel-panic-49-installer-39
*** Use it to install both Spring and Kernel Panic in one go.
*** Then use the shortcuts created in your Start Menu or Desktop.
** If you run '''Linux''':
*** Get a Linux static build of the Spring engine from https://springrts.com/wiki/Download
*** Get and unzip that file: https://web.archive.org/web/20230203213815/http://zwzsg.ddns.net/kp/zips/Kernel_Panic_4.9.zip
*** Unzip both in the same folder, so that Kernel_Panic_4.9_Launcher_Linux is next to spring executable
*** Run Kernel_Panic_4.9_Launcher_Linux
*** Alternatively, running spring directly would bring a greenish menu once ingame
*** For multiplayer or advanced options, run SpringLobby

* <u>Experienced Users:</u>
** If you have already the Spring engine (or prefer to install it yourself): Here you can get a zip with the mod file, the maps, and a tiny executable for single player frontend. Unzip into your Spring root folder: https://web.archive.org/web/20230203213815/http://zwzsg.ddns.net/kp/zips/Kernel_Panic_4.9.zip
** If you are certain you have all the maps and just need a quick link to the mod file itself: https://web.archive.org/web/20230203214135/http://zwzsg.ddns.net/kp/mods/Kernel_Panic_4.9.sd7

----

==Media:==

===Youtube Videos:===

[http://youtube.com/watch?v=doF7owZ0blk&fmt=18 http://i.ytimg.com/vi/doF7owZ0blk/default.jpg]
[http://youtube.com/watch?v=Ug1c19yaZac http://i.ytimg.com/vi/Ug1c19yaZac/default.jpg] [http://youtube.com/watch?v=GAZQhRlt5bU http://i.ytimg.com/vi/GAZQhRlt5bU/default.jpg]
[http://www.youtube.com/watch?v=3q48ys5hFtI&fmt=18 http://i.ytimg.com/vi/3q48ys5hFtI/default.jpg]

----
===Still shots:===

[http://tof.canardpc.com/view/076c8061-5505-44a1-96f4-1bb68e6b7ae5.jpg http://tof.canardpc.com/preview/076c8061-5505-44a1-96f4-1bb68e6b7ae5.jpg] [http://tof.canardpc.com/view/4e607ea7-c428-4ca3-8b70-b12cbf44c18c.jpg http://tof.canardpc.com/preview/4e607ea7-c428-4ca3-8b70-b12cbf44c18c.jpg] [http://tof.canardpc.com/view/23b958ce-d5c9-4b66-b3f9-684db81f9683.jpg http://tof.canardpc.com/preview/23b958ce-d5c9-4b66-b3f9-684db81f9683.jpg]

[http://tof.canardpc.com/view/44f4804f-ec99-40f9-a2e2-c3dc0b7617b8.jpg http://tof.canardpc.com/preview/44f4804f-ec99-40f9-a2e2-c3dc0b7617b8.jpg] [http://tof.canardpc.com/view/e5184baf-6c95-4c90-8469-b00a4f092054.jpg http://tof.canardpc.com/preview/e5184baf-6c95-4c90-8469-b00a4f092054.jpg] [http://tof.canardpc.com/view/cbe6dae0-a696-450a-bf22-236043d76511.jpg http://tof.canardpc.com/preview/cbe6dae0-a696-450a-bf22-236043d76511.jpg]

----

==License:==
Extracted from the <code>Kernel_Panic_readme.txt</code> file:

<pre>
========--------------------------------------------
License:
--------
- The content of the /mods/Kernel*.sd7 is Public Domain, save:
/LuaUI/Widgets/kp_buildbar.lua
/LuaRules/Gadgets/autohold.lua
/LuaRules/Gadgets/Burrow.lua
/LuaRules/Gadgets/game_spawn.lua
which are GPL, taken from http://www.caspring.org or http://springrts.com
- The maps Marble Madness and Direct Memory Access are Public Domain
- The maps Major Madness and Speed Balls 16 Way status are unknown
- The maps Central Hub, Corrupted Core, Dual Core, Quad Core were CC BY-NC-SA and are now CC-BY-SA
https://springrts.com/phpbb/viewtopic.php?f=43&t=21331&p=401680#p397471
https://springrts.com/phpbb/viewtopic.php?f=43&t=27499&start=6
- The Spring engine is GPL, available from http://spring.clan-sy.com
</pre>

----

== Game Modes:==
By default the aim is to destroy the homebase and all the minifacs of all opposing teams.
<br /><br />
Other "mod options" available are:
* '''King Of The Hill :''' Keeps control of the map center for a given time to win.
* '''O.N.S. :''' Adds shields to buildings, preventing homebase rush.
* '''Save Our Mem :''' Unit leave "leaks" that must be reclaimed.
* '''Color Wars :''' Whoever controls the most territory when timer elapse wins.
* '''Heroes of Mainframe :''' You only control a very buffed up but single unit. Best used with "Pre-placed Minifacs".
* '''Rebalancing formula :''' Let you change the stat of any units of weapons without the hassle of making a mutator.
<br />
For details, read [https://web.archive.org/web/20230203212631/http://zwzsg.ddns.net/kp/Kernel_Panic_readme.txt <code>Kernel_Panic_readme.txt</code>] or click [?] next to each mod option in your lobby.
----

==Units and Buildings:==

===System units:===

<table><td>https://springrts.com/mediawiki/images/5/54/96x96Kernel.png</td><td>'''The Kernel:''' You start with one of these. It can build all mobile units in the game. Has rapid auto-heal and lots of health.</td></table>

<table><td>https://springrts.com/mediawiki/images/b/b2/96x96Socket.png</td><td>'''The Socket:''' The socket is a factory which can only be built on a geothermal vent. It can solely build bits, and slower than the kernel can. It autoheals, and has a decent amount of health.</td></table>

<table><td>https://springrts.com/mediawiki/images/8/8c/96x96Terminal.png</td><td>'''The Terminal:''' This is a new structure that gets placed on geovents. It can dispatch a nuclear bomber once every 90 seconds that will deal about 16000 damage to a large target area, i.e. it destroys everything except factories. It does much less damage to the kernel and hole. The bomber can strike any position on the map, there is no defense.</td></table>

<table><td>https://springrts.com/mediawiki/images/1/1e/96x96Assembler.png</td><td>'''The Assembler:''' The assembler is a construction unit. It can build sockets, but it cannot assist-build. Slow, little health. Equipped with a radar to detect mines and other cloacked units.</td></table>

<table><td>https://springrts.com/mediawiki/images/0/0a/96x96Bit.png</td><td>'''The Bit:''' Your basic attacking unit. Cheap, fast, small, not very much health. Is armed with a SPARCling laser. Can be built by a kernel or a socket.</td></table>

<table><td>https://springrts.com/mediawiki/images/e/e3/96x96Byte.png</td><td>'''The Byte:''' A large, strong, and slow attacking unit. Can holds it's own against many bits, as it has lots of health and a powerful gun. More armored when closed. Can plow through bad blocks. The byte has an alternate firing mode, the mine launcher, which throws 5 mines at the cost of much health.</td></table>

<table><td>https://springrts.com/mediawiki/images/5/51/96x96Pointer.png</td><td>'''The Pointer:''' An artillery unit. Its normal shot is not so useful against moving units, but can kill kernels and sockets pretty quickly. Is slow and has little health, so it needs protection. The pointer has an alternate firing mode, the NX Flag, which set a wide area ablaze for a minute, causing constant damage to all units, or buildings within it's range.</td></table>

----

===Hacker units:===
<table><td>https://springrts.com/mediawiki/images/7/7f/96x96NewHoleLow.png</td><td>'''Security Hole:''' The Hacker kernel equivalent.</td></table>

<table><td>https://springrts.com/mediawiki/images/7/70/96x96Window.png</td><td>'''Window:''' The Hacker socket equivalent.</td></table>

<table><td>https://springrts.com/mediawiki/images/f/fb/96x96Obelisk.png</td><td>'''Obelisk:''' This building is a stationary artillery weapon, it can fire an infection shot every 40 seconds (the obelisk has a pink fire on top when it's ready to shoot) that will cover a large area in poison. The poison does a bit of damage (about 1000) and turns any enemy that dies inside the cloud into a Virus. The weapon's range is fairly limited. Best used against stationnary herds of Bits/Bugs.</td></table>

<table><td>https://springrts.com/mediawiki/images/c/c5/96x96NewTrojan.png</td><td>'''Trojan:''' This unit is your constructor as well as radar platform (needed for detecting mines and cloaked units), just like the assembler. It builds all the same stuff as the assembler, except it has the window instead of the socket and the obelisk instead of the terminal.</td></table>

<table><td>https://springrts.com/mediawiki/images/9/94/96x96Virus.png</td><td>'''Virus:''' A crappy little swarm unit. It cannot be built but is produced when killing enemy units with certain weapons. Namely, the Virus, the Worm, and the Obelisk.</td></table>

<table><td>https://springrts.com/mediawiki/images/f/ff/96x96NewBug.png</td><td>'''Bug:''' The Hacker spam unit. The Bug is weaker than the Bit but can sense movement outside of its LOS. It has a stronger weapon and more range but cannot shoot at things behind it or through friendly units and won't take much damage before dying. The mine ability of the old bug has been removed. Instead it can now morph into the Exploit with the deploy button, or the bombard button.</td></table>

<table><td>https://springrts.com/mediawiki/images/c/c4/96x96Exploit.png</td><td>'''Exploit:''' This is the new name for the bug cannon. It's a building the Bug morphs into with the deploy or bombard command. The Exploit is a stationary artillery emplacement that does more damage the further the target is away. Even more frail than the Bug, so don't let any foe come near.</td></table>

<table><td>https://springrts.com/mediawiki/images/4/40/96x96NewWorm.png</td><td>'''Worm:''' The worm is a sneaky assassin, travelling cloacked, then surfacing only to kill many bits at once with its large area of effect weapon, which turn any slain units into virus. The worm large splash damage will damage your own units. However, it does practicaly no damage against other worms or virus. When cloacked, the worm does not automatically attack, you have to give attack orders manually. If you'd rather have your worms auto-attack even when cloacked, set autohold to off. The autohold setting of new worms is inherited from the Security Hole.</td></table>

<table><td>https://springrts.com/mediawiki/images/f/f4/96x96DoS.png</td><td>'''Denial of Service:''' Not an artillery, but close: fire a beam that stun units. For bigger targets it'll take longer to stun them so perform a DDoS (use multiple) to stun them fast. Once the DoS stops firing the target will quickly unfreeze. It moves faster than the pointer but causes a particle trail that can be seen from far away.</td></table>

----

===Network units:===
The network faction is built around mobility, its small factories (Ports) don't produce units openly but instead increment a virtual counter (the Buffer). Packets in the Buffer can be materialized at any teleporter unit (currently that means the Port and the Connection), it's also possible to dematerialize the Packets back into the Buffer by making them enter a teleport.

<table><td>https://springrts.com/mediawiki/images/7/76/96x96Carrier.png</td><td>'''Carrier:''' The base building, like a Kernel or Security Hole.</td></table>

<table><td>https://springrts.com/mediawiki/images/4/46/96x96Port.png</td><td>'''Port:''' The production building. It puts Packets into the Buffer, to materialize them select the Dispatch command. Dispatch will send 12 Packets if available, you can hold ALT when giving the order to make the Port dispatch until the Buffer is empty.</td></table>

<table><td>https://springrts.com/mediawiki/images/8/83/96x96Firewall.png</td><td>'''Firewall:''' This building can cover units (affects friendly units in a certain radius around the target location) in a protective shield for 20 seconds. The shield halves all damage the unit receives and throws the other half back at the attacker.</td></table>

<table><td>https://springrts.com/mediawiki/images/6/6c/96x96Gateway.png</td><td>'''Gateway:''' The constructor. It is lightly armed to help against enemy raids.</td></table>

<table><td>https://springrts.com/mediawiki/images/8/8b/96x96Packet.png</td><td>'''Packet:''' The basic light spam unit, it's weaker in combat than both competitors but much faster.</td></table>

<table><td>https://springrts.com/mediawiki/images/2/26/96x96Connection.png</td><td>'''Connection:''' Mostly a mobile teleporter (i.e. can dispatch Packets and let them enter like a Port). The Connection has decent armor and an arc beam that can do a lot of damage to single targets and has good range. It can defeat most large units one on one but engaging Bytes will probably result in pointer fire which the Connection cannot withstand and the arc beam is not optimal for engaging swarms.</td></table>

<table><td>https://springrts.com/mediawiki/images/0/01/96x96Flow.png</td><td>'''Flow:''' An air unit. The Flow moves fairly slowly but can of course cross any terrain. It's equipped to attack light targets (spam units and fire support) but it's highly vulnerable to return fire. If you want to use them in open combat give them a meatshield and hope the enemy doesn't field long range units, Pointers, DoSes and Connections make short work of Flows if they hit.</td></table>

----

===All side Units:===

<table><td>https://springrts.com/mediawiki/images/9/98/96x96BadBlock.png</td><td>'''The Bad Block:''' A tiny wall, built by Assembler/Trojan/Gateway. Blocks small units movement. Do not block shots however. Easily removed by the Debug or simply crushing them with a Byte or Connection.</td></table>

<table><td>https://springrts.com/mediawiki/images/a/a4/96x96Mine.png</td><td>'''The Logic Bomb:''' A mine that can be built by the Assembler/Trojan/Gateway. And also launched by Bytes. It takes out Bits & Bugs in a single blow, has a decent damage radius, and doesn't chain explode. Use with care, as the blast hurts your own units too. Limited to 32.</td></table>

<table><td>https://springrts.com/mediawiki/images/3/35/96x96MineBlaster.png</td><td>'''The Debug:''' An easy way to clear an area of all mines and walls, this is a one shot weapon built by the Assembler/Trojan/Gateway.</td></table>

----

==Playing Guide for System:==


Playing Kernel Panic is fairly simple and quickly learned, but can be hard to master and can be very complex. It is recommended that beginners start with play the System faction, as they can be considered the least "gimmicky" of the factions.


One rather effective general strategy for a duel on small maps is to send three to five bits to destroy your enemy's early game units, and, to a lesser degree, for scouting purposes. This is most effective if they started with construction units, as this will likely cripple their plans for an early expansion, and gives you a slight head start. After the initial attack, if your scouting shows that your enemy started with offensive units, build a byte for defense, and place it between your Kernel and the hill. After that, build an assembler and use it to build a socket on one the three closest building locations, which should automatically start producing bits. After this, you should order your assembler to build more sockets on free spots close to it. It is crucial that all sockets' rally points are below them, as bits turning inside a socket will stall production until it is able to exit the factory. It is sometimes wise to repeat the prior process with one or two other assemblers. After this is done, construct about ten bits from your factor, and set your kernel to alternate between building bytes and pointers.


What units you build at your kernel, and what you use them for, is an important factor in winning. As buildings can't be resumed, sending in groups of bits to kill construction units creating buildings can be very effective at stopping expansion attempts. Building too many pointers, will result in them being destroyed by connections, bits and especially worms, due to their stealth. Also, bytes are easily destroyer by and pointers, and exploits. A good general purpose ratio seems to be to queue one byte and one pointer, but this will need adapting as the game develops, and depending on the enemy's play style.

Scouting is important too, as many enemies will leave their factories undefended, and knowing their build, and general unit use can help you in adapting the units you use to better fight them. Note that the Network can instantly spawn packets at any of their ports, or connections with their buffer system, meaning that all their factories should be considered defended. Single bits can be used to scout to find the enemy's current expansion attempts.

When attacking a Byte or Connection with bits, it is important to overwhelm it with large numbers of bits. For bytes, try to exploit a byte's blind spot directly under it, by moving bits into that area. If your byte is under attack, moving it backwards to keep the attacking units in it's shooting arc can help repel the attack. It is not recommended to engage a worm with bits, as it's attack will convert your bits to viruses on the worm's owner's side.


On Marble Madness, there are two main ways paths to victory. The simplest one is to control the hill and use pointers stationed on the hill to destroy the enemy's factories, and kernel. Gaining control of the hilltop will likely not be without resistance, because it requires a decent amount of time for units to reach the top of the hill, meaning most units involved will be spam units from your factories on it, and the fact that it will likely be highly contended. However, if you control it, you have a large advantage over the enemy as you can shell your opponents home base with ease. The other way is around the hill, which can be very effective if you control terrain you can use pointers to great effect. In both strategies, using pointers is the crucial factor. While they are hard to use correctly, they are game-winners as they destroy home bases and enemy units with ease.

----

==Credits:==
- Original concept by Boirunner<br>
- About all the work done by KDR_11k<br>
- Sounds by Noruas<br>
- Maintenance by zwzsg<br>
- Maps by Boirunner, Runecrafter, zwzsg, and TradeMark<br>
- Some Lua interface upgrade based of jK and trepan code<br>

----
Back to [[Games]]
[[Category:Games]]

The Complete Guide To Making A Spring Game

2022-11-19T06:13:00Z

Visionm: update getting spring springfiles urls

= The Complete Guide to Making a Spring Game =

by PTSnoop. Everything you could want to know about making games for the Spring engine, all on one page.



== Useful Downloads ==
<span class="warning">ATTENTION: Engine changes mean the games/examples <br/>below DO NOT WORK 100% CORRECT ANYMORE:</span>
For exampe {{forumlink|topic=31015|title=no start units are spawned.}} Instead try [[SpringTutorialGame|SpringTutorialGame]]
----------
[https://springfiles.springrts.com/files/games/empty_mod.sdz Empty Game] - the basic folder structure, and the files you need to get one cube model in game.

[https://springfiles.springrts.com/files/games/empty_mod_plus_tank.sdz Empty Game Plus Tank] - the basic folder structure, plus one working tank unit.

[https://springfiles.springrts.com/files/games/example_mod.sdz Example Game] - a very simple example game. Contains a Factory, Tank, Builder, and Energy Tower.

== Ideas ==

Presumably you already have some of these. If not, just wait around on the forums until someone makes a "this would be a great game can someone make it plz" thread.

It's probably worth sketching out some unit designs, concept art, game mechanics, and so forth, at this point, before you learn what can and can't be easily done with the engine. This way, you'll probably end up with a much more original game at the end of the process. Just bear in mind that you'll have to change around a lot of these ideas once you start finding out what works and what doesn't.

== Getting Spring ==

On Windows: Go to the [[Download]] page and download the installer. Install it.

On Linux: Depends on your distro. There's a [https://launchpad.net/~spring/+archive/ppa ppa] for Ubuntu, and [[SetupGuide | various guides]] for various other distros.

This'll give you the engine and lobby, but no games or maps. It's probably best if you download the [https://springfiles.springrts.com/files/games/example_mod.sdz basic example mod] and a [https://springfiles.springrts.com/files/maps/small_supreme_battlefield_v3.sd7 smallish map], and put them in your /games and /maps folder respectively (for Windows, those'll be in C:\Users\YOURUSERNAME\My Documents\My Games\Spring ; for Linux, ~/.spring . You may have to create some folders.) Then load up SpringLobby and start a game against a computer RAI to make sure it's working fine.

== Tools Used in this Tutorial ==
*Texture Editing
**[https://www.gimp.org/downloads/ Gimp]
*Modeling
**[http://www.wings3d.com/ Wings 3D]
*Coding
**[https://notepad-plus-plus.org/ Notepad++]

== Making a 3D Model ==

There are [http://www.wings3d.com/?page_id=676 far] [https://wiki.beyondunreal.com/Legacy:Wings3D/Getting_Started better] [https://tutorial-index.com/index.php/site/site_category/tut_wings_3d/ tutorials] for learning Wings3D than this one I'm about to write. I suggest you go through a few of them rather than this one. Having said that, I'm still going to rush through the basics here. Because otherwise, it wouldn't really be a "Complete Guide".

If you want to skip this bit, I've put the complete untextured model inside the [https://www.springfiles.com/show_file.php?id=2821 Example Mod]; just extract it as a zip file and look inside /objects3d.

Once you've opened up Wings3D, it'll look something like this:

[[Image:Wings1.png]]

Click your middle mouse button, and move your mouse around. The screen should rotate. Left click to escape rotation mode.
Roll the middle mouse button to zoom in and out.
While in rotation mode, drag your middle mouse button to pan around.

Right click on the background; it'll give you a menu.

[[Image:Wings2.png]]

Click the square to the right of the word "Cube". It'll give you some more options (namely, the dimensions of the cube). Choose 20x20x20, and click OK.
(If you'd just clicked on the word "Cube" rather than the square, it'd have just given you a 2x2x2 cube.)

You should have a fairly large cube. (You may have to zoom out to see it properly.)

[[Image:Wings3.png]]

At the top of the screen, you'll notice four buttons:

[[Image:Wings4.png]]

These are for selecting vertices, edges, faces, and bodies. Play around with each of them; you'll soon figure out how they work. You'll notice clicking on one thing doesn't deselect the last thing; to deselect, you'll have to click on the thing again, or press space to deselect everything.

These four buttons also have keyboard shortcuts v, e, f, b. These are really useful, and worth getting used to.

You'll notice the cube is half-submerged in the ground. To move it above ground, select the whole cube body, and right-click.

You'll see a new bunch of options. Click "Move". You'll see some more options. Click "Y".
( The Y axis points upwards; the X and Z point to the side and front of your unit, respectively. )

The cube will start moving as you move your mouse left and right. The number in the top left hand corner tells you how much it's moving by. To place the cube in a new position, left-click; to snap it back to where it was originally, right-click instead.

To move in fixed units, rather than just continuous up/down, hold down the shift key while moving. This is useful for positioning things carefully, and for knowing where things are later on. Ctrl and Ctrl+Shift move in tenths and hundreds of units. Try to put the cube such that it's 10 units above where it was before (the undo button may be useful here).

[[Image:Wings5.png]]

Choose Face mode, and select the top face of the cube. Right click, and select "Scale Uniform". Scale the face to 50% (Ctrl will help here) and click.
Now right click again, and move this face down 10 units in the same way you moved the whole box before.

[[Image:Wings6.png]]

Okay, now let's create another cube for the turret. There's no need for the options here, so just click on the word "Cube".

[[Image:Wings6.png]]

Oh noes! Where's the new cube gone?

Okay, don't panic. Click on "Window" (on the File Edit View... row), and open up the Outliner. Then repeat for the Geometry Graph.

[[Image:Wings7.png]]

These are useful windows, since they show you everything in your model. Drag and resize these windows to somewhere sensible.

From the geometry graph, you can select specific pieces of your model. Pick the top one by clicking on its grey cube.

[[Image:Wings8.png]]

Deselect this piece, then select the other one. Then right click anywhere and try to move it upwards.

[[Image:Wings9.png]]

It should appear out of the top of the other shape. Put it 12 units above where it was before, so it hovers above the other shape.

Now select the face pointing in the Z direction, towards the front of the unit. The blue letter Z should show the right face.
Right-click and move this face a reasonably long way in the Z direction.

[[Image:Wings10.png]]

Now create a sphere, with radial x and y values of 10 and 10, and move it up to the top of the model.

[[Image:Wings11.png]]

Now let's give this incredibly ugly tank some tracks. Pick the edge tool, and select two edges along one side.

[[Image:Wings12.png]]

Press C. A new edge should appear, connecting the previous two.
Now select the face that's now the lower half of that side (not both halves!), right-click, extrude, X. Extrude it out 2 units.

[[Image:Wings13.png]]

Do the same for the other side.

Now extrude the fronts and backs of the tracks, forwards and backwards in the Z direction.

[[Image:Wings14.png]]

And there we have our first tank model!

Now at this stage, before we texture anything, it would be a good idea to use the edge tool, to select all the edges of the cube blocks (you can do this from the geometry graph), and right-click set Hardness to Hard. This makes all those edges orange.

But when you click on this button here:

[[Image:Wings15.png]]

Then it gives you a more rendered look, blurring soft edges together and keeping hard edges clean and distinct. It doesn't look that amazing at this stage (especially without textures) but once your properly-modelled original units are in game, the proper hard/soft edges make them look that bit better. (Actually, you could do this later on in the process if you want, at any point before exporting to 3ds later on. But this seemed like a good time to mention it.)

[[Image:Wings16.png]]

So now we have a fairly basic clunky tank, ready for texturing. I think it's worth stressing at this point that it's worth going through lots more modelling tutorials and/or playing around with all the options to see what they do; also, when making models for real, it's worth bearing in mind that it's much better to make your own intriguing creative shapes than to just bolt cubes together. It takes longer, and isn't as good for easy tutorials, but it's worth it.

== UVMapping and Texturing a 3D Model ==

This section is based loosely on the tutorial [https://springrts.com/phpbb/viewtopic.php?t=10612 here].

Okay, so we have a clunky tank model, but it's all grey. It needs texture.

To do this, we'll need to UVMap the model. What this means is to take the surface of the model and map it onto a 2d surface, so you can edit the 2d surface (in an image editor) and then it'll wrap around the model nicely. In theory.

At the moment, the model is in three parts; the base, the sphere turret, and the barrel. If we dived straight in and started uvmapping now, we'd end up with three texture files, which at the moment the engine can't cope with. We need to combine the parts into one body.

Using the body tool (shortcut b), select all the pieces, right-click, select "Combine". You should end up with one body.

[[Image:Uv_1.png]]

With the body selected, right-click, then right-click on "UV Mapping". A new window will appear; once you zoom out in the new window, it should look something like this.

[[Image:Uv_2.png]]

To uvmap this model, you'll need to split it up into faces. There are three main ways you can do this.

1) You can select edges, right click > "Mark edges for cut". The computer will cut along these edges, and leave you with a pretty decent net. This gives you control over which faces end up next to each other, on what sides.

2) You can select faces, right click, and mark them as different colours. The computer will take each side separately, keeping same-coloured faces together. This gives you control over which faces end up grouped together.

3) You can right click > "Segment by" > "Projection". The computer does all the work, and leaves you with a bunch of coloured faces. This is the cheating way, gives you not much control over what goes next to what, and gives you some pretty strange results sometimes. But it's soooooo much faster. This is what I normally use, occasionally with a bit of neatening-up of colours afterwards.

[[Image:Uv_3.png]]

Once you've got all your edges or faces marked, right click, and Continue, Unfolding. The computer will give you something like this.

[[Image:Uv_4.png]]

At this point, it's probably worth moving and resizing your windows (with the bottom right hand corner) so you can see both your model and your texture.

[[Image:Uv_5.png]]

You'll notice the computer's given you a default letter-number texture. This is quite useful, since it shows you what kind of level of detail you can get with your model. Smaller letters means more detail.

You'll notice the uvmap has quite a lot of duplicated shapes. For example, there's one trapezoid for the left-hand-side tracks, and a different one for the right-hand-side tracks. We may as well just use the same texture for both, so let's move one onto the other.

The easiest way to do this is to select both trapezoids, right-click > Move To > Center, then right-click > Move and move them to where you want them.

[[Image:Uv_6.png]]

Do this for all the duplicated shapes.

[[Image:Uv_7.png]]

You may have to rotate or flip some shapes to get them to line up. These tools are fairly self-explanatory.

Now if you look at the barrel of the main gun, then you'll probably have some sides have letters running from the turret to the end, and some have the end to the turret (if that makes any sense.)

[[Image:Uv_8.png]]

The final model'll probably look better if we have them all running the same direction. In the 3d model window, select the faces running the wrong direction, then flip them in the 2d texture window.

[[Image:Uv_9.png]]

Now if you look at the texture window, you'll see a lot of wasted space. We can scale each shape to use some of that space, and allow for more detailed textures.

(Beware: if you have multiple shapes overlapping, and you click on them, you'll just select the top one. To select multiple shapes in the same place, drag a box over some of the shape, and it'll pick all layers.)

[[Image:Uv_10.png]]

You'll notice I've made the main body texture pieces much larger, since they're going to have the most important texture on them. You'll also notice I've made the underside texture piece quite a lot smaller, since it's not really going to be seen by anyone unless they flip your tank over. Also, I've left slight gaps between each piece; otherwise, texture from one might bleed into the other.

You'll also notice there's still a lot of unused space; if I spent more time on this I could tighten it up a bit more. But I'd much rather get on with writing this tutorial.

Now the UVMapping is finished, you can create a texture for it. Right-click in the 2D window, click Create Texture.

[[Image:Uv_11.png]]

First of all, click Delete Unused Pass. This should leave you with a background and a "draw edges"; have a look at the options for each. Check the colour of the background; make sure it's got A (alpha) set to 1.0 rather than 0.0 (some versions of Wings3D handle this differently).

There are options for texture size. The general rule for texture size is that the more of this type of unit your players are going to be using, the smaller the texture. 256x256 is a good number for normal units; you might give your end-of-game epic unit of doom something closer to 1024x1024.

Click OK, and you should get something like this:

[[Image:Uv_12.png]]

Now you can close down the 2d uv-editor window, and look at your Outliner. You should see your black-and-white square texture in there. Select it, right-click on it, click "Make External" and save it somewhere as a .tga file.

Okay, now you can minimise Wings3D and open up the .tga file in an image editor. I'll be using GIMP here. Keep Wings3D open, though; we'll need it later on.

[[Image:Uv_13.png]]

GIMP is easy enough to use, so I'm not going to cover it in very much detail here. Start out with just bucket fill and pencil with different brush sizes, then have a look at the Pattern Fill tool option for bucket fill, and you should be able to get something like:

[[Image:Uv_14.png]]

...or hopefully much better and more interesting. I'm rushing here, hence the flat-colour areas (generally a bad idea) and generic blobby camoflage.

One thing that isn't very clear from the screenshots is that I've gone around the edge of a few areas with more colour. If you just go with the black lines you've been given, then white borders may start to bleed into your final textures. If you paint over the white around things, then this won't happen.

Now we can move back into Wings3D, where I've turned more-rendered-mode back on again.

[[Image:Uv_15.png]]

You'll notice the old texture is still in place. To bring the new texture in, right-click on the white square texture, and Refresh.

[[Image:Uv_16.png]]

And now everything looks so much more textured!

(In practice, leaving this step until the end is a bad idea. It's best to flick between Wings3D and Gimp, trying things out.)

Now the model's been textured, we'll need to separate out those pieces we combined together before. If everything's in one body, then the turret won't be able to move independently of the base, etc. Using the body tool, select the tank, then right click > Separate.

Everything'll split back into constituent parts, with fairly generic names (cube2_sep7). You might want to rename these back to something sensible in the Geometry Graph at this point (right click > Rename). I've gone for "body", "turret" and "gun".

And there we have the completed textured model. It's looking very blockish and plain, but hopefully you'll be able to do better once you start modelling properly.

(This finished textured model can be found in the Example Mod.)

Don't close GIMP just yet; we'll need it for the next part.

== Preparing a Model for the Engine ==

The original tutorial this part is based on can be found [https://springrts.com/phpbb/viewtopic.php?f=14&t=13034 here]. Thanks, Pressure Line!

Okay, so we've got our model in Wings3D, uvmapped and textured. But at the moment, all the texture is fixed; there isn't anywhere for team colours. For that, switch back to GIMP.

In Spring, the main texture for each model uses the Alpha channel for teamcolour. Most programs use Alpha for transparency, so this may make your image previews slightly odd. But it'll all look fine once it's in game. In the alpha channel, white is teamcolour, black is no teamcolour, and greys in between are in between. If this doesn't make sense, just keep reading and hopefully it'll all be fine once we've finished.

(I say "main texture" because Spring also allows for secondary textures, which use red for glow, green for reflectivity, and alpha for transparency. I won't cover these here in any detail; play around with these if you want to learn more.)

In GIMP, collapse everything into one layer if you've got more than one. Right click on the layer, and click Add Alpha Channel if it's available. (If it's not, you've probably already got an alpha channel.)

Click Colors > Components > Decompose. This'll give you a box; set it to RGBA and press OK.

[[Image:Upspr_2.png]]

This should give you a second GIMP window, with greyscale and four layers. These are your Red, Green, Blue and Alpha channels. You'll notice the Alpha channel is completely white; we don't want this, because it'll make your whole unit teamcoloured instead of the grey-and-camoflage that we want for most of it.

Copy one of the other layers into the Alpha layer, so you can see where things are. Then make everything black, except for the texture for the turret at the top; make that white.

[[Image:Upspr_3.png]]

Then select Colors > Components > Recompose, and swap back to your first image. You'll see that most of it's vanished, except for the part you want in teamcolour. Don't panic; it's still there, it's just transparent. Save this as TGA.

(Alternatively, at this point, you could save it as DDS (you'll want DXT3 or DXT5, and lots and lots of mipmaps). I personally use TGA, because I've never got round to getting the GIMP DDS plugin working on my machine. If you use DDS, you'll get better performance.)

You can close GIMP down at this point, unless you're going to be still tweaking things.

Now we'll need to get the model out of Wings3D and into [[Upspring]]. Swap back to Wings3D, click File > Export, and click on the box next to 3D Studio (3ds). This'll give you some options.

[[Image:Upspr_4.png]]

You want "Swap X and Y axes" off, Export normals and UV coords both on, and default texture file type set to Targa (tga). Click OK, and save it somewhere you'll remember.

(At this point, if you wanted to, you could use OBJ instead of 3DS; there's no real difference for [[Upspring]] as far as I can tell.)

Now open up [[Upspring]]. You should see something like this.

[[Image:Upspr_5.png]]

Click File > Open, browse to your folder, tell it to look for 3ds files, open the file.

[[Image:Upspr_6.png]]

It'll ask you what you want to do with the multiple meshes. Tell it 2) Load all objects as childs (children?) of an empty root object.

[[Image:Upspr_7.png]]

There's your model, looking small and untextured. On the right, choose the Objects tab.

[[Image:Upspr_8.png]]

You've got a hierarchy of model pieces. These determine what moves when what piece moves. We want the gun to move when the turret moves, and we want both of those to move when the whole body moves, so use the cut and paste buttons above to arrange things more like this:

[[Image:Upspr_9.png]]

I've also renamed the root piece to "base", because it looks better.

Next, we need to move the origin for each piece, to define the points that things rotate around. Zoom in so you can see things properly (by dragging with the right mouse button), then select the "only move origin" option, and select the turret in the hierarchy.

[[Image:Upspr_10.png]]

The X pos, Y pos and Z pos options specify the position of the origin. By default everything's at (0,0,0). Now at this point, you could move into Wings3D, look at the actual height, and put it in the box. Or you can do what I do, and type guesses into the Y pos box until I get the red dot in what looks like the right place. (0,12,0) looks fine.

[[Image:Upspr_11.png]]

Now, interestingly, the gun origin will automatically have moved to (0,-12,0) to stay at the same place. This is because, when we set the origin of the turret, all pieces below the turret in the hierarchy will now measure their positions relative to that piece. Set the turret value to (0,0,0) so the origin's in the same place as the turret.

We'll need another piece later on, to mark the end of the barrel of the gun, so bullets know where to fire from. To do this, select the gun, click "Add empty", call it "flare".Position it just in front of the end of the barrel. (0,0,15) looks good to me.

[[Image:Upspr_12.png]]

Now move onto the Model tab. This gives you options for model centre and radius (this defines the hitsphere), and model height (this defines where the health bar goes). Again, you can measure these carefully in Wings3D, or just guess. There are Estimate buttons, but they often need a bit of adjusting afterwards.

To see what your numbers are doing, click on the "3D" to the top left hand corner of the 3D view, and tell it "Draw model radius and height".

[[Image:Upspr_13.png]]

Now all the unit needs is the texture. Click over to the Mapping tab, click Browse for Texture 1, and load your texture from before.

[[Image:Upspr_14.png]]

And there we have the texture, with a teamcolour turret. If you've got a second texture for reflectivity and so on, you can put that as Texture 2.

Now if you're using TGA textures rather than DDS, you'll need one extra step. Click Texture Mapping > Show UV Mapping. It'll show your texture; click Edit > Flip UVs. Close the UV editor.

[[Image:Upspr_15.png]]

Now your texture looks strange and mangled. In fact, this is what your unit would have looked like if you'd put it in game without flipping UVs like that. Once it's in game, it'll be fine. This strange texture-flipping is a consequence of the way DDS files measure coordinates, I think. If you're using DDS, you won't need to do this step.

One last thing: click on Object > Recalculate vertex normals, 3d0 style > All objects, then OK. This'll sort out some normals or something, I'm not too sure what it does but it makes your textures look better.

Now all you need to do is save the model as an s3o file.

And there we have our finished model and texture! Now to get them in game.

== Putting the Unit in a Game ==

The Spring engine uses .sdz or .sd7 files to load game content. In practice, these are just .zip and .7z files with renamed suffixes; to open up any mod, just rename it and extract it. Also, the Spring engine lets you just put all your game files in a folder in your /games directory, as long as it ends in .sdd .

The best place to get started here is to download the [https://springfiles.com/spring/games/empty-mod Empty Mod], extract it to a folder called EmptyMod.sdd in your /games directory. This is basically the bare minimum to get a unit in game.

Open up SpringLobby; if you've put it in the right place and everything else's correct, you should see an entry for "Empty Mod" in your games list. (You might need to tell it to Tools > Reload Maps/Games first.) If you try playing it, it'll put a blank immobile cube at your start point.

To get the tank unit in game, you'll need as bare minimum an s3o file in /objects3d, a texture file in /unittextures, and a unitdef in /units. You already have two out of three; put them in the right folders.

Next, you'll need to make a unitdef. There are two ways of doing this: the old TA-ish way or the new lua way. You can write an FBI file, which is a text file with a list of variables, or you can write a lua file, which is a text file with a list of variables with slightly different syntax. In general, older tutorials and a fair bit of documentation will talk about FBI, but I'm going to use lua instead because it's more flexible and (I vaguely remember) slightly faster. Here's an example lua unitdef:

<pre>
local unitName = "tank"

local unitDef = {
--Internal settings
BuildPic = "filename.bmp",
Category = "TANK SMALL NOTAIR NOTSUB",
ObjectName = "tank3.s3o",
name = "Generic Tank",
Side = "TANKS",
TEDClass = "TANK",
UnitName = "tank",
script = "tankscript.lua",

--Unit limitations and properties
BuildTime = 1000,
Description = "A generic tank unit.",
MaxDamage = 800,
RadarDistance = 0,
SightDistance = 400,
SoundCategory = "TANK",
Upright = 0,

--Energy and metal related
BuildCostEnergy = 100,
BuildCostMetal = 0,

--Pathfinding and related
Acceleration = 0.15,
BrakeRate = 0.1,
FootprintX = 2,
FootprintZ = 2,
MaxSlope = 15,
MaxVelocity = 2.0,
MaxWaterDepth = 20,
MovementClass = "Default2x2",
TurnRate = 900,

--Abilities
Builder = 0,
CanAttack = 1,
CanGuard = 1,
CanMove = 1,
CanPatrol = 1,
CanStop = 1,
LeaveTracks = 0,
Reclaimable = 0,

--Hitbox
-- collisionVolumeOffsets = "0 0 0",
-- collisionVolumeScales = "20 20 20",
-- collisionVolumeTest = 1,
-- collisionVolumeType = "box",

--Weapons and related
BadTargetCategory = "NOTAIR",
ExplodeAs = "TANKDEATH",
NoChaseCategory = "AIR",

}

return lowerkeys({ [unitName] = unitDef })

</pre>

It's worth looking through this and understanding what each entry does. Most are fairly self-explanatory; for the ones that aren't, there's [[Gamedev:UnitDefs | this page]].

Put this file in your /units folder, then open up /gamedata/sidedata.lua and change 'startunit = "cube"' to 'startunit = "tank". Then start up the mod in Spring.

[[Image:Mod_2.png]]

We should now have a model in game! You should be able to select it, and right-click it around the place. It can't attack anything yet, but one step at a time.

We're going to make this tank shoot small orange blobs. For this we need three things: a small orange blob image for it to fire, a weapon entry in the unitdef, and a unit animation script.

For the small orange blob image, I'm going to use flame.tga from Evolution RTS (it's a good game, with models and textures under CC-BY-NC-ND and almost everything else under a do-whatever-you-want license; well worth checking out). It's in the /bitmaps folder of the example mod; put it in your own /bitmaps folder. Next, we need to open up /gamedata/resources.lua and tell the engine we've got a flame texture; just put a line "flame = 'flame.tga' " in the projectiletextures brackets (or comment out the one I've already left in there).

Here's the lua unitdef from before, with the new weapon data in place:

<pre>
local unitName = "tank"

local unitDef = {
--Internal settings
BuildPic = "filename.bmp",
Category = "TANK SMALL NOTAIR NOTSUB",
ObjectName = "tank3.s3o",
name = "Generic Tank",
Side = "TANKS",
TEDClass = "TANK",
UnitName = "tank",
script = "tankscript.lua",

--Unit limitations and properties
BuildTime = 1000,
Description = "A generic tank unit.",
MaxDamage = 800,
RadarDistance = 0,
SightDistance = 400,
SoundCategory = "TANK",
Upright = 0,

--Energy and metal related
BuildCostEnergy = 100,
BuildCostMetal = 0,

--Pathfinding and related
Acceleration = 0.15,
BrakeRate = 0.1,
FootprintX = 2,
FootprintZ = 2,
MaxSlope = 15,
MaxVelocity = 2.0,
MaxWaterDepth = 20,
MovementClass = "Default2x2",
TurnRate = 900,

--Abilities
Builder = 0,
CanAttack = 1,
CanGuard = 1,
CanMove = 1,
CanPatrol = 1,
CanStop = 1,
LeaveTracks = 0,
Reclaimable = 0,

--Hitbox
-- collisionVolumeOffsets = "0 0 0",
-- collisionVolumeScales = "20 20 20",
-- collisionVolumeTest = 1,
-- collisionVolumeType = "box",

--Weapons and related
BadTargetCategory = "NOTAIR",
ExplodeAs = "TANKDEATH",
NoChaseCategory = "AIR",

weapons = {
[1] = {
def = "orangeblob",
},
},
}

local weaponDefs = {
orangeblob = {
name = "Orange Plasma Cannon",
weapontype = "Cannon",
accuracy = 10,
areaofeffect = 100,
avoidfeature = false,
avoidfriendly = true,
canattackground = true,
collidefriendly = true,
collisionsize = 8,
commandfire = false,
craterboost = 0,
cratermult = 0,
edgeeffectiveness = 0.1,
explosionspeed = 128,
impulseboost = 0,
impulsefactor = 0,
intensity = 1,
noselfdamage = true,
size = 4,
-- soundstart = "tank_fire",
-- soundhit = "explo01",
range = 250,
reloadtime = 1.5,
rgbcolor = "1.0 1.0 1.0",
turret = true,
texture1 = "flame",
weaponvelocity = 400,
-- explosiongenerator = "custom:TANKGUN_FX",
damage =
{
default = 55,
},
},
}

unitDef.weaponDefs = weaponDefs
return lowerkeys({ [unitName] = unitDef })
</pre>

Finally, the animation script. This tells the unit what things to move when firing, moving, exploding etc. All we really want at this point is for the turret to rotate and pitch to the right angle.

Again there are two ways of doing this: the old TA-style method, and the new lua method. You've got the choice of writing the animation script in BOS, then compiling it into COB using Scriptor; this is the best-documented method, but it needs the compiler, and it isn't as flexible. The other method is to write the animation script in lua; this lets you reload scripts mid-game without needing to recompile anything, and allows for the whole lua api in your animation scripts (more on lua later). The only real reason for using COB at the moment is "I already have a working game with vast hordes of COB animations, and it would take a long time to change them all". If you're starting out a new game, then lua is really the best option.

here's an example animation script to go in /scripts/tankscript.lua :

<pre>
local base = piece "base"
local body = piece "body"
local turret = piece "turret"
local gun = piece "gun"
local flare = piece "flare"
-- declares all the pieces we'll use in the script.

local SIG_AIM = 2

local RESTORE_DELAY = Spring.UnitScript.GetLongestReloadTime(unitID) * 2
-- picks a sensible time to wait before trying to turn the turret back to default.

function script.Create()
return 0
end

local function RestoreAfterDelay(unitID)
-- defines a local funtion to wait a bit, then move the turret back to how it was originally.
Sleep(RESTORE_DELAY)
Turn(turret, y_axis, 0, math.rad(35))
Turn(gun, x_axis, 0, math.rad(30))
end

function script.AimWeapon(weaponID, heading, pitch)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
-- each time the Signal is called, all other functions with the same SignalMask will stop running. This makes sure the tank isn't trying to fire at something, and restore the turret position, at the same time.
Turn(turret, y_axis, heading, math.rad(35))
Turn(gun, x_axis, -pitch, math.rad(30))
WaitForTurn(turret, y_axis)
WaitForTurn(gun, x_axis)
StartThread(RestoreAfterDelay)
return true
end

function script.FireWeapon(weaponID)
EmitSfx(flare, 0)
end

function script.QueryWeapon() return flare end
-- The piece that the bullet/laser/whatever comes out of.

function script.AimFromWeapon() return gun end
-- The unit looks from this piece down the QueryWeapon piece, to see whether it's aiming at anything.

function script.Killed(recentDamage, maxHealth)
return 0
end

function script.HitByWeapon(x,z,weaponDef,damage)
-- This stops the unit taking damage until it's been built.
if GetUnitValue(COB.BUILD_PERCENT_LEFT)>2 then return 0
else return damage
end
end
</pre>

Now all these files are in the right folders, start the game. You should now have a small tank, able to drive around and shoot at things!

You'll probably have noticed two things. Firstly, the explosion from being hit by an orange blob isn't very dramatic. Secondly, there's no sound. Let's fix the sound first.

First of all, you'll need an explosion sound. I'm using Explosion3 from https://www.partnersinrhyme.com/soundfx/PDsoundfx/gunsbombs.shtml, chopped around a bit in Audacity: again, you can get it from the Example Mod. Put it in /sounds .

Next, we'll need to tell the engine about the sound file. Open up /gamedata/sounds.lua , and add in a new entry, so it looks something like:

<pre>
local Sounds = {
SoundItems = {
--- RESERVED FOR SPRING, DON'T REMOVE
IncomingChat = {
file = "sounds/incoming_chat.wav",
rolloff = 0.1,
maxdist = 10000,
priority = 100, --- higher numbers = less chance of cutoff
maxconcurrent = 1, ---how many maximum can we hear?
},
MultiSelect = {
file = "sounds/multiselect.wav",
rolloff = 0.1,
maxdist = 10000,
priority = 100, --- higher numbers = less chance of cutoff
maxconcurrent = 1, ---how many maximum can we hear?
},
MapPoint = {
file = "sounds/mappoint.wav",
rolloff = 0.1,
maxdist = 10000,
priority = 100, --- higher numbers = less chance of cutoff
maxconcurrent = 1, ---how many maximum can we hear?
},
--- END RESERVED

--WEAPONS

orangeblob_explo = {
file = "sounds/Explosi3.wav",
rolloff=3, dopplerscale = 0, maxdist = 6000,

priority = 10, --- higher numbers = less chance of cutoff
maxconcurrent = 4, ---how many maximum can we hear?
},

--[[DefaultsForSounds = { -- this are default settings
file = "ThisEntryMustBePresent.wav",
gain = 1.0,
pitch = 1.0,
priority = 0,
maxconcurrent = 16, --- some reasonable limits
--maxdist = FLT_MAX, --- no cutoff at all
},
--- EXAMPLE ONLY!
MyAwesomeSound = {
file = "sounds/booooom.wav",
preload, -- put in memory!
loop, -- loop me!
looptime=1000, --- milliseconds!
gain = 2.0, --- for uber-loudness
pitch = 0.2, --- bass-test
priority = 15, --- very high
maxconcurrent = 1, ---only once
--maxdist = 500, --- only when near
},]]
},
}

return Sounds
</pre>

Finally, we need to tell the unitdef what sound to use. Open it up, and in the weapondef, add the line

soundhit = "orangeblob_explo",

Now, if you try the game in Spring, you should get an explosion sound every time an orange blob hits something. To add a sound on firing, do the same, but add

soundstart = "whatevername",

to the weapondef instead.

<span class="warning">Note: If SpringRTS displays errors when loading the sound, try using OGG format instead. See this [https://springrts.com/phpbb/viewtopic.php?f=52&t=36920 thread for more error details].</span>

Now for the explosion. For particle effects like this, there are two ways (the old TA-style way and the new lua way, again). You can write a CEG tdf file defining what sprites and particles go where and do what, or you can use LUPS (Lua Particle System). Now, this time I'm going to recommend the old TA-style way, because it's well documented and I know how to use it (whereas I don't have a clue how to use LUPS, or where to find out how to use it), but more importantly because it doesn't work on some ATI graphics cards. LUPS is much more flexible, but for now it's best only used for aeroplane trails and other effects that people won't complain about if they're missing.

To use CEG, first you'll need to put a tdf file like this one in the /gamedata/explosions folder:

<pre>
[TANKGUN_FX]
{
[groundflash]
{
flashSize = 45;
flashAlpha = 0.9;
circleGrowth = 3;
circleAlpha = 0.3;
ttl = 30;
color = 1, 0.5, 0;
air=1;
ground=1;
water=1;
}
[heatcloud_MED_EXPLOSION_FX01]
{
class=heatcloud;
[properties]
{
texture=explodeheat;
heat = 30;
maxheat = 30;
heatFalloff = 1;
size = 30;
sizeGrowth = -0.3;
sizemod = 0;
sizemodmod = 0;
speed = 0, 1.5, 0;
pos = 0, 5, 0;
}
air=1;
water=1;
ground=1;
count=1;
}

[MOREDOTS]
{
class=CSimpleParticleSystem;

[properties]
{
alwaysVisible=1;
Texture=randdots;

colorMap = 1.0 1.0 1.0 0.05 0.2 0.9 0.5 0.01 0.1 0.8 0.1 0.00;

pos = 0, 2, 0;
gravity = 0, -0.1, 0;
emitVector = 0, 1, 0;
emitRot = 45;
emitRotSpread = 32;

sizeGrowth = 0.5;
sizeMod = 1;

airdrag = 0.8;
particleLife = 5;
particleLifeSpread = 7;
numParticles = 16;
particleSpeed = 8;
particleSpeedSpread = 3;
particleSize = 20;
particleSizeSpread = 0;

directional = 1;
useAirLos = 0;
}
air=1;
ground=1;
count=1;
}

}
</pre>

You'll also need some more explosion images (also shamelessly stolen from EvoRTS), again available in the Example Mod.

You'll need to put these in /bitmaps, then name them in /gamedata/resources.lua . Also in the weapondef, you'll need to put

explosiongenerator = "custom:TANKGUN_FX",

And now, in game, you should have a working moving tank that shoots things! Congratulations!

== Other Small Things ==

In SpringLobby, you'll notice a "Side: 1" option whenever you mouse over one of the players. It's easy enough to change the "1" to something a bit more descriptive of your side, by putting a 16x16 bmp in /sidepics . If your faction is called "TANK" in sidedata.lua, then call it /sidepics/tank.bmp .

Once you have construction units, it'll help if players have pictures of whatever it is they're building. Put these in /unitpics, and put lines in the unitdefs like
BuildPic = "filename.bmp",

== Structure of a Game ==

Before moving on to factories, builders, and other types of unit, I think it's worth going through the structure of what folder means what in a mod file.

* /bitmaps - This contains the .tga files for explosions, lasers, and so on. Each image here needs to be named in /gamedata/resources.lua before it can be used.
** /bitmaps/loadpictures - Any jpg files in here will be shown while the game is loading.

* /gamedata - Lua files defining game information.
** gamedata/armordefs.lua - defines different armour groupings. More information: [[Armordefs.lua]].
** /gamedata/explosions - TDF files for CEG explosions.
** /gamedata/messages.lua - messages given whenever a team loses the game. More information: [[Messages.lua]]
** /gamedata/modrules.lua - various parameters for your game, like flanking bonuses, rate at which experience is gained, etc. Have a look at existing games to see what they do. More information: [[Modrules.lua]]
** /gamedata/movedefs.lua - defines different types of movement (hovercraft, tank, ship etc). More information: [[Movedefs.lua]].
** /gamedata/resources.lua - all the bitmaps in /bitmaps, with names and what they do (are they for projectiles, groundflares, etc)
** /gamedata/sidedata.lua - defines the different factions, and what unit they start off with. In theory, you could do all this with a lua gadget (more on this later), but sidedata.lua works pretty well anyway.
** /gamedata/sounds.lua - defines all the sound files, with values for volume, priority, doppler effect, etc.

* /LuaRules - contains gadgets. These are scripting files that change gameplay; more info later.
** /LuaRules/Gadgets/spawnPlayer.lua - creates a starting unit at the beginning of the game, depending on /gamedata/sidedata.lua . In theory, you could adapt this to generate random units, create whole bases at the start of games, etc.
** /LuaRules/Gadgets/unit_script.lua - this is needed for lua animation scripts to work, for some reason.
* /LuaUI - contains widgets. These are scripting files that change the user interface; more info later.

* /music - contains music for the music widget.
* /sounds - contains sound.

* /objects3d - contains all the s3o models.
* /scripts - contains all the unit animation scripts.
* /units - contains unit definitions.
* /unittextures - contains textures for the s3o models.

* /unitpics - pictures for each unit, shown on build mens.
* /sidepics - pictures for each faction, shown in lobby.

* /[[modinfo.lua]] - defines the mod name, description, and if it requires any pre-existing content.
* /EngineOptions.txt - exactly what it says on the tin. Look at different games to see what they do.

== Other Types of Unit ==

At the moment, you've got a tank unit. This is useful, but for your game, you'll probably need some factories, builders, buildings, and so on (depending on how unconventional your game is). I think the best way to show how to make these units is by example, so here's a basic mod with about one of each:

Load up a game against RAI (that AI works for pretty much any mod, as long as your lua isn't too strange). Then extract it open (it's really just a .zip file), look through the code and see what the scripts and unitdefs are like.

== Lua Gadgets and Widgets ==

Now this is where things start getting really interesting. Gadgets are small lua script files that let you add things to the basic Spring gameplay. And by "things", I mean "anything". Want units that morph into other units? Lua. Want tech trees and unit prerequisites? Lua. Want units that fire other units? Lua. Want meteor strikes and random dinosaurs to spawn out of the map and attack players? Lua. Want napalm? Lua. Want time travel? Well, [https://achrongame.com/ maybe a separate engine designed for RTS time travel would help you better here], but presumably it can be done with enough Lua.

And because it's so versatile, for now I'm just going to point you to [[Lua Scripting | the lists of callouts and callins]] and stand back. Maybe I'll come back to this bit and write a basic gadget tutorial at a later date, but for now the forums are your friend.

It's not very big yet, though, so for more examples just look at the [https://github.com/Balanced-Annihilation/Balanced-Annihilation/tree/master/luarules/gadgets Balanced Annihilation gadget source code].

Widgets are like Gadgets, but instead of changing gameplay they change the user interface. So if you want to add a bunch more buttons along the right hand side, or glowing outlines around certain types of unit, you'd probably use a widget. You can also add widgets to your local copy of Spring that aren't in the mod file itself; this can be useful to give yourself debug information that other players won't have, but bear in mind that it's pretty likely other players will also be using their own array of widgets to enhance their gaming abilities when playing against you.

Have a look at the [https://github.com/Balanced-Annihilation/Balanced-Annihilation/tree/master/luaui/Widgets_BA Balanced Annihilation widget source code] for some examples.

== Maps and Missions ==

Okay, so you've got a working multiplayer game. Now how about single player?

There aren't really any Spring games at the moment with a single player campaign. All the tools are in place, but no-one's actually used them yet. Now, I'm willing to bet that if you manage to give your game a decent SP campaign, and the multiplayer and graphics aren't too bad, it could quickly be adopted as the Spring engine's flagship game. No, I'm serious here.

To make some maps, see [https://springrts.com/wiki/Mapdev:Main Map Development]

For single player missions, there's a [https://springrts.com/phpbb/viewtopic.php?f=14&t=24278 Mission Editor] <s>with a [https://code.google.com/p/zero-k/wiki/MissionEditorTutorial good tutorial] of its own, so I don't need to write one</s>. Enjoy!

[[Category:Game Dev]]

The Complete Guide To Making A Spring Game

2022-11-19T04:44:13Z

Visionm: update useful downloads urls

= The Complete Guide to Making a Spring Game =

by PTSnoop. Everything you could want to know about making games for the Spring engine, all on one page.



== Useful Downloads ==
<span class="warning">ATTENTION: Engine changes mean the games/examples <br/>below DO NOT WORK 100% CORRECT ANYMORE:</span>
For exampe {{forumlink|topic=31015|title=no start units are spawned.}} Instead try [[SpringTutorialGame|SpringTutorialGame]]
----------
[https://springfiles.springrts.com/files/games/empty_mod.sdz Empty Game] - the basic folder structure, and the files you need to get one cube model in game.

[https://springfiles.springrts.com/files/games/empty_mod_plus_tank.sdz Empty Game Plus Tank] - the basic folder structure, plus one working tank unit.

[https://springfiles.springrts.com/files/games/example_mod.sdz Example Game] - a very simple example game. Contains a Factory, Tank, Builder, and Energy Tower.

== Ideas ==

Presumably you already have some of these. If not, just wait around on the forums until someone makes a "this would be a great game can someone make it plz" thread.

It's probably worth sketching out some unit designs, concept art, game mechanics, and so forth, at this point, before you learn what can and can't be easily done with the engine. This way, you'll probably end up with a much more original game at the end of the process. Just bear in mind that you'll have to change around a lot of these ideas once you start finding out what works and what doesn't.

== Getting Spring ==

On Windows: Go to the [[Download]] page and download the installer. Install it.

On Linux: Depends on your distro. There's a [https://launchpad.net/~spring/+archive/ppa ppa] for Ubuntu, and [[SetupGuide | various guides]] for various other distros.

This'll give you the engine and lobby, but no games or maps. It's probably best if you download the [https://springfiles.com/spring/games/example-mod basic example mod] and a [https://springfiles.com/spring/spring-maps/smallsupremebattlefieldv2 smallish map], and put them in your /games and /maps folder respectively (for Windows, those'll be in C:\Users\YOURUSERNAME\My Documents\My Games\Spring ; for Linux, ~/.spring . You may have to create some folders.) Then load up SpringLobby and start a game against a computer RAI to make sure it's working fine.

== Tools Used in this Tutorial ==
*Texture Editing
**[https://www.gimp.org/downloads/ Gimp]
*Modeling
**[http://www.wings3d.com/ Wings 3D]
*Coding
**[https://notepad-plus-plus.org/ Notepad++]

== Making a 3D Model ==

There are [http://www.wings3d.com/?page_id=676 far] [https://wiki.beyondunreal.com/Legacy:Wings3D/Getting_Started better] [https://tutorial-index.com/index.php/site/site_category/tut_wings_3d/ tutorials] for learning Wings3D than this one I'm about to write. I suggest you go through a few of them rather than this one. Having said that, I'm still going to rush through the basics here. Because otherwise, it wouldn't really be a "Complete Guide".

If you want to skip this bit, I've put the complete untextured model inside the [https://www.springfiles.com/show_file.php?id=2821 Example Mod]; just extract it as a zip file and look inside /objects3d.

Once you've opened up Wings3D, it'll look something like this:

[[Image:Wings1.png]]

Click your middle mouse button, and move your mouse around. The screen should rotate. Left click to escape rotation mode.
Roll the middle mouse button to zoom in and out.
While in rotation mode, drag your middle mouse button to pan around.

Right click on the background; it'll give you a menu.

[[Image:Wings2.png]]

Click the square to the right of the word "Cube". It'll give you some more options (namely, the dimensions of the cube). Choose 20x20x20, and click OK.
(If you'd just clicked on the word "Cube" rather than the square, it'd have just given you a 2x2x2 cube.)

You should have a fairly large cube. (You may have to zoom out to see it properly.)

[[Image:Wings3.png]]

At the top of the screen, you'll notice four buttons:

[[Image:Wings4.png]]

These are for selecting vertices, edges, faces, and bodies. Play around with each of them; you'll soon figure out how they work. You'll notice clicking on one thing doesn't deselect the last thing; to deselect, you'll have to click on the thing again, or press space to deselect everything.

These four buttons also have keyboard shortcuts v, e, f, b. These are really useful, and worth getting used to.

You'll notice the cube is half-submerged in the ground. To move it above ground, select the whole cube body, and right-click.

You'll see a new bunch of options. Click "Move". You'll see some more options. Click "Y".
( The Y axis points upwards; the X and Z point to the side and front of your unit, respectively. )

The cube will start moving as you move your mouse left and right. The number in the top left hand corner tells you how much it's moving by. To place the cube in a new position, left-click; to snap it back to where it was originally, right-click instead.

To move in fixed units, rather than just continuous up/down, hold down the shift key while moving. This is useful for positioning things carefully, and for knowing where things are later on. Ctrl and Ctrl+Shift move in tenths and hundreds of units. Try to put the cube such that it's 10 units above where it was before (the undo button may be useful here).

[[Image:Wings5.png]]

Choose Face mode, and select the top face of the cube. Right click, and select "Scale Uniform". Scale the face to 50% (Ctrl will help here) and click.
Now right click again, and move this face down 10 units in the same way you moved the whole box before.

[[Image:Wings6.png]]

Okay, now let's create another cube for the turret. There's no need for the options here, so just click on the word "Cube".

[[Image:Wings6.png]]

Oh noes! Where's the new cube gone?

Okay, don't panic. Click on "Window" (on the File Edit View... row), and open up the Outliner. Then repeat for the Geometry Graph.

[[Image:Wings7.png]]

These are useful windows, since they show you everything in your model. Drag and resize these windows to somewhere sensible.

From the geometry graph, you can select specific pieces of your model. Pick the top one by clicking on its grey cube.

[[Image:Wings8.png]]

Deselect this piece, then select the other one. Then right click anywhere and try to move it upwards.

[[Image:Wings9.png]]

It should appear out of the top of the other shape. Put it 12 units above where it was before, so it hovers above the other shape.

Now select the face pointing in the Z direction, towards the front of the unit. The blue letter Z should show the right face.
Right-click and move this face a reasonably long way in the Z direction.

[[Image:Wings10.png]]

Now create a sphere, with radial x and y values of 10 and 10, and move it up to the top of the model.

[[Image:Wings11.png]]

Now let's give this incredibly ugly tank some tracks. Pick the edge tool, and select two edges along one side.

[[Image:Wings12.png]]

Press C. A new edge should appear, connecting the previous two.
Now select the face that's now the lower half of that side (not both halves!), right-click, extrude, X. Extrude it out 2 units.

[[Image:Wings13.png]]

Do the same for the other side.

Now extrude the fronts and backs of the tracks, forwards and backwards in the Z direction.

[[Image:Wings14.png]]

And there we have our first tank model!

Now at this stage, before we texture anything, it would be a good idea to use the edge tool, to select all the edges of the cube blocks (you can do this from the geometry graph), and right-click set Hardness to Hard. This makes all those edges orange.

But when you click on this button here:

[[Image:Wings15.png]]

Then it gives you a more rendered look, blurring soft edges together and keeping hard edges clean and distinct. It doesn't look that amazing at this stage (especially without textures) but once your properly-modelled original units are in game, the proper hard/soft edges make them look that bit better. (Actually, you could do this later on in the process if you want, at any point before exporting to 3ds later on. But this seemed like a good time to mention it.)

[[Image:Wings16.png]]

So now we have a fairly basic clunky tank, ready for texturing. I think it's worth stressing at this point that it's worth going through lots more modelling tutorials and/or playing around with all the options to see what they do; also, when making models for real, it's worth bearing in mind that it's much better to make your own intriguing creative shapes than to just bolt cubes together. It takes longer, and isn't as good for easy tutorials, but it's worth it.

== UVMapping and Texturing a 3D Model ==

This section is based loosely on the tutorial [https://springrts.com/phpbb/viewtopic.php?t=10612 here].

Okay, so we have a clunky tank model, but it's all grey. It needs texture.

To do this, we'll need to UVMap the model. What this means is to take the surface of the model and map it onto a 2d surface, so you can edit the 2d surface (in an image editor) and then it'll wrap around the model nicely. In theory.

At the moment, the model is in three parts; the base, the sphere turret, and the barrel. If we dived straight in and started uvmapping now, we'd end up with three texture files, which at the moment the engine can't cope with. We need to combine the parts into one body.

Using the body tool (shortcut b), select all the pieces, right-click, select "Combine". You should end up with one body.

[[Image:Uv_1.png]]

With the body selected, right-click, then right-click on "UV Mapping". A new window will appear; once you zoom out in the new window, it should look something like this.

[[Image:Uv_2.png]]

To uvmap this model, you'll need to split it up into faces. There are three main ways you can do this.

1) You can select edges, right click > "Mark edges for cut". The computer will cut along these edges, and leave you with a pretty decent net. This gives you control over which faces end up next to each other, on what sides.

2) You can select faces, right click, and mark them as different colours. The computer will take each side separately, keeping same-coloured faces together. This gives you control over which faces end up grouped together.

3) You can right click > "Segment by" > "Projection". The computer does all the work, and leaves you with a bunch of coloured faces. This is the cheating way, gives you not much control over what goes next to what, and gives you some pretty strange results sometimes. But it's soooooo much faster. This is what I normally use, occasionally with a bit of neatening-up of colours afterwards.

[[Image:Uv_3.png]]

Once you've got all your edges or faces marked, right click, and Continue, Unfolding. The computer will give you something like this.

[[Image:Uv_4.png]]

At this point, it's probably worth moving and resizing your windows (with the bottom right hand corner) so you can see both your model and your texture.

[[Image:Uv_5.png]]

You'll notice the computer's given you a default letter-number texture. This is quite useful, since it shows you what kind of level of detail you can get with your model. Smaller letters means more detail.

You'll notice the uvmap has quite a lot of duplicated shapes. For example, there's one trapezoid for the left-hand-side tracks, and a different one for the right-hand-side tracks. We may as well just use the same texture for both, so let's move one onto the other.

The easiest way to do this is to select both trapezoids, right-click > Move To > Center, then right-click > Move and move them to where you want them.

[[Image:Uv_6.png]]

Do this for all the duplicated shapes.

[[Image:Uv_7.png]]

You may have to rotate or flip some shapes to get them to line up. These tools are fairly self-explanatory.

Now if you look at the barrel of the main gun, then you'll probably have some sides have letters running from the turret to the end, and some have the end to the turret (if that makes any sense.)

[[Image:Uv_8.png]]

The final model'll probably look better if we have them all running the same direction. In the 3d model window, select the faces running the wrong direction, then flip them in the 2d texture window.

[[Image:Uv_9.png]]

Now if you look at the texture window, you'll see a lot of wasted space. We can scale each shape to use some of that space, and allow for more detailed textures.

(Beware: if you have multiple shapes overlapping, and you click on them, you'll just select the top one. To select multiple shapes in the same place, drag a box over some of the shape, and it'll pick all layers.)

[[Image:Uv_10.png]]

You'll notice I've made the main body texture pieces much larger, since they're going to have the most important texture on them. You'll also notice I've made the underside texture piece quite a lot smaller, since it's not really going to be seen by anyone unless they flip your tank over. Also, I've left slight gaps between each piece; otherwise, texture from one might bleed into the other.

You'll also notice there's still a lot of unused space; if I spent more time on this I could tighten it up a bit more. But I'd much rather get on with writing this tutorial.

Now the UVMapping is finished, you can create a texture for it. Right-click in the 2D window, click Create Texture.

[[Image:Uv_11.png]]

First of all, click Delete Unused Pass. This should leave you with a background and a "draw edges"; have a look at the options for each. Check the colour of the background; make sure it's got A (alpha) set to 1.0 rather than 0.0 (some versions of Wings3D handle this differently).

There are options for texture size. The general rule for texture size is that the more of this type of unit your players are going to be using, the smaller the texture. 256x256 is a good number for normal units; you might give your end-of-game epic unit of doom something closer to 1024x1024.

Click OK, and you should get something like this:

[[Image:Uv_12.png]]

Now you can close down the 2d uv-editor window, and look at your Outliner. You should see your black-and-white square texture in there. Select it, right-click on it, click "Make External" and save it somewhere as a .tga file.

Okay, now you can minimise Wings3D and open up the .tga file in an image editor. I'll be using GIMP here. Keep Wings3D open, though; we'll need it later on.

[[Image:Uv_13.png]]

GIMP is easy enough to use, so I'm not going to cover it in very much detail here. Start out with just bucket fill and pencil with different brush sizes, then have a look at the Pattern Fill tool option for bucket fill, and you should be able to get something like:

[[Image:Uv_14.png]]

...or hopefully much better and more interesting. I'm rushing here, hence the flat-colour areas (generally a bad idea) and generic blobby camoflage.

One thing that isn't very clear from the screenshots is that I've gone around the edge of a few areas with more colour. If you just go with the black lines you've been given, then white borders may start to bleed into your final textures. If you paint over the white around things, then this won't happen.

Now we can move back into Wings3D, where I've turned more-rendered-mode back on again.

[[Image:Uv_15.png]]

You'll notice the old texture is still in place. To bring the new texture in, right-click on the white square texture, and Refresh.

[[Image:Uv_16.png]]

And now everything looks so much more textured!

(In practice, leaving this step until the end is a bad idea. It's best to flick between Wings3D and Gimp, trying things out.)

Now the model's been textured, we'll need to separate out those pieces we combined together before. If everything's in one body, then the turret won't be able to move independently of the base, etc. Using the body tool, select the tank, then right click > Separate.

Everything'll split back into constituent parts, with fairly generic names (cube2_sep7). You might want to rename these back to something sensible in the Geometry Graph at this point (right click > Rename). I've gone for "body", "turret" and "gun".

And there we have the completed textured model. It's looking very blockish and plain, but hopefully you'll be able to do better once you start modelling properly.

(This finished textured model can be found in the Example Mod.)

Don't close GIMP just yet; we'll need it for the next part.

== Preparing a Model for the Engine ==

The original tutorial this part is based on can be found [https://springrts.com/phpbb/viewtopic.php?f=14&t=13034 here]. Thanks, Pressure Line!

Okay, so we've got our model in Wings3D, uvmapped and textured. But at the moment, all the texture is fixed; there isn't anywhere for team colours. For that, switch back to GIMP.

In Spring, the main texture for each model uses the Alpha channel for teamcolour. Most programs use Alpha for transparency, so this may make your image previews slightly odd. But it'll all look fine once it's in game. In the alpha channel, white is teamcolour, black is no teamcolour, and greys in between are in between. If this doesn't make sense, just keep reading and hopefully it'll all be fine once we've finished.

(I say "main texture" because Spring also allows for secondary textures, which use red for glow, green for reflectivity, and alpha for transparency. I won't cover these here in any detail; play around with these if you want to learn more.)

In GIMP, collapse everything into one layer if you've got more than one. Right click on the layer, and click Add Alpha Channel if it's available. (If it's not, you've probably already got an alpha channel.)

Click Colors > Components > Decompose. This'll give you a box; set it to RGBA and press OK.

[[Image:Upspr_2.png]]

This should give you a second GIMP window, with greyscale and four layers. These are your Red, Green, Blue and Alpha channels. You'll notice the Alpha channel is completely white; we don't want this, because it'll make your whole unit teamcoloured instead of the grey-and-camoflage that we want for most of it.

Copy one of the other layers into the Alpha layer, so you can see where things are. Then make everything black, except for the texture for the turret at the top; make that white.

[[Image:Upspr_3.png]]

Then select Colors > Components > Recompose, and swap back to your first image. You'll see that most of it's vanished, except for the part you want in teamcolour. Don't panic; it's still there, it's just transparent. Save this as TGA.

(Alternatively, at this point, you could save it as DDS (you'll want DXT3 or DXT5, and lots and lots of mipmaps). I personally use TGA, because I've never got round to getting the GIMP DDS plugin working on my machine. If you use DDS, you'll get better performance.)

You can close GIMP down at this point, unless you're going to be still tweaking things.

Now we'll need to get the model out of Wings3D and into [[Upspring]]. Swap back to Wings3D, click File > Export, and click on the box next to 3D Studio (3ds). This'll give you some options.

[[Image:Upspr_4.png]]

You want "Swap X and Y axes" off, Export normals and UV coords both on, and default texture file type set to Targa (tga). Click OK, and save it somewhere you'll remember.

(At this point, if you wanted to, you could use OBJ instead of 3DS; there's no real difference for [[Upspring]] as far as I can tell.)

Now open up [[Upspring]]. You should see something like this.

[[Image:Upspr_5.png]]

Click File > Open, browse to your folder, tell it to look for 3ds files, open the file.

[[Image:Upspr_6.png]]

It'll ask you what you want to do with the multiple meshes. Tell it 2) Load all objects as childs (children?) of an empty root object.

[[Image:Upspr_7.png]]

There's your model, looking small and untextured. On the right, choose the Objects tab.

[[Image:Upspr_8.png]]

You've got a hierarchy of model pieces. These determine what moves when what piece moves. We want the gun to move when the turret moves, and we want both of those to move when the whole body moves, so use the cut and paste buttons above to arrange things more like this:

[[Image:Upspr_9.png]]

I've also renamed the root piece to "base", because it looks better.

Next, we need to move the origin for each piece, to define the points that things rotate around. Zoom in so you can see things properly (by dragging with the right mouse button), then select the "only move origin" option, and select the turret in the hierarchy.

[[Image:Upspr_10.png]]

The X pos, Y pos and Z pos options specify the position of the origin. By default everything's at (0,0,0). Now at this point, you could move into Wings3D, look at the actual height, and put it in the box. Or you can do what I do, and type guesses into the Y pos box until I get the red dot in what looks like the right place. (0,12,0) looks fine.

[[Image:Upspr_11.png]]

Now, interestingly, the gun origin will automatically have moved to (0,-12,0) to stay at the same place. This is because, when we set the origin of the turret, all pieces below the turret in the hierarchy will now measure their positions relative to that piece. Set the turret value to (0,0,0) so the origin's in the same place as the turret.

We'll need another piece later on, to mark the end of the barrel of the gun, so bullets know where to fire from. To do this, select the gun, click "Add empty", call it "flare".Position it just in front of the end of the barrel. (0,0,15) looks good to me.

[[Image:Upspr_12.png]]

Now move onto the Model tab. This gives you options for model centre and radius (this defines the hitsphere), and model height (this defines where the health bar goes). Again, you can measure these carefully in Wings3D, or just guess. There are Estimate buttons, but they often need a bit of adjusting afterwards.

To see what your numbers are doing, click on the "3D" to the top left hand corner of the 3D view, and tell it "Draw model radius and height".

[[Image:Upspr_13.png]]

Now all the unit needs is the texture. Click over to the Mapping tab, click Browse for Texture 1, and load your texture from before.

[[Image:Upspr_14.png]]

And there we have the texture, with a teamcolour turret. If you've got a second texture for reflectivity and so on, you can put that as Texture 2.

Now if you're using TGA textures rather than DDS, you'll need one extra step. Click Texture Mapping > Show UV Mapping. It'll show your texture; click Edit > Flip UVs. Close the UV editor.

[[Image:Upspr_15.png]]

Now your texture looks strange and mangled. In fact, this is what your unit would have looked like if you'd put it in game without flipping UVs like that. Once it's in game, it'll be fine. This strange texture-flipping is a consequence of the way DDS files measure coordinates, I think. If you're using DDS, you won't need to do this step.

One last thing: click on Object > Recalculate vertex normals, 3d0 style > All objects, then OK. This'll sort out some normals or something, I'm not too sure what it does but it makes your textures look better.

Now all you need to do is save the model as an s3o file.

And there we have our finished model and texture! Now to get them in game.

== Putting the Unit in a Game ==

The Spring engine uses .sdz or .sd7 files to load game content. In practice, these are just .zip and .7z files with renamed suffixes; to open up any mod, just rename it and extract it. Also, the Spring engine lets you just put all your game files in a folder in your /games directory, as long as it ends in .sdd .

The best place to get started here is to download the [https://springfiles.com/spring/games/empty-mod Empty Mod], extract it to a folder called EmptyMod.sdd in your /games directory. This is basically the bare minimum to get a unit in game.

Open up SpringLobby; if you've put it in the right place and everything else's correct, you should see an entry for "Empty Mod" in your games list. (You might need to tell it to Tools > Reload Maps/Games first.) If you try playing it, it'll put a blank immobile cube at your start point.

To get the tank unit in game, you'll need as bare minimum an s3o file in /objects3d, a texture file in /unittextures, and a unitdef in /units. You already have two out of three; put them in the right folders.

Next, you'll need to make a unitdef. There are two ways of doing this: the old TA-ish way or the new lua way. You can write an FBI file, which is a text file with a list of variables, or you can write a lua file, which is a text file with a list of variables with slightly different syntax. In general, older tutorials and a fair bit of documentation will talk about FBI, but I'm going to use lua instead because it's more flexible and (I vaguely remember) slightly faster. Here's an example lua unitdef:

<pre>
local unitName = "tank"

local unitDef = {
--Internal settings
BuildPic = "filename.bmp",
Category = "TANK SMALL NOTAIR NOTSUB",
ObjectName = "tank3.s3o",
name = "Generic Tank",
Side = "TANKS",
TEDClass = "TANK",
UnitName = "tank",
script = "tankscript.lua",

--Unit limitations and properties
BuildTime = 1000,
Description = "A generic tank unit.",
MaxDamage = 800,
RadarDistance = 0,
SightDistance = 400,
SoundCategory = "TANK",
Upright = 0,

--Energy and metal related
BuildCostEnergy = 100,
BuildCostMetal = 0,

--Pathfinding and related
Acceleration = 0.15,
BrakeRate = 0.1,
FootprintX = 2,
FootprintZ = 2,
MaxSlope = 15,
MaxVelocity = 2.0,
MaxWaterDepth = 20,
MovementClass = "Default2x2",
TurnRate = 900,

--Abilities
Builder = 0,
CanAttack = 1,
CanGuard = 1,
CanMove = 1,
CanPatrol = 1,
CanStop = 1,
LeaveTracks = 0,
Reclaimable = 0,

--Hitbox
-- collisionVolumeOffsets = "0 0 0",
-- collisionVolumeScales = "20 20 20",
-- collisionVolumeTest = 1,
-- collisionVolumeType = "box",

--Weapons and related
BadTargetCategory = "NOTAIR",
ExplodeAs = "TANKDEATH",
NoChaseCategory = "AIR",

}

return lowerkeys({ [unitName] = unitDef })

</pre>

It's worth looking through this and understanding what each entry does. Most are fairly self-explanatory; for the ones that aren't, there's [[Gamedev:UnitDefs | this page]].

Put this file in your /units folder, then open up /gamedata/sidedata.lua and change 'startunit = "cube"' to 'startunit = "tank". Then start up the mod in Spring.

[[Image:Mod_2.png]]

We should now have a model in game! You should be able to select it, and right-click it around the place. It can't attack anything yet, but one step at a time.

We're going to make this tank shoot small orange blobs. For this we need three things: a small orange blob image for it to fire, a weapon entry in the unitdef, and a unit animation script.

For the small orange blob image, I'm going to use flame.tga from Evolution RTS (it's a good game, with models and textures under CC-BY-NC-ND and almost everything else under a do-whatever-you-want license; well worth checking out). It's in the /bitmaps folder of the example mod; put it in your own /bitmaps folder. Next, we need to open up /gamedata/resources.lua and tell the engine we've got a flame texture; just put a line "flame = 'flame.tga' " in the projectiletextures brackets (or comment out the one I've already left in there).

Here's the lua unitdef from before, with the new weapon data in place:

<pre>
local unitName = "tank"

local unitDef = {
--Internal settings
BuildPic = "filename.bmp",
Category = "TANK SMALL NOTAIR NOTSUB",
ObjectName = "tank3.s3o",
name = "Generic Tank",
Side = "TANKS",
TEDClass = "TANK",
UnitName = "tank",
script = "tankscript.lua",

--Unit limitations and properties
BuildTime = 1000,
Description = "A generic tank unit.",
MaxDamage = 800,
RadarDistance = 0,
SightDistance = 400,
SoundCategory = "TANK",
Upright = 0,

--Energy and metal related
BuildCostEnergy = 100,
BuildCostMetal = 0,

--Pathfinding and related
Acceleration = 0.15,
BrakeRate = 0.1,
FootprintX = 2,
FootprintZ = 2,
MaxSlope = 15,
MaxVelocity = 2.0,
MaxWaterDepth = 20,
MovementClass = "Default2x2",
TurnRate = 900,

--Abilities
Builder = 0,
CanAttack = 1,
CanGuard = 1,
CanMove = 1,
CanPatrol = 1,
CanStop = 1,
LeaveTracks = 0,
Reclaimable = 0,

--Hitbox
-- collisionVolumeOffsets = "0 0 0",
-- collisionVolumeScales = "20 20 20",
-- collisionVolumeTest = 1,
-- collisionVolumeType = "box",

--Weapons and related
BadTargetCategory = "NOTAIR",
ExplodeAs = "TANKDEATH",
NoChaseCategory = "AIR",

weapons = {
[1] = {
def = "orangeblob",
},
},
}

local weaponDefs = {
orangeblob = {
name = "Orange Plasma Cannon",
weapontype = "Cannon",
accuracy = 10,
areaofeffect = 100,
avoidfeature = false,
avoidfriendly = true,
canattackground = true,
collidefriendly = true,
collisionsize = 8,
commandfire = false,
craterboost = 0,
cratermult = 0,
edgeeffectiveness = 0.1,
explosionspeed = 128,
impulseboost = 0,
impulsefactor = 0,
intensity = 1,
noselfdamage = true,
size = 4,
-- soundstart = "tank_fire",
-- soundhit = "explo01",
range = 250,
reloadtime = 1.5,
rgbcolor = "1.0 1.0 1.0",
turret = true,
texture1 = "flame",
weaponvelocity = 400,
-- explosiongenerator = "custom:TANKGUN_FX",
damage =
{
default = 55,
},
},
}

unitDef.weaponDefs = weaponDefs
return lowerkeys({ [unitName] = unitDef })
</pre>

Finally, the animation script. This tells the unit what things to move when firing, moving, exploding etc. All we really want at this point is for the turret to rotate and pitch to the right angle.

Again there are two ways of doing this: the old TA-style method, and the new lua method. You've got the choice of writing the animation script in BOS, then compiling it into COB using Scriptor; this is the best-documented method, but it needs the compiler, and it isn't as flexible. The other method is to write the animation script in lua; this lets you reload scripts mid-game without needing to recompile anything, and allows for the whole lua api in your animation scripts (more on lua later). The only real reason for using COB at the moment is "I already have a working game with vast hordes of COB animations, and it would take a long time to change them all". If you're starting out a new game, then lua is really the best option.

here's an example animation script to go in /scripts/tankscript.lua :

<pre>
local base = piece "base"
local body = piece "body"
local turret = piece "turret"
local gun = piece "gun"
local flare = piece "flare"
-- declares all the pieces we'll use in the script.

local SIG_AIM = 2

local RESTORE_DELAY = Spring.UnitScript.GetLongestReloadTime(unitID) * 2
-- picks a sensible time to wait before trying to turn the turret back to default.

function script.Create()
return 0
end

local function RestoreAfterDelay(unitID)
-- defines a local funtion to wait a bit, then move the turret back to how it was originally.
Sleep(RESTORE_DELAY)
Turn(turret, y_axis, 0, math.rad(35))
Turn(gun, x_axis, 0, math.rad(30))
end

function script.AimWeapon(weaponID, heading, pitch)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
-- each time the Signal is called, all other functions with the same SignalMask will stop running. This makes sure the tank isn't trying to fire at something, and restore the turret position, at the same time.
Turn(turret, y_axis, heading, math.rad(35))
Turn(gun, x_axis, -pitch, math.rad(30))
WaitForTurn(turret, y_axis)
WaitForTurn(gun, x_axis)
StartThread(RestoreAfterDelay)
return true
end

function script.FireWeapon(weaponID)
EmitSfx(flare, 0)
end

function script.QueryWeapon() return flare end
-- The piece that the bullet/laser/whatever comes out of.

function script.AimFromWeapon() return gun end
-- The unit looks from this piece down the QueryWeapon piece, to see whether it's aiming at anything.

function script.Killed(recentDamage, maxHealth)
return 0
end

function script.HitByWeapon(x,z,weaponDef,damage)
-- This stops the unit taking damage until it's been built.
if GetUnitValue(COB.BUILD_PERCENT_LEFT)>2 then return 0
else return damage
end
end
</pre>

Now all these files are in the right folders, start the game. You should now have a small tank, able to drive around and shoot at things!

You'll probably have noticed two things. Firstly, the explosion from being hit by an orange blob isn't very dramatic. Secondly, there's no sound. Let's fix the sound first.

First of all, you'll need an explosion sound. I'm using Explosion3 from https://www.partnersinrhyme.com/soundfx/PDsoundfx/gunsbombs.shtml, chopped around a bit in Audacity: again, you can get it from the Example Mod. Put it in /sounds .

Next, we'll need to tell the engine about the sound file. Open up /gamedata/sounds.lua , and add in a new entry, so it looks something like:

<pre>
local Sounds = {
SoundItems = {
--- RESERVED FOR SPRING, DON'T REMOVE
IncomingChat = {
file = "sounds/incoming_chat.wav",
rolloff = 0.1,
maxdist = 10000,
priority = 100, --- higher numbers = less chance of cutoff
maxconcurrent = 1, ---how many maximum can we hear?
},
MultiSelect = {
file = "sounds/multiselect.wav",
rolloff = 0.1,
maxdist = 10000,
priority = 100, --- higher numbers = less chance of cutoff
maxconcurrent = 1, ---how many maximum can we hear?
},
MapPoint = {
file = "sounds/mappoint.wav",
rolloff = 0.1,
maxdist = 10000,
priority = 100, --- higher numbers = less chance of cutoff
maxconcurrent = 1, ---how many maximum can we hear?
},
--- END RESERVED

--WEAPONS

orangeblob_explo = {
file = "sounds/Explosi3.wav",
rolloff=3, dopplerscale = 0, maxdist = 6000,

priority = 10, --- higher numbers = less chance of cutoff
maxconcurrent = 4, ---how many maximum can we hear?
},

--[[DefaultsForSounds = { -- this are default settings
file = "ThisEntryMustBePresent.wav",
gain = 1.0,
pitch = 1.0,
priority = 0,
maxconcurrent = 16, --- some reasonable limits
--maxdist = FLT_MAX, --- no cutoff at all
},
--- EXAMPLE ONLY!
MyAwesomeSound = {
file = "sounds/booooom.wav",
preload, -- put in memory!
loop, -- loop me!
looptime=1000, --- milliseconds!
gain = 2.0, --- for uber-loudness
pitch = 0.2, --- bass-test
priority = 15, --- very high
maxconcurrent = 1, ---only once
--maxdist = 500, --- only when near
},]]
},
}

return Sounds
</pre>

Finally, we need to tell the unitdef what sound to use. Open it up, and in the weapondef, add the line

soundhit = "orangeblob_explo",

Now, if you try the game in Spring, you should get an explosion sound every time an orange blob hits something. To add a sound on firing, do the same, but add

soundstart = "whatevername",

to the weapondef instead.

<span class="warning">Note: If SpringRTS displays errors when loading the sound, try using OGG format instead. See this [https://springrts.com/phpbb/viewtopic.php?f=52&t=36920 thread for more error details].</span>

Now for the explosion. For particle effects like this, there are two ways (the old TA-style way and the new lua way, again). You can write a CEG tdf file defining what sprites and particles go where and do what, or you can use LUPS (Lua Particle System). Now, this time I'm going to recommend the old TA-style way, because it's well documented and I know how to use it (whereas I don't have a clue how to use LUPS, or where to find out how to use it), but more importantly because it doesn't work on some ATI graphics cards. LUPS is much more flexible, but for now it's best only used for aeroplane trails and other effects that people won't complain about if they're missing.

To use CEG, first you'll need to put a tdf file like this one in the /gamedata/explosions folder:

<pre>
[TANKGUN_FX]
{
[groundflash]
{
flashSize = 45;
flashAlpha = 0.9;
circleGrowth = 3;
circleAlpha = 0.3;
ttl = 30;
color = 1, 0.5, 0;
air=1;
ground=1;
water=1;
}
[heatcloud_MED_EXPLOSION_FX01]
{
class=heatcloud;
[properties]
{
texture=explodeheat;
heat = 30;
maxheat = 30;
heatFalloff = 1;
size = 30;
sizeGrowth = -0.3;
sizemod = 0;
sizemodmod = 0;
speed = 0, 1.5, 0;
pos = 0, 5, 0;
}
air=1;
water=1;
ground=1;
count=1;
}

[MOREDOTS]
{
class=CSimpleParticleSystem;

[properties]
{
alwaysVisible=1;
Texture=randdots;

colorMap = 1.0 1.0 1.0 0.05 0.2 0.9 0.5 0.01 0.1 0.8 0.1 0.00;

pos = 0, 2, 0;
gravity = 0, -0.1, 0;
emitVector = 0, 1, 0;
emitRot = 45;
emitRotSpread = 32;

sizeGrowth = 0.5;
sizeMod = 1;

airdrag = 0.8;
particleLife = 5;
particleLifeSpread = 7;
numParticles = 16;
particleSpeed = 8;
particleSpeedSpread = 3;
particleSize = 20;
particleSizeSpread = 0;

directional = 1;
useAirLos = 0;
}
air=1;
ground=1;
count=1;
}

}
</pre>

You'll also need some more explosion images (also shamelessly stolen from EvoRTS), again available in the Example Mod.

You'll need to put these in /bitmaps, then name them in /gamedata/resources.lua . Also in the weapondef, you'll need to put

explosiongenerator = "custom:TANKGUN_FX",

And now, in game, you should have a working moving tank that shoots things! Congratulations!

== Other Small Things ==

In SpringLobby, you'll notice a "Side: 1" option whenever you mouse over one of the players. It's easy enough to change the "1" to something a bit more descriptive of your side, by putting a 16x16 bmp in /sidepics . If your faction is called "TANK" in sidedata.lua, then call it /sidepics/tank.bmp .

Once you have construction units, it'll help if players have pictures of whatever it is they're building. Put these in /unitpics, and put lines in the unitdefs like
BuildPic = "filename.bmp",

== Structure of a Game ==

Before moving on to factories, builders, and other types of unit, I think it's worth going through the structure of what folder means what in a mod file.

* /bitmaps - This contains the .tga files for explosions, lasers, and so on. Each image here needs to be named in /gamedata/resources.lua before it can be used.
** /bitmaps/loadpictures - Any jpg files in here will be shown while the game is loading.

* /gamedata - Lua files defining game information.
** gamedata/armordefs.lua - defines different armour groupings. More information: [[Armordefs.lua]].
** /gamedata/explosions - TDF files for CEG explosions.
** /gamedata/messages.lua - messages given whenever a team loses the game. More information: [[Messages.lua]]
** /gamedata/modrules.lua - various parameters for your game, like flanking bonuses, rate at which experience is gained, etc. Have a look at existing games to see what they do. More information: [[Modrules.lua]]
** /gamedata/movedefs.lua - defines different types of movement (hovercraft, tank, ship etc). More information: [[Movedefs.lua]].
** /gamedata/resources.lua - all the bitmaps in /bitmaps, with names and what they do (are they for projectiles, groundflares, etc)
** /gamedata/sidedata.lua - defines the different factions, and what unit they start off with. In theory, you could do all this with a lua gadget (more on this later), but sidedata.lua works pretty well anyway.
** /gamedata/sounds.lua - defines all the sound files, with values for volume, priority, doppler effect, etc.

* /LuaRules - contains gadgets. These are scripting files that change gameplay; more info later.
** /LuaRules/Gadgets/spawnPlayer.lua - creates a starting unit at the beginning of the game, depending on /gamedata/sidedata.lua . In theory, you could adapt this to generate random units, create whole bases at the start of games, etc.
** /LuaRules/Gadgets/unit_script.lua - this is needed for lua animation scripts to work, for some reason.
* /LuaUI - contains widgets. These are scripting files that change the user interface; more info later.

* /music - contains music for the music widget.
* /sounds - contains sound.

* /objects3d - contains all the s3o models.
* /scripts - contains all the unit animation scripts.
* /units - contains unit definitions.
* /unittextures - contains textures for the s3o models.

* /unitpics - pictures for each unit, shown on build mens.
* /sidepics - pictures for each faction, shown in lobby.

* /[[modinfo.lua]] - defines the mod name, description, and if it requires any pre-existing content.
* /EngineOptions.txt - exactly what it says on the tin. Look at different games to see what they do.

== Other Types of Unit ==

At the moment, you've got a tank unit. This is useful, but for your game, you'll probably need some factories, builders, buildings, and so on (depending on how unconventional your game is). I think the best way to show how to make these units is by example, so here's a basic mod with about one of each:

Load up a game against RAI (that AI works for pretty much any mod, as long as your lua isn't too strange). Then extract it open (it's really just a .zip file), look through the code and see what the scripts and unitdefs are like.

== Lua Gadgets and Widgets ==

Now this is where things start getting really interesting. Gadgets are small lua script files that let you add things to the basic Spring gameplay. And by "things", I mean "anything". Want units that morph into other units? Lua. Want tech trees and unit prerequisites? Lua. Want units that fire other units? Lua. Want meteor strikes and random dinosaurs to spawn out of the map and attack players? Lua. Want napalm? Lua. Want time travel? Well, [https://achrongame.com/ maybe a separate engine designed for RTS time travel would help you better here], but presumably it can be done with enough Lua.

And because it's so versatile, for now I'm just going to point you to [[Lua Scripting | the lists of callouts and callins]] and stand back. Maybe I'll come back to this bit and write a basic gadget tutorial at a later date, but for now the forums are your friend.

It's not very big yet, though, so for more examples just look at the [https://github.com/Balanced-Annihilation/Balanced-Annihilation/tree/master/luarules/gadgets Balanced Annihilation gadget source code].

Widgets are like Gadgets, but instead of changing gameplay they change the user interface. So if you want to add a bunch more buttons along the right hand side, or glowing outlines around certain types of unit, you'd probably use a widget. You can also add widgets to your local copy of Spring that aren't in the mod file itself; this can be useful to give yourself debug information that other players won't have, but bear in mind that it's pretty likely other players will also be using their own array of widgets to enhance their gaming abilities when playing against you.

Have a look at the [https://github.com/Balanced-Annihilation/Balanced-Annihilation/tree/master/luaui/Widgets_BA Balanced Annihilation widget source code] for some examples.

== Maps and Missions ==

Okay, so you've got a working multiplayer game. Now how about single player?

There aren't really any Spring games at the moment with a single player campaign. All the tools are in place, but no-one's actually used them yet. Now, I'm willing to bet that if you manage to give your game a decent SP campaign, and the multiplayer and graphics aren't too bad, it could quickly be adopted as the Spring engine's flagship game. No, I'm serious here.

To make some maps, see [https://springrts.com/wiki/Mapdev:Main Map Development]

For single player missions, there's a [https://springrts.com/phpbb/viewtopic.php?f=14&t=24278 Mission Editor] <s>with a [https://code.google.com/p/zero-k/wiki/MissionEditorTutorial good tutorial] of its own, so I don't need to write one</s>. Enjoy!

[[Category:Game Dev]]