George: objDamage syntax and return values

[alterecco]

Looking at objDamage to document it on xelerus. What is the syntax of the third argument (the one that in vanilla is used as ("pteravores" 0x40). Also, what return values other than 'destroyed are there?

[george moromisato]

The third argument of objDamage is an "objSource" parameter, which is a way of describing who/what caused the damage. This is used in calculations for friendly fire and to generate the epitaph ("Killed by ...")

An objSource parameter can be one of the following:

Nil: In which case, it is assumed to be damage without a cause ("Killed by damage")
An object: Meaning that the object caused the damage
A list: In which case, the list describes more about the source of damage. The list can be in one of two forms:

(noun nounFlags)

OR

(obj [cause [secondaryObj [noun [nounFlags]]]])

nounis a noun phrase representing the cause of the damage. E.g., "pteravores"
nounFlags is a set of bit-values (that may be OR'ed together) to indicate how to use the noun in a sentence. The flags are:

0x01 = Always prefix with definite article ("the")
0x02 = Pluralize the first word
0x04 = Pluralize by adding "es" to the end (instead of "s")
0x08 = Plural form is specified after a semi-colon
0x10 = Pluralize the second word in the noun
0x20 = Article should be "an" instead of "a" or vice versa (only if standard heuristics fail)
0x40 = Do not use an article in the name
0x80 = Noun is a proper name (e.g., "Arco Vaughn")

For the long-form list:

obj is the object that caused the damage
cause allows for alternate epitaphs in case it is not simple damage. Cause can be one of the following:

'damage : This is normal damage
'runningOutOfFuel : This is the normal "ran out of fuel" epitaph
'radiationPoisoning : This is the "died of radiation" epitaph
'self : This is the self-destruct epitaph
'disintegration : Disintegrated
'weaponMalfunction : Killed by a weapon malfunction
'ejecta : Killed by ejacta
'explosion : Killed by an explosion
'shatter : Killed by shatter
'playerCreatedExplosion : Killed by some explosion that the player cause (D'oh!)

secondaryObj should be set to Nil (this is not currently used)

Note that objDestroy and sysCreateWeaponFire also take an (optional) objSource parameters

The return value of objDamage can be one of the following:

'noDamage
'absorbedByShields
'armorHit
'structuralHit (same as armorHit, but for stations)
'destroyed
'passthrough
'passthroughDestroyed (obj was destroyed AND the shot passed through)
'destroyedAbandoned (station was destroyed)