ImmoMan's Module Guide

DeeZire · 03-07-2004, 08:48 AM

Very very nice indeed. Well written

I still have not got round to completely disecting the programmers docs into a form that mere humans can understand but am working on it.

However, in the meantime I thought I'd answer some of the trickier questions that are at the bottom of ImmoMans Guide in a bid to plug some gaps in whats already wide knowledge

I havent answered stuff like 'does this upgrade module use RequiredStatus etc since most of those can be figured out anyways - go and try it out!

What does the second value in the AutoAcquireEnemiesWhenIdle parameter for the AIUpdateInterface module do?
The first parameter is set to 'yes' or 'no' and is used to determine if the object should automatically acquire enemy objects as potential targets for attack whilst it is idle. The second parameter determines how enemy objects should behave towards this object and can be set to NOTWHILEATTACKING or ATTACK_BUILDINGS. When you use ATTACK_BUILDINGS, you should do so only on 'defensive' type objects (e.g. on base defense structures) and (preferably) set the first parameter to 'yes'. This means that the object will automatically be attacked if enemy objects are not already attacking something - this answers a question I saw a few days back where somebody was asking what determines which objects automatically get attacked by your units. The NOTWHILEATTACKING setting was made for debug purposes and isnt used, it basically forces enemy objects to ignore attacking this object if they are already attacking something else which is the default behavior anyway - consequently this can cause problems with the 'Attack Move' command if used.

What is the default value for MoodAttackCheckRate in AIUpdateInterface?
This value is used as an override to the default attacking behavior and defaults to '0', and is only used when the objects mood is Aggressive or Alert. The most common value used is 250 which means 'when you are Aggressive or Alert, conduct target scans for attack four times every second' (i.e. 250/1000 milliseconds) - it can be used to prevent objects with fast firing or powerful weapons to fire them very quickly, very often.

What does BoneFXDamage do?
What does BoneFXUpdate do?
BoneFXDamage requires no parameters - its purpose is to allow use of the BoneFXUpdate module on the object. The BoneFXUpdate module allows dynamic application of specific ParticleSystems and FX at specific places on the object under specific conditions. Its used most commonly on cinematic objects for cinematic purposes to get them to look spectacular, where the normal logic just doesnt cut it or the object itself has many bones outside of the StandardPublicBone list (GameData.INI). BoneFXUpdate can contain these;-

DamageFXTypes =
DamageParticleTypes =
DamageOCLTypes =
These work like the DeathTypes in the FXListDie module and specify the DamageTypes that trigger the relevant effects.

PristineFXListN =
DamagedFXListN =
ReallyDamagedFXListN =
RubbleFXListN =
(N = numbered 1 to 8). Specify the FX from FXList.INI to be used when the object is in the relevant ConditionState (Pristine is the perfect, un-damaged condition). It is specified like this;-
bone:[bone name] OnlyOnce = [Yes/No] [MinDelayMS] [MaxDelayMS] FXList:[entry from FXList.INI]

PristineOCLN =
DamagedOCLN =
ReallyDamagedOCLN =
RubbleOCLN =
(N = numbered 1 to 8). Specify the OCL from ObjectCreationList.INI to be used when the object is in the relevant ConditionState (Pristine is the perfect, un-damaged condition). It is specified like this;-
bone:[bone name] OnlyOnce = [Yes/No] [MinDelayMS] [MaxDelayMS] OCL:[entry from ObjectCreationList.INI]

PristineParticleSystemN =
DamagedParticleSystemN =
ReallyDamagedParticleSystemN =
RubbleParticleSystemN =
(N = numbered 1 to 8). Specify the particle system from ParticleSystem.INI to be used when the object is in the relevant ConditionState (Pristine is the perfect, un-damaged condition). It is specified like this;-
bone:[bone name] OnlyOnce = [Yes/No] [MinDelayMS] [MaxDelayMS] PSys:[entry from ParticleSystem.INI]

What do LateralScaffoldSpeed and VerticalScaffoldSpeed for the BridgeBehavior module do?
The code support is still there, mainly to support World Builder, but this was used in the days when bridges could be destroyed and repaired. In Roads.INI, each bridge has a ScaffoldObjectName = defined. When the bridge is destroyed and then subsequently repaired (which was done by Dozers and Workers in the same way as telling them to repair one of your own structures) that scaffold object was used to 'surround' the bridge whilst it was being repaired, similar to the scaffolds that appear around your structures when they being constructed. Its the effect used when you make a script in World Builder for an object to 'repair named bridge or structure'. These two parameters control the relative speed at which the scaffolds appear and rise laterally (left and right) and vertically (up and down). They are specified on a 'per bridge' basis since different bridges are different dimensions. IIRC, the scaffold objects are missing from Generals but can be found in Zero Hour.

What does the CheckpointUpdate module do?
Makes the object behave exactly like the gates in Tiberian Sun. Theres no parameters required, but you do need to have animations and the relavant ConditionStates on the object for DOOR_1_OPENING, DOOR_1_CLOSING etc etc so that it works. It works only when friendly objects (same or allied side) approach it.

What is CommandButtonHuntUpdate for?
Exists purely to allow this object to be instructed to undertake a 'hunt' mission via scripts in World Builder using one of its 'special abilities' rather than its default weapon. Normally, if told to hunt, the object will do so using its default weapon. This is why the Hijakcer scripts dont work in Generals, the unit does not have this module so it cant hunt using the 'hijack vehicle' CommandButton! (IIRC, it does get it in Zero Hour though).

Does ConvertToHijackedVehicleCrateCollide use ForbiddenKindOf and FXList?
Yes and No. The module is hardcoded to call for the HijackVehicle sound effect when it is sucessfully triggered so no FXList is required. Specifying and forbidding specific KindOfs depend on the presence of an AIUpdate module on the 'target' object.

What does DamDie do?
Its required for the logic that adjusts water height behind and in front of the Dam when its destroyed. It has no parameters but should be placed after any other death FX or OCL modules to make sure that they get seen before the water height changes. If you dont include this on a Dam object, bad crashiness can result as you end up with two different heights of water terrain with no physical means of that being allowed.

Does DeliverPayloadAIUpdate really not use the same parameters as AIUpdateInterface?
Yes thats right, it is linked to the DeliverPayload definition in ObjectCreationList.INI and its seperate as its to be used only on special objects (i.e. Special Power objects like Cargo Planes) whose purpose is purely to deliver a payload;-

Code:

DeliverPayloadAIUpdate
	DoorDelay = [integer]
	DeliveryDistance = [integer]
	MaxAttempts = [integer]
	DropDelay = [integer]
	DropOffset = [x: y: z:]
	DropVariance = [x: y: z:]
	PutInContainer = [object name]
End

Does EjectPilotDie use RequiredStatus?
No, because by default objects are set as having a driver, so you only need to exempt an object from ejecting its pilot under specific instances.

Is the explanation of FlightPathAdjustDistPerSecond in DumbProjectileBehavior correct?
Yes it just doesnt read very well. What it actually means is that 'this objects speed can be adjusted by this much per second in order to allow it to pursue its target'.

Does TumbleRandomly in DumbProjectileBehavour work?
Yes (partially) as long as the object follows a bezier path to its target. Its hardly noticable, it just makes the projectile 'wobble' a bit whilst in flight.

What does EnemyNearUpdate do?
Doesnt take any parameters, it allows you to make use of the ENEMYNEAR ConditionState on the object, allowing for specific animations, particle systems or image states when the enemy is near the object.

Does FXListDie use RequiredStatus?
Yes, indeed it does.

Does ProneUpdate still work?
Yes it does;-

Code:

ProneUpdate
[this module allows the use of the PRONE ConditionState with this object]
	DamageToFramesRatio = [real number]
End

What effect does setting UpdateModuleStartsAttack to No have in the SpecialAbility module?
It would prevent the object from being placed in the ATTACKING ConditionState and thus its animations would not be played - this would also cause issues as the object would be told to attack yet it would not be placed in an attack mission. If your special ability is not a type of 'attack' then its status would be USING_ABILITY instead.

What does SpecialPowerCreate do?
Two things - (i) it makes sure the public timer gets displayed upon creation of the object. In older builds, it displayed the public timer on the object itself (like the 'Building xx%' text you get when you build the object) so its not as critical now as it once was; and (ii) it makes sure the timer starts 'charging' when the object is created so that the special power is not instantly ready when the object is placed on the map.

Does BonusDurationPerCaptured on SpyVisionSpecialPower still work?
Yes and no. If you make units 'capturable' as if they were structures, then you would get a bonus to the duration of the SpyVisionSpecialPower with this statement. The bonus does not apply to 'sniped' vehicles that you subsequently 'capture', nor does it apply to structures.

More specific explanation of TensileFormationUpdate and its Enabled parameter?
Ill explain this one at a later time, it was used for the original avalanche effect and is very cool.

What does RubbleParticleSystem do in TransitionDamageFX? Is there also a RubbleFXList?
Yes, you can use the following (N = 1 to 12);-

DamagedFXListN =
ReallyDamagedFXListN =
RubbleFXListN =

DamagedOCLN =
ReallyDamagedOCLN =
RubbleOCLN =

DamagedParticleSystemN =
ReallyDamagedParticleSystemN =
RubbleParticleSystemN =

What does ExitPitchRate do in TransportContain?
Adjusts the visible pitch of the object when it exits the transport! Used for things like bombs dropping from planes so they dont appear at thier default orientation when they exit the container.

Mithril · 03-07-2004, 01:00 PM

Great job Deezire!

Immo will be happy about this, I am sure.

The AIUpdate part is especially interesting, but I am also looking forward for a definition of the TensileFormationUpdate.

One question though, what does the Enabled paramter in the FloatUpdate mean?

I added it to all my ships and it worked regardless of the state of the parameter..

DeeZire · 03-07-2004, 02:31 PM

Some more, I have a little time

The POWTruckBehavior module needs removing from the guide, it aint valid and wont work in any public build.

This one is missing from the guide - its not that useful these days as it was once used to set the status bit for aircraft (EXTRA_FUEL) which doesnt work anymore but for the heck of it;-

Code:

StatusBitsUpgrade
	TriggeredBy = [upgrade name from Upgrade.INI]
	StatusToSet = [status name]
	StatusToClear = [status name]
	ConflictsWith = [upgrade name(s) from Upgrade.INI]
   FXListUpgrade = [entry from FXList.INI]
End

Valid StatusBits are DESTROYED, CAN_ATTACK, UNDER_CONSTRUCTION, UNSELECTABLE, NO_COLLISIONS, NO_ATTACK, AIRBORNE_TARGET, PARACHUTING, REPULSOR, HIJACKED, WET, AFLAME (on fire), IS_FIRING_WEAPON, IS_BRAKING, STEALTHED, DETECTED, CAN_STEALTH, SOLD, UNDERGOING_REPAIR, RECONSTRUCTING, MASKED (disguised), IS_ATTACKING, USING_ABILITY, IS_AIMING_WEAPON, NO_ATTACK_FROM_AI, IGNORING_STEALTH, IS_CARBOMB

More specific explanation of WaveGuideUpdate?
An object using this module should have KindOf = WAVEGUIDE set. Its a special object used to control the behavior of a 'water wave' as it collides with objects and moves, as the water itself doesnt actually do anything (being a special type of terrain, it doesnt actually interact with objects in the same way that objects interact with eachother). The guide explains in basic terms what each parameter does but its worth noting that this behavior was written specifically for this effect and the module is hardcoded to use the following particle systems from ParticleSystem.INI (even though some of them are not even defined by default in the final release);-
WaveSpray01
WaveSpray02
WaveSpray03
WaveSplashRight01
WaveSplashLeft01
WaterWaveBridge
WaveHit1
WaveSplash01

What is the function of the UpgradeToRemove [Tag] parameter in UpgradeDie?
To remove an OBJECT_UPGRADE type of upgrade from an object when its destroyed - not doing so can sometimes result in the flag which indicates that the object has been upgraded not being reset, preventing further upgrades of the same type of object. IN the case of object upgrades like Battle Drones, omission of this could at times lead to the Battle Drone hovering about even after its 'parent vehicle' has been destroyed.

What does FloatUpdate do?
I thought people had figured this one out by now! You can set Enabled = to 'yes' or 'no'. People think that the setting makes no difference, which is not true. The very presence of this module on your object, even without any parameters, makes the object bob about like it was under the effects of water currents/movements. Setting it to 'yes' means that you have to use a different set of locomotion rules for the object, and means you can use SEA_LEVEL on the locomotor's ZAxisBehavior =, the effect being that the object will move about and be lifted by the water level, meaning that it stays relative to the water level that its on.

What do ConstructionCompleteDuration and DisabledTypesToProcess on ProductionUpdate do?
ConstructionCompleteDuration is used to determine the delay between the ConditionStates DOOR_N_WAITING_OPEN and DOOR_N_CLOSING on factories, like the War Factory, to ensure that a newly built object gets out in time before the door starts to close. DisabledTypesToProcess is only used on objects that have a ProductionUpdate but may be disabled through lack of power or otherwise. Any disabled types that are processed will still allow the structure to 'produce' things even when disabled by those disabled type conditions. DisabledTypes include DISABLED_HACKED, DISABLED_EMP, DISABLED_HELD, DISABLED_PARALYZED, DISABLED_UNMANNED, DISABLED_UNDERPOWERED, DISABLED_FREEFALL, DISABLED_SCRIPT_UNDERPOWERED, DISABLED_SCRIPT_DISABLED. This is only used on Chinas Nuke Silo, the settings mean that you can still build the upgrades it provides even when low on power - but if it gets hit by an EMP Bomb, you cant use it at all.

Does KeepObjectDie use the same parameters as DestroyDie?
Nope, it doesnt use any parameters. The only purpose of this module is to force the object to leave the images indicated by its RUBBLE ConditionState when its destroyed. For this reason, the RUBBLE state should be defined seperately on this object and not, as is the case with normal player-buildable structures, combined with REALLYDAMAGED. If you use this module, you should not use DestroyDie on the object since it is not actually destroyed in the true sense - the object remains on the map in its RUBBLE state but can no longer interact in any way.

What does AlwaysCircular do on GenerateMinefieldBehavior?
Ensures that the whole minefield is generated within a circular fashion around the objects' GeometryMajorRadius =.

mad ivan · 03-07-2004, 02:44 PM

whoa!grat job DeeZ.So...what exactly will happen when I apply the WaveGuideUpdate to a unit with the KindOf = WAVEGUIDE?Will it do something specific when a unit moves or something?

btw, immoman mind if i do a php-based online version of the guide.I can do some pretty good stuff using php

DeeZire · 03-07-2004, 02:55 PM

As a point of interest, it is the presence of any type of AIUpdate module that triggers the 'Unit Lost' EVA announcement. This needs fixing in a patch so it doesnt affect certain KindOfs (i.e. DRONE and special power objects).