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:
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".
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.
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.
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
- 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>
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.
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.