Spring RTS Engine

Since it seems this is not common knowledge here, I'll describe all the weapontypes in Spring, not in full detail.

These are the weapontypes Spring knows. There are no others, every weapon is one of these. I will use the names you can put into the WeaponType tag for easier access, I'll also list other tags that can create such a weapon. They are listed in the order they are decided by WeaponDefHandler so a weapon that fulfills the requirements for two uses the type that's listed earlier. WeaponType overrides the automatic detection completely and always takes precedence.

The weapon patch in rev 4264 changes some of the hardcoded behaviour to be mod-definable but this text assumes Spring 75b2. Please refer to the changelog for the list of changes.

AircraftBomb (dropped=1)
Drops a ballistic projectile (aka Plasma) at the same movement vector as the unit itself. It's only meant for planes. A plane that has a CBombDropper as its weapon1 is a bomber. The CBombDropper automatically calculates its burst and burstrate tags from its reload time and uses 5 as its reload time instead. It will fire if the first bomb would drop within a circle roughly unitspeed*burst*burstrate so the longer the burst and the faster the unit the larger the circle in which it will drop instead of not firing and hoping the next attack run will pass that circle.

StarburstLauncher(vlaunch=1)
Fires a projectile that rises vertically (starts with no velocity) for <weapontimer> seconds, then turns at a fixed rate towards its target. The projectile's lifetime depends on its range divided by its max speed (ignores acceleration) and the weapontimer somehow so the weapon can fall short depending on how these values are set. This is the only weapon that can properly perform intercepts and be interceptable. Emits a smoketrail.

BeamLaser (beamlaser=1)
Should be well known, this thing spawns a beam and does a portion of its total damage each frame. It can't have a burst or burstrate, it can't have collidefriendly=0, it can't be emit-sfxed if it has a beamtime longer than one frame and its damage decreases over range if the minIntensity=1 tag isn't used. The largebeamlaser tag allows changing the visual effect of the laser, doesn't affect the behaviour of the weapon itself in any way though. Beamlasers can be really annoying... BTW, their beam doesn't collide with water so if they're set to waterweapon=1 they can shoot normally even when underwater (won't shoot at underwater targets though).

Shield (isShield=1)
The shield. Really not much to say about this, the tags are all documented in the changelog.

TorpedoLauncher (waterweapon=1)
Fires a projectile that will behave ballistically out of water and like a missile in water. Since waterweapon=1 is usually set for them they can fire underwater and they will target underwater units. The torpedo is the only projectile that doesn't explode on the water surface. An aircraft carrying a TorpedoLauncher is a special case, the thing turns into a bomb dropepr that will spawn a torpedo projectile, probably to get the whole bomber flight behaviour. Note that the waterweapon tag is also used to make a weapon fire underwater, independent of its type.

DGun (weaponname contains the word "disintegrator")
This shoots a fireball that travels in a straight line. The fireball has no range limitation by itself so if it misses or is fired in FPS mode it will travel across the whole map and further. DGuns don't properly check their line of fire, if terrain is in the way they fire anyway. These things are meant to be used with noexplode=1 but of course you CAN use them without that, too. If ballistic=1 is set the fireball will be affected by gravity, the weapon won't compensate for it though so it will hit the ground before reaching the target. Might be useful for a Scorched Earth mod or something since you'd have to aim it manually to hit anything.

LightningCannon (sic) (lineofsight=1 and rendertype=7)
An instant hit weapon like the Beamlaser except with a lightning graphic and even more annoying. It won't damage shields and it has a hardcoded inaccuracy (comparable to targetMoveError, the code comment is "should make it weaker against air"...). Shares some of the weirdnesses with the beamlaser, e.g. being able to penetrate water.

LaserCannon (lineofsight=1 and either beamweapon=1 or weaponname contains "laser" (marked as "workaround for SWTA))
The OTA-style laser. Probably one of the least annoying weapons in the engine. Its length is defined by the duration tag (together with the speed), BTW.

MissileLauncher (lineofsight=1 and smoketrail=1)
Shoots a smoke-emitting projectile. It can use guidance, acceleration, etc. The projectile's lifetime depends on range/maxspeed so a slowly accelerating missile will fall short. It can also use trajectoryheight to have the shot arc but that has trouble with aiming at targets higher or lower than the shooter (see bug report, this REALLY could use some fixing). Pretty versatile weapon overall, if the laser rendering code was ported into this we could pretty much axe the LaserCannon completely.

EmgCannon (lineofsight=1 and rendertype=4 and color=2)
Few know about this, it's a line of sight (i.e. not ballistic) weapon that can use billboard rendering (looks like a sprite). No idea what drawbacks this has, noone ever uses it.

Flame (lineofsight=1 and rendertype=5)
The flamethrower. A really annoying weapon. AFAIK it won't even aim ahead of moving targets. Can't say much else about it since I haven't tried using it much but overall I'd avoid the weapontype and fake the effect somehow, it's not pretty when fast and won't hit jack when slow.

Cannon (anything that didn't trigger another weapon)
Aka plasma. Shoots a ballistic projectile. Unlike the DGun it aims properly. Can't be emit-sfxed properly, maybe a ballistic DGun can fill that role.

Melee (only reachable through WeaponType)
When it fires it simply damages the target, no ifs or buts. It doesn't use a projectile and doesn't care about the line of fire. It won't even report a proper heading and pitch to AimWeapon so if you plan on using it in 75b2 you have to slave it to another weapon to handle the aiming. May be useful to be the damage dealer for a cosmetic weapon, i.e. you slave the Melee to a weapon that does no damage but looks pretty and the Melee does the damage. Kinda like the weapons in Warcraft and so.

Rifle (only reachable through WeaponType)
An instant hit weapon but an apparently unmaintained one. It has a hardcoded firing and explosion effect. I wouldn't use it.

CNoWeapon (weaponname is NOWEAPON, not reachable by any tag)
Apparently a placeholder used when a weapon isn't present. It's not really a weapondef but generated when the unit demands a NOWEAPON.

Sticky this? Very handy.

KDR_11k wrote:EmgCannon (lineofsight=1 and rendertype=4 and color=2)
Few know about this, it's a line of sight (i.e. not ballistic) weapon that can use billboard rendering (looks like a sprite). No idea what drawbacks this has, noone ever uses it.

The color=2 happens even if you force the weapontype- aka your projectile gets coloured yellowish.

Stuckied.

There's also the reference here:

http://spring.clan-sy.com/wiki/Weapon_Variables

Although some of it is out-of-date or otherwise incorrect, and should be fixed, or even better yet, moved to the appropriate Wiki sub-sections.

Many things need to be added, like CollisionSize (very, very important variable) ExplosionSpeed (ditto) EdgeEffectiveness (now that it actually works, it's important), and Collide / Avoid Friendly / Feature (very important).





About the FlameWeapon... it's affected by TargetMoveError, and by the relative velocity of the projectiles, like other line-of-sight weapons.

Aiming problems reflect the fact that people tend to give it a range and velocity which aren't suited for first-shot hits, and tend to give it plenty of Tolerance.

The hard thing with the weapon is that it's the only really good simulation of a flamethrower that fires a cone that we have, so people tend to just use it for that. However, it's actually extremely versatile, and can be used for lots and lots of other things. In PURE, for example, I use it for shotguns, and for linear plasma that changes color as it moves (that doesn't change size, because it doesn't have to, btw). It does not have to just act like a flamethrower, and is extremely versatile, with the caveats that it cannot be ballistic, nor use the drawing method for Beamlasers, which I wish it could, because I hate straight billboarded sprites.

KDR, you did not mention the SizeGrowth tag, which is very important to how this weapon functions, or the various graphical things it can do, such as ColorMap (it was the first thing to have ColorMap applied), FlameGfxTime, which allows it to "fade out", or other factors. And you've dismissed it, when I've been using it for shotguns, flamers, and many other things, and it works just fine, so long as you are aware of how it works.

Sorry, if I seem a bit miffed / defensive, but between me and Yeha and JC, we spent quite awhile making it work like we wanted it to, and I think it works great, so long as you understand what you're doing. It's probably the single-most versatile weapon, visually and in some ways game-design-wise, in Spring.

While I agree that most Spring weapons still have some stupid code in them (the hardcoded TargetMoveError for LightningWeapons, for example, should be changed to strict TargetMoveError, that's quick fix), it's just not fair to write off a weapon that you admit you haven't tried using much, especially as it actually works like it was designed to, and so far as I know, has no "legacy code" from SJ sitting in it.

Be nice if it lead targets though.

It can... just set TargetMoveError to 0, then it leads as well as anything in Spring leads. Which is not perfect, especially for low-velocity stuff, but it's impossible for it to be perfect anyhow.

Argh, tolerance does nothing for turreted weapons, it's just the aiming cone angle in TA angles for turret=0 weapons. You get the same effect by using WeaponMainDir and MaxAngleDif (except the weapon won't be shooting only straight forward that way). TargetMoveError is multiplied with the target speed and added to the accuracy calculation, it should not have an effect on leading the target (and I just tested it, it doesn't). The flamer is simply missing the predict code that lets it aim ahead of the target.

Also note that this is more to tell people what types exist, not their usage. I didn't explain the beamtime for beamlasers or the whole bunch of options for lasercannons, either.

Argh, tolerance does nothing for turreted weapons, it's just the aiming cone angle in TA angles for turret=0 weapons.

<tests>

You're right, and that's not how it should work. Tolerance / Pitchtolerance were supposed to give us a conical tolerance for firing solutions, to allow for a margin of error and allow weapons with a bit of trouble achieving accurate-enough angle-of-aim to satisfy their requirements!

Instead, there seems to be some sort of fudge-factor being used, that is universally applied!

That's not right, why was it changed? It used to work, and it has a definite purpose. No wonder I've been seeing "vibrating aim" on certain weapons with long distances between the fulcrum and the piecenum

There is no way to make tolerance apply to the aiming direction, you cannot know where to apply tolerance and almost everything would break if suddently turn bla to x, wait for turn no longer meant bla is turned to x. Only reaiming if the target position moves more than <tolerance> degrees fucks any script that includes loading animations, charging, script limits, etc up. I really doubt that it ever worked the way you describe it because there's no way for that to work without making any complex script impossible.

Pitchtolerance doesn't exist, BTW.

There is no universal fudge factor, AimWeapon is simply called every SlowUpdate, if the script in AimWeapon returns true the weapon fires. That's all there is to it. If the weapon manages to turn to the heading it was given it will shoot, even if the target has moved away.

Vibrating aim has nothing to do with any of this, it's because the aim direction is calculated from the QueryWeapon piece and that angle can change during the aiming process. If the target is close enough the angle will oscillate fast enough that the aiming never finishes.

figured I could do some explaining on some tags, too.

--------------------------------------------------------------------

--------------------------------------------------------------------

note that this may not work well with beam weapons, use minIntensity (0..1) tag to fix that.

to be continued

KDR_11k wrote:stuff

Argh is right though. Tolerance used to work, and it was quite visible when we had visualised firing cones. It's also important.

I remember visible cones being in SVN for 74 or 75, tolerance didn't have much meaning then either. What's it supposed to do?

It did what I said it did. Please do not presume stuff, or imply that this was stupid, or that I don't know what I'm talking about.

What did it do? I've already explained that, but lemme draw ya a picture, maybe this will make it clear:



Basically, when aiming, the engine projected a cone from the aimpoint that was used to check and see if a weapon had satisfied the aiming conditions. As you can see, in my picture, the green line does not satisfy aiming requirements, but the red cone (shown in mspaint glory, I'm not at home) intersects the circle, resulting in a valid firing solution.

Why two values? Because sometimes you want a weapon to satisfy differently in radians X than it does in radians Y. There never has been a tolerance for radians Z, because all OTA stuff, and Spring stuff for that matter, always assumes a rotation Y and X to arrive at any possible firing solution (which I personally don't like, but live with). Tolerance / Pitchtolerance was in OTA, and it wasn't there because the programmers were stupid

This is something OTA had in it, for a very important reason: without this test, weapons like Berthas tend to wiggle a lot, because while visually they look correct, insofar as players are concerned, mathematically, they aren't perfectly aimed. Add in the small errors introduced by LOS calcs and checks for movement, and you end up with a weapon that seems to wave about a lot, trying to satisfy aiming conditions. Tolerance gets rid of this problem, by allowing the unit to satisfy even if it's not perfect, resulting in smoother aiming.

And yes, this results in weapons that do not aim perfectly... but that's OK. A Tolerance of 500, for example, was more than enough to keep most weapons from wiggling too much, but was tight enough to result in hits during most aiming sequences. And if not, you could always tighten it up, requiring a higher degree of accuracy, at the cost of some wiggling.

There are other, very important, uses for this. A high tolerance value (i.e., less true accuracy) can be used for flamethrowers and machineguns, where, for gameplay reasons, it is often best to have the weapon start firing early at a given target, because then it will arrive at a proper position... or, against a fast-moving target with a slower turret, it will never really aim correctly, but will open fire anyhow, and with Accuracy values of a certain level, you can cause the weapon to hit occasionally, but not every time the weapon opens fire- which sounds minor, but is actually kind've important for certain types of gameplay.

I used Tolerance, when it still was in Spring, very extensively in NanoBlobs, and I'm kind've annoyed to find it's been completely removed. That whole "oscillating barrel" behavior you're referring to is exactly what Tolerance was designed to handle... but there are other rather cool uses for it.

The whole visible cones thing was something Trepan put in, and then removed, apparently because of some lame whining from somebody who doesn't even build games with the engine, even though I said at least twice how useful it was

Finally an Argh post I can 100% agree with?

@imbaczek:

TargetBorder defaults to 1, correct?

CylinderTargeting defaults to 0, correct?

For a typical Unit, firing a lineofsight weapon such as a Beamlaser, what are the advantages, if any, of using CylinderTargeting, and why would we use targetBorder for anything except for maybe AA weapons (to improve leading) and for hand-to-hand? Is targetBorder more or less efficient, computationally?

Gonna have to test all this, I think- I haven't messed with it, so I'm using whatever the current defaults are (it's all working pretty well, but I think that targetBorder may be partly responsible for the whole "my Units attack stuff that isn't showing up in LOS yet" problem I was alluding to earlier, now that I've looked at what it does...

@FLOZi: <shrugs> probability said it had to happen someday. Besides which, did you never see the crazy things I did with Tolerance with the Mechpack II units? I had a unit that would fire a ring of explosives around itself, with a Tolerance of 65536 and Accuracy of 65536, a fixed velocity, and Spin- one of several things that has never, ever, even slightly worked right in Spring...

I'd never noticed you before Spring in all honesty. I gave up on OTA units a very long time ago to concentrate on AATA and TACW.

Is it just me, or did I just derail the thread?

Ok, weapons...

So, like... other than dancing missiles and stuff, KDR... ya wanna hear my wishlist? Tell ya what, instead of offering one... here are a few things I'd like to see changed. I have some other ideas that would be simple to add to Spring now that I know a bit more about how it all works (for example, I can give you the sketch of a weapon that lasts more than one frame now, it's really easy, we just need a class set up and a way to get it from the TDF parser).

Anyhow, enough idle chatter. If you could, please go ahead and fix the LaserProjectiles, like you suggested in the Request thread. It's easy:

Change the current drawing code in /trunk/rts/Sim/Projectiles/WeaponProjectiles/LaserProjectile.cpp // void CLaserProjectile::Draw(void) to this, please:
And then just add the colormap support:
And remove the references to texture2, intensity, etc. (you need to remove this from the Sim/Weapons/WeaponDefHandler.cpp, I know you know this, but other people may not yet), and it's pretty much done, and this particle class would render more efficiently and look better, too.

While I'm talking about things that annoy me... there is a big problem with FlameProjectile that I did not mention earlier, in my defense of that projectile type. FlameProjectile does not currently check collisions correctly for Features (it always ignores them). This could be fixed by adding / modifying the following functions:
... which would fix the problem of FlameProjectiles not being able to, among other things, SET TREES ON FIRE. Which has always annoyed me. Never you mind that Trees are Features, and thus must obey all Feature-related collision and damage events (dammit, for the last time, all of these things should be Units, so that we can just set up an Armor table, get rid of tons of extra code we really don't need, and make Spring more efficient, able to support animated Features, and simplify maintenance, to boot...).

Oh, and while you're at it, could ya maybe get rid of this line, or make it available as a variable? ... I didn't realize that the rise was hard-coded, that explains a couple of goofy things. It'd be best, IMO, to add a new TDF tag, "projectileRise", or something, and make it something that can be done to any WeaponProjectile in Spring, frankly. That'd require some standardization however (another topic, for another day- but the long story short is that most weapons have about 30% code duplication for common tasks that still hasn't been made into an #include yet, which is one of the causes of things not obeying what the modders assume is a tag that will work for everything, and the arguments about efficiency should be had at some point- I don't think I'm qualified to judge that one, but we might want to talk about it).

There's other stuff I'd like to do... um, can I make suggestions, and help you get this stuff fixed, if I offer at least somewhat-ok code to get going with? I do not have time to post full diffs, I am on a very limited time-budget right now, but I realize that you don't want to do work that I want done just on my vague sayso... say no if you must, but I really would like to add a couple of weapon types that should be very easy, and fix a lot of the problems with the current ones (which are mainly being caused because each class of weapon has not been standardized to respect all tags, etc., so most of it's easily fixed by copy-pasting code, with a few exceptions).

[EDIT]Added code removing Intensity support, added line for proper colorMap support. Added line supporting thickness, including default value, see code below.

Here, lemme add more stuff about the LaserCannon fixes, I'll give ya most of the code (I think, mind ye, I haven't edited the headers, don't forget, and I may have missed something- by all means, this must get tested):

With LaserCannons, let's finally, totally remove legacy support. Waste of CPU time and resources, and we can leave a safe default for the truly lazy. I know we're going to hear whining, so here at the end, lemme offer all OTA modders a hotfix.

Firstly, get rid of support for color1 / color2 and intensity, which aren't necessary any more. From LaserCannon.cpp:
Secondly, in WeaponDefHandler.cpp, change this section:
...dropping texture2, which we no longer need, and adding safe Colormap support, making all LaserCannon shots red unless specified otherwise.

Next, we'll remove the 5-frame intensity falloff... that can be done very easily with Colormap anyhow, in fact Colormap would allow it to fade over the entire duration of the flighttime, if we want, which most people won't.
Finally, we need to change texture1, the "laserfallofftex", to a safe, new alternative laser beam texture that still looks pretty much like the old one:



...which I hereby release under CC, no restrictions, blah blah blah. Please, just use it. I can make a prettier one with Photoshop when I get back home, this was a rework in GIMP, needs an identical alpha channel added and made into TGA.

Next, we need to give all of the modders, who don't seem to get / use colormap, to actually use it. Easy enough:

Here's a red laserbeam:
Here's a green laserbeam:
Here's a blue laserbeam:
Here's a yellow laserbeam:


... that covers OTA colors, but if ya want more, here's...

... A purple laserbeam:
... An orange laserbeam: ... that covers all of our primary / secondary colors.

So, there ya go, people. No more OTA backwards-compatibility, fix your mods really quick, it won't take long, the average OTA mod has maybe 30 lasercannons in it, and uses all of 4 colors.

But, wait... we can do sooo much more here... because colorMap is so flexible.

How's about a laser that start white, then fades to blue with a touch of green?


[EDIT]Removed intensity entirely. Added default value for thickness to WeaponDefHandler (there wasn't a default before, lol).

Your long explaination about tolerance has confused me a lot but I think I can figure out what you want: wait-for-turn in an AimWeaponX function would terminate when the turn is closer than <tolerance> to the final rotation. You can just write your scripts to act like that without needing the engine to enforce another hacky special rule. Weapons don't care where you turn the unit, it's just assumed that when AimWeapon returns true the weapon is lined up so the shot is always aimed at the target location, even if your turret points the other way.

why would we use targetBorder for anything except for maybe AA weapons (to improve leading) and for hand-to-hand? Is targetBorder more or less efficient, computationally?

It's meant for mods with huge units like those Gundam epic coms or weapons with really short ranges. Computationally it's no different to not using the tag (unless your computer is so slow that one addition makes a notable impact). It does not change leading in any way, it only makes a unit count as in range if the edge of its collision sphere is in range, not the center. Default behaviour is aiming at the center and it does not affect LOS in any way.

Instead of posting code here you shoud either say what exactly you changed or just post a patch for the changed code, don't post arbitrary sections of code, I have no idea what you've changed there and I won't touch code like that. Beamcaps would be easy to fix but I was asking for what should trigger their removal. I'm not just going to remove them completely, there's valid reasons for having them there.

Breaking legacy support like that is a bad idea, there's no reason why intensity and the color tags would need removal, it'd only piss 99% of the modders off because they were using those tags and don't want to adjust them for hundreds of weapons. There's no reason to remove them, after all other areas of the code support colormaps without breaking other tags.

You're setting deleteMe without checking for noExplode, BTW, which would break that tag.

Argh wrote:@imbaczek:

TargetBorder defaults to 1, correct?

CylinderTargeting defaults to 0, correct?

No and yes. Default targetBorder is 0 and the double t in the other tag needs to be fixed if it isn't already, I keep forgetting about it

As for efficiency, targetBorder is a little bit more expensive; also I think the whole cylinderTargetting image is wrong I mixed it up, it changes the range sphere into a cylinder, not the target hitsphere. It's been done specifically done for Melee weapons. I'll fix the image in a minute.
edit: fixed image: