Wormbo's Enhanced Items
Scripting Guide

EnhancedWeapon - Introduction

The EnhancedWeapon class helps creating better weapons by offering

This document also contains the class references of the EnhancedProjectile and EnhancedAmmo classes, but most of their functionality is also available in the EnhancedWeapon class, so it is explained there.

EnhancedWeapon Variables

General variables

name SamePriorityLike
When this variable is set to something different than 'None' it will use the switch priority of the weapon with that name instead of its own value.
This is useful when replacing existing weapons with similar Enhanced Items versions, because they can use the priority of the original weapons.
name DoublePriorityName
The name to use when reading the double switch priority of this weapon. This value is used when the weapon has a slave weapon. (like double Enforcer)
int DoubleSwitchPriority
The auto switch priority when the weapon has a slave weapon.
localized string DoubleName
The display name of the weapon when it has a slave weapon.
name IdenticalTo
Used by the OtherIsA and ClassIsA functions to identify new versions of a weapon if it is not a subclass of the original one.
globalconfig bool bDropEffects
This variable usually has the same value like bDropEffects in PickupPlus and EnhancedProjectile. If it is true the weapon should drop some effects to increase the framerate.
float SpeedScale [replicated to owning client]
This variable is used to adjust the weapon's firing speed. The default value is multiplied with the speed scale value calculated by PickupPlus items.
class<Projectile> SubMunitionClass
A projectile class to spawn at the point of impact. These projectiles fly away into random directions.
int SubMunitionCount
The number of submunition projectiles to spawn. If this is a larger amount you should modify the SpawnSubmunition function in combination with Tick to reduce the number of projectiles spawned within the same frame.
class<Effects> ExplosionEffectClass
An explosion effect displayed at the point of impact.
class<Decal> ExplosionDecal
A decal to spawn at the point of impact.

Death message related variables

Note: Death message related variables are only used by instant hit weapons.
Death messages can use special placeholders:

%k
The killer's name. This placeholder can't be used in suicide messages.
%o
The victim's name. If this is not used in a suicide message, the suicider's name is placed in front of the message.
%w
The killer's weapon.
%p
The weapon's projectile.
In UT's death messages each of the first three placeholders may only appear once. However, EnhancedItems death messages can contain them more than once.

localized string ProjectileName
The name of the projectile(s) used by this weapon. These are no real projectiles, since this is an instant hit weapon, but this is used to replace "%p" in the death messages.
localized string DirectHitString
The death message used for direct hits.
localized string SplashHitString
The death message to use for splash damage. (e.g. explosions)
localized string HeadHitString
The death message to use for head shots.
localized string SuicideString
Male suicide message.
localized string SuicideFString
Female suicide message.
localized string HeadSuicideString
Male suicide message for head shots.
localized string HeadSuicideFString
Female suicide message for head shots.
class<LocalMessage> HeadShotMessage
This message will be displayed whenever a hit is declared as a head shot. This especially applies when the damage type is not 'Decapitated'.
class<Actor> DeathMessageActorClass
This can be either a subclass of EnhancedWeapon or EnhancedProjectile.
The death messages of the DeathMessageActorClass are used instead of the ones in this class. You can create abstract subclasses of EnhancedProjectile to create "damage types". These damage types can be used by any actor class that supports the death message system of EnhancedItems like PickupPlus, EIEffects or EnhancedMutator.
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.

Damage related variables

name SplashDamageType
The damage type of splash damage. Use something like 'RocketSplashDamage' so armor items can identify this as splash damage.
name HeadDamageType
The damage type of head shots. Use 'Decapitated' to display the default "Head Shot" announcement when someone is killed with a head shot.
name SplashDamageType
The damage type of splash damage. Use something like 'RocketSplashDamage' so armor items can identify this as splash damage.
bool bCanHeadShoot
Specifies whether weapon can cause head shots.
bool bConstantSplashDamage
Usually splash damage is not as strong when the victim is further away from the explosion. By setting this variable to true the splash damage will have the same strength in the whole splash area.
float Damage
The actual amount of damage this weapon causes.
float DamageRadius
The size of the splash area. If you specify 0 here, the weapon can only cause direct hits or head shots.
float MomentumTransfer
The amount of momentum transfer applied by direct hits and head shots.
float SplashMomentum
The amount of momentum transfer applied by splash hits.
float MomentumModifier
Describes, how the owner's damage scaling affects the amount of momentum applied to victims. The following formula applies both to MomentumTransfer and SplashMomentum.
momentum = MomentumTransfer + (MomentumTransfer * (Instigator.DamageScaling - 1) * MomentumModifier)
float SplashRangeModifier
Describes, how the owner's damage scaling affects the radius of the splash area. (uses the same formula as above)
float Range
The range of this melee weapon. (don't use for ranged weapons)
float MaxRange
Maximum range of this instant hit weapon. (non-melee)
float HeadShotDamageFactor
The damage is multiplied by this value when doing a head shot.
float HeadShotHeight
If this weapon can cause head shots and the opponent is hit above a certain height relative to his/her CollisionHeight the hit is a head shot.
This is checked by multiplying HeadShotHeight with the player's CollisionHeight and comparing it with the difference of the z-components of the player's Location and the HitLocation. A HeadShotHeight of 0 means any hit above the player's Location is a head shot, while -1 means any hit. The default height used by UT weapons is 0.62.

Dual weapon variables

EnhancedWeapon SlaveWeapon [replicated to owning client]
This variable points to the slave weapon when using two weapons. It provides direct access to the slave when using weapons similar to the Enforcer.
EnhancedWeapon MasterWeapon [replicated to owning client when bIsSlave is true]
Set for the slave weapon as a reference to the master weapon.
bool bIsSlave [replicated to owning client]
This variable indicates that this weapon is used in the SlaveWeapon property of the MasterWeapon.
bool bCustomDrawSlave
When using a modified version of the RenderOverlays function that also handles drawing the slave make sure this variable is set to true.

Variables used in menus

localized string MenuName
This name is displayed in menus like the advanced weapon priority list.
Mesh MenuMesh
Used instead of the PickupViewMesh when displayed in the advanced weapon priority list.
float MenuDrawScale
Used instead of PickupViewScale.
rotator MenuRotation
The default rotation of the MenuMesh in the advanced weapon priority list. (Yaw will be ignored.)

EnhancedWeapon Functions

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.
vector EstimatedHitNormal (out vector HitLocation, out Actor HitActor, optional vector CurLocation, optional vector Distance, optional bool HitLevel, optional vector Extend)
Returns the HitNormal, if the level wouldn't change and the projectile would fly from CurLocation along vector Distance and hits something within the range specified by Distance. Returns a vector of size 0 if it would hit nothing or HitLevel is true and it would hit any other actor than the level.
If HitLevel isn't true HitActor is set like in the Trace function, if HitLevel is true HitActor will be set to Level or None depending on if it hit level geometry or not.

Weapon operation related functions

vector CalcZoomedFireOffset ( ) [simulated]
Similar to the CalcDrawOffset function, but bases the calculation on the fact, that the player uses zooming which basically changes the firing offset.
SplashDamage (vector HitLocation, actor Other, vector HitNormal, optional bool bSpecialHit)
A replacement for the HurtRadius function. The SplashDamage function automatically sets up the proper death messages. bSpecialHit specifies, that the head shot messages should be used.
DirectHit (vector HitLocation, actor Other, vector HitNormal, optional bool bSpecialHit, optional bool bSplashHit)
This function should be used instead of TakeDamage. It automatically sets up the proper death message. bSpecialHit specifies, that the head shot messages should be used, while bSplashHit causes the splash damage message to be displayed. If both options are specified bSpecialHit only will have an effect.
name AdjustSplashDamageType (Actor Other)
Can be used to return a different splash damage type based on the damaged actor. (Used by the SplashDamage function.)
SpawnExplosionEffects (vector HitLocation, vector HitNormal) [simulated]
Spawns an explosion effect at the specified location.
SpawnSubMunition (vector HitLocation, vector HitNormal, int Number)
Spawns submunition projectiles. Modify this function, if you are spawning huge amounts of projectiles.
ModifySubMunition (Projectile Other)
Called by SpawnSubMunition. This function can modify the projectiles after they have been spawned.

Death message related functions

Usually you don't have to use these functions, since they are called automatically by SplashDamage and DirectHit.

class<Actor> ReturnMessageActor ( )
Returns the actor class used to generate death messages. This is the DeathMessageActorClass if it contains a subclass of EnhancedWeapon or EnhancedProjectile. Otherwise it's this weapon's class. (or projectile's class if called from EnhancedProjectile)
SetKillType (bool bSplashHit, bool bHeadHit) [final]
Sets up a death message type for the next kills. Multiple SetKillType calls can be nested up to five levels deep, i.e. if SetKillType is called the previous one is cached until RestoreKillType is called.
RestoreKillType ( )
Restores the previous death message. This function should be called as often as SetKillType. Death messages should be reset as soon as possible, since they are also used for kills and suicides causes by non-EnhancedItems actors, which in this case display the wrong death message.

The EnhancedProjectile class

Most damage and death message related variables and function of the EnhancedWeapon class are also available for EnhancedProjectiles, so they are not described again here. Some of the function parameters are optional for EnhancedProjectiles, since their default values can be calculated from the projectile's location or velocity.

General variables and function

name IdenticalTo
globalconfig bool bDropEffects
globalconfig bool bKeepLightEffects
If the projectile has light effects and the frame rate is low these effects are usually disabled or downgraded to improve the frame rate. When this variable is set light effects will not be changed.
Actor MyTarget [replicated to clients]
The target of this projectile.
class<Projectile> SubMunitionClass
int SubMunitionCount
class<Effects> ExplosionEffectClass
class<Decal> ExplosionDecal
bool bLifeSpanMode, bNoLifeSpan
Used internally by the LifeSpanMode function.
vector EstimatedHitNormal(out vector HitLocation, out actor HitActor, optional vector CurLocation, optional vector Distance, optional bool bHitLevelOnly, optional vector Extend)
bool LifeSpanMode ( ) [simulated, final]
Returns whether the LifeSpan mutator is used.
string GetHumanName ( )
Returns the name of this projectile. This function is originally defined in the Actor class.
rotator RotationFromVector(vector NewDirection, optional rotator OldRotator) [static, final]
Converts a vector to rotator. The missing Roll component of the rotator is taken from the optional OldRotator parameter.

Death message related variables and functions

localized string ProjectileName
localized string DirectHitString
localized string SplashHitString
localized string HeadHitString
localized string SuicideString
localized string SuicideFString
localized string HeadSuicideString
localized string HeadSuicideFString
class<Actor> DeathMessageActorClass
EIDeathMessageMutator EIDMM
class<Inventory> FiredFrom
The weapon class this projectile is fired from. This can also be any Inventory class, because only the ItemName value is used to replace the %w in death messages.
class<Actor> ReturnMessageActor ( )
SetKillType (bool bSplashHit, bool bHeadHit) [final]
RestoreKillType ( ) [final]

Damage related variables and functions

bool bKeepDamageScaling
float SpawnDamageScaling
When the projectile is spawned it saves the current DamageScaling of its instigator in SpawnDamageScaling if bKeepDamageScaling is True. This value will be used later instead of the instigator's DamageScaling value when the projectile explodes.
name SplashDamageType
name HeadDamageType
name SplashDamageType
bool bCanHeadShoot
bool bConstantSplashDamage
float Damage
float DamageRadius
float MomentumTransfer
float SplashMomentum
float MomentumModifier
float SplashRangeModifier
float HeadShotDamageFactor
float HeadShotHeight
class<LocalMessage> HeadMessage
SplashDamage (optional vector HitLocation, optional actor Other, optional vector HitNormal, optional bool bSpecialHit)
DirectHit (vector HitLocation, Actor Other, optional vector HitNormal, optional bool bSpecialHit)
name AdjustSplashDamageType (Actor Other)
SpawnExplosionEffects (vector HitLocation, vector HitNormal) [simulated]
SpawnSubMunition (vector HitLocation, vector HitNormal, int Number)
ModifySubMunition (Projectile Other)
Explosion (optional vector HitLocation, optional vector HitNormal, optional Actor HitActor) [simulated]
This function should contain all the code to create the explosion effects and damage. For most simple projectiles the default version of this function already has all the functionality needed. Use this function instead of Explode.

The EnhancedAmmo class

EnhancedAmmo classes can specify, how they should be regenerated. This is used e.g. by the Relic of Wealth from the Enhanced Relics mutator in the Enhanced Items mod or the Ammo Regen relic in Q3T.
Again: If anything has no explanation it was already mentioned in the EnhancedWeapon section.

RegenSuggestion
int Max
The maximum amount of ammo gained through regeneration.
int Interval
A relative interval of time for regeneration.
int Amount
The amount of ammo to regenerate per regeneration interval.
This struct describes, how this ammo class should be regenerated by the Relic of Wealth or any other ammo regenerating items.
RegenSuggestion SuggestedRegeneration
The SuggestedRegeneration variable contains the RegenSuggestion struct.
bool bIsSuperWeapon
Specified, whether this ammo class belongs to a super weapon like the Redeemer, the Chaos UT Gravity Vortex or the Rockets UT Mega Missile Launcher.
name IdenticalTo
EIDeathMessageMutator EIDMM
bool ClassIsA (class Other, coerce string DesiredType) [static, final]
bool OtherIsA (actor Other, name DesiredType) [static, final]
SetKillType (bool bSplashHit, bool bHeadHit, class<Actor> DamageProjectileClass) [final]
(EnhancedAmmo has no DeathMessageActorClass variable, so the class has to be specified here.)
RestoreKillType ( ) [final]