documentation (split from pending stuff)

[Caydr]

Please document these changes better:

- Added modinfo.tdf 'version', 'mutator', and 'shortName' tags (What are they for? Where are they used? What happens if they aren't present?)

- Added the following to modrules.tdf (default values shown):
[DISTANCE] {
builderUse2D=0; (what is this?)
}
[EXPERIENCE] {
powerScale=1.0; (power scale? what's that?)
healthScale=0.7; (same)
reloadScale=0.4; (same)
}

- Added optional 3D ranging for all builder operations (build, repair, reclaim, etc...) (per-unitdef buildRange3D=true) (what does this do?)

- adds [flankingBonus] { defaultMode = 1; } to modrules
- replaces the old bonus shield system with flanking bonus
- new unitDef parameters:
int flankingBonusMode
float flankingBonusMax
float flankingBonusMin
float flankingBonusMobilityAdd
float3 flankingBonusDir (Please explain what this all means)

- Added the "canSelfDestruct = true" unitDef tag (I think I know what this is but I've never seen a true/false FBI tag, only 1/0 ones)

- added the weapon tag leadLimit that limits the maximum distance a unit will lead a target
(default is -1 which means infinite). (what is this?)

- added the weapon tag predictBoost (default 0 for non-burnblow, 0.5 for burnblow weapons) which fixes the
"this should be turned into a separate tag" comment in Weapon.cpp. No idea what it does but it doesn't
break anything. (How can you be sure it doesn't break anything if you yourself admit you have no idea what it is? Can someone do some research on what effects it has and how it is to be used?)

Thanks

[lurker]

Added modinfo.tdf 'version', 'mutator', and 'shortName' tags (What are they for? Where are they used? What happens if they aren't present?)

Big sticky in Mods forum: http://spring.clan-sy.com/phpbb/viewtop ... 14&t=13053


- Added optional 3D ranging for all builder operations (build, repair, reclaim, etc...) (per-unitdef buildRange3D=true) (what does this do?)

If it's 2D, the builder can construct in an infinitely high cylinder, and if 3D in a sphere.


- Added the following to modrules.tdf (default values shown):
[DISTANCE] {
builderUse2D=0; (what is this?)

Probably a sort of default to buildRange3D. EDIT: I can't find this code anywhere.


[EXPERIENCE] {
powerScale=1.0; (power scale? what's that?)
healthScale=0.7; (same)
reloadScale=0.4; (same)
}

These are multipliers to what effect experience has. If powerScale is 1.0, then the unit's power will approach a 100% bonus as the unit gains experience, etc. Apparently power is just a generic value number used for things like experience calcs. Health is obvious, and the reload time of a weapon is divided by (1.0 + the boost from experience * reloadScale).


- adds [flankingBonus] { defaultMode = 1; } to modrules
- replaces the old bonus shield system with flanking bonus
- new unitDef parameters:
int flankingBonusMode
float flankingBonusMax
float flankingBonusMin
float flankingBonusMobilityAdd
float3 flankingBonusDir (Please explain what this all means)

Did you read the wiki page I wrote on it? http://spring.clan-sy.com/wiki/Units:FlankingBonus


- Added the "canSelfDestruct = true" unitDef tag (I think I know what this is but I've never seen a true/false FBI tag, only 1/0 ones)

It's the same as the other bools, so 1/0 works.


- added the weapon tag leadLimit that limits the maximum distance a unit will lead a target
(default is -1 which means infinite). (what is this?)

This is the behavior where weapons will predict the movement of units and aim ahead. The perfect example of using this tag is to set punishers to a number like 150 so they don't shoot backwards into your base.


- added the weapon tag predictBoost (default 0 for non-burnblow, 0.5 for burnblow weapons) which fixes the
"this should be turned into a separate tag" comment in Weapon.cpp. No idea what it does but it doesn't
break anything. (How can you be sure it doesn't break anything if you yourself admit you have no idea what it is? Can someone do some research on what effects it has and how it is to be used?)

Whoever wrote up the changeset didn't know what it was, not the person who wrote the code.
This is the same prediction behavior that the previous tag addresses. There was previously an interesting bit of code that cut the aim-ahead of flak and other weapons with burnblow in half. Now we have this, where the aim-ahead is multiplied by (1.0 - predictboost).

[Caydr]

I appreciate you going to the trouble of posting that, but what I'm also concerned about other/future mod makers. Can the changelog be updated with that information?

[lurker]

Let's put the changelog up on the wiki.

[Tobi]

Let me quote myself for the 100st time: a changelog is not meant as documentation. A changelog is ment as a summary of the SVN changelog, to provide a quick overview to anyone interested in the changes made. Not to provide full fledged documentation including examples, argumentation as to whether something is done X and not Y, not to explain the used algorithms. After all a changelog has a way too broad target audience to turn it into documentation.

If you don't know how to do something in MS Word, you look in the changelog? No, you look in the HELP.

So, document in trunk/Documentation or on the wiki please thanks (or in SVN log if you're a dev and CBA to write real docs, but IMHO that's bad habit too)

[Caydr]

Yes that's what I'd like too, but often nobody does anything like that and it's left up to experimentation.

That's not so bad, but then what happens a year from now when that feature's still not documented and those of us who could answer might not be around anymore and some newbie modder is left with a list of "dunno what this does" changes, or worse, change nobody remembered to document in the first place?

I don't care where the stuff is written down, just as long as it's somewhere central and easily located. I get too many emails from people who want to know, for instance, what pitchtospeed or whatever those tags JC added do. He could search and find Argh's analysis but I tested what he wrote and it's not accurate. I have to answer, only JC knows and he's not around anymore. That's not good for anyone, and those tags would probably be very helpful.

[SinbadEV]

Could we start a glossary style wiki section devoted to documentation of this nature... basically start with the most recent changelog and make each change a link to a page that explains the behavior adjusted by the changelog, when a new change superseded an old change then the target page would be updated... Some changes would just be linked to current pages on the wiki and the target page could be updated...

I know devs aren't really necessarily interested in updating the information so I would expect the community to do the linking for anything that is readily apparent or can be gleaned from posts or the mantis.

I'm really liking this approach and it would be a good start... hmmm...

[SinbadEV]

http://spring.clan-sy.com/wiki/The_Talking_Changelog <- What I Made

edit: -fixed the formatting a bit

http://spring.clan-sy.com/wiki/Using_chat <- An Example of what I want to see

[Caydr]

Sheesh, we need a proper expandable web site layout... there's not much to do, just rebuild the tables and insert some.... stuff... I'd do it.

[clumsy_culhane]

Let me quote myself for the 100st time: a changelog is not ment as documentation. A changelog is ment as a summary of the SVN changelog, to provide a quick overview to anyone interested in the changes made. Not to provide full fledged documentation including examples, argumentation as to whether something is done X and not Y, not to explain the used algorithms. After all a changelog has a way too broad target audience to turn it into documentation.

If you don't know how to do something in MS Word, you look in the changelog? No, you look in the HELP.

So, document in trunk/Documentation or on the wiki please thanks (or in SVN log if you're a dev and CBA to write real docs, but IMHO that's bad habit too)

good post, i agree, on all but one thing. Meant is spelt meant, not ment.

[Tobi]

fixed