UnrealScript Iterators

Overview

UnrealScript's foreach command makes it easy to deal with large groups of actors, for example all of the actors in a level, or all of the actors within a certain distance of another actor. The foreach command works in conjunction with a special kind of function called an iterator function whose purpose is to iterate through a list of actors.

Here is a simple example of using an iterator with the foreach command:

// Display a list of all lights in the level.
function Something()
{
	local Actor A;

	// Go through all actors in the level.
	log( "Physics:" );
	foreach AllActors( class 'Actor', A )
	{
		if( A.Physics != PHYS_Interpolating )
			log( A );
	}
}

The first parameter in all foreach commands is a constant class, which specifies what kinds of actors to search. You can use this to limit the search to, for example, all Pawns only.

The second parameter in the foreach command is a variable that is assigned as an actor for the duration of each iteration through the foreach loop.

Iterator Functions

Here are all of the iterator functions that work with the foreach command.

Actor

These iterator functions are all members of the Actor class so if you want to use an iterator from within a function in a non-Actor, you must have an actor variable and use the following syntax:

AllActors ( class<actor> BaseClass, out actor Actor, optional class InterfaceClass )

Iterates through all actors in the level. If you specify an optional InterfaceClass, only includes actors that implement the InterfaceClass.

DynamicActors( class<actor> BaseClass, out actor Actor, optional class InterfaceClass )

Iterates through all actors with bStatic=false

ChildActors( class<actor> BaseClass, out actor Actor )

Iterates through all actors owned by this actor.

BasedActors( class<actor> BaseClass, out actor Actor )

Iterates through all actors which use this actor as a base.

TouchingActors( class<actor> BaseClass, out actor Actor )

Iterates through all actors which are touching (interpenetrating) this actor.

TraceActors( class<actor> BaseClass, out actor Actor, out vector HitLoc, out vector HitNorm, vector End, optional vector Start, optional vector Extent )

Iterates through all actors which touch a line traced from the Start point to the End point, using a box of collision extent Extent. On each iteration, HitLoc is set to the hit location, and HitNorm is set to an outward-pointing hit normal.

OverlappingActors( class<actor> BaseClass, out actor Actor, float Radius, optional vector Loc, optional bool bIgnoreHidden )

Iterates through all actors within a specified Radius of the specified location (or if none is specified, this actor's location).

VisibleActors( class<actor> BaseClass, out actor Actor, optional float Radius, optional vector Loc )

Iterates through a list of all actors who are visible to the specified ==Loc==ation (or if no location is specified, this actor's location).

VisibleCollidingActors ( class<actor> BaseClass, out actor Actor, float Radius, optional vector Loc, optional bool bIgnoreHidden )

returns all colliding (bCollideActors==true) actors within a certain radius for which a trace from Loc (which defaults to caller's Location) to that actor's Location does not hit the world. Much faster than AllActors() since it uses the collision hash.

CollidingActors ( class<actor> BaseClass, out actor Actor, float Radius, optional vector Loc )

returns colliding (bCollideActors==true) actors within a certain Radius. Much faster than AllActors() for reasonably small radii since it uses the collision hash

ComponentList( class<ActorComponent> BaseClass, out ActorComponent out_Component )

returns all components in the actor's Component's list

AllOwnedComponents( class<Component> BaseClass, out ActorComponent OutComponent )

returns all components attached "directly or indirectly" to the actor

LocalPlayerControllers( class<PlayerController> BaseClass, out PlayerController PC)

returns all local PlayerControllers

The syntax for using one of these iterators from a non-Actor would be:

foreach ActorVar.DynamicActors(class'Pawn', P)

So, from within an Interaction class, you could do:

foreach ViewportOwner.Actor.DynamicActors(class'Pawn', P)

WorldInfo

These iterator functions are all members of the WorldInfo class so you need a reference to the WorldInfo to use any of these.

AllControllers(class<Controller> BaseClass, out Controller C)

Iterates through all the Controllers (Player or AI) currently in the level.

AllPawns(class<Pawn> BaseClass, out Pawn P, optional vector TestLocation, optional float TestRadius)

Iterates through all the Pawns within the current level. You can optionally specify a radius (TestRadius) to iterate within around a given location (TestLocation)

AllNavigationPoints(class<NavigationPoint> BaseClass, out NavigationPoint N)

Iterates through the list of all NavigationPoints in the NavigationPointList.

RadiusNavigationPoints(class<NavigationPoint> BaseClass, out NavigationPoint N, vector Point, float Radius)

Iterates through the list of all NavigationPoints in the NavigationPointList within the specified Radius of the location specified by the Point parameter.

AllClientConnections(out Player ClientConnection, out int ClientIP, out int ClientPort)

Iterates through the list of all Player objects that have a Network Connection, along with their IP and Port. May only be run on servers.

The syntax for using one of these iterators from an Actor would be:

foreach WorldInfo.AllControllers(class'Controller', C)

From within a non-Actor, you could do:

foreach class'WorldInfo'.static.GetWorldInfo().AllControllers(class'Controller', C)

Foreach with Dynamic Arrays

Dynamic arrays now support iteration using the foreach command as well. The basic syntax is:

foreach ArrayVariable(out ArrayItem, optional out ItemIndex)
{
   ...
}

ArrayItem must be of the same type as the elements in the array. Each iteration will increment the index and write out the item as well as the index if a property is supplied.

See the Iterating Dynamic Arrays section on the UnrealScript Variables page for more information.