Difference between revisions of "Legacy:Actor (UT)/Functions"

Revision as of 13:02, 13 February 2016

Native Functions

General Functions

string ConsoleCommand (string Command) [native, but not final] 

Execute a console command.

Error (coerce string S) 

Handle an error and kill this one actor.

Actor Spawn (class<Actor> SpawnClass, optional Actor SpawnOwner, optional name SpawnTag, optional vector SpawnLocation, optional rotator SpawnRotation) 

Spawn an actor. Returns an actor of the specified class, not of class Actor (this is hardcoded in the compiler). Returns None if the actor could not be spawned (either the actor wouldn't fit in the specified location, or the actor list is full). Defaults to spawning at the spawner's location and with the spawner's rotation.

bool Destroy() 

Destroy this actor. Returns true if destroyed, false if indestructable. Destruction is latent. It occurs at the end of the tick.

SetTimer (float NewTimerRate, bool bLoop) 

If bLoop is true, causes Timer() events every NewTimerRate seconds. Otherwise, causes Timer() to be called once in NewTimerRate seconds. SetTimer(0.0, False); stops the timer.

Latent Functions

Latent Function are special native functions that can only be used in state code. (i.e. in labels outside of functions within states. See ScriptedPawn's script for excellent examples). They will cause script execution within the state to pause until some condition is met. All other functions and states in other classes will continue to execute normally.

While you cannot define new latent functions, it possible to pull a similar effect:

While (!SomeConditionIsMet()) //Pause until this function returns true
  Sleep(0.0);

Sleep (float Seconds) 

Waits for the specified amount of time. Note using continual low values of sleep() (<0.1) is not recommended, as this creates signnificant dependance on frame rate. For instance, the minigun has this problem, where different frame rates make it fire different amounts of bullets in a second. See this graph.

FinishAnim ( ) 

Waits till the current animation is finished. WARNING: If you have an AnimEnd() that plays a new animation, this will never pass!

FinishInterpolation ( ) 

Only used mostly in movers. Pauses until the mover has finished interpolated to the next key.

Collision

SetCollision (optional bool NewColActors, optional bool NewBlockActors, optional bool NewBlockPlayers) 

bool SetCollisionSize (float NewRadius, float NewHeight) 

Actor Trace (out vector HitLocation, out vector HitNormal, vector TraceEnd, optional vector TraceStart, optional bool bTraceActor, optional vector Extent) 

Trace a line and see what it collides with first. Takes this actor's collision properties into account. Returns first hit actor, the LevelInfo if hit level geometry, or None if hit nothing. bTraceActors specifies whether Trace should check for actors at all.

Highlander: UT2003 info, Trace returns as expected the static mesh actor if it hits a static mesh, and returns the TerrainInfo if it hits terrain.

bool FastTrace (vector TraceEnd, optional vector TraceStart) 

Returns True when there is no world geometry between the two points. The actor's location is used as start if no TraceStart is specified.

Movement

bool Move (vector Delta) 

Moves an actor to Location + Delta. Stops if is blocked.

bool SetLocation (vector NewLocation) 

Self-explanatory

bool SetRotation (rotator NewRotation) 

Self-explanatory. See also rotator.

bool MoveSmooth (vector Delta) 

Moves an actor to Location + Delta. If blocked, the actor will slide on the object it collided with (i.e. as your player does when you walk into a wall).

AutonomousPhysics (float DeltaSeconds) 

Used in PlayerPawn in netgames. Causes Physics to be handed with a DeltaTime of DeltaSeconds.

SetPhysics (EPhysics newPhysics) 

Sets the actor's movement physics.

Relations

SetBase (Actor NewBase) 

SetOwner (Actor NewOwner) 

Animations

PlayAnim (name Sequence, optional float Rate, optional float TweenTime)

Plays an Animation (must have a mesh set for this to work!)

• Sequence = Anim sequence Name
• Rate = Animation Rate multiplier
• TweenTime = Amount of Time to "tween" into the first frame of this animation sequence if in a different sequence.

LoopAnim (name Sequence, optional float Rate, optional float TweenTime, optional float MinRate)

Plays an animation that loops until another animation is played.

TweenAnim (name Sequence, float Time)

Tween into a new animation.

bool IsAnimating ( )

Returns whether the actor's mesh currently plays an animation.

name GetAnimGroup (name Sequence)

Returns the group of the actor's current animation.

bool HasAnim (name Sequence)

Returns whether the specified animation is present for the actor's current mesh.

LinkSkelAnim (Animation Anim)

Generally never used. Will Link a Skeletal animation to a skeletal mesh.

Sounds

PlaySound (sound Sound, optional ESoundSlot Slot, optional float Volume, optional bool bNoOverride, optional float Radius, optional float Pitch)

Plays a sound.

• Slot: Sound slot (allows actors to play multiple sounds at once)
• bNoOverride: If true and a sound is currently playing in the specified slot, the new sound will not play (override the current sound).
• Volume, Radius, Pitch: see discussion

PlayOwnedSound (sound Sound, optional ESoundSlot Slot, optional float Volume, optional bool bNoOverride, optional float Radius, optional float Pitch) [simulated] 

This plays a sound that will not be replicated to network clients. It is generally used for first-person weapon sound effects, HUD notifications, etcetera.

DemoPlaySound (sound Sound, optional ESoundSlot Slot, optional float Volume, optional bool bNoOverride, optional float Radius, optional float Pitch) [simulated]

float GetSoundDuration (sound Sound) 

Returns the length of the sound in seconds.

AI Functions

MakeNoise (float Loudness) 

Inform other creatures that you've made a noise they might hear (they are sent a HearNoise message). Senders of MakeNoise should have an Instigator if they are not Pawn (UT)s.

bool PlayerCanSeeMe ( ) 

PlayerCanSeeMe returns true if some player has a line of sight to actor's location.

Other Functions

string GetMapName (string NameEnding, string MapName, int Dir) 

The horribly slow function that uses an O(X^2) algorithm to find maps. When searching for maps it's useful to set the NameEnding parameter to the prefix for the type of maps you are looking for. The MapName parameter can be set to any map name (possibly even maps that don't exist) and its value is used to derive the name of the next map returned by this function. The Dir parameter should be set to 1 to move forwards in the list of map names, -1 to move backwards, and 0 to return the same map. A Dir of 0 is onle every used with a MapName value of "" to obtain the first map in the list of maps for a given map prefix. Be aware that this function will loop from the last map in a "list" to the "first" map in the list without warning.

GetNextSkin (string Prefix, string CurrentSkin, int Dir, out string SkinName, out string SkinDesc) 

Another slow function that finds skins.

string GetURLMap ( ) 

Supposedly returns the current map's filename. (although gives false results in save games and demos).

string GetNextInt (string ClassName, int Num) 

Reads through the INT files in the system directory and returns the classname of entries with a MetaClass given by ClassName.

GetNextIntDesc (string ClassName, int Num, out string Entry, out string Description) 

Like GetNextINT, only supports the Description tag in INT files.

bool GetCacheEntry (int Num, out string GUID, out string Filename) 

Reads through the cache.ini and returns the FileName and GUID of files within the cache directory.

bool MoveCacheEntry (string GUID, optional string NewFilename) 

Will "move" an entry somewhere... (haven't fully tested it).

Scripted Functions and Engine Notifications

General Notifications

AnimEnd ( ) 

Called when an animation has completed.

Destroyed ( ) 

Called when the actor is destroyed.

Expired ( ) 

Called when the actor's LifeSpan has reached 0.

GainedChild (Actor Other) 

Called when this actor becomes the Owner of other.

LostChild (Actor Other) 

Called when this actor is no longer the Owner of other (including other being destroyed()).

Tick (float DeltaTime) 

Called once each frame. DeltaTime is the time that has passed since the last frame.

Timer ( ) 

Called when the Timer has expired (Launched by SetTimer()).

TravelPreAccept ( ) 

Called when carried onto a new level, before AcceptInventory.

TravelPostAccept ( ) 

Called when carried into a new level, after AcceptInventory.

BecomeViewTarget ( ) 

Called by PlayerPawn when this actor becomes its ViewTarget.

Initialisation

(also see Creating Actors and Objects)

Spawned ( ) 

Called only when the actor is created using the Spawn method.

PreBeginPlay ( ) 

Called immediately before gameplay begins.

BeginPlay ( ) 

Called when gameplay begins.

PostBeginPlay ( ) 

Called after gameplay begins, before variables have been replicated to the clients.

SetInitialState ( ) [simulated] 

Called after PostBeginPlay to set the initial state of the actor.

PostNetBeginPlay ( ) [simulated] 

Called on net clients after the data packet that spawned this actor has been completely processed. However, replicated variables are NOT guarenteed to have reached the client.

Triggers

Trigger (Actor Other, Pawn (UT) EventInstigator) 

Handled in subclasses.

UnTrigger (Actor Other, Pawn (UT) EventInstigator) 

Handled in subclasses.

BeginEvent ( ) 

EndEvent ( ) 

Physics and World Interaction

HitWall (vector HitNormal, Actor HitWall) 

Called when the actor hits a fall. ( NB, defined for projectile actors only and called from within touch() if the touching actor has blockall set. )

Falling ( ) 

Called when Pawns begin to fall.

Landed (vector HitNormal) 

Called when an actor hits the ground. (What is the angle in relation to a flat plane that the ground must be at to be considered ground and not a wall?)

ZoneChange (ZoneInfo NewZone) 

Called when actor is about to enter a new Zone.

Touch (Actor Other) 

Called when Other touches this actor (and this actor doesn't block that actor).

PostTouch (Actor Other) 

// called for PendingTouch actor after physics completes

UnTouch (Actor Other) 

Called when Other is no longer touching this actor.

Bump (Actor Other) 

Called when an actor bumps into this actor and is blocked.

BaseChange ( ) 

Called when the actor's base changes.

Attach (Actor Other) 

Detach (Actor Other) 

KillCredit (Actor Other) 

Not implemented in Epic's Code.

Actor SpecialHandling (Pawn (UT) Other) 

Used by the navigation system to modify results.

bool EncroachingOn (Actor Other) 

Called when this actor is trying to take up the same space as Other. (and block each other?)

EncroachedBy (Actor Other) 

Called when Other has taken up this actor's space. (and block each other).

InterpolateEnd (Actor Other) 

EndedRotation ( ) 

Called when an actor's rotation has reached DesiredRotation?

FellOutOfWorld ( ) 

This is called when an actor enters zone 0. Zone 0 is the region of non-subtracted space in your level. Actors can enter this zone through BSP errors or if they are of a type that does not collide with the world.

bool PreTeleport (Teleporter InTeleporter) 

Called by InTeleporter when trying to Teleport this actor. Return true to prevent Teleporter from Teleporting.

PostTeleport (Teleporter OutTeleporter ) 

Not implemented?

Damage

KilledBy (Pawn (UT) EventInstigator) 

TakeDamage (int Damage, Pawn (UT) EventInstigator, vector HitLocation, vector Momentum, name DamageType) 

Implemented in subclasses.

Rendering

RenderOverlays (Canvas Canvas) 

Draw on canvas before flash and fog are applied. (used for drawing weapons). Note that only the PlayerPawn receives this call from the engine.

RenderTexture (ScriptedTexture (UT) Tex) 

Called when a scripted texture with this Actor set as NotifyActor needs rendering.

SetDisplayProperties (ERenderStyle NewStyle, texture NewTexture, bool bLighting, bool bEnviroMap) 

Set the display properties of an actor. By setting them through this function, it allows the actor to modify other components (such as a Pawn (UT)'s Weapon (UT)) or to adjust the result based on other factors (such as a Pawn (UT)'s other Inventory (UT) wanting to affect the result)

SetDefaultDisplayProperties ( ) 

Sets the default display properties similar to SetDisplayProperties.

Messages

BroadcastMessage (coerce string Msg, optional bool bBeep, optional name Type) 

Broadcast a string message to all players. This calls ClientMessage on all Pawn (UT)s (see Pawn (UT)/Events). See SpecialEvent for an example. Type can be one of 'Event' (default), 'CriticalEvent', 'Say', 'TeamSay', 'DeathMessage', 'Pickup' and maybe other types for custom HUD classes.

BroadcastLocalizedMessage (class<LocalMessage (UT)> Message, optional int Switch, optional PlayerReplicationInfo RelatedPRI_1, optional PlayerReplicationInfo RelatedPRI_2, optional Object OptionalObject) 

Broadcast a localized message to all players. Most message deal with 0 to 2 related PRIs. The LocalMessage (UT) class defines how the PRI's and optional actor are used.

Other Functions

HurtRadius (float DamageAmount, float DamageRadius, name DamageName, float Momentum, vector HitLocation) [final] 

Hurt other actors within a radius of this actor. ExplosionChain uses this, for example.

string GetItemName (string FullName) 

Returns the string representation of the name of an object without the package prefixes.

string GetHumanName ( ) 

Returns the human readable string representation of an object.

Mychaeel: I've seen that elsewhere too – I really think that everything up to and including the "function" keyword should be stripped from function prototype here on the Wiki in order to keep the clutter at a minimum. It's much more important to see that a function returns a string value than knowing that it's native(123).

Wormbo: Ok, how about putting really important stuff (final, static, etc.) in brackets behind the function definition?
HurtRadius (float DamageAmount, float DamageRadius, name DamageName, float Momentum, vector HitLocation) [final]

Mychaeel: I could live with that.  :-)

Wormbo: How's that?

Mychaeel: Much tidier :-)

Hugh: I've just made a change to the SetTimer() description - I think I'm right, but can someone confirm?

Zedsquared: Looks good but has anyone experimented to see what happens if timer() takes longer than TimerRate to execute? do you get another event fired or will it wait?

Mychaeel: Since UnrealScript code doesn't execute in parallel and lengthy execution of code in Timer blocks everything else, the engine will simply fire the next timer event in the next tick.

BesigedB: Tick, tock, tick, tock.

Highlander: I guess this is a Trace related question, ive noticed that when a trace() hits terrain the HitLocation points towards the TerrainInfo actor ?? Am i correct or am i loosing my mind?

Claw: Hmm, are you certain it's the HitLocation? I experienced something similar in UT; when a Trace hit the Level, the HitActor would be the LevelInfo (maybe ZoneInfo if one existed, I never checked). Maybe your code uses HitActor.Location?

Highlander: Positive, it doesnt matter as i found a way around the particular problem that uses less traces. It does return the TerrainInfo as the actor however, the vsize of the hitlocation was 3000units + in my tests. (The trace was 128 units long) and i was approximately 3000 units from the center of the map where the terrain info was.

Foxpaw: Hitlocation is relative to the center of the world, as far as I know... I think that the terraininfo and center of the map just coincided. Can someone confirm this? I've noticed that in UT2003 instantfire weapons scratch the hitlocation and replace it with the end of the trace instead of the point where the trace actually impacted the map, that seems silly but I expect it's done that way for a reason.

Claw: Strange, when I just tested it again with the newest patch, the HitLocation definitely wasn't the HitActor's Location. It wasn't the correct spot either. But I verified the error is linked to the position where the trace starts. From the center of the map Trace works allright.

Foxpaw: HitLocation isn't usually the location of the actor you hit, but instead the point upon that objects collision sphere/cylinder/whatever. I'm not sure why your traces would not be returning the correct location for hitlocation when you hit the world - it works fine for me.