Romero UnrealScript

Using Delegates in UnrealScript

2013-07-01T14:32:00.001-03:00

A delegate in UnrealScript is a type of variable that references a function. With the use of delegate is possible to set the function that should be called during the execution of the game.

Before we create a new delegate we will first use one that is already defined in Unreal Engine 3.

A Dynamic Array has a function to sort its data. This function takes as a parameter another function that will be stored internally in a delegate. The description of this function in the UnrealScript Language Reference is as follows:

"Sort(SortDelegate): uses SortDelegate to sort the contents of the array in-place. SortDelegate should have signature matching the following:

delegate int ExampleSort(ArrayType A, ArrayType B) { return A < B ? -1 : 0; }

// a negative return value indicates the items should be swapped"

This description tells us to create a function that takes two parameters of the same type that is used in the Dynamic Array. We need to compare the two parameters and return a negative value if the items need to change position.

The function is using the ternary operator "? :" which is a type of "if" command abbreviated. The expression "A < B ? -1 : 0" means that the comparison before the "?" will be evaluated. If the result is true, then the resulting value will be the first, which in this example is "-1". If false, the resulting value will be the second, which is "0". It is important to note that in this example the list will be in descending order. That is, the highest values will be first in the list.

The function that is created does not need to have the word "delegate" in its definition.

Now imagine that we have in our game a Dynamic Array of Pawns as below:

var array <Pawn> pawnList;

We want this list to be sorted by the Pawn's Health attribute. The Pawns with more health must be at the beginning of the list.

Example function to sort the Pawns.

function int SortPawn(Pawn A, Pawn B)
{
    local int result;
          
    if(A.Health < B.Health)
    {
        result = -1;
    } 
    else 
    {
        result = 0;
    }
    
    return result;
}

The same function can be written in another way:

function int SortPawn(Pawn A, Pawn B)
{
    return (A.Health < B.Health) ? -1 : 0;
}

To sort you must call the Sort() function of the Dynamic Array:

pawnList.Sort( SortPawn );

Now let's learn how to create a new delegate. To define a delegate in a class do so:

delegate delegateName( parameters ... );

To define a function that takes a delegate as a parameter:

function functionName( delegate< delegateName > delegateParameter)
{
}

In the example below it was created a delegate that will be called when a player (UTPawn) is dying. This delegate can be used to notify some other class in the game that need to perform an action when this happens.

class UTPawnDelegate extends UTPawn;

delegate notifyDeath( Pawn player ) ;

function SetDelegate( delegate< notifyDeath > newDelegate)
{
    notifyDeath = newDelegate ;
}

simulated function PlayDying(class<DamageType> DamageType, vector HitLoc)
{
    Super.PlayDying( DamageType, HitLoc );
    
    notifyDeath( self );
}

Using Dynamic Arrays in UnrealScript

2013-05-22T15:33:00.000-03:00

Dynamic Array is a collection of data items that can be resized during the execution of the game.

A Dynamic Array is a variable type declared as follows:

var array < arrayType > arrayName ;

The array type can be primitives such as int and float or any class such as Actor and Pawn.

A Dynamic Array can also be defined as local variable within a function using the keyword "local".

The current size of a Dynamic Array can be found in their Length attribute. Access to the individual elements of a Dynamic Array can be done with an index in the same way as in a static array. Remember that the index of an array always starts from 0.

A simple example using Dynamic Array:

class EnemyTypes extends Actor;

var array <int> enemyTypeList;


function int getEnemyType(int index)
{
    if(index < 0 || index >= enemyTypeList.Length) 
    {
        return -1;  // Error: Invalid Index
    } 
    else 
    {
        return enemyTypeList[ index ];
    }
}

function setEnemyType(int index, int enemyType)
{
    if(index >= 0 && enemyType >= 0)
    {
        enemyTypeList[ index ] = enemyType;
    }
}

Note that in the above example, in the function setEnemyType(), there is no problem if the index is greater than the current size of the array, because a Dynamic Array will increase its size to store the required index.

There are some functions that are part of a Dynamic Array. Below are the main ones:

AddItem( Element ): Adds an Element to the end of the Dynamic Array. The Element must be the same type of the Dynamic Array.

RemoveItem( Element ): Removes an Element of the Dynamic Array.

InsertItem( int Index, Element): Inserts an Element in the Dynamic Array at the specified index.

Find( Element ): Search for the Element within the Dynamic Array and returns the index of the found element, or "-1" if not found.

I did an example that creates a random amount of Shield Belts (class UTGameContent.UTDroppedShieldBelt) in random positions. The Shield Belts instances that were created are added to a Dynamic Array. After creating all Shield Belts, the Dynamic Array is iterated using the ForEach operator to register in the Log the position of each Shield Belt created.

Code and image of this example:

class TestDynamicArrays extends UTGame;

var array <UTDroppedShieldBelt> shieldList;

function StartMatch()
{
    local UTDroppedShieldBelt shieldInstance;    
    local vector shieldLocation;
    local int totalShields;    
    
    super.StartMatch();

    totalShields = 10 + Rand(10);     
    
    do
    {
        //Choose a random position
        shieldLocation.X = -1000 + Rand(2001); //-1000 to 1000;
        shieldLocation.Y = -1000 + Rand(2001); //-1000 to 1000;
        shieldLocation.Z = 50 ;
    
        shieldInstance = spawn(class 'UTGameContent.UTDroppedShieldBelt', , ,shieldLocation);
        
        shieldList.addItem( shieldInstance );        
                
    } until ( shieldList.Length == totalShields ) ;
    
    `Log("TOTAL OF SHIELDS =" @ shieldList.Length);
    
    //write in the log the position of all shields
    foreach shieldList( shieldInstance )
    {
      `Log( "Location =" @ shieldInstance.Location );
    }
}

This log shows what was registered in one of the executions of the example.

[0294.02] ScriptLog: TOTAL OF SHIELDS = 18
[0294.02] ScriptLog: Location = -390.00,183.00,50.00
[0294.02] ScriptLog: Location = -946.00,-300.00,50.00
[0294.02] ScriptLog: Location = -101.00,133.00,50.00
[0294.02] ScriptLog: Location = 225.00,701.00,50.00
[0294.02] ScriptLog: Location = 611.00,-908.00,50.00
[0294.02] ScriptLog: Location = -650.00,-532.00,50.00
[0294.02] ScriptLog: Location = -550.00,449.00,50.00
[0294.02] ScriptLog: Location = -245.00,531.00,50.00
[0294.02] ScriptLog: Location = 307.00,-890.00,50.00
[0294.02] ScriptLog: Location = -14.00,-534.00,50.00
[0294.02] ScriptLog: Location = -191.00,101.00,50.00
[0294.02] ScriptLog: Location = -756.00,832.00,50.00
[0294.02] ScriptLog: Location = 796.00,390.00,50.00
[0294.02] ScriptLog: Location = -833.00,-915.00,50.00
[0294.02] ScriptLog: Location = 780.00,-248.00,50.00
[0294.02] ScriptLog: Location = 492.00,841.00,50.00
[0294.02] ScriptLog: Location = 461.00,-526.00,50.00
[0294.02] ScriptLog: Location = 179.00,-266.00,50.00

Iterating with ForEach in UnrealScript

2013-04-15T14:49:00.001-03:00

Before talk about iteration let's imagine an example. Say you built a game that in the levels there are several UTWeaponPickupFactory actors, but only one of them will have a special behavior that will be programmed in UnrealScript.

The UTWeaponPickupFactory class is found in this class hierarchy:

For this example I will place in the level several UTWeaponPickupFactory actors as shown in the image below.

I selected one of the UTWeaponPickupFactory actors, opened the Properties Window (F4 key) and set the "Tag" property with the value SPECIAL_FACTORY. This Tag property is in the Object category as seen in this image.

When starting the game we need to iterate through all the UTWeaponPickupFactory actors until find the one that has the value SPECIAL_FACTORY in the "Tag" property. When find it we will store the object reference of the current UTWeaponPickupFactory actor to be able to handle it in UnrealScript.

That's what this code does.

class TestIteration extends UTGame;

var UTWeaponPickupFactory SpecialFactory;

function StartMatch()
{
    local UTWeaponPickupFactory factory;
   
    Super.StartMatch();
   
    foreach DynamicActors( class'UTWeaponPickupFactory', factory )
    {
       
      if( factory.tag == 'SPECIAL_FACTORY' ) 
      {
        SpecialFactory = factory;
        break;     // Ends the search
      }
    }
    
    Broadcast( self, " Object Name =" @ SpecialFactory.name) ;    
}

To test this code in UDK set the Game Type to "TestIteration". (UDK Menu: View -> WorldProperties -> Game Type)

The "foreach" command works with one type of function known as Iterator. These functions have two parameters, the first parameter specifies the type of actor that it should search and the second is a variable that will receive the reference of the current actor in each iteration.

DynamicActors() is the most used iterator function. It searches in the Actors that are not StaticMeshActor. There are several other iterator functions. The main iterators are declared together in the Actor class, just search for "iterator" in the file Actor.uc.

There are other important iterators declared in the WorldInfo class (Actor->Info->ZoneInfo->WorldInfo). To use them you need to put a variable of the type "WorldInfo" in front of the iterator function name. All Actors have a "WorldInfo" variable. Code Sample:

//Extract from GameInfo.uc (Actor->Info->GameInfo)

function StartBots()
{
    local Controller P;

    foreach WorldInfo.AllControllers(class'Controller', P)
    {
        if (P.bIsPlayer && !P.IsA('PlayerController'))
        {
            if (WorldInfo.NetMode == NM_Standalone)
            {
                RestartPlayer(P);
            }
            else
            {
                P.GotoState('Dead','MPStart');
            }
        }
    }
}

Object and Actor References in UnrealScript

2013-04-05T09:24:00.000-03:00

Some beginners confuse an object with the variable that references the object. This lack of understanding can cause some errors when writing new UnrealScript codes.

Analyze the code below and think about the values that will be written on the screen.

class TestObjReference extends UTGame;

var int xValue;
var int yValue;
var vector vectorStruct;
var Pawn pawnObj;
     
event PostBeginPlay()
{
  SetTimer(3);    
}

function Timer()
{        
  xValue = 10;
  yValue = 10;
  vectorStruct.X = 10;

          //Get a reference to the Player Pawn
  pawnObj = GetALocalPlayerController().Pawn;     
  pawnObj.health = 10;    
    
  ChangeValues( xValue, yValue, vectorStruct, pawnObj);
    
  Broadcast(self, "xValue =" @ xValue);
  Broadcast(self, "yValue =" @ yValue);
  Broadcast(self, "vectorStruct.X =" @ vectorStruct.X );
  Broadcast(self, "pawnObj.health =" @ pawnObj.health);    
}

function ChangeValues(int x, out int y, vector xVector, Pawn xPawn )
{
  x = 50;
  y = 50;
  xVector.X = 50;
  xPawn.health = 50;    
}

If you want to test this code in UDK just set the Game Type to "TestObjReference". (UDK Menu: View -> WorldProperties -> Game Type)

The primitive variables like "int" and "float" and the structs such as "Vector" and "Rotator" contains the values that are assigned to them. But Objects and Actors variables are just references, so they do not contain the values of objects. The image below represents the use of variables of this code in memory.

When you declare a variable of some class it starts with the value "None". This means that it does not reference any object. You can get a reference to an object or create one using the "New" operator. If the variable references an Actor (or a subclass) you must use the "Spawn" function to create a new object.

In the image above we can see that although the variables "pawnObj" and "xPawn" are different they refer to the same object Player Pawn, whereas the variables "vectorStruct" and "xVector" do not have any kind of relationship.

The variables "xValue" and "x" are independent whereas the variables "yValue" and "y" are related because the variable "y" was declared as "out" in the function ChangeValues().

The image below shows the values that will be written on the screen.

When you declare a variable of a specific class, this variable can also refer the subclasses. However, to access the variables and functions that belong to the subclasses is necessary to "cast" this variable into the desired subclass.

The code below shows a simple example of an Actor variable that references an object of the Pawn class. The cast is necessary to access the "Health" variable that belongs to the Pawn class.

function Timer()
{
  local Actor actorObj;

  actorObj = GetALocalPlayerController().Pawn;     

  Pawn(actorObj).health = 10;    
}

Conclusion of "UnrealScript for Beginners"

2012-06-28T06:48:00.000-03:00

In 1999, I had my first contact with the Unreal Engine through the Unreal Tournament game. I was very impressed with the graphics, music, artificial intelligence, weapons and game dynamics. When I remember this game, automatically the Intro music and the voice of the narrator at the beginning of the game start to echo in my mind.

Nowadays, I admire the Unreal Engine by a programmer's perspective. It is fascinating the technology and complexity existent in the core of the Unreal Engine that was developed by the brilliant mind of Tim Sweeney.

I would like to thank Epic Games for creating this amazing engine and made it available through the UDK that allowed many people's dreams to become possible.

"The time has come to prove you are the best.
To crush your enemies;

to win the Tournament."

(Unreal Tournament 1 Intro)

Platformer Kit: SPG_AIPawn class (UnrealScript)

2012-06-27T10:27:00.001-03:00

The SPG_AIPawn class represents the bots that attack the player in the Platform Kit. The variables defined for this class are:

class SPG_AIPawn extends Pawn
      placeable;

// Dynamic light environment component to help speed up lighting calculations for the pawn
var(Pawn) const DynamicLightEnvironmentComponent LightEnvironment;

// Ground speed of the pawn, display as Ground Speed in the editor
var(Pawn) const float UserGroundSpeed<DisplayName=Ground Speed>;

// Explosion particle system to play when blowing up
var(Pawn) const ParticleSystem ExplosionParticleTemplate;

// Explosion sound to play
var(Pawn) const SoundCue ExplosionSoundCue;

// Explosion damage amount 
var(Pawn) const int ExplosionDamage;

// Archetyped pick up to drop
var(Pawn) const archetype DroppedPickup ArchetypedPickup;

// Percentage chance to drop pickups
var(Pawn) const float ChanceToDropPickup;

// Current enemy
var Actor Enemy;

There is an Archetype for the SPG_AIPawn class. The image below shows the specific variables of the SPG_AIPawn class.

The Tick() function is executed every frame. In this function a reference to the player is stored in the Enemy variable, if this has not been done.

After that, if the bot is already walking on the ground (Physics == PHYS_Walking), it gets the player's location and adjust its velocity and rotation to move toward the player.

simulated function Tick(float DeltaTime)
{
    local PlayerController PlayerController;
    local Vector Direction;
    local Rotator NewRotation;

    Super.Tick(DeltaTime);

    // If we don't have an enemy yet...
    if (Enemy == None)
    {
        // Find the player controller in the world
        PlayerController = GetALocalPlayerController();

        if (PlayerController != None && PlayerController.Pawn != None)
        {
            // Set the enemy to the player controller's pawn
            Enemy = PlayerController.Pawn;
        }
    }
    else if (Physics == PHYS_Walking)
    {
        // Find the direction in order for me to look at my enemy
        Direction = Enemy.Location - Location;

        // Only need to use the yaw from the direction
        NewRotation = Rotator(Direction);
        NewRotation.Pitch = 0;
        NewRotation.Roll = 0;

        // Set the rotation so that I look at the enemy
        SetRotation(NewRotation);

        // Set my velocity, so I move towards the enemy
        Velocity = Normal(Enemy.Location - Location) * UserGroundSpeed;

        // Set my acceleration, so I move towards the enemy
        Acceleration = Velocity;
    }
}

When a bot collides with the player, the Bump() function is executed. For more information about collision read the article: "Collision in UnrealScript".

The player, who is represented by the variable Other in this function, receives damage whose value is set in the ExplosionDamage variable. In the image of the Archetype we can see that the default value of this variable is 5.

The particles effect that represents the explosion is triggered and is played the sound of the explosion stored in the variable ExplosionSoundCue. For more information about SoundCue, read the article: "Playing Sounds in UnrealScript".

event Bump(Actor Other, PrimitiveComponent OtherComp, Vector HitNormal)
{
    Super.Bump(Other, OtherComp, HitNormal);

    if (SPG_PlayerPawn(Other) != None)
    {
        // Apply damage to the bumped pawn
        Other.TakeDamage(ExplosionDamage, None, Location, Vect(0, 0, 0), class'DamageType');

        // Play the particle effect
        if (ExplosionParticleTemplate != None)
        {
            WorldInfo.MyEmitterPool.SpawnEmitter(ExplosionParticleTemplate, Location);
        }

        // Play the explosion sound
        if (ExplosionSoundCue != None)
        {
            PlaySound(ExplosionSoundCue);
        }

        // Destroy the pawn
        Destroy();
    }
}

When a bot is eliminated by the player, the PlayDying() function is executed. In this function the physics of the bot is defined as PHYS_RigidBody so that it falls to the ground.

Is checked the possibility of the bot drop a health item, which is represented by the class SPG_HealthPickup. This test is done with the expression: "FRand() <= ChanceToDropPickup". FRand() is an UnrealScript function that returns a random value between 0.0 and 1.0. The variable ChanceToDropPickup is defined in the Archetype with the value "0.3". This means that there is a chance of 30% that a health item falls from the bot.

simulated function PlayDying(class<DamageType> DamageType, vector HitLoc)
{
    local DroppedPickup DroppedPickup;

    Mesh.MinDistFactorForKinematicUpdate = 0.0;
    Mesh.ForceSkelUpdate();
    Mesh.SetTickGroup(TG_PostAsyncWork);
    CollisionComponent = Mesh;
    CylinderComponent.SetActorCollision(false, false);
    Mesh.SetActorCollision(true, false);
    Mesh.SetTraceBlocking(true, true);
    SetPawnRBChannels(true);

    SetPhysics(PHYS_RigidBody);

    Mesh.PhysicsWeight = 1.f;

    if (Mesh.bNotUpdatingKinematicDueToDistance)
    {
        Mesh.UpdateRBBonesFromSpaceBases(true, true);
    }

    Mesh.PhysicsAssetInstance.SetAllBodiesFixed(false);
    Mesh.bUpdateKinematicBonesFromAnimation = false;
    Mesh.WakeRigidBody();

    // Set the actor to automatically destroy in ten seconds.
    LifeSpan = 10.f;

    // Chance to drop a pick up
    if (ArchetypedPickup != None && FRand() <= ChanceToDropPickup)
    {
        // Spawn a dropped pickup
        DroppedPickup = Spawn(ArchetypedPickup.Class,,, Location,, ArchetypedPickup);

        if (DroppedPickup != None)
        {
            // Set the dropped pick up to falling
            DroppedPickup.SetPhysics(PHYS_Falling);

            // Set the velocity of the dropped pickup to the toss velocity
            DroppedPickup.Velocity.X = 0;
            DroppedPickup.Velocity.Y = 0;
            DroppedPickup.Velocity.Z = RandRange(200.f, 250.f);
        }
    }
}

Platformer Kit: SPG_Weapon class (UnrealScript)

2012-06-26T14:52:00.001-03:00

The SPG_Weapon class represents the weapon used in the Platformer Kit. It is based on the Link Gun weapon of Unreal Tournament, but only has the option of shooting with projectile.

If you do not know about the Weapon class first read the article: "Weapon Class (UnrealScript)".

The variables of the SPG_Weapon class are available for changing in the editor.

class SPG_Weapon extends Weapon;

// Name of the socket which represents the muzzle socket
var(Weapon) const Name MuzzleSocketName;

// Particle system representing the muzzle flash
var(Weapon) const ParticleSystemComponent MuzzleFlash;

// Projectile classes that this weapon fires. DisplayName lets the editor show this as WeaponProjectiles
var(Weapon) const array< class<Projectile> > Projectiles<DisplayName=Weapon Projectiles>;

// Sounds to play back when the weapon is fired
var(Weapon) const array<SoundCue> WeaponFireSounds;

An Archetype was also created for SPG_Weapon class. The image below shows the values of some variables.

The SPG_Weapon class uses two Sockets. One to define the position in the 3D model of the weapon where the projectile is fired. The other Socket belongs to the SPG_PlayerPawn class and defines the position where the weapon must stay relative to the player. To understand more about Sockets, read the article at UDN: "Skeletal Mesh Sockets".

In the PostBeginPlay() function, the Particle System Component represented by the "MuzzleFlash" variable is attached to the Socket of the weapon. The weapon is attached to the player in the ClientGivenTo() function.

simulated event PostBeginPlay()
{
    local SkeletalMeshComponent SkeletalMeshComponent;

    Super.PostBeginPlay();

    if (MuzzleFlash != None)
    {
        SkeletalMeshComponent = SkeletalMeshComponent(Mesh);
        if (SkeletalMeshComponent != None && SkeletalMeshComponent.GetSocketByName(MuzzleSocketName) != None)
        {
            SkeletalMeshComponent.AttachComponentToSocket(MuzzleFlash, MuzzleSocketName);
        }
    }
}

One function that is executed when the weapon is fired is the PlayFireEffects(). It is responsible for activating the Particles System and play the weapon firing sound.

For more information about Particles Systems, read the article at UDN: "Particles Systems".

Below is the image when the weapon is fired and the code of the PlayFireEffects() function.

simulated function PlayFireEffects(byte FireModeNum, optional vector HitLocation)
{
    if (MuzzleFlash != None)
    {
        // Activate the muzzle flash
        MuzzleFlash.ActivateSystem();
    }

    // Play back weapon fire sound if FireModeNum is within the array bounds and if the 
    // weapon fire sound in that array index is not none
    if (FireModeNum < WeaponFireSounds.Length && WeaponFireSounds[FireModeNum] != None && Instigator != None)
    {
        Instigator.PlaySound(WeaponFireSounds[FireModeNum]);
    }
}

The other function that is executed when the weapon is fired is the ProjectileFire(). It is responsible for creating a new projectile and start it in the correct position and direction.

The position of the projectile is obtained from the GetWeaponStartTraceLocation() function of the SPG_PlayerPawn class, which is represented in the code by the variable Instigator.

simulated function Projectile ProjectileFire()
{
    local Vector SpawnLocation;
    local Rotator SpawnRotation;
    local class<Projectile> ProjectileClass;
    local Projectile SpawnedProjectile;

    // tell remote clients that we fired, to trigger effects
    IncrementFlashCount();

    // Only allow servers to spawn projectiles
    if (Role == ROLE_Authority)
    {
        // This is where we would spawn the projectile
        SpawnLocation = Instigator.GetWeaponStartTraceLocation();

        // This is the rotation we should spawn the projectile
        SpawnRotation = GetAdjustedAim(SpawnLocation);

        // Get the projectile class
        ProjectileClass = GetProjectileClass();
        if (ProjectileClass != None)
        {
            // Spawn the projectile setting the projectile's owner to myself
            SpawnedProjectile = Spawn(ProjectileClass, Self,, SpawnLocation, SpawnRotation);

            // Check if we've spawned the projectile, and that it isn't going to be deleted
            if (SpawnedProjectile != None && !SpawnedProjectile.bDeleteMe)
            {
                // Initialize the projectile
                SpawnedProjectile.Init(Vector(SpawnRotation));
            }
        }
      
        // Return it up the line
        return SpawnedProjectile;
    }

    return None;
}

Platformer Kit: SPG_PlayerPawn class (UnrealScript)

2012-06-25T13:17:00.000-03:00

The SPG_PlayerPawn class represents the player's character. If you do not know about the Pawn class first read the article: "Pawn Class (UnrealScript)".

The variables below of the SPG_PlayerPawn class are available for changing in the editor.

class SPG_PlayerPawn extends Pawn;

// Dynamic light environment component to help speed up lighting calculations for the pawn
var(Pawn) const DynamicLightEnvironmentComponent LightEnvironment;

// How fast a pawn turns
var(Pawn) const float TurnRate;

// How high the pawn jumps
var(Pawn) const float JumpHeight;

// Socket to use for attaching weapons
var(Pawn) const Name WeaponSocketName;

// Height to set the collision cylinder when crouching
var(Pawn) const float CrouchHeightOverride<DisplayName=Crouch Height>;

// Radius to set the collision cylinder when crouching
var(Pawn) const float CrouchRadiusOverride<DisplayName=Crouch Radius>;

An Archetype was also created for SPG_PlayerPawn class. The image below shows the values of some variables.

The FaceRotation() function of the SPG_PlayerPawn class is called from the UpdateRotation() function of the SPG_PlayerController class.

This function will adjust two types of rotation: the rotation of the aim and the rotation of the character.

The rotation of the aim is adjusted from the variable "AimNode.Aim.Y" based on the value of the Pitch variable of the Rotator that is passed as a parameter. The variable AimNode is of the AnimNodeAimOffset type.

The rotation of the character is done based on the value of the Yaw variable of the Rotator that is passed as a parameter, using the SetRotation() function of the Pawn class.

simulated function FaceRotation(Rotator NewRotation, float DeltaTime)
{
    local Rotator FacingRotation;

    // Set the desired yaw the new rotation yaw
    if (NewRotation.Yaw != 0)
    {
        DesiredYaw = NewRotation.Yaw;
    }

    // If the current yaw doesn't match the desired yaw, then interpolate towards it
    if (CurrentYaw != DesiredYaw)
    {
        CurrentYaw = Lerp(CurrentYaw, DesiredYaw, TurnRate * DeltaTime);
    }

    // If we have a valid aim offset node
    if (AimNode != None)
    {
        // Clamp the current pitch to the view pitch min and view pitch max
        CurrentPitch = Clamp(CurrentPitch + NewRotation.Pitch, ViewPitchMin, ViewPitchMax);

        if (CurrentPitch > 0.f)
        {
            // Handle when we're aiming up
            AimNode.Aim.Y = float(CurrentPitch) / ViewPitchMax;
        }
        else if (CurrentPitch < 0.f)
        {
            // Handle when we're aiming down
            AimNode.Aim.Y = float(CurrentPitch) / ViewPitchMin;
           
            if (AimNode.Aim.Y > 0.f)
            {
                AimNode.Aim.Y *= -1.f;
            }
        }
        else
        {
            // Handle when we're aiming straight forward
            AimNode.Aim.Y = 0.f;
        }
    }

    // Update the facing rotation
    FacingRotation.Pitch = 0;
    FacingRotation.Yaw = CurrentYaw;
    FacingRotation.Roll = 0;

    SetRotation(FacingRotation);
}

The DoJump() function is called to perform the jump of the character. It takes into account the different types of Physics that the character can be.

In essence, the velocity along the Z axis (up) receives the value of the JumpHeight variable that was defined for this class and can be adjusted in the Archetype. After it is checked whether the player is on a moving platform. If true, then the velocitity of the platform (Base.Velocity.Z) influences the velocity of the jump of the player.

function bool DoJump(bool bUpdating)
{
    if (bJumpCapable && !bIsCrouched && !bWantsToCrouch && (Physics == PHYS_Walking || Physics == PHYS_Ladder || Physics == PHYS_Spider))
     {
        if (Physics == PHYS_Spider)
        {
            Velocity = JumpHeight * Floor;
        }
        else if (Physics == PHYS_Ladder)
        {
            Velocity.Z = 0.f;
        }
        else
        {
            Velocity.Z = JumpHeight;
        }

        if (Base != None && !Base.bWorldGeometry && Base.Velocity.Z > 0.f)
        {
            Velocity.Z += Base.Velocity.Z;
        }

        SetPhysics(PHYS_Falling);
        return true;
    }

    return false;
}

Platformer Kit: SPG_PlayerController class (UnrealScript)

2012-06-22T16:11:00.000-03:00

The SPG_PlayerController class is responsible for adapting the commands of the player to the platform style.

If you do not know about the Controller class, first read the article: "Controller Class (UnrealScript)".

One of the functions that is overridden is the UpdateRotation() whose code is below.

function UpdateRotation(float DeltaTime)
{
    local Rotator DeltaRot;

    // Set the delta rotation to that of the desired rotation, as the desired rotation represents
    // the rotation derived from the acceleration of the pawn
    DeltaRot = DesiredRotation;

    // Set the delta pitch to read from the look up input
    DeltaRot.Pitch = PlayerInput.aLookUp;

    // Never need to roll the delta rotation
    DeltaRot.Roll = 0;

    // Shake the camera if necessary
    ViewShake(DeltaTime);

    // If we have a pawn, update its facing rotation
    if (Pawn != None)
    {
        Pawn.FaceRotation(DeltaRot, DeltaTime);
    }
}

There are two types of rotations that occur in the Platformer Kit. One is the rotation that occurs when the player changes the direction he is moving. The other is the rotation of the aim that changes the direction of the fire.

The rotation of the player is manipulated through the use of the variable DesiredRotation. The rotation of the aim is obtained from the variable aLookUp of the PlayerInput class. The variable aLookUp maps the forward and backward movement of the Mouse. The image below shows the player looking upwards.

The FaceRotation() function which will be called from the Pawn object, is that defined in the SPG_PlayerPawn class.

In the PlayerMove() function an acceleration is calculated based on the variable "PlayerInput.aStrafe" which represents the horizontal movement. This acceleration is stored in the variable of type Vector "NewAccel". The function code is below.

state PlayerWalking
{
    function PlayerMove(float DeltaTime)
    {
        local Vector X, Y, Z, NewAccel, CameraLocation;
        local Rotator OldRotation, CameraRotation;
        local bool bSaveJump;

        // If we don't have a pawn to control, then we should go to the dead state
        if (Pawn == None)
        {
            GotoState('Dead');
        }
        else
        {
            // Grab the camera view point as we want to have movement aligned to the camera
            PlayerCamera.GetCameraViewPoint(CameraLocation, CameraRotation);

            // Get the individual axes of the rotation
            GetAxes(CameraRotation, X, Y, Z);

            // Update acceleration
            NewAccel = PlayerInput.aStrafe * Y;
            NewAccel.Z = 0;
            NewAccel = Pawn.AccelRate * Normal(NewAccel);

            // Set the desired rotation
            DesiredRotation = Rotator(NewAccel);

            // Update rotation
            OldRotation = Rotation;
            UpdateRotation(DeltaTime);

            // Update crouch
            Pawn.ShouldCrouch(bool(bDuck));

            // Handle jumping
            if (bPressedJump && Pawn.CannotJumpNow())
            {
                bSaveJump = true;
                bPressedJump = false;
            }
            else
            {
                bSaveJump = false;
            }

            // Update the movement, either replicate it or process it
            if (Role < ROLE_Authority)
            {
                ReplicateMove(DeltaTime, NewAccel, DCLICK_None, OldRotation - Rotation);
            }
            else
            {
                ProcessMove(DeltaTime, NewAccel, DCLICK_None, OldRotation - Rotation);
            }

            bPressedJump = bSaveJump;
        }
    }
}

At the end of the PlayerMove() function there is the following test: "if (Role < ROLE_Authority)". This is used to check if the game is a client that is using a server. If this code is running on a server or in a single player game then the value of the "Role" variable will be equal to "ROLE_Authority."

Platformer Kit: SPG_GameInfo class (UnrealScript)

2012-06-21T16:22:00.000-03:00

The main adjustments of the SPG_GameInfo class were done to enable the use of Archetypes of the player's Pawn and Weapon classes.

This class contains the references of the Archetypes in the DefaultPawnArchetype and DefaultWeaponArchetype variables.

class SPG_GameInfo extends SimpleGame;

// Variable which references the default pawn archetype stored within a package
var() const archetype Pawn DefaultPawnArchetype;
// Variable which references the default weapon archetype stored within a package
var() const archetype Weapon DefaultWeaponArchetype;

If you do not know the GameInfo class, take a look at my article, "GameInfo Class (UnrealScript)".

The SPG_GameInfo class overrides the SpawnDefaultPawnFor() function so that the instance of the player's Pawn class is created based on the Archetype.

function Pawn SpawnDefaultPawnFor(Controller NewPlayer, NavigationPoint StartSpot)
{
    local Rotator StartRotation;
    local Pawn SpawnedPawn;

    // Quick exit if NewPlayer is none or if StartSpot is none
    if (NewPlayer == None || StartSpot == None)
    {
        return None;
    }

    // Only the start spot's yaw from its rotation is required
    StartRotation = Rot(0, 0, 0);
    StartRotation.Yaw = StartSpot.Rotation.Yaw;

    // Spawn the default pawn archetype at the start spot's location and the start rotation defined above
    // Set SpawnedPawn to the spawned
    SpawnedPawn = Spawn(DefaultPawnArchetype.Class,,, StartSpot.Location, StartRotation, DefaultPawnArchetype);

    // Return the value of SpawnedPawn
    return SpawnedPawn;
}

The SpawnDefaultPawnFor() function uses a local variable of type Rotator called StartRotation to get only the rotation on the yaw axis from the StartSpot of the game. For more information about rotation, read my article: "Using Rotators in UnrealScript".

After that, it creates a new instance of Pawn based on the Archetype "DefaultPawnArchetype" using the Spawn() function.

Another function that is overridden in the SPG_GameInfo class is the AddDefaultInventory(). In this function is obtained a reference of the SPG_InventoryManager class in order to create the weapon based on the Archetype DefaultWeaponArchetype.

event AddDefaultInventory(Pawn P)
{
    local SPG_InventoryManager SPG_InventoryManager;

    Super.AddDefaultInventory(P);

    // Ensure that we have a valid default weapon archetype
    if (DefaultWeaponArchetype != None)
    {
        // Get the inventory manager
        SPG_InventoryManager = SPG_InventoryManager(P.InvManager);
        if (SPG_InventoryManager != None)
        {
            // Create the inventory from the archetype
            SPG_InventoryManager.CreateInventoryArchetype(DefaultWeaponArchetype, false);
        }
    }
}

In the defaultproperties block are specified the Archetypes of the Pawn and Weapon, besides the classes responsible for the HUD and the PlayerController.

defaultproperties
{
    // What player controller class to create for the player
    PlayerControllerClass=class'SPG_PlayerController'
    // What default pawn archetype to spawn for the player
    DefaultPawnArchetype=SPG_PlayerPawn'StarterPlatformGameContent.Archetypes.PlayerPawn'
    // What default weapon archetype to spawn for the player
    DefaultWeaponArchetype=SPG_Weapon'StarterPlatformGameContent.Archetypes.LinkGunWeapon'
    // What HUD class to create for the player
    HUDType=class'SPG_HUD'
}

Platformer Kit: SPG_InventoryManager class (UnrealScript)

2012-06-19T16:57:00.000-03:00

The SPG_InventoryManager class exists to allow the creation of inventory items based on Archetypes. In the Platformer Kit it is used to create the weapon of the player.

The class code is below:

class SPG_InventoryManager extends InventoryManager;

simulated function Inventory CreateInventoryArchetype(Inventory NewInventoryItemArchetype, optional bool bDoNotActivate)
{
    local Inventory    Inv;
  
    // Ensure the inventory archetype is valid
    if (NewInventoryItemArchetype != None)
    {
        // Spawn the inventory archetype
        Inv = Spawn(NewInventoryItemArchetype.Class, Owner,,,, NewInventoryItemArchetype);
      
        // Spawned the inventory, and add the inventory
        if (Inv != None && !AddInventory(Inv, bDoNotActivate))
        {
            // Unable to add the inventory, so destroy the spawned inventory
            Inv.Destroy();
            Inv = None;
        }
    }

    // Return the spawned inventory
    return Inv;
}

defaultproperties
{
    // Create the pending fire array
    PendingFire(0)=0
    PendingFire(1)=0
}

The CreateInventoryArchetype() function is called from the SPG_GameInfo class. It uses the Spawn() function to create an instance of the Inventory class based on the Archetype received as parameter.

The Spawn() function is defined in the Actor class and has the following parameters:

native noexport final function coerce actor Spawn
(
    class<actor>      SpawnClass,
    optional actor    SpawnOwner,
    optional name     SpawnTag,
    optional vector   SpawnLocation,
    optional rotator  SpawnRotation,
    optional Actor    ActorTemplate,
    optional bool     bNoCollisionFail
);

Once created the instance of Inventory, it is added to the player's inventory through the AddInventory() function. You can find the code of this function in my article "PickupFactory and Inventory in UnrealScript".

If for some reason it is not possible to add the Inventory, the Destroy() function should be called to remove the object from memory. The Destroy() function is not executed immediately, so you need to assign "None" to the variable after the call to the Destroy() function.

Platformer Kit: SPG_HealthPickup class (UnrealScript)

2012-06-15T14:21:00.000-03:00

The SPG_HealthPickup class is used to represent a health item that can be dropped from an enemy when he dies. This class is a subclass of DroppedPickup. Its variables are:

class SPG_HealthPickup extends DroppedPickup
      placeable;

// Static mesh used by the pick up
var(HealthPickup) const StaticMeshComponent Mesh;

// Sound to play when the pick up is picked up by a pawn
var(HealthPickup) const SoundCue PickupSound;

// How much health to give to the pawn when picked up
var(HealthPickup) const int HealthToGive;

The Platformer Starter Kit also uses an Archetype of this class to ease changes in the values of its variables.

The image below shows the default values of the Archetype of the SPG_HealthPickup class.

If you know nothing about Pickups, I recommend reading my article "PickupFactory and Inventory in UnrealScript".

The "GiveTo(Pawn P)" function is called when the player gets an item. It just plays a sound and gives more health to the player:

function GiveTo(Pawn P)
{
    // Play sound
    if (PickupSound != None)
    {
        PlaySound(PickupSound);        
    }

    // Add health to the player, but clamp it to the pawn's maximum health
    P.Health = Min(P.Health + HealthToGive, P.HealthMax);

    // Handle the rest of pick up
    PickedUpBy(P);
}

The "int Min(int A, int B)" function returns the smallest number between two integers and is used to prevent the player's health exceeds the maximum value. The "PickedUpBy(Pawn P)" function belongs to the DroppedPickup class and it just calls the "Destroy()" function to remove this Pickup from the game.

The SPG_HealthPickup class overrides the "ValidTouch(Pawn Other)" function, which is within the state "Pickup" of the DroppedPickup class, with a simpler version of the function. This function is called every time there is a collision with an object of type Pawn to check if it is the player who is picking up the item.

auto state Pickup
{
    function bool ValidTouch(Pawn Other)
    {
        // make sure its a live player
        if (Other == None || !Other.bCanPickupInventory || (Other.DrivenVehicle == None && Other.Controller == None))
        {
            return false;
        }

        // make sure thrower doesn't run over own weapon
        if (Physics == PHYS_Falling && Other == Instigator && Velocity.Z > 0)
        {
            return false;
        }

        return true;
    }
}

Finally, we have the defaultproperties block whose code is below. It defined an object of StaticMeshComponent type with the name MyStaticMeshComponent. If you look at the image of the Archetype that was created for this class, the Mesh property is associated with the MyStaticMeshComponent object that will be used as a component, using ":" and the name of the object.

defaultproperties
{
    // Remove the sprite component
    Components.Remove(Sprite);

    // Add the static mesh component
    Begin Object Class=StaticMeshComponent Name=MyStaticMeshComponent
    End Object
    Mesh=MyStaticMeshComponent
    Components.Add(MyStaticMeshComponent);
}

Platformer Kit: SPG_Camera class (UnrealScript)

2012-06-08T12:06:00.001-03:00

The Platformer Starter Kit uses a side view similar to the old 2D platform games. The SPG_Camera and SPG_CameraProperties classes are used to define the camera.

The SPG_CameraProperties class has only a Vector used to define the position of the camera relative to the player. The class code is below:

class SPG_CameraProperties extends Object
      HideCategories(Object);

// How much to offset the camera by
var(CameraProperties) const Vector CameraOffset;

defaultproperties
{
}

An Archetype was created based on this class in the package "StarterPlatformGameContent.Archetypes.CameraProperties" as shown in the image below.

The SPG_Camera class has an instance of the SPG_CameraProperties class that is loaded from the Archetype:

class SPG_Camera extends Camera;

var const archetype SPG_CameraProperties CameraProperties;

/**
 * Updates the camera's view target. Called once per tick
 *
 * @param    OutVT        Outputted camera view target
 * @param    DeltaTime    Time since the last tick was executed
 */
function UpdateViewTarget(out TViewTarget OutVT, float DeltaTime)
{
    // Early exit if:
    // - We have a pending view target
    // - OutVT currently equals ViewTarget
    // - Blending parameter is lock out going
    if (PendingViewTarget.Target != None && OutVT == ViewTarget && BlendParams.bLockOutgoing)
    {
        return;
    }

    // Add the camera offset to the target's location to get the location of the camera
    OutVT.POV.Location = OutVT.Target.Location + CameraProperties.CameraOffset;
    // Make the camera point towards the target's location
    OutVT.POV.Rotation = Rotator(OutVT.Target.Location - OutVT.POV.Location);
}

defaultproperties
{
    CameraProperties=SPG_CameraProperties'StarterPlatformGameContent.Archetypes.CameraProperties'
}

If you do not know anything about the Camera class, I recommend reading my article "Camera Class (UnrealScript)".

The SPG_Camera class modifies the camera in a very simple way, just overriding the UpdateViewTarget() function of the Camera class. This function receives as output parameter an variable of type TViewTarget, which is a structure (struct) defined in Camera class:

//Extract from Camera class...

/**
 * View Target definition
 * A View Target is responsible for providing the Camera with an ideal Point of View (POV)
 */
struct native TViewTarget
{
    /** Target Actor used to compute ideal POV */
    var()    Actor                   Target;

    /** Controller of Target (only for non Locally controlled Pawns) */
    var()    Controller              Controller;

    /** Point of View */
    var()    TPOV                    POV;

    /** Aspect ratio */
    var()    float                   AspectRatio;

    /** PlayerReplicationInfo (used to follow same player through pawn transitions, etc., when spectating) */
    var()    PlayerReplicationInfo   PRI;
};

Within the structure TViewTarget there is a variable called POV that represents the Point of View. It's of type TPOV which is a structure defined in Object class:

//Extract from Object class...

/**
 * Point Of View type.
 */
struct TPOV
{
    /** Location */
    var() Vector    Location;

    /** Rotation */
    var() Rotator    Rotation;

    /** FOV angle */
    var() float        FOV;

    structdefaultproperties
    {
        FOV=90.f
    }
};

Regarding the existing code in the UpdateViewTarget() function of the SPG_Camera class, the conditional test below was copied from the UpdateViewTarget() function of the Camera class and is used only to prevent the ViewTarget from being changed during an interpolation.

if (PendingViewTarget.Target != None && OutVT == ViewTarget && BlendParams.bLockOutgoing)

The camera setup is done in the two lines of code below, which defines the position of the Point of View as the player's position added with the existing Vector in the SPG_CameraProperties class. After that, it is defined the rotation needed to point the camera toward the player.

OutVT.POV.Location = OutVT.Target.Location + CameraProperties.CameraOffset;
OutVT.POV.Rotation = Rotator(OutVT.Target.Location - OutVT.POV.Location);

Platformer Kit: SPG_HUD class (UnrealScript)

2012-05-25T15:10:00.000-03:00

We have seen several concepts related to programming with UnrealScript. Now it's time to see all these concepts together and applied in a game.

In UDN (Unreal Developer Network) there is an excellent game example to study UnrealScript which is the Platformer Starter Kit, available at:

http://udn.epicgames.com/Three/DevelopmentKitGemsPlatformerStarterKit.html

This page at UDN has all the necessary guidelines to configure and run the Kit in UDK.

The UnrealScript source code of the Platformer Starter Kit is very well commented. Even so, some parts of the code is very complex for Beginners in UnrealScript. I'll start a series of articles analyzing the existing UnrealScript classes in the Platformer Starter Kit with the goal of generating an additional material to help in understanding the logic of this example of a functional game.

Let's start by looking at the simplest class: SPG_HUD. The only goal of this class is to draw on the bottom left of the screen the text "Health" with the numeric value that represents the current health of the player as in the image below.

If you do not know anything about the HUD class, I recommend reading my article "Drawing the HUD".

The SPG_HUD class has only the PostRender() function containing the following code.

event PostRender()
{
    local float XL, YL;
    local String Text;

    Super.PostRender();

    // Ensure that PlayerOwner and PlayerOwner.Pawn are valid
    if (PlayerOwner != None && PlayerOwner.Pawn != None)
    {
        // Set the text to say Health: and the numerical value of the player pawn's health
        Text = "Health: " $ PlayerOwner.Pawn.Health;
        // Set the font
        Canvas.Font = class'Engine'.static.GetMediumFont();
        // Set the current drawing color
        Canvas.SetDrawColor(255, 255, 255);
        // Get the dimensions of the text in the font assigned
        Canvas.StrLen(Text, XL, YL);
        // Set the current drawing position to the be at the bottom left position with a padding of 4 pixels
        Canvas.SetPos(4, Canvas.ClipY - YL - 4);
        // Draw the text onto the screen
        Canvas.DrawText(Text);
    }
}

The comments below are related to existing concepts in the above code.

There are two main functions in the HUD class used to draw on the screen, which are "DrawHud()" and "PostRender()". The "DrawHud()" is only called if the variable bShowHud is equal to true and if the Score Table is not visible (bShowScores equal to false). To understand the relationship between the functions "DrawHud()" and "PostRender()", analyze the function "PostRender()" of the HUD class (Engine package).

The PlayerOwner variable is declared in the HUD class and represents the PlayerController responsible for the HUD. Its initialization is done in the function "PostBeginPlay()" of the HUD class.

The concatenation of strings can be done using two operators: $ and @. The only difference between them is that the @ operator puts a space between the strings. Numerical values used in the concatenation are automatically converted to strings. Another way to concatenate strings is using the operators $= and @= that appends a string to an existing string variable. For example, to complement the text of the HUD with the information HealthMax, we can do so:

Text = "Health: " $ PlayerOwner.Pawn.Health;
Text @= "- HealthMax:" @ PlayerOwner.Pawn.HealthMax;

The font used to write the text is obtained from a static function in the Engine class. There are four pre-defined sizes of fonts that are obtained through the functions:

native static final function Font GetTinyFont();
native static final function Font GetSmallFont();
native static final function Font GetMediumFont();
native static final function Font GetLargeFont();

The definition of the font color is done by the SetDrawColor() function of the Canvas class. The color is represented in RGB format, where each parameter is one byte (0-255). It can also be defined the Alpha element of the color that represents its opacity. There is also the SetDrawColorStruct() function which receives a struct of type color. Below are the two functions:

native final function SetDrawColor(byte R, byte G, byte B, optional byte A = 255);

/** Set the draw color using a color struct */
final function SetDrawColorStruct(color C)
{
    SetDrawColor(C.R, C.G, C.B, C.A);
}

Using Archetypes in UnrealScript

2012-04-28T18:39:00.000-03:00

The use of archetypes allows us to store an instance of a class to be modified and used as a template to create other instances of that class in the level editor. This feature is very handy for Designers who want to modify Actors in the level without relying entirely on the programmer.

Create an Archetype is simple, just select an Actor of the level, right-click and choose "Create Archetype ...", as seen in the image below:

Another way to create an archetype is through the window "Actor Classes". Select a class and right-click to see the option "Create Archetype...".

After that, a dialog box is displayed where you should enter the name of the new archetype and the package where it will be stored. The "Grouping" is optional.

After creation, the new archetype will be displayed in the "Content Browser". You can change its properties by clicking the right button on the Archetype and choosing "Properties...". To get the full name of the Archetype choose "Copy Full Name to Clipboard" and then paste in the desired place.

I created a class called ArchetypeSpawner to illustrate the use of archetypes in UnrealScript. This class is placeable and has a variable named archetypeReference which is used to refer to an archetype. There is a function that can be called by other classes to create an instance based on the archetype referenced. In this example it was created a 5-second Timer that will call this function once. The great advantage of this example using archetypes is that the variable is displayed in the editor for the Designer, so he can create any Archetype and inform the full name in the variable archetypeReference in the properties window, as seen in the image and code below.

class ArchetypeSpawner extends Actor
      placeable;

var() const archetype Actor archetypeReference;
//The use of the archetype modifier is optional.
      
event simulated PostBeginPlay()
{
    SetTimer(5);    
}

function Timer()
{
    SpawnArchetypeAt( self.Location );
}    

function Actor SpawnArchetypeAt( vector startLocation ) 
{    
    local Actor archetypeSpawned;
    
    archetypeSpawned = Spawn(archetypeReference.Class, , , startLocation, , archetypeReference);
    
    return archetypeSpawned;
}      

defaultproperties
{    
    archetypeReference=UltraHealthPack'ArchetypeExample.HealthPackArchetype'
}

For more information about Archetypes:

Archetypes Technical Guide

AI Navigation in UnrealScript

2012-04-09T22:16:00.001-03:00

Moving in a level is a fundamental aspect of Artificial Intelligence in games. The most common form of AI navigation is based on waypoints that are placed on the level to create a network of paths. The UDK also supports a more efficient navigation system based on "Navigation Mesh" which results in a more natural movement.

Waypoints are represented by the class PathNode:

In the AIController class we have a code example that uses the waypoints system:

//Extract from AIController class (Engine package)

state ScriptedMove
{
    // state functions...
    
    Begin:
    // while we have a valid pawn and move target, and
    // we haven't reached the target yet
    while (Pawn != None &&
           ScriptedMoveTarget != None &&
           !Pawn.ReachedDestination(ScriptedMoveTarget))
    {
        // check to see if it is directly reachable
        if (ActorReachable(ScriptedMoveTarget))
        {
            // then move directly to the actor
            MoveToward(ScriptedMoveTarget, ScriptedFocus);
        }
        else
        {
           // attempt to find a path to the target
           MoveTarget = FindPathToward(ScriptedMoveTarget);
           if (MoveTarget != None)
           {
               // move to the first node on the path
               MoveToward(MoveTarget, ScriptedFocus);
           }
           else
           {
               // abort the move                
               ScriptedMoveTarget = None;
           }
        }
    }
}

In the system based on "Navigation Mesh", the path is represented by a set of convex polygons that are generated automatically in the level from an actor known as Pylon:

The functions related to pathfinding using "Navigation Mesh" are contained in a class called NavigationHandle. This class works with the concept of Path Constraints and Goal Evaluators. The use of Path Constraints allows to set criteria to be taken into account during the pathfinding. The simplest Path Constraint is the NavMeshPath_Toward. The Goal Evaluator is used to define the end of pathfinding. The most common Goal Evaluator is the NavMeshGoal_At.

Looking in the source code that came with the UDK, I found a simple example of pathfinding using "Navigation Mesh". The code below is from the function GeneratePathToActor() of the GameCrowdAgent class:

//Extract from GameCrowdAgent class (GameFramework package)

/**
  * Generate a path to Goal on behalf of the QueryingAgent
  */
event vector GeneratePathToActor( Actor Goal, optional float WithinDistance, optional bool bAllowPartialPath )
{
    local vector NextDest;

    LastPathingAttempt = WorldInfo.TimeSeconds;
    NextDest = Goal.Location;

    // make sure we have a valid navigation handle
    if ( NavigationHandle == None )
    {
        InitNavigationHandle();
    }
    if( (NavigationHandle != None) && !NavigationHandle.ActorReachable(Goal) )
    {
        class'NavMeshPath_Toward'.static.TowardGoal( NavigationHandle, Goal );
        class'NavMeshGoal_At'.static.AtActor( NavigationHandle, Goal, WithinDistance, bAllowPartialPath );

        if ( NavigationHandle.FindPath() )
        {
            NavigationHandle.GetNextMoveLocation(NextDest, SearchExtent.X);
        }
        NavigationHandle.ClearConstraints();
    }

    return NextDest;
}

For more information about AI Navigation:

AI & Navigation

Using Configuration Files in UnrealScript

2012-03-17T10:02:00.000-03:00

Configuration files are files in plain text format with the extension ".ini" with informations that will be used by the game.

In the folder "..\UDK-20??-??\UDKGame\Config" you will find various configuration files used by the UDK. As an example, the file "DefaultInput.ini" that is used for key binds.

The main advantage in using configuration files is to allow the setting of a game without having to recompile the source code. Thus a Game Designer can make the adjustments of the data of a game without relying on a programmer.

To use a configuration file in a class, add the modifier config as follows:

class ClassName extends SuperClass config(ConfigName);

To identify what are the variables that will get their values from the configuration files, also use the config modifier when declaring the variables:

var config int exampleVar;

The next step is to create in the folder "..\UDK-20??-??\UDKGame\Config" a configuration file named "DefaultConfigName.ini" containing the values to be stored in variables. When the game runs it will look for a file called "UDKConfigName.ini". If this file is not found, the game will look for "DefaultConfigName.ini" in order to create the "UDKConfigName.ini" with default values. You should not edit the file "UDKConfigName.ini" because at some time it may be overwritten and you will lose your changes.

We can use the function "SaveConfig()" to save in the file "UDKConfigName.ini" new values of configuration variables that were modified during the execution of the game. There is another function called "StaticSaveConfig()" which allows the default values to be restored. This is a common option in the settings screen of games, as can be seen in the image below.

The function "StaticSaveConfig()" is static, that means it does not need an object to be executed. The static functions are like class functions, to run it just use the class name plus the word static as in this example:

class'ClassName'.static.StaticSaveConfig();

As an example, I made a class that draws on the screen some information that was obtained in a configuration file, as can be seen in the image below.

I created a configuration file called "DefaultWarrior.ini" containing the following information:

[RomeroScripts.CyberWarrior]
codename=DeadLocker
age=33

implants=Bionic Eye
implants=Night Vision
implants=Thermal Resistence

Attributes=(strength=12, agility=10, baseExperience=5000, currentExperience=6000)

The first line shows what is the class that will use this file. "RomeroScripts" is the name of the package that I use and "CyberWarrior" is the name of the class.

The class "CyberWarrior" defines the configuration variables. Then it uses a Timer of 1 second to increase the Current Experience and uses another Timer of 10 seconds to save the data of the player. The function "DrawHUD()" draws the informations on the screen.

class CyberWarrior extends SimplePawn
      config(Warrior);

var config string codename;      
var config int age;

var config Array<string>    implants;

struct stAttributes
{
    var int strength, agility, baseExperience, currentExperience;
};

var config stAttributes Attributes;

event simulated PostBeginPlay()
{
    SetTimer(1, true);
    SetTimer(10, true, 'SaveWarrior');
}
function Timer()
{
    Attributes.currentExperience++;    
}
function SaveWarrior()
{
    SaveConfig();
}

simulated function DrawHUD( HUD H )
{
    local int i;
    
    super.DrawHUD(H);
    
    H.Canvas.SetDrawColor(255, 255, 255); // White   
    
    H.Canvas.SetPos(50, 10);   
    H.Canvas.DrawText("Codename:" @ codename @ "- Age:" @ age) ;
    
    H.Canvas.SetPos(50, 40);
    H.Canvas.DrawText( "*** Attributes ***" );
    H.Canvas.SetPos(50, 55);
    H.Canvas.DrawText( "Strength :" @ Attributes.strength);
    H.Canvas.SetPos(50, 70);
    H.Canvas.DrawText( "Agility :" @ Attributes.agility);
    H.Canvas.SetPos(50, 85);
    H.Canvas.DrawText( "Base Experience :" @ Attributes.baseExperience);
    H.Canvas.SetPos(50, 100);
    H.Canvas.DrawText( "Current Experience :" @ Attributes.currentExperience);
    
    H.Canvas.SetPos(300, 40);
    H.Canvas.DrawText( "*** Implants ***");
    for( i =0; i < implants.Length; i++)
    {
       H.Canvas.SetPos(300, 55 + i * 15);       
       H.Canvas.DrawText( implants[i] );
    }    
}

To use this class we need to create the new GameInfo that will reference the class CyberWarrior:

class GameWarrior extends SimpleGame;

defaultproperties
{        
    DefaultPawnClass=class'RomeroScripts.CyberWarrior'    
}

I'm using as the base class "SimpleGame" because it is easier to write on the screen in "SimpleGame" than using the "UTGame".

When running the game you will see that the information "Current Experience" is changed every second. Wait at least 10 seconds before leaving the game to be saved the current state of the class. When you exit the game, look for the file "UDKWarrior.ini" in the configuration folder. You'll see that "currentExperience", which is within the "Attributes", was modified. Also appear in this file other configuration variables that belong to the superclass "SimplePawn".

For more information:

Configuration files

Vehicle Class (UnrealScript)

2012-03-06T19:07:00.002-03:00

The Vehicle class is a subclass of Pawn. The vehicle system in the UDK is quite complex and allows the creation of different types of vehicles. The image below shows the subclasses of the Vehicle class in the UDK:

We can see four types of vehicles defined that are: UTVehicle_Cicada, UTVehicle_Hoverboard, UTVehicle_Manta and UTVehicle_Scorpion. However, all of these classes have the abstract modifier. This indicates that objects of these classes cannot be created. The main idea of abstract classes is to create a base class with several features to serve as a model. The classes that really define the vehicles are those that end with the name "_Content".

To place vehicles in the level you have to use the UDKVehicleFactory class which is a subclass of "Actor->NavigationPoint". The image below shows the existing types in UDK:

There are only three Factory. The vehicle that is missing is the Hoverboard because it is already available to the player in the game type "Vehicle Capture The Flag". To test it in the editor set the Game Type to UTVehicleCTFGame_Content and after starting the game press the "Q" key to use the Hoverboard that is a sort of skateboard without wheels as seen in the image below.

To enter a vehicle that is available on the level, go near it and press the "E" key. If you can enter the vehicle, one of the functions of the Vehicle class that will be called is "DriverEnter(Pawn P)" whose code is below.

//Extract from Vehicle class (Engine package)

/** DriverEnter()
 * Make Pawn P the new driver of this vehicle
 * Changes controller ownership across pawns
 */
function bool DriverEnter(Pawn P)
{
    local Controller C;

    // Set pawns current controller to control the vehicle pawn instead
    C = P.Controller;
    Driver = P;
    Driver.StartDriving( self );
    if ( Driver.Health <= 0 )
    {
        Driver = None;
        return false;
    }
    SetDriving(true);

    // Disconnect PlayerController from Driver and connect to Vehicle.
    C.Unpossess();
    Driver.SetOwner( Self ); // This keeps the driver relevant.
    C.Possess( Self, true );

    if( PlayerController(C) != None && !C.IsChildState(C.GetStateName(), LandMovementState) )
    {
        PlayerController(C).GotoState( LandMovementState );
    }

    WorldInfo.Game.DriverEnteredVehicle(self, P);
    return true;
}

This function takes the object reference of the Pawn who entered the vehicle and keep in the variable Driver so it can be restored when leaves the vehicle. The Controller stops to reference the Pawn through the function "Unpossess()" and will now reference the vehicle through the function "Possess (Self, true)". The Self object is the reference to the vehicle and the second parameter with the value "true" indicates that it is a transition to a vehicle. A test is done to verify if the Controller is a PlayerController and if it is not in the state LandMovementState. LandMovementState is a variable of type name that was defined in the Pawn class. This type of variable is used to store the name of an item in UnrealScript such as names of classes, functions and states. In the Pawn class it receives the value PlayerWalking in the DefaultProperties. In the Vehicle class this variable receives the value PlayerDriving. This means that when entering a vehicle the PlayerController go to the state PlayerDriving.

In the PlayerController we can see a good example of the use of states. Each Tick the "PlayerMove()" function is called, if the state is PlayerWalking then the "PlayerMove()" function will call the "ProcessMove()" function, but if the state is PlayerDriving then the "PlayerMove()" function will call "ProcessDrive()". The code below shows the functions defined for the state PlayerDriving in the PlayerController class.

//Extract from PlayerController classe (Engine package)

// Player Driving a vehicle.
state PlayerDriving
{
ignores SeePlayer, HearNoise, Bump;

    function ProcessMove(float DeltaTime, vector NewAccel, eDoubleClickDir DoubleClickMove, rotator DeltaRot);

    // Set the throttle, steering etc. for the vehicle based on the input provided
    function ProcessDrive(float InForward, float InStrafe, float InUp, bool InJump)
    {
        local Vehicle CurrentVehicle;

        CurrentVehicle = Vehicle(Pawn);
        if (CurrentVehicle != None)
        {            
            bPressedJump = InJump;
            CurrentVehicle.SetInputs(InForward, -InStrafe, InUp);
            CheckJumpOrDuck();
        }
    }

    function PlayerMove( float DeltaTime )
    {        
        UpdateRotation(DeltaTime);
      
        ProcessDrive(PlayerInput.RawJoyUp, PlayerInput.RawJoyRight, PlayerInput.aUp, bPressedJump);
        if (Role < ROLE_Authority)
        {
            ServerDrive(PlayerInput.RawJoyUp, PlayerInput.RawJoyRight, PlayerInput.aUp, bPressedJump, 
                        ((Rotation.Yaw & 65535) << 16) + (Rotation.Pitch & 65535));
        }

        bPressedJump = false;
    }

    unreliable server function ServerUse()
    {
        local Vehicle CurrentVehicle;

        CurrentVehicle = Vehicle(Pawn);
        CurrentVehicle.DriverLeave(false);
    }

    event BeginState(Name PreviousStateName)
    {
        CleanOutSavedMoves();
    }

    event EndState(Name NextStateName)
    {
        CleanOutSavedMoves();
    }
}

For more information about the Vehicle class:

Vehicle System Technical Guide

Using Physics in UnrealScript

2012-02-27T21:46:00.002-03:00

The code below shows an enumeration in the Actor class that indicates the possible types of physics that an Actor can use.

//Extract from Actor class

var(Movement) const enum EPhysics
{
    PHYS_None,
    PHYS_Walking,
    PHYS_Falling,
    PHYS_Swimming,
    PHYS_Flying,
    PHYS_Rotating,
    PHYS_Projectile,
    PHYS_Interpolating,
    PHYS_Spider,
    PHYS_Ladder,
    PHYS_RigidBody,
    PHYS_SoftBody, 
    PHYS_NavMeshWalking, 
    PHYS_Unused,
    PHYS_Custom,    
} Physics;

I didn't find any official reference about the meaning of each of these types. To define the physic type of an Actor use the function SetPhysics() passing as parameter one of the enumeration values, as in the example below:

SetPhysics(PHYS_Projectile);

To initialize the physics of a Pawn use the function SetMovementPhysics() that has the following code:

//Extract from Pawn class

function SetMovementPhysics()
{
    // check for water volume
    if (PhysicsVolume.bWaterVolume)
    {
        SetPhysics(PHYS_Swimming);
    }
    else if (Physics != PHYS_Falling)
    {
        SetPhysics(PHYS_Falling);
    }
}

When an object of the Pawn class is with the physics type PHYS_Falling he is affected by gravity and will fall until touch a ground when turns to PHYS_Walking. In the PHYS_Flying type, the Actor is not affected by the effect of gravity. In the PHYS_Rotating type only the rotation of the actor changes and the location doesn't change.

The Actor variables most used by the physics system are the Velocity and Acceleration vectors that change the position of the Actor. For rotation we have the variable RotationRate that defines the speed of rotation. The actor also had the variable DesiredRotation, but it was moved to the Pawn class. This variable is used to rotate a Pawn smoothly until it reaches the specified rotation in DesiredRotation.

I did a very simple example that only changes the physics type of the player to PHYS_Flying. The following code defines a new GameInfo, to test it is necessary to set the Game Type in the editor as UTGameFlying.

class UTGameFlying extends UTGame;

function StartMatch()
{ 
 local UTPlayerController playerController;
 
 super.StartMatch();
 foreach LocalPlayerControllers(class 'UTPlayerController', playerController) 
 {
    if( playerController.pawn != None ) 
    {            
      playerController.pawn.SetPhysics(PHYS_Flying);            
    }
 }
}

For more information about Physics in UDK:
Physics Home

Weapon Class (UnrealScript)

2012-02-16T20:50:00.002-03:00

The Weapon class is a subclass of Inventory. The Weapon System in UDK is very flexible for creating different types of weapons or usable items. The image below shows the existing subclasses of Weapon in UDK:

Each weapon can have multiple firing modes. The UDK uses two types: primary, which is fired with the left mouse button, and the secondary, which is fired with the right mouse button. However, other firing modes can be created. For each firing mode is necessary to define the fire type. The UDK already has defined two fire types, the Instant Fire that is used for very fast weapons such as a Sniper Rifle. In this fire type, the bullet is not created. What happens at the time of the shooting is that a trace is done representing the path of the bullet to find any obstacle collision immediately. The other fire type is the Projectile Fire. When the weapon is fired in this fire type, an object of Projectile class is created with the information of speed and direction. The Projectile class is responsible for the collision checking.

The fire types are defined in the Weapon class in an Enumeration (enum). An enum is very useful to limit the possible values that a variable can have. A dynamic Array is used to define the fire type for each firing mode. Each position in the Array represents a firing mode. The index of an Array starts in zero, so the information of the primary firing mode is in the index zero and the information of the secondary firing mode is in the index one. The following code shows the declaration of the enum and the Array.

// Extract from Weapon class (Engine package)

enum EWeaponFireType
{
    EWFT_InstantHit,
    EWFT_Projectile,
    EWFT_Custom,
    EWFT_None
};

var Array<EWeaponFireType>  WeaponFireTypes;

A good weapon example in UDK is the Link Gun. This is the default weapon that the player gets when runs a game in UDK as UTGame. The Link Gun's primary firing mode is of type EWFT_Projectile that launches fast plasmas projectiles. The secondary firing mode is of type EWFT_InstantHit that fires a constant plasma beam as shown below.

The class that defines the Link Gun weapon is UTWeap_LinkGun. In the defaultproperties block are defined the fire type and the class that represents the projectile for the primary firing mode as seen in the code below.

//Extract from UTWeap_LinkGun class (UTGame package)

defaultproperties
{
  //...

  WeaponFireTypes(0)=EWFT_Projectile
  WeaponProjectiles(0)=class'UTProj_LinkPlasma'

  //...
}

The function of the Weapon class responsible for firing weapons of type EWFT_InstantHit is InstantFire(). The function used in the type EWFT_Projectile to fire projectiles is ProjectileFire(). Below is a sample code of the ProjectileFire() function in the UTWeapon class.

//Extract from UTWeapon class (UTGame package)

simulated function Projectile ProjectileFire()
{
    local vector        RealStartLoc;
    local Projectile    SpawnedProjectile;

    // tell remote clients that we fired, to trigger effects
    IncrementFlashCount();

    if( Role == ROLE_Authority )
    {
        // this is the location where the projectile is spawned.
        RealStartLoc = GetPhysicalFireStartLoc();

        // Spawn projectile
        SpawnedProjectile = Spawn(GetProjectileClass(),,, RealStartLoc);

        if( SpawnedProjectile != None && !SpawnedProjectile.bDeleteMe )
        {
            SpawnedProjectile.Init( Vector(GetAdjustedAim( RealStartLoc )) );
        }

        // Return it up the line
        return SpawnedProjectile;
    }

    return None;
}

For more information about the Weapon class:
Weapon System Technical Guide

PickupFactory and Inventory in UnrealScript

2012-02-02T21:10:00.001-03:00

The PickupFactory class was created to provide inventory items for players in the levels of the Unreal Tournament game. It is represented visually by a base and by the item that it provides as in the image above.

PickupFactory is a subclass of NavigationPoint which is a subclass of Actor. The tree class below shows the types of PickupFactory available in UDK:

Another way to represent an inventory item in the level is using the DroppedPickup class. This class is used when a Pawn throws an inventory item in the level, this can happen when he dies.

The InventoryManager class is responsible for managing the inventory items of a Pawn. As an example of inventory items in Unreal Tournament we have the Jump Boots, the Berserker which increases the rate of fire, the UDamage that increases the damage, and all weapons are subclasses of the Inventory class as can be seen in the image below.

When a Pawn touches a PickupFactory or a DroppedPickup, an object of Inventory class is provided to the player through the function "Inventory.GiveTo(Pawn Other)". This function calls another function of InventoryManager called AddInventory() that checks if the new inventory item exists in a linked list of Inventory objects before adding it. After this, the function "Inventory.GivenTo()" is called which finally calls the function "Inventory.AdjustPawn()" that is responsible for adding or removing the effect of the item in the Pawn object.

The code below is from the AddInventory() function of InventoryManager class. In this function we can see the use of the linked list of objects of the Inventory class.

//In the InventoryManager class: 

simulated function bool AddInventory(Inventory NewItem, optional bool bDoNotActivate)
{
    local Inventory Item, LastItem;
    
    if( (NewItem != None) && !NewItem.bDeleteMe )
    {
        // if we don't have an inventory list, start here
        if( InventoryChain == None )
        {
            InventoryChain = newItem;
        }
        else
        {
            // Skip if already in the inventory.
            for (Item = InventoryChain; Item != None; Item = Item.Inventory)
            {
                if( Item == NewItem )
                {
                    return FALSE;
                }
                LastItem = Item;
            }
            LastItem.Inventory = NewItem;
        }
        
        //Instigator is a variable that keeps a reference to the Pawn that gets the Item.
        NewItem.SetOwner( Instigator );
        NewItem.Instigator = Instigator;
        NewItem.InvManager = Self;
        NewItem.GivenTo( Instigator, bDoNotActivate);
        
        Instigator.TriggerEventClass(class'SeqEvent_GetInventory', NewItem);
        return TRUE;
    }

    return FALSE;
}

Camera Class (UnrealScript)

2012-01-08T23:00:00.001-03:00

The Camera class is used to define the point of view of the player in the 3D game world. To move the camera during the game simply adjust its Location and Rotation properties. The Camera class works together with the Pawn and PlayerController classes to control its position and effects that occur during the game.

In Unreal Tournament the default camera used is in first person. This camera is simple to define as we just need to get the point of view related to the eyes of the Actor that represents the player. This is done with this function in Pawn class:

GetActorEyesViewPoint( out vector out_Location, out Rotator out_Rotation )

The third-person camera is used in some situations in the game Unreal Tournament, for example when the player enters a vehicle. Setting a third-person camera is much more complex because we must also consider whether there is any obstacle between the camera and the player. The code that calculates the position for this camera is in this function of UTPawn class:

bool CalcThirdPersonCam( float fDeltaTime, out vector out_CamLoc, out rotator out_CamRot, out float out_FOV )

The Camera class has a function called UpdateCamera(float DeltaTime) that is called every frame. This function calls another function DoUpdateCamera(float DeltaTime) which calls UpdateViewTarget(out TViewTarget OutVT, float DeltaTime). The function UpdateViewTarget allows the Pawn class to set the camera position calling its CalcCamera() function in the code snippet below:

//Inside Camera.UpdateViewTarget(out TViewTarget OutVT, float DeltaTime):
                
 TPawn = Pawn(OutVT.Target);
 // Give Pawn Viewtarget a chance to dictate the camera position.
 // If Pawn doesn't override the camera view, then we proceed with our own defaults
 if( TPawn == None || !TPawn.CalcCamera(DeltaTime, OutVT.POV.Location, OutVT.POV.Rotation, OutVT.POV.FOV) )
 { 
   //camera default...
 }

The code below is the function CalcCamera of the UTPawn class:

simulated function bool CalcCamera( float fDeltaTime, out vector out_CamLoc, out rotator out_CamRot, out float out_FOV )
{
    // Handle the fixed camera

    if (bFixedView)
    {
        out_CamLoc = FixedViewLoc;
        out_CamRot = FixedViewRot;
    }
    else
    {
        if ( !IsFirstPerson() )    // Handle BehindView
        {
            CalcThirdPersonCam(fDeltaTime, out_CamLoc, out_CamRot, out_FOV);
        }
        else
        {
            // By default, we view through the Pawn's eyes..
            GetActorEyesViewPoint( out_CamLoc, out_CamRot );
        }

        if ( UTWeapon(Weapon) != none)
        {
            UTWeapon(Weapon).WeaponCalcCamera(fDeltaTime, out_CamLoc, out_CamRot);
        }
    }
    return true;
}

At the end of this code we can see that the function allows the weapon in use to do some adjustment to the camera through the WeaponCalcCamera() function. I looked in the weapons classes of UTDemo that come with the UDK and none implements this function. An example of a weapon that should do this adjustment is the Sniper Rifle in Zoom mode.

For more information about Camera:

Camera Technical Guide

Sniper Rifle Zoom in UT2004

Using Rotators in UnrealScript

2012-01-02T07:14:00.004-03:00

In UnrealScript the rotation of 3D objects is done through the use of a structure called Rotator that is defined in the Object class as follows:

struct immutable Rotator
{
    var() int Pitch, Yaw, Roll;
};

Each of the integer variables Pitch, Yaw and Roll, represents the rotation around an axis. The keyword "immutable" is a structure modifier used to optimize the serialization of Rotator variables.

The Unreal Engine uses integer values between -32768 and +32767 to represent the angle in degrees between -180 and 180, or 0 to 65535 for the angles of 0 to 360 degrees. This range of values corresponds to the capacity of a 16-bit integer variable and maybe is an inheritance from the 1st version of the Unreal Engine, because at this time the mathematical operations with integers were much faster than the operations done with float numbers.

To help in the conversion of angles between degrees, radians and Unreal Rotation, some constants are defined in the Object class:

const Pi = 3.1415926535897932;
const RadToDeg = 57.295779513082321600;    // 180 / Pi
const DegToRad = 0.017453292519943296;    // Pi / 180
const UnrRotToRad = 0.00009587379924285;// Pi / 32768
const RadToUnrRot = 10430.3783504704527;// 32768 / Pi
const DegToUnrRot = 182.0444;
const UnrRotToDeg = 0.00549316540360483;

To use these constants just multiply by the desired value. For example, if we want to find out how much is 90 degrees in Unreal Rotation, do as follows:

unreal90Degree = 90 * DegToUnrRot;

The Actor class has a variable called Rotation of type Rotator defined as follows:

/** The actor's rotation; use SetRotation to change. */
var(Movement) const rotator    Rotation;

This variable is defined as const (constant) indicating that its contents can not be changed. To change the rotation of an Actor you must use the SetRotation function:

native(299) final function bool SetRotation( rotator NewRotation );

The native keyword indicates that this function is implemented in C++, so we can not see its source code, because in the UDK only comes UnrealScript source code. The final keyword means that this function can not be overridden in a subclass.

I made an example to demonstrate the use of the Rotator. I use a ship of Unreal Tournament and did a movement of rotation around each axis.

class TestRotator extends Actor
      placeable;
    
var float velRotation;

event Tick(float DeltaTime)
{
   local float deltaRotation;
   local Rotator newRotation;
   
   deltaRotation = velRotation * DeltaTime; 
   
   newRotation = Rotation;
   
   newRotation.Pitch += deltaRotation;
   newRotation.Yaw  += deltaRotation;   
   newRotation.Roll  += deltaRotation;   

   SetRotation( newRotation );       
}

defaultproperties
{
    velRotation=5000
   
    Begin Object Class=DynamicLightEnvironmentComponent Name=LightEnvironmentComp
        bEnabled = true
    End Object    
    Components.add( LightEnvironmentComp )
    
    Begin Object Class=SkeletalMeshComponent Name=SVehicleMesh
        SkeletalMesh=SkeletalMesh'VH_Cicada.Mesh.SK_VH_Cicada'
        AnimTreeTemplate=AnimTree'VH_Cicada.Anims.AT_VH_Cicada'
        PhysicsAsset=PhysicsAsset'VH_Cicada.Mesh.SK_VH_Cicada_Physics'
        AnimSets.Add(AnimSet'VH_Cicada.Anims.VH_Cicada_Anims')
        LightEnvironment = LightEnvironmentComp
    End Object
    Components.add( SVehicleMesh )        
}

PlayerInput Class (UnrealScript)

2011-12-18T23:03:00.004-03:00

The PlayerInput class was created to help manage the player input. This class is an inner class of PlayerController class. This means that an object of PlayerInput class can not exist without an object of PlayerController class.

The PlayerInput class is declared this way:

class PlayerInput extends Input within PlayerController

An inner class has direct access to variables and functions of the outer class. But if in the inner class there are variables / functions with the same name, you must use the keyword "Outer" to reference the outer class. It is always recommended to use the keyword "Outer" to avoid confusion in the code. As an example, the PlayerController class has a variable named "bDemoOwner". To access it in the PlayerInput class, use:

Outer.bDemoOwner

The instance of the PlayerInput class is created in the function "InitInputSystem()" of PlayerController class as follows:

PlayerInput = new(Self) InputClass;

The "InputClass" is defined in the PlayerController's DefaultProperties and "Self" is the reference of PlayerController class that will be stored in the Outer object of PlayerInput class.

-----

As seen in the article on Key Binds and Exec Functions, the configuration file "DefaultInput.ini" is used to define the commands that can be executed by the player.

In the PlayerInput class are defined variables that will store some information related to Axes. These variables have a modifier called input making them accessible to the Unreal input system.

Below are some examples of variables in the PlayerInput class:

var input    float    aBaseX;
var input    float    aBaseY;
var input    float    aBaseZ;
var input    float    aMouseX;
var input    float    aMouseY;
var input    float    aForward;
var input    float    aTurn;
var input    float    aStrafe;
var input    float    aUp;
var input    float    aLookUp;

var input    float    aRightAnalogTrigger;
var input    float    aLeftAnalogTrigger;

Example of a binding to one of these variables:

.Bindings=(Name="GBA_MoveForward",Command="Axis aBaseY Speed=1.0")

The action GBA_MoveForward assign the position of the axis of the input device directly to the variable aBaseY. The "Speed" attribute is used to multiplier the value of the axis.

-----

When a function is bind to a key/button, it will only be called once when the key is pressed. The function will only be called again when you release and press the key/button. This way we can not implement actions that are performed while the key is being pressed.

To solve this problem we can use an exec function that receives a boolean value as parameter. When the key is pressed the function is called with the value "true" and when the key is released (Onrelease) the function is called with the value "false".

As an example, in the Unreal Tournament the Score Table is displayed while the F1 key is being pressed. When you release the F1 key the Score Table is no longer displayed.

The code below shows the binding and the function that stores the boolean value.

//In DefaultInput.ini:

.Bindings=(Name="GBA_ShowScores",Command="SetShowScores true | Onrelease SetShowScores false")


//In HUD class (Engine package):

/** sets bShowScores to a specific value (not toggle) */
exec function SetShowScores(bool bNewValue)
{ 
    bShowScores = bNewValue; 
}

Exploring the UnrealScript source code with UnCodeX

2011-11-25T22:55:00.001-03:00

The largest and most updated reference about UnrealScript is the source code that comes with the UDK. But sometimes it's difficult to follow the source code and understand the relationship between the classes.

To help in this task we will use a tool called UnCodeX, which was developed by Michiel 'elmuerte' Hendriks, and can be downloaded on the project page.

The installation is simple, in the first execution of the UnCodeX a message box will appear asking you to change the settings. Choose "Yes". If you want to change the settings later, access the menu: "Tree -> Settings...".

In the setting "Source Paths" add the folder "\Development\Src" of the UDK, as in the image below.

The UnCodeX will analyze all the packages and classes to display them as follows:

As an example we will research and analyze a class. In the previous tutorial I used the static mesh of "Jump Boots" of the Unreal Tournament. Let's try to find the class that implements the "Jump Boots".

Access the Menu: "Find -> Find Class ...", type in the search query "boots" and check the "Search from the top" as in the image, so that the research is done from the base Object class.

Press "OK" to start the search. The UnCodex found the class "UTJumpBoots" which is exactly what we wanted. If we want to continue the search, press F3 to "Find Next".

Right-clicking in the class, we can see that it's in the package "UTGameContent". Let's choose the option "Show Properties..." to have an overview of variables and functions of this class.

Looking at the source code of this class we can see some functions that deal with the multiplayer aspect of Unreal Tournament.

Let's start by looking at the "defaultproperties" block. It defined the StaticMesh that will represents this class in the game. Some values are assigned for the variables, such as the variable "Charges" which indicates how many times the boots can be used.

The AdjustPawn() function adds or removes the bonus of the boots on the player. In this function we can see an comments error caused by a Copy/Paste operation.

Another interesting function is BotDesireability() that calculates the interest of the bot for this item. Basically, the function checks if the bot already has one and how many times can still be used.

The main goal of this tutorial is to show that you can learn many things about UnrealScript viewing the source code that comes with UDK.