Spring RTS Engine

I would like to have a dummy file that shows how to set up weapons and there projectiles.
Ive looked around but i havent found anything regarding the syntax of it. Would be nice if someone yould help me a bit.

You pretty much have 2 general approaches:

1.)
You choose the Lua approach which means your unit definition files are written in Lua syntax where the weapon definitions can be put just right into the unit definition file. I attached the armpw.lua file from CA as an example for you...

2.)
You do the unit definition in the FBI style and use definitions that you write into files in the mod's "weapons" directory. This might be the easier method to understand...

I attached the ARMPW.txt as an example unit definition file and the vhlt.txt as a weapon definition file (note - while both files are plain text files and nothing more they need special file endings to work - forum attachment forbids unkown endings though and that's why I had to rename them)...

The unit definition file (here ordered in alphabetical order) features all the definitions for the unit like how much it costs, what it can do and so on. There you'll find the line "weapon1=EMG;". That applies the weapon with the name "EMG" as the first unit's weapon...

In the vhlt.txt you now see a weapon definition. It starts with a [VHLT] which is the name you want to give to the weapon. It's followed by a "{" which pretty much says that here the weapon's definition starts and after all the bla bla there's a "}" at the very end. So you actually could do many weapon definitions in one single .tdf file by just putting them below each other. Inside those brackets there are all the weapon definitions - some are self-explanatory some are not...

You can find the available tags as well as a description of their meaning in the Wiki - i.e. for example HERE. The same goes for the FBI definitions you e.g. can look up HERE. I say e.g. because some additionals details are a bit scattered on different pages. Just go HERE to have a look at what's currently been written about that topic...

I hope this has been helpful...

I highly recommend that you use the lua format if you're starting a new mod. In fact, use lua for unit scripting too. IMO, it's easier to learn this one language since you can use it for pretty much everything now.

I heard a lot about Lua by now, it really seems to be preferred. What does it do essentially? Is there a starters guide on it?


Also the example Lua file is a bit messy. I can hardly seperate it into different parts.

Also the example Lua file is a bit messy. I can hardly seperate it into different parts.

Yeah - that's imo a disadvantage of the Lua system for unit definitions: You have lots of things put in one file...

The example file starts with some general unit definitions i.e. how much does it cost, how much health does it have, what's its name and so on. The big textwall right in the middle of that is something specific to the game CA where they applied multiple language versions of the unit's description you get ingame...

The general definitions end in line 86 and are followed by definitions for the weapons the unit is going to use which goes up to line 135. The last "featuredefs" part is about the corpse a unit will leave when it is destroyed. When you scroll up to the unit definitions you'll find a line saying Thats why in that featuredefs part this "DEAD" now gets defined in line 140f. It consist of some details about the wreck the unit should leave when being destroyed like which model to use for that or how much resources you get when you reclaim the wreck. You won't just find a definition for the "DEAD" corpse but also one for "DEAD2" and "HEAP". That's because Spring supports the destruction of such corpses by weapons. So e.g. in the inital definition of the corpse feature called "DEAD" you'll find this line This means that once too many damage was dealt to the corpse (depending on the damage value you give it) the corpse gets replaced by a new one - in this case by the "DEAD2" corpse...

So in this case it was decided to do this sort of "development" for the corpse when being under fire: DEAD -> DEAD2 -> HEAP

You actually don't need to leave any corpse or do multiple stages of destruction levels for it - if you want to use something like that depends on your game and if it makes sense there to e.g. have corpses that block your units but can be reclaimed or simply blown away to get clear the path...

As for regarding the entire file and all the tags that got used there: In the end you just have to look up what each of them does. Their names usually give you an immediate clue of what they are for so that shouldn't be that hard to figure out...

So i now coded the unit as a Lua file, but it crashes on loading.
What do i need to do to make my script work?
(i know there was something to be done but i cant remember where i read it.)

fwiw, if you are using lua defs there is nothing stopping you having seperate myawesomeweapon.lua def files in the weapons subdir.

So i now coded the unit as a Lua file, but it crashes on loading.
What do i need to do to make my script work?
(i know there was something to be done but i cant remember where i read it.)

1. Make sure that if your script refers to any sounds or bitmaps (through CEG effects) those resources actually exist, and are referenced properly in their respective files.

It is not required to have either.

2. There are no requirements for a Feature, if the Unit dies, but I am fairly sure Spring still crashes if that referenced object doesn't exist.

3. Readability of Lua files is actually really arbitrary. You can use whitespace and comments "--" for single lines and "--[[ ]]" for blocks to make things cleaner.

okay i got it working so far.
To add another question:
Where can i set the point the bullet leaves? It currently leaves from the base of the turret not from the end of the barrel.

Also where can the firing angle be set? (it can shoot at almost 180 degrees by default, the turret turns fully afterwards)

To set the point the bullet leaves, go into your script, and add the following: Don't forget to also add the Piece name "flare" to the list at the beginning of your script, i.e.:
Then put a point object into your S3O with UpSpring ("add empty object"), and name it "flare".

As for firing angle... it really depends on what you want it to do. You can lock down turret arcs, but it's not entirely straightforward. Give us a bit more explanation.

Is that code for Lua? And where to add ir exactly?
i added it to the main section and weapon section, but it didnt change anything (yes i have a flarepoint)


Also i wanted the turret to fully turn and not to start firing when turing already.

Argh's code is for the COB approach (although the Lua equivalents don't look that much different)...

Concerning weapons you have four functions which handle everything:

• AimWeapon1 (heading, pitch)
• AimFromWeapon1(piecenum)
• FireWeapon1()
• QueryWeapon1(piecenum)

The AimWeapon part is about giving instructions what to do when the unit tries to aim. To give an example for a tank: I'd say ignore the two lines in the beginning about the signals for now. The AimWeapon1 function "gives" you the values "heading" and "pitch" representing how much the unit has to aim left/right and up/down. That's why in this aiming script their are used to torn the tank's turret left/right with the heading value and the sleeve up/down using the pitch value (actually you subtract the pitch value from "0" in order to get the "right" algebraic sign). The speed values say how fast things are going to rotate...

The actual "turn the respective pieces until they are in the right position" orders then are followed by "wait-for-turn" orders making the script wait until the rotation is done before proceeding. Once that's done - i.e. once the turret & sleeve are aiming in the right direction everything is fine and you want to tell the engine that the unit now is ready to fire. You do that by returning a "(TRUE)" or just a "1" if you prefer this over writing out the TRUE...
We already have discussed the actual aiming. We still need to tell where from the unit should aim i.e. from which point of the unit the actual left/right and up/down angles should be determined. That's what this function is for and you just can give any piece your model consists of for that...
This function tells what happens what should be done immediately after a weapon has fired. In this case the barrel rocks back and then slowly moves back to the initial position...
The last thing missing is from which spot the actual missile, projectile, laser or whatever weapon you made should be emitted. In this case it's the part called "firepoint" you'll most certainly want to put at the barrel's end...

As a final comment something about pieces and those signals in the aiming function. At the beginning of your script you have to write down of which pieces your model consists. This might look like this: You also should define the signals at the beginning of your script like this: So in the end you sort of apply a unique number to the SIG_AIM constant. But why would you need something like this at all and just for the aiming part? You need it because the aiming function gets called afaik two times a second. To make sure you don't have multiple aiming functions running at the same time fighting each other you use those signals which will kill other running threads of the function. That's why you define a signal for each weapon you want to have and apply a unique number or "bitmask" for that manner to them...

Does this belong in the unit def? or do i need to create a script for it?
(currently im using a lua definition for unit and weapon and on scribts there is a .cob thingy). How will the script look as a whole?

Everything I worte here belongs into the unit's script and is written in COB language. The ideas behind it are the same for the Lua version though and probably even have nearly the same function names...

The pure unit definition file actually only consists of some tags with some values - no script logic or anything like that...

Concerning some actually complete Lua unit scripts I don't know of a really good learning example for this - it has been officially there for just a couple of days anyway. But maybe have a look at this to at least have a working example:
http://spring1944.svn.sourceforge.net/v ... RTiger.lua