Wormbo's Enhanced Items
Scripting Guide

PickupPlus - Introduction

The PickupPlus class offers lots of possibilities. Some of are used to interact with the EnhancedWeapon class or the Enhanced Player Icon, others are used to coordinate the combination of several PickupPlus items.
Besides the PickupPlus class itself EnhancedItems.u offers two subclasses:

General PickupPlus variables and functions

The PickupPlus class consists of about 37kB of code, so putting all variables and functions in one big list won't be much more helpful than looking at the code itself. I'll try to divide it into several groups. These groups are:

Globalconfig variables

bool bDropEffects
This variable usually has the same value like bDropEffects in EnhancedWeapon and EnhancedProjectile. If it is true the pickup should drop some effects to increase the framerate.
bool bDrawShieldEffect
If this value is true the pickup may add visual effects to the player's weapon. The actual way how to do this is described later on this page and in the EnhancedWeapon description.
bool bEnhancedStatusDoll
If this value is true the PickupPlus tries to activate the Enhanced Status Icon by spawning the EIChallengeHUD mutator.
bool bDebugMode
This activates the debug mode of Enhanced Items. In this mode many classes (not limited to the PickupPlus subclasses) log their current actions. Some examples are the RegisterHUDMutator() function of EnhancedMutator and the MultiPickupPlus class.

Other general variables

name IdenticalTo
Used by OtherIsA() and ClassIsA() to identify PickupPlus versions of a pickup.
bool bDeactivatable [replicated to owning client]
Usually items with bAutoActivate=True cannot be deactivated. This variable solves that problem.
bool bNeverAutoActivate
Overrides DMMutator's (BaseMutator of all UT game types) habit of setting bAutoActivate to true for all pickups.
bool bDeniedAnnounce
float DeniedRadius
sound DeniedAnnounce
DeniedAnnounce is heard by any player within DeniedRadius when the item gets picked up by another player and bDeniedAnnounce=True.
sound GlobalRespawnSound
This sound is heard by all PlayerPawns when the item respawns.
sound GlobalPickupSound
This sound is heard by all PlayerPawns when the item is picked up.
name ReplaceTag
After the item has been picked up it checkes the owner's inventory for other PickupPlus subclasses with the same ReplaceTag and removes them.
bool bAllowSameClassPickup
If this variable is false items of the same class cannot be picked up.
EIDeathMessageMutator EIDMM
This variable contains a reference to the EIDeathMessageMutator responsible for displaying the enhanced death messages. The mutator automatically sets this value through a SpawnNotify subclass.
localized float UnitRatio[4]
localized string UnitDisplay[4]
localized string UnitFullName[4]
globalconfig string DecimalChar
globalconfig int UsedUnit
These variables are used by the ConvertDistance function to display distances as meters, Unreal Units, etc.
UsedUnit saves the default target unit, DecimalChar saves the character to use as decimal point. UnitRatio, UnitDisplay and UnitFullName are localized variables, i.e. their values can be changed via EnhancedItems.int. By default one meter equals 44 Unreal Units, so players have a height of 1.77 meters.

General functions

bool ClassIsA (class Other, coerce string DesiredType) [static, final]
Returns true when Other is a subclass of DesiredType or if Other is a subclass of EnhancedProjectile, EnhancedAmmo, EnhancedWeapon or PickupPlus it returns whether DesiredType is equal to Other.default.IdenticalTo.
bool OtherIsA (actor Other, name DesiredType) [static, final]
Returns true when Other is a subclass of DesiredType or if Other is an EnhancedProjectile, an EnhancedAmmo, an EnhancedWeapon or a PickupPlus it returns whether DesiredType is equal to Other.IdenticalTo.
Inventory FindInventoryType (Actor Other, name DesiredType, optional bool bFindIdentical) [static, final]
Similar to the FindInventoryType function of the Pawn class. The difference is that this function also looks for subclasses and, if bFindIdentical is true, for PickupPlus classes with IdenticalTo equal to DesiredType. Other is of class Actor, so you can continue searching in an inventory chain after you already found an item. Just pass the found item as first parameter.
float GetInfoOn (string InfoType, optional string OtherInfo)
For correct results this function should be called with FirstPickupPlus(Pawn(Owner)).GetInfoOn(...). The function returns a float value gathered from all PickupPlus items in the player's inventory. By default the following InfoType strings can be used:
MaxDefaultOwnerHealth       (owner's health gets regenerated up to this value)
CurrentDamageFactor         (combination of all active damage multipliers)
CurrentOwnerSpeedFactor     (combination of all active speed multipliers)
CurrentWeaponSpeedFactor
CurrentJumpZFactor          	.
CurrentAirControl           	.
CurrentOwnerMassFactor      	.
CurrentOwnerBuoyancyFactor
(see Q3 Health mutator for an example with the MaxDefaultOwnerHealth info)
ReplaceText (out string Text, coerce string Replace, coerce string With) [static, final]
Replaced each occurance of Replace in Text with With.
int EstimatedPawnHitpoints (Pawn Other, optional name DamageType) [static, final]
Calculated the amount of hit points Other has when being damaged with DamageType. The calculation takes Other's armor into account. (Other isn't actually damaged.)
PlayGlobalSound (sound GlobalSound, optional bool bDontPlayInSlots) [final]
Plays a sound for all players. If bDontPlayInSlots is false or omitted the sound is played through the ClientPlaySound() function, otherwise it's played via PlaySound for the player or his ViewTarget (if any).
bool AllowPickup (Pawn Other)
This function works a bit like HandlePickupQuery() except that it's called for the item that is about to be picked up. The item can decide whether it wants to be picked up by Other before the gametype, a mutator or any of Other's inventory items is queried.
PickupPlus FirstPickupPlus (Pawn Other) [static, final]
Returns the first PickupPlus in Other's inventory chain. If bDebugMode is enabled, this function checks the inventory chain for errors (infinite loops, wrong owner, etc.) and logs them. (see bDebugMode above)
PickupPlus NextPickupPlus ( ) [final]
Returns the next PickupPlus in owner's inventory chain after this one. If bDebugMode is enabled this function checks the inventory chain, too.
SpawnEIChallengeHUD ( )
This function is called from PreBeginPlay() if bEnhancedStatusDoll is True. It spawns the Enhanced Player Icon.
string ConvertDistance (float Distance, optional int NewUnit, optional int OldUnit, optional int Accuracy, optional bool bNoUnit, optional bool bLongName) [static, simulated]
This function converts distance values. It returns a string like "23.5 ft" or "11,32 meters". The available measuring units can be set in EnhancedItems.int, the character to use as decimal point can be configured by the player. If OldUnit is not specified the distance will be converted from Unreal Units, if NewUnit is not specified UsedUnit+1 will be used. bNoUnit specifies that only the converted number should be returned, while bLongName adds the full name of the measuring unit, e.g. "Unreal Units" instead of "UU".

Weapon interaction

PickupPlus items can interact with their owner's weapon in many ways. The most common one is the weapon affector, a pickup receiving a FireEffect() call from a weapon. This relationship between pickup and weapon has been improved by providing the possibility of creating affector chains. These are built with the RegisterAsAffector() function and can hold an unlimited number of PickupPlus items + one non-PickupPlus item at the end of the chain.

Variables and constants

MaxDamageFactor = 10.0
MinDamageFactor = 0.3
Used by the SetDamageFactor() function. The player's DamageScaling property is scaled between these two values.
MaxSpeedFactor = 2.5
MinSpeedFactor = 0.3
Used by the SetSpeedFactor() and SetOwnerSpeed() functions. Speed properties are scaled between these two values. (also see Owner-related variables and functions)
float AddToDamageFactor
bool bPawnDamageUp
Used together with the SetDamageFactor() function to change the owning Pawn's DamageScaling value. If several PickupPlus items use this function their AddToDamageFactor values are multiplied.
Since the SetDamageFactor() function examines all PickupPlus items in the player's inventory it needs to know whether an item wants to change the damage factor. This is managed by bPawnDamageUp. When the variable is set to True by default the PickupPlus will automatically apply the damage factor through PickupFunction() and GiveTo().
bPawnDamageUp is set to True when executing the SetDamageFactor() function and False when using ResetDamageFactor().
float AddToSpeedFactor
bool bWeaponSpeedUp
Used together with the SetSpeedFactor() function to change the weapon's SpeedScale value. If several PickupPlus items use this function their AddToSpeedFactor values are multiplied.
Since the SetSpeedFactor() function examines all PickupPlus items in the player's inventory it needs to know whether an item wants to change the speed factor. This is managed by bWeaponSpeedUp. Unlike the damage factor property the weapon speed factor is not automatically applied through PickupFunction() or GiveTo().
bWeaponSpeedUp is set to True when executing the SetSpeedFactor() function and False when using ResetSpeedFactor().
TournamentPickup NextAffector [replicated to owning client]
Used to create a one-way linked list of items affecting one weapon. This is done via the RegisterAsAffector() function. Although the property is declared with TournamentPickup actually only the last item can be a TournamentPickup which is not a subclass of PickupPlus. To remove an item from this list call UnRegisterAsAffector().
(See UsArR33's Linked Lists tutorial at the Unreal Wiki to find out, how linked lists work. See example Damage Amplifier I for details on creating affector chains.)
TournamentWeapon AffectedWeapon [replicated to owning client]
The weapon currently affected by this item.
bool bFireEffectLast
Specifies that the FireFunction() of this item should be executed after the FireFunction() of NextAffector.
bool bRenderOverlays
Specifies that this item wants to execute the PreRenderOverlaysFor() and PostRenderOverlaysFor() functions. These functions only work when the affected weapon is an EnhancedWeapon. (see Visual effects further down for a description of these functions and the example Damage Amplifier II for details on using them)

Weapon functions

RegisterAsAffector (TournamentWeapon W) [final]
This function add the item to the affector chain of the TournamentWeapon specified. The item should not already be in the affector chain of another weapon when calling this function. AffectedWeapon is set to W and NextAffector is set to W's previous Affector.
UnRegisterAsAffector (TournamentWeapon W) [final]
This function removes the item from W's affector chain.
UnRegisterFromWeapons ( ) [final]
This function checks all weapons and removes this item from their affector chains. Also the weapons' SpeedScale values are recalculated so this item has no connection to any weapon anymore.
Try to avoid using this function since it is very slow.
SetKillType (bool bSplashHit, bool bHeadHit, class DamageProjectileClass) [final]
RestoreKillType ( ) [final]
SetKillType() sets the death message for all players killed until RestoreKillType() is called. These functions work like in EnhancedWeapon and EnhancedProjectile except that the class containing the death message has to be specified as a parameter.
FireFunction ( ) [simulated]
Use this function instead of TournamentPickup's FireEffect() to allow all affectors to add extra effects when firing a weapon.
SetDamageFactor ( ) [final]
Sets the owning pawn's DamageFactor to the product of the damage factors of all PickupPlus items that have bPawnDamageUp=True. bPawnDamageUp is set to True.
ResetDamageFactor ( ) [final]
Sets the owning pawn's DamageFactor to the product of the damage factors of all PickupPlus items that have bPawnDamageUp=True except this one. bPawnDamageUp is set to False.
SetSpeedFactor (Weapon W) [final]
Sets the weapon's SpeedScale to the product of the speed factors of all PickupPlus items that have bWeaponSpeedUp=True. bWeaponSpeedUp is set to True.
ResetSpeedFactor (Weapon W) [final]
Sets the weapon's SpeedScale to the product of the speed factors of all PickupPlus items that have bWeaponSpeedUp=True except this one. bWeaponSpeedUp is set to False.

Armor and damage detection

EnhancedItems introduces a more detailed system of damage types which allows to create more complex armor items.

Armor variables

bool bAltCharge [replicated to owning client]
int AltCharge [replicated to owning client]
Alternative charge of this item. When the item is an armor the charge is not displayed in UT's HUD. To use AltCharge instead of Charge set bAltCharge to true. Use the GetCharge() function to get the charge of a PickupPlus instead of checking its Charge and AltCharge values separately.
bool bIsSpecialArmor
Special armors do not use their charge to absorb damage.
float ProtectedDamageFactor
When DamageType is either equal to ProtectionType1 or ProtectionType2 no charge is used to absorb the damage. Pickups (and TournamentPickups) decrease the damage to 0. PickupPlus items multiply the damage with ProtectedDamageFactor. This value is 0 by default, so a PickupPlus handles these kinds of damage like any other item.

Armor functions

int GetCharge ( )
Returns Charge when bAltCharge is false and AltCharge when bAltCharge is true.
bool IsSplashDamage (coerce string DamageType) [static]
Returns whether DamageType is splash damage. (like 'RocketSplashDamage' or 'JoltedSplashDamage')
bool DamageIsTypeOf (coerce string TestType, coerce string DesiredType) [static]
Returns whether a damage type is a "subclass" of another one. (e.g. 'RocketSplashDamage' and 'RocketDeath' are "subclasses" of 'Rocket') If DesiredType is 'SplashDamage' the IsSplashDamage() function is used to check TestType instead.
Note: These are no real subclasses. The damage types are just converted to strings and checked whether the first one begins like the second one.
bool DamageProtectionFactor (name DamageType, out float Factor)
Used by ArmorAbsorbDamage(). This function returns true, if a general multiplier should be applied to the amount of damage. The multiplier then is returned via the Factor parameter.
bool ArmorAbsorbDamage (int Damage, name DamageType, vector HitLocation)
ArmorAbsorbDamage() is originally declared in the Inventory class. It returns the amount of damage left after this item has applied its damage reduction effect.
First the DamageProtectionFactor() function is checked. If it returnes true ArmorAbsorbDamage() returns the Damage multiplied with the Factor parameter returned by DamageProtectionFactor(). Next it checks whether the DamageType is 'Drowned'. In this case the function returns the original damage value. Then an armor damage value is calculated. If the item is no special armor that value is substracted from the item's Charge or AltCharge. If no charge is left the armor damage value is reduced to the actual amount of charge left and the item will be destroyed. Then the function returns the damage value reduced by the armor damage value.
int ArmorPriority (name DamageType)
ArmorPriority() is also declared in the Inventory class. It returns a value used to sort all armor items by effectivness.

Visual effects

Effects variables

class<PlayerShellEffect> ShellType
PlayerShellEffects are used to create an effect surrounding a player.
Texture ShellSkin
The ShellSkin will be applied to the player shell effect once it is spawned.
PlayerShellEffect ShellEffect
The actual PlayerShellEffect curently in use. This is set by the CreateShell function.
class<PlayerShellEffect> PickupShellType
PlayerShellEffects can also be used to surround an item on the map.
Texture PickupShellSkin
The PickupShellSkin will be applied to the pickup shell effect once it is spawned.
PlayerShellEffect PickupShellEffect
The actual PlayerShellEffect curently in use as pickup shell. This is set by the BeginState function of state Pickup.
bool bShellAlwaysOn
The player shell effect should always be visible. The FlashShell function disables the effect's translucency for a certain abount of time.
bool bIsChestArmor
bool bIsThighArmor
bool bIsShieldArmor
bool bIsBeltArmor
bool bIsGlovesArmor
bool bIsBootsArmor
The item should be displayed as the specified type of armor by the Enhanced Status Icon.
bool bIsChestSpecial
bool bIsThighSpecial
bool bIsShieldSpecial
bool bIsBeltSpecial
bool bIsGlovesSpecial
bool bIsJumpBoots
The item should be displayed as jump boots, special belt, etc. by the Enhanced Status Icon.
bool bMakesInvisible
The item makes the player invisible.
bool bRenderOverlays [replicated to owning client]
The item wants to use the Pre/PostRenderOverlaysFor function to draw a visual effect when the weapon is rendered. The item should check the client's bDrawShieldOverWeapon variable before using this feature in a network game.

Effects functions

CreateShell ( ) [simulated]
Spawns a PlayerShellEffect and saves the reference to it in the ShellEffect variable if this variable was empty. The shell effect's Master is set to this PickupPlus, its Texture and MultiSkin[1] are set to ShellSkin.
ShowShell ( ) [simulated]
Calles the ShowMe function of the ShellEffect.
FlashShell (float Duration) [simulated]
If bShellAlwaysOn is true the ShellEffect's SetFlashTime function is called. Otherwise the ShellEffect's VisibleTime is set to Duration.

Owner-related variables and functions

Owner-related variables

float AddToOwnerSpeed
float AddToJumpZFactor
float DesiredAirControl
bool bPawnSpeedUp
Used together with the SetOwnerSpeed() function to change the owning Pawn's GroundSpeed, WaterSpeed, AirSpeed, AccelRate, JumpZ and AirControl values. If several PickupPlus items use this function their AddToOwnerSpeed/AddToJumpZFactor values are multiplied and the highest DesiredAirControl value is used.
Since the SetOwnerSpeed() function examines all PickupPlus items in the player's inventory it needs to know whether an item wants to change the speed factor. This is managed by bPawnSpeedUp. When the variable is set to True by default the PickupPlus will automatically apply the speed factors through PickupFunction() and GiveTo().
bPawnSpeedUp is set to True when executing the SetOwnerSpeed() function and False when using ResetOwnerSpeed().
float AddToMassFactor
float AddToBuoyancyFactor
bool bPawnMassAffect
Used together with the SetOwnerMass() function to change the owning Pawn's Mass and Buoyancy values. If several PickupPlus items use this function their AddToMassFactor/AddToBuoyancyFactor values are multiplied.
Since the SetOwnerMass() function examines all PickupPlus items in the player's inventory it needs to know whether an item wants to change the owner's mass or buoyancy. This is managed by bPawnMassAffect. When the variable is set to True by default the PickupPlus will automatically apply the mass/buoyancy factors through PickupFunction() and GiveTo().
bPawnMassAffect is set to True when executing the SetOwnerMass() function and False when using ResetOwnerMass().

Owner-related functions

SetOwnerSpeed ( ) [final]
Sets the owning pawn's speeds and JumpZ value to the product of the speed factors/JupmZ factors and the AirControl to the highest DesiredAirControl of all PickupPlus items that have bPawnSpeedUp=True. bPawnSpeedUp is set to True.
ResetOwnerSpeed ( ) [final]
Sets the owning pawn's speeds and JumpZ value to the product of the speed factors/JupmZ factors and the AirControl to the highest DesiredAirControl of all PickupPlus items that have bPawnSpeedUp=True except this one. bPawnSpeedUp is set to False.
SetOwnerMass ( ) [final]
Sets the owning pawn's mass and buoyancy to the product of the mass factors of all PickupPlus items that have bPawnMassAffect=True. bPawnMassAffect is set to True.
ResetOwnerMass ( ) [final]
Sets the owning pawn's mass and buoyancy to the product of the mass factors of all PickupPlus items that have bPawnMassAffect=True except this one. bPawnMassAffect is set to False.

<not yet finished>

TimedPowerup subclass

TimedPowerups activate after they have been picked up, stay active for a certain amount of time and then deactivate and remove themselves from the owner's inventory. Like all PickupPlus items they can be selected an temporarly deactivated via the re-activated item selection keys.
Two examples for TimedPowerups are EI_UDamage and EI_Invisibility which are both part of the Enhanced Items mod. A third example which also demonstrates deactivatable items is the Gravity Belt in Enhanced Chaos Items.

Important variables

float FullCharge
This is the amount of charge the item initially has.
float Remaining [replicated to clients]
This is the amount of charge the item still has left. This value initially is 0.
float TimingInterval
This is the interval of time the item uses internally to count down Remaining and to call TimedAction().
float FinalCount [replicated to clients]
If Remaining drops below this the DeactivateSound starts playing.
FinalCount and Remaining are replicated to clients so they can display these values properly on the HUD even if they are changed by the server.
int FinalCountInterval
The internal integer variable FinalCounter is increased by 1 each timing interval when in final countdown. If it can be divided by FinalCountInterval without remainder the DeactivateSound is played this timing cycle.
bool bPreFinalCount
If this is true and Remaining is equal to FinalCount * 2 an additional DeactivateSound is played.
bool bDeactivateCount
Specified whether the very last DeactivateSound should be played. (Remaining has reached 0.)
bool bAddCharge
If this is true Remaining gets increased by FullCharge when another item of the same class is picked up. Remaining gets restored to FullCharge when this is false.
bool bDeactivateUseCharge
Specifies whether this item also uses its charge when it is deactivated.

Important functions

ActivateAction ( ) [simulated]
Is called when the item enters 'Activated' state after pickup or when reactivated.
DeactivateAction ( ) [simulated]
Is called when the item leaves 'Activated' state after charge is used up or when item is deactivated.
TimedAction ( ) [simulated]
Is called once in each timing cycle when the item is in 'Activated' state.

HoldablePowerup subclass

HoldablePowerups work like the holdables in Quake 3 Arena. They stay in the player's inventory until they are activated via the 'mutate UseHoldable' command which is handled by the EIUseHoldable mutator. This mutators also controls item selection and automatic activation of HoldablePowerups.

Important variables

bool bKillsOwner
Bots sometimes use their holdable just to make room for a new one. By setting this variable to true you can tell them that this holdable will kill them as soon as they use it. Useful for all kinds of kamikaze holdables.
bool bCanHaveMultipleCopies
int NumCopies [replicated to clients]
Although these are declared in Engine.Pickup they are important for holdables. When bCanHaveMultipleCopies is true the holdable can activate again as long as NumCopies (decreased by 1 each time) is still greater that 0. This is the only way to carry more than one holdable at the same time.
bool bMultiUse
The holdable doesn't disappear after it has been used but instead goes to the 'Activated' state. (By default the holdable is in 'Ready' state.)
bool bMoreUsageChecks
If this variable is false bots only check this holdable when they get hit. If this variable is true, addidtional usage checks are done every 0.1 seconds.
bool bInstantAutoUse
bool UseMe
If bInstantAutoUse is true the holdable is activated instantly. If bInstantAutoUse is false and the auto-usage checks evaluate to true UseMe is set to true and the timer is set to 0.01 seconds. This way any TakeDamage calls that may have caused the activation can finish before the holdable activates.
localized string UseText
localized string ReUseText
class<LocalMessage> UseMessageClass
If the UseMessageClass is None and the (Re)UseText is not empty a ClientMessage is sent to the owner when the holdable is (re-)activated. If the UseMessageClass is not None and the (Re)UseText is not empty a LocalMessage is sent instead. The switch of this message is 0 when the holdable is activated from 'Ready' state and 1 if activated from 'Activated' state. The OptionalObject always is the class of the holdable powerup.

Important functions

bool DoActiveAction ( )
Does the effect of the holdable and returns whether it could be activated or not.
UseHoldable ( )
This function handles the activation process. (ActivateSound, use message, log activation, go to 'Activated' state and decrease NumCopies) Use the DoActiveAction() function to control the effect of the holdable.
bool RecommendUse (name DamageType, int Damage, pawn InstigatedBy, vector HitLocation, optional bool bUrgent)
bool GoodUsage (name DamageType, int Damage, pawn InstigatedBy, optional bool bUrgent)
Use GoodUsage to describe when to use this holdable. (e.g. blow up the Kamikaze holdable when in crowded area, use medkit when low on health, etc.) It is called from RecommendUse which is called by the EIUseHoldable mutator and the more usage check timer. For both functions bUrgent means the call came from the MutatorTakeDamage function of EIUseHoldable.