Scripting Command Reference

*Taken from the RealmCrafter: Standard documentation.*

```
		AbilityKnown(Actor, Ability)

```

**Description:**
The AbilityKnown command returns 1 if an ability is
known by a player (i.e. in the ability book, but not necessarily memorised), or
0 if the ability is not known.

**Example:**

```
		Function Main()
			Result = AbilityKnown(Actor(), "Heal Self")
			If (Result == 0)
				Output(Actor(), "You do not know the healing spell")
			Else
				Output(Actor(), "You already know the healing spell")
			EndIf
			Return()
		End Function

```

```
		AbilityLevel(Actor, Ability)

```

**Description:**

The AbilityLevel command returns the level an ability
is at if the actor knows it, or 0 if the actor does not know it. You can change
the level with the SetAbilityLevel command.

**Example:**

```
		Function Main()
			Result = AbilityLevel(Actor(), "Heal Self")
			Output(Actor(), "Your healing spell is at level" $+ Result)
			Return()
		End Function

```

```
		AbilityMemorised(Actor, Ability)

```

**Description:**
The AbilityMemorised command returns 1 if an ability
is known and memorised by a player, or 0 if the ability is not memorised. All
known abilities must be memorised before they can be used.

**Example:**

```
		Function Main()
			Result = AbilityMemorised(Actor(), "Heal Self")
			If (Result == 0)
				Output(Actor(), "You have not memorised the healing spell")
			Else
				Output(Actor(), "You are ready to use the healing spell")
			EndIf
			Return()
		End Function

```

```
		AddAbility(Actor, Ability, [Level])

```

**Description:**
The AddAbility command gives an actor access to an
ability in their ability book. It will need to be memorised before they can use
it. Abilities could be used for many things, including magic, psionic powers,
martial arts, etc.
The Ability parameter is the name of an ability created
in the main editor. The optional Level parameter allows you to create the
ability with a high level. The default level is 1.

**Example:**

```
		Function Main()
			// Give player a healing spell
			AddAbility(Actor(), "Heal Self")
			Return()
		End Function

```

```
		DeleteAbility(Actor, Ability)

```

**Description:**
The DeleteAbility command removes an ability from an
actor's ability book, so that it may no longer be used, unless it is added again
with the AddAbility command.

**Example:**

```
		Function Main()
			// Remove player's healing spell, if present
			DeleteAbility(Actor(), "Heal Self")
			Return()
		End Function

```

### SetAbilityLevel

**Usage:**

```
		SetAbilityLevel(Actor, Ability, Level)

```

**Description:**
The SetAbilityLevel command changes the level an
ability is at, if the actor knows it. The level appears in the ability book and
can be used by the ability script to alter the effects of the ability.

**Example:**

```
		Function Main()
			// Increase healing spell to level 2
			SetAbilityLevel(Actor(), "Heal Self", 2)
			Return()
		End Function

```

## Actor Commands

### Actor

**Usage:**

```
		Actor()

```

**Description:**
The Actor command returns a handle to the actor for
whom the script is running. An actor handle is required for use in many commands
such as Output. Usually the actor whose handle is
returned is the player. For example: if the script is executed by a player
right-clicking an NPC, Actor will return the handle of the player actor, and ContextActor will return the handle of the NPC
actor.

**Example:**

```
		Function Main()
			Player = Actor()
			Output(Player, "Hello World!") // Displays Hello World!
			Return()
		End Function

```

### ActorAggressiveness

**Usage:**

```
		ActorAggressiveness(Actor)

```

**Description:**
The ActorAggressiveness command returns the
aggressiveness level of an actor. As this setting is per-actor rather than
per-actor instance, it cannot be changed. The values returned are as follows:

0 - Passive
1 - Defensive
2 - Aggressive
3 - Non-combatant

**Example:**

```
		Function Main()
			AggLvl = ActorAggressiveness(Actor())
			Output(Actor(), "Your aggression level: " $+ AggLvl)

			Return()
		End Function

```

### ActorAIState

**Usage:**

```
		ActorAIState(Actor, State)

```

**Description:**
The ActorAIState command returns the current AI mode
of an actor. There are various possible states:
0 - Wait in current
position, attack any valid targets who come into range
1 - Patrol - walk to
destination, then set destination to new waypoint if available
2 - Run -
same as Patrol but running instead of walking
3 - Chase and attack target

4 - For actors who are paused at a waypoint while on patrol
5 - Pet mode
- actor will follow leader and attack leader's target (actor MUST have a leader
to use this)
6 - Pet attack mode - actor is chasing and attacking the
leader's target
7 - Pet wait mode - actor waits in current position and does
absolutely nothing

**Example:**

```
		Function Main()
			// Give an NPC a boost if it is attacking
			State = ActorAIState(Actor())
			If (State == 3 | State == 6)
				SetAttribute(Actor(), "Health", Attribute(Actor(), "Health") + 20)
			EndIf

			Return()
		End Function

```

### ActorBeard

**Usage:**

```
		ActorBeard(Actor)

```

**Description:**
The ActorBeard command returns the beard mesh which
the actor is using. The returned value is a number between 1 and 5.

**Example:**

```
		Function Main()
			MyBeard = ActorBeard(Actor())
			Output(Actor(), "You are using beard " $+ MyBeard)
			Return()
		End Function

```

### ActorClothes

**Usage:**

```
		ActorClothes(Actor)

```

**Description:**
The ActorClothes command returns the body texture
which the actor is using. The returned value is a number between 1 and 5.

**Example:**

```
		Function Main()
			MyBody = ActorClothes(Actor())
			Output(Actor(), "You are using body texture " $+ MyBody)
			Return()
		End Function

```

### ActorDestinationX

**Usage:**

```
		ActorDestinationX(Actor)

```

**Description:**
The ActorDestinationX command returns the X
coordinate of the point to which the specified actor is travelling.

**Example:**

```
		Function Main()
			X = ActorDestinationX(Actor())
			Z = ActorDestinationZ(Actor())
			Output(Actor(), "You are travelling towards point (" $+ X $+ ", " $+ Z $+ ")"
			Return()
		End Function

```

### ActorDestinationZ

**Usage:**

```
		ActorDestinationZ(Actor)

```

**Description:**
The ActorDestinationZ command returns the Z
coordinate of the point to which the specified actor is travelling.

**Example:**

```
		Function Main()
			X = ActorDestinationX(Actor())
			Z = ActorDestinationZ(Actor())
			Output(Actor(), "You are travelling towards point (" $+ X $+ ", " $+ Z $+ ")"
			Return()
		End Function

```

### ActorDistance

**Usage:**

```
		ActorDistance(ActorA, ActorB)

```

**Description:**
The ActorDistance command returns the distance
between two actors, as a floating point value.

**Example:**

```
		Function Main()
			Result = ActorDistance(Actor(), ContextActor())
			Output(Actor(), "Distance to context actor: " $+ Result)
			Return()
		End Function

```

### ActorFace

**Usage:**

```
		ActorFace(Actor)

```

**Description:**
The ActorFace command returns the face texture which
the actor is using. The returned value is a number between 1 and 5.

**Example:**

```
		Function Main()
			MyFace = ActorFace(Actor())
			Output(Actor(), "You are using face texture " $+ MyFace)
			Return()
		End Function

```

### ActorGender

**Usage:**

```
		ActorGender(Actor)

```

**Description:**
The ActorGender command returns whether an actor is
male, female or neither. If the actor is male, the command returns 1. If it is
female, it returns 2, and if it is neither the command returns 3.

**Example:**

```
		Function Main()
			MyGender = ActorGender(Actor())
			If (MyGender == 1)
				Output(Actor(), "You are male.")
			ElseIf (MyGender == 2)
				Output(Actor(), "You are female.")
			ElseIf (MyGender == 3)
				Output(Actor(), "You have no gender.")
			EndIf
			Return()
		End Function

```

### ActorGlobal

**Usage:**

```
		ActorGlobal(Actor, ID)

```

**Description:**
The ActorGlobal command returns the value of a given
actor global variable. IDs range from 0 to 9. Each actor has 10 global
variables, which can be accessed from any script. This is useful for storing
data on a per-actor basis.

**Example:**

```
		Function Main()
			SetActorGlobal(Actor(), 2, 5)
			Result = ActorGlobal(Actor(), 2)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### ActorGroup

**Usage:**

```
		ActorGroup(Actor)

```

**Description:**
The ActorGroup command returns the ID number of an
actor's group. The value returned is between 0 and 65535, with zero being no
group. For more information, see SetActorGroup.

**Example:**

```
		Function Main()
			MyGroup = ActorGroup(Actor())
			Output(Actor(), "You are in group number " $+ MyGroup)
			Return()
		End Function

```

### ActorHair

**Usage:**

```
		ActorHair(Actor)

```

**Description:**
The ActorHair command returns the hair mesh which the
actor is using. The returned value is a number between 1 and 5.

**Example:**

```
		Function Main()
			MyHair = ActorHair(Actor())
			Output(Actor(), "You are using hair " $+ MyHair)
			Return()
		End Function

```

### ActorHasEffect

**Usage:**

```
		ActorHasEffect(Actor, Effect)

```

D**escription:**
The ActorHasEffect command returns 1 if an effect is
currently active on an actor, or 0 if not. For more information see AddActorEffect.

**Example:**

```
		Function Main()
			Result = ActorHasEffect(Actor(), "Poison")
			If (Result == 0)
				Output(Actor(), "You are not poisoned")
			Else
				Output(Actor(), "You have been poisoned!")
			EndIf
			Return()
		End Function

```

### ActorID

**Usage:**

```
		ActorID(Race, Class)

```

**Description:**
The ActorID command returns an ID number representing
a particular race/class actor combination. These IDs are set when an actor is
created in the main editor, and do not change. These IDs can then be used with
other scripting commands, such as WaitKill and Spawn.

**Example:**

```
		Function Main()
			// Wait for player to kill 5 Orcs
			ID = ActorID("Orc", "Warrior")
			WaitKill(Actor(), ID, 5)
			Return()
		End Function

```

### ActorIDFromInstance

**Usage:**

```
		ActorIDFromInstance(Actor)

```

**Description:**
The ActorIDFromInstance command returns an ID number
representing a particular race/class actor combination. These IDs are set when
an actor is created in the main editor, and do not change. These IDs can then be
used with other scripting commands, such as WaitKill
and Spawn.
The difference between this command and
ActorID is that instead of specifying the race and
class for the actor ID to be returned, you specify an existing actor instance
(e.g. a player or NPC), and the ID of the actor it is based on will be returned.

**Example:**

```
		Function Main()
			Player = Actor()

			// Turn the player into a wolf
			OldID = ActorIDFromInstance(Player)
			ID = ActorID("Wolf", "Critter")
			ChangeActor(Player, ID)

			// Wait 10 seconds
			DoEvents(10000)

			// Turn him back into whatever he was before
			ChangeActor(Player, OldID)

			Return()
		End Function

```

### ActorInTrigger

**Usage:**

```
		ActorInTrigger(Actor, Trigger)

```

**Description:**
The ActorInTrigger command returns 1 if the specified
actor is inside the volume of the specified trigger, or 0 if outside. Trigger
IDs are always the same once the trigger is placed, and can be found as the
first parameter passed to a trigger script. See the Parameter command for how to extract this value.

**Example:**

```
		Function Main()
			// Give actor 10 health if within the volume of trigger 3
			Ac = Actor()
			If (ActorInTrigger(Ac, 3))
				SetAttribute(Ac, "Health", Attribute(Ac, "Health") + 10)
			EndIf

			Return()
		End Function

```

### ActorIsHuman

**Usage:**

```
		ActorIsHuman(Actor)

```

**Description:**
The ActorIsHuman command returns 1 if the specified
actor is a human player, or 0 if it is an NPC.

**Example:**

```
		Function Main()
			Human = ActorIsHuman(Actor())
			If (Human == 1)
				Output(Actor(), "You are a human player.")
			Else
				// Don't bother sending a message, NPCs can't read them anyway!
			EndIf
			Return()
		End Function

```

### ActorLeader

**Usage:**

```
		ActorLeader(Actor)

```

**Description:**
The ActorLeader command returns 'owner' of an
specified actor. If the actor is not a pet, the command returns 0. Otherwise, an
actor handle will be returned. You can set the leader of an actor with the SetLeader command.

**Example:**

```
		Function Main()
			SetLeader(ContextActor(), Actor())
			Output(Actor(), "You gained a pet!")
			Return()
		End Function

```

### ActorLevel

**Usage:**

```
		ActorLevel(Actor)

```

**Description:**
The ActorLevel command returns the level of an actor.
All actors start at level one and increase in levels as they gain experience.
See GiveXP.

**Example:**

```
		Function Main()
			Result = ActorLevel(Actor())
			Output(Actor(), "You are at level " $+ Result)
			Return()
		End Function

```

### ActorMount

**Usage:**

```
		ActorMount(ActorHandle)

```

**Description:**
The ActorMount command returns a handle to the actor
being ridden by a specified actor. If the specified actor is not riding any
mount, 0 will be returned.
See ActorRider.

**Example:**

```
		Function Main()
			Player = Actor()
			Mount = ActorMount(Player)
			If (Mount != 0)
				Output(Player, "You are riding on a " $+ Race(Mount))
			EndIf
			Return()
		End Function

```

### ActorOutdoors

**Usage:**

```
		ActorOutdoors(Actor)

```

**Description:**
The ActorOutdoors command returns 1 if the actor is
in an outdoors zone, or otherwise 0.

**Example:**

```
		Function Main()
			If (ActorOutdoors(Actor()) == 1)
				Output(Actor(), "You are outdoors")
			Else
				Output(Actor(), "You are indoors")
			EndIf
			Return()
		End Function

```

### ActorPets

**Usage:**

```
		ActorPets(Actor)

```

**Description:**
The ActorPets command returns the total number of
actors who have the specified actor as their leader. You can set the leader of
an actor with the SetLeader command.

**Example:**

```
		Function Main()
			Pets = ActorPets(Actor())
			Output(Actor(), "You have " $+ Pets $+ " pets!")
			Return()
		End Function

```

### ActorRider

**Usage:**

```
		ActorRider(ActorHandle)

```

**Description:**
The ActorRider command returns a handle to the actor
riding a specified actor. If the specified actor is not being ridden, 0 will be
returned.
See ActorMount.

**Example:**

```
		Function Main()
			Player = Actor()
			Rider = ActorRider(Player)
			If (Rider != 0)
				Output(Player, "A " $+ Race(Rider) $+ " is riding on you!")
			EndIf
			Return()
		End Function

```

### ActorTarget

**Usage:**

```
		ActorTarget(ActorHandle)

```

**Description:**
The ActorTarget command returns the handle of the
actor targeted by the specified actor. The target is whichever actor the
specified actor is currently attacking. If there is no target, zero will be
returned.

**Example:**

```
		Function Main()
			Player = Actor()
			Target = ActorTarget(Player)
			Output(Player, "You are attacking " $+ Name(Target))
			EndIf
			Return()
		End Function

```

### ActorUnderWater

**Usage:**

```
		ActorUnderWater(Actor)

```

**Description:**
The ActorUnderWater command returns 1 if the
specified actor is swimming in any water area, or 0 if it is not.

**Example:**

```
		Function Main()
			Swimming = ActorUnderWater(Actor())
			If (Swimming == 1)
				Output(Actor(), "You are swimming.")
			Else
				Output(Actor(), "You aren't swimming.")
			EndIf
			Return()
		End Function

```

### ActorX

**Usage:**

```
		ActorX(Actor)

```

**Description:**
The ActorX command returns the current X position of
an actor as a floating point value.

**Example:**

```
		Function Main()
			MyX = ActorX(Actor())
			MyY = ActorY(Actor())
			MyZ = ActorZ(Actor())
			Output(Actor(), "Your position: " $+ MyX $+ ", " $+ MyY $+ ", " $+ MyZ)
			Return()
		End Function

```

### ActorXP

**Usage:**

```
		ActorXP(Actor)

```

**Description:**
The ActorXP command returns the current number of XP
(experience) points an actor has. These are reset to zero whenever the actor
level is changed with the SetActorLevel
command.

**Example:**

```
		Function Main()
			Result = ActorXP(Actor())
			Output(Actor(), "You have " $+ Result $+ " experience points.")
			Return()
		End Function

```

### ActorXPMultiplier

**Usage:**

```
		ActorXPMultiplier(ActorID)

```

**Description:**
The ActorXPMultiplier command retrieves the XP
multiplier value for an actor template, as set in the "Actors" tab of the GE.
This may be useful for implementing custom XP calculations. The ActorID
parameter is the ID number of an actor template, which can be found using the ActorID and ActorIDFromInstance commands.

**Example:**

```
		Function Main()
			// Display XP multiplier for the context actor
			ID = ActorIDFromInstance(ContextActor())
			XPM = ActorXPMultiplier(ID)
			Output(Actor(), "Multiplier: " $+ XPM)

			Return()
		End Function

```

### ActorY

**Usage:**

```
		ActorY(Actor)

```

**Description:**
The ActorY command returns the current Y position of
an actor as a floating point value.

**Example:**

```
		Function Main()
			MyX = ActorX(Actor())
			MyY = ActorY(Actor())
			MyZ = ActorZ(Actor())
			Output(Actor(), "Your position: " $+ MyX $+ ", " $+ MyY $+ ", " $+ MyZ)
			Return()
		End Function

```

### ActorZ

**Usage:**

```
		ActorZ(Actor)

```

**Description:**
The ActorZ command returns the current X position of
an actor as a floating point value.

**Example:**

```
		Function Main()
			MyX = ActorX(Actor())
			MyY = ActorY(Actor())
			MyZ = ActorZ(Actor())
			Output(Actor(), "Your position: " $+ MyX $+ ", " $+ MyY $+ ", " $+ MyZ)
			Return()
		End Function

```

### ActorZone

**Usage:**

```
		ActorZone(Actor)

```

**Description:**
The ActorZone command returns the name of the zone an
actor is currently in.

**Example:**

```
		Function Main()
			Result = ActorZone(Actor())
			Output(Actor(), "Your zone: " $+ Result)
			Return()
		End Function

```

### ActorZoneInstance

**Usage:**

```
		ActorZoneInstance(Actor)

```

D**escription:**
The ActorZoneInstance command returns the instance ID
of the zone an actor is currently in. These IDs range from 0 to 99. 0 is the
default instance of a zone which is always present.
For more information see
CreateZoneInstance.

**Example:**

```
		Function Main()
			Result = ActorZoneInstance(Actor())
			Output(Actor(), "Your instance: " $+ Result)
			Return()
		End Function

```

### AddActorEffect

**Usage:**

```
		AddActorEffect(Actor, Effect, Attribute, Value, Time, IconID)

```

D**escription:**
The AddActorEffect command creates an icon on a
player's screen for a specified amount of time. You may also choose one
attribute to affect for the duration, but other effects are up to you to script.
This is useful for spells which have a temporary effect, traps, diseases,
powerups and other effects. If you add an effect with the same name twice, the
effect duration will be extended, but the icon will not appear twice on the
player's screen.
The Effect parameter is the name you wish to give to the
effect. This is displayed to the player when they hover the mouse over the icon
on their screen. The Attribute is the name of an attribute to alter for the
duration of the effect, and can be left blank if you do not wish to affect any
attribute. The Value is the amount to change the attribute by, and can be
positive negative. Time is the length of time (in seconds) for which the effect
will last. IconID is the ID number of the texture to use for the effect icon.

**Example:**

```
		Function Main()
			// Poison the player!
			AddActorEffect(Actor(), "Poison", "Strength", -10, 30, 11)
			Return()
		End Function

```

### AnimateActor

**Usage:**

```
		AnimateActor(Actor, Animation, Speed, [FixedSpeed])

```

**Description:**
The AnimateActor command makes an actor perform an
animation once. If the animation is not available for the actor you choose,
nothing will happen. The animation will be seen be all players who can see the
actor.
The Animation parameter is the name of the animation to play. The
Speed is any floating point value, where 0.5 is half speed, 1.0 is normal speed,
and 2.0 is double speed. The FixedSpeed parameter should be set to 1 to play the
animation at a fixed speed, regardless of its length in frames.

**Example:**

```
		Function Main()
			AnimateActor(Actor(), "Dig", 0.7)
			Return()
		End Function

```

### Attribute

**Usage:**

```
		Attribute(Actor, Name)

```

**Description:**
The Attribute command returns the level of a given
attribute for an actor.

**Example:**

```
		Function Main()
			MyStr = Attribute(Actor(), "Strength")
			Output(Actor(), "You have " $+ MyStr $+ " strength!")
			Return()
		End Function

```

### ChangeActor

**Usage:**

```
		ChangeActor(Actor, ActorID)

```

**Description:**
The ChangeActor command allows you to change the
actual actor template an actor instance is based on. For instance, you could
turn a vampire into a bat and vice versa. The actor's hair, clothes, face etc.
will not be lost in the transition, but its gender may change if its current
gender is not possible as the target actor.
The ActorID parameter specifies
which actor template the actor should become. You can find an ActorID using ActorID or ActorIDFromInstance.

**Example:**

```
		Function Main()
			Player = Actor()

			// Turn the player into a wolf
			OldID = ActorIDFromInstance(Player)
			ID = ActorID("Wolf", "Critter")
			ChangeActor(Player, ID)

			// Wait 10 seconds
			DoEvents(10000)

			// Turn him back into whatever he was before
			ChangeActor(Player, OldID)

			Return()
		End Function

```

### ChangeMoney

**Usage:**

```
		ChangeMoney(Actor, Amount)

```

**Description:**
The ChangeMoney command adds the amount specified to
the total money level of an actor. The amount is in base units (the lowest
tier), and can be negative to take money away.

**Example:**

```
		Function Main()
			ChangeMoney(Actor(), 5)
			Output(Actor(), "You received 5 copper pieces!")
			Return()
		End Function

```

### Class

**Usage:**

```
		Class(Actor)

```

**Description:**
The Class command returns the name of an actor's
class (e.g. Warrior or Thief).

**Example:**

```
		Function Main()
			MyClass = Class(Actor())
			Output(Actor(), "Your class is " $+ MyClass)
			Return()
		End Function

```

### ContextActor

**Usage:**

```
		ContextActor()

```

**Description:**
The ContextActor command returns a handle to the
context actor of the script. An actor handle is required for use in many
commands such as Output. Usually the actor whose
handle is returned is an NPC. For example: if the script is executed by a player
right-clicking an NPC, Actor will return the handle of
the player actor, and ContextActor will return the handle of the NPC actor.

**Example:**

```
		Function Main()
			NPC = ContextActor()
			Strength = Attribute(NPC, "Strength")
			Output(Actor(), Strength) // This will display the NPCs speed
			Return()
		End Function

```

### CountPartyMembers

**Usage:**

```
		CountPartyMembers(Actor)

```

**Description:**
The CountPartyMembers command will return the number
of members in an actor's party. You can use the PartyMember command to retrieve each one. The number
does not include the actor himself. If the actor has no party, this command will
return 0.

**Example:**

```
		// Send a message to a player's party
		Function Main()
			// Count party members
			Player = Actor()
			Result = CountPartyMembers(Player)
			Count = 1

			// Send to each in turn
			.Loop
			If (Count > Result)
				GoTo(Done)
			EndIf

			Ac = PartyMember(Player, Count)
			Output(Ac, "Hello party member!")

			Count = Count + 1
			GoTo(Loop)

			// Finished
			.Done
			Return()
		End Function

```

### DeleteActorEffect

**Usage:**

```
		DeleteActorEffect(Actor, Effect)

```

**Description:**
The DeleteActorEffect command prematurely removes an
effect icon from an actor, if present. For more information see AddActorEffect.

**Example:**

```
		Function Main()
			// Cure the player of poison
			DeleteActorEffect(Actor(), "Poison")
			Return()
		End Function

```

### FindActor

**Usage:**

```
		FindActor(Name, [Type])

```

**Description:**
The FindActor command returns a handle to the first
actor found matching the criteria specified. The Name is the name of the actor
to find (in the case of NPCs, this is by default the same as the race). The Type
specifies whether to look through NPCs, players, or both. A Type of 1 will
search player characters only (whether in-game or not), a Type of 2 will search
NPCs only, and a Type of 3 will search through all actors. If no Type value is
specified, it will default to 3.

**Example:**

```
		Function Main()
			// Send a message to Fred
			Player = FindActor("Fred", 1)
			If (Player != 0)
				Output(Player, "Hello Fred!")
			EndIf
			Return()
		End Function

```

### FireProjectile

**Usage:**

```
		FireProjectile(Actor, TargetActor, Projectile)

```

**Description:**
The FireProjectile command launches a projectile from
the specified actor, attacking the target actor. Damage etc. is calculated and
applied automatically, based on the projectile settings.

**Example:**

```
		Function Main()
			FireProjectile(Actor(), ContextActor(), "Fireball")
			Return()
		End Function

```

### FirstActorInZone

**Usage:**

```
		FirstActorInZone(Zone, Instance)

```

**Description:**
The FirstActorInZone command returns a handle to the
first actor in a given zone and instance. This is useful to begin a loop through
all actors in the zone using NextActorInZone.

**Example:**

```
		Function Main()
			// Send a message to every human actor in the "forest" zone
			FirstActor = FirstActorInZone("Forest", 0)
			If (FirstActor)
				.Loop
				Actor = NextActorInZone(FirstActor)
				If (Actor == FirstActor)
					Return()
				EndIf

				If (ActorIsHuman(Actor))
					Output(Actor, "Hello there!")
				EndIf
				GoTo(Loop)
			EndIf
			Return()
		End Function

```

### GiveItem

**Usage:**

```
		GiveItem(Actor, Name, Amount)

```

**Description:**
The GiveItem command adds the given item to an
actor's inventory. The Amount value can be negative to take items away, if
present. Use HasItem to check if items are present
first.

**Example:**

```
		Function Main()
			// Give the player a weapon
			GiveItem(Actor(), "Razor Mace", 1)
			Return()
		End Function

```

### GiveKillXP

**Usage:**

```
		GiveKillXP(Actor, TargetActor)

```

**Description:**
The GiveKillXP command gives experience points to
actor. It works on both player characters and NPCs. The actor will increase in
level if you give them enough points.
The difference between this command
and GiveXP is that instead of specifying an exact
number of XP points, you specify a target actor. The number of XP points
assigned will be the number that would be assigned if the actor killed the
target actor. This is convenient to let the RC engine automatically calculate XP
points as it normally does, without having to use KillActor (e.g. in a custom
combat script).
The target actor is not affected by the use of this command.

**Example:**

```
		Function Main()
			// Give the player the XP points for killing the NPC, and kill the NPC
			NPC = ContextActor()
			GiveKillXP(Actor(), NPC)
			SetAttribute(NPC, "Health", 0)
			Return()
		End Function

```

### GiveXP

**Usage:**

```
		GiveXP(Actor, Amount)

```

**Description:**
The GiveXP command gives experience points to actor.
It works on both player characters and NPCs. The actor will increase in level if
you give them enough points.

**Example:**

```
		Function Main()
			// Reward for quest completion
			GiveXP(Actor(), 150)
			Return()
		End Function

```

### HasItem

**Usage:**

```
		HasItem(Actor, Name, Amount)

```

D**escription:**
The HasItem command returns 1 if the actor has the
specified amount of an item in its inventory, or 0 if not.

**Example:**

```
		Function Main()
			If (HasItem(Actor(), "Razor Mace", 1))
				Output(Actor(), "You have a mace!")
			Else
				Output(Actor(), "You do not have a mace")
			EndIf
			Return()
		End Function

```

### KillActor

**Usage:**

```
		KillActor(Actor, [KillerActor])

```

**Description:**
The KillActor command is an easy way to kill an actor
and automatically calculate XP and any faction rating hit for the killer. If you
do not specify an actor for the optional KillerActor parameter, this is exactly
the same as using SetAttribute to set the
actor's health to zero. If you are applying scripted damage (e.g. in an ability
script or a custom attack script) but do not want to manually calculate XP and
the faction rating hit, use this command to kill the actor before your scripted
damage otherwise makes its health go to zero.
Another advantage of using
this command is that if you have set a death script for the dead actor, it will
be called with the handle of the killer actor as the ContextActor. If you choose not to use this command
(e.g. to customise the formula used to calculate XP points) you will have to
call the death script via ThreadExecute in
order to pass the handle of the killer.

**Example:**

```
		Function Main()
			// The player kills the context actor
			KillActor(ContextActor(), Actor())
			Return()
		End Function

```

### MaxAttribute

**Usage:**

```
		MaxAttribute(Actor, Name)

```

**Description:**
The MaxAttribute command returns the maximum level of
a given attribute for an actor.

**Example:**

```
		Function Main()
			MyStrMax = MaxAttribute(Actor(), "Strength")
			Output(Actor(), "You can have up to " $+ MyStrMax $+ " strength!")
			Return()
		End Function

```

### Money

**Usage:**

```
		Money(Actor)

```

**Description:**
The Money command returns the total amount of money
an actor has. The amount returned is in base units (the lowest tier).

**Example:**

```
		Function Main()
			MyMoney = Money(Actor())
			Output(Actor(), "You have " $+ MyMoney $+ " copper pieces!")
			Return()
		End Function

```

### MoveActor

**Usage:**

```
		MoveActor(Actor, X, Y, Z[, MoveCamera])

```

**Description:**
The MoveActor command sets an actor's exact position
in its current zone. Positions can be determined from the numbers in the lower
right corner of the GE "Zones" tab. The optional MoveCamera flag should be set
to true if the actor is a player, and you want their camera to "fly" to the new
location rather than instantly appearing there.

E**xample:**

```
		Function Main()
			Result = MoveActor(Actor(), 0, 0, 0)
			Output(Actor(), "Returned to origin")
			Return()
		End Function

```

### Name

**Usage:**

```
		Name(Actor)

```

**Description:**
The Name command returns an actor's name. For player
characters, this will be the name they entered when creating their character.
For NPCs, it will be the actor's race, unless you have previously changed the
actor's name using SetName.

**Example:**

```
		Function Main()
			MyName = Name(Actor())
			Output(Actor(), "Hello there " $+ MyName)
			Return()
		End Function

```

### NextActor

**Usage:**

```
		NextActor([ActorHandle])

```

**Description:**
The NextActor command returns a handle to the next
actor in the list of all in-game actors. If the ActorHandle parameter is left
out, NextActor will return the first actor in the list. This command allows you
to easily cycle through and do something to every actor in the game.

**Example:**

```
		Function Main()
			// Send a message to every human actor in the game
			Actor = NextActor()
			If (Actor != 0)
				.Loop
				If (ActorIsHuman(Actor))
					Output(Actor, "Hello there!")
				EndIf
				Actor = NextActor(Actor)
				If (Actor != 0)
					Goto(Loop)
				EndIf
			EndIf
			Return()
		End Function

```

### NextActorInZone

**Usage:**

```
		NextActorInZone(ActorHandle)

```

**Description:**
The NextActorInZone command returns a handle to the
next actor in the same zone as the specified actor. This is useful to very
quickly iterate through all actors in a single zone. Unlike NextActor, this command will loop infinitely through
the actors in a zone, rather than returning 0 when the last actor is reached.
Because of this you must check when you reach the original actor rather than
when you reach 0.
See also FirstActorInZone.

**Example:**

```
		Function Main()
			// Send a message to every human actor in the same zone as the player
			Player = Actor()
			Actor = NextActorInZone(Player)
			If (Actor != Player)
				.Loop
				If (ActorIsHuman(Actor))
					Output(Actor, "Hello there!")
				EndIf
				Actor = NextActorInZone(Actor)
				If (Actor != Player)
					GoTo(Loop)
				EndIf
			EndIf
			Return()
		End Function

```

### OpenTrading

**Usage:**

```
		OpenTrading(ActorA, ActorB)

```

**Description:**
The OpenTrading command will open a trading window
between two actors. This is mainly useful to allow players to buy things from or
sell things to NPCs. NPCs will only trade items previously added to their
inventory with the GiveItem command.
ActorA must
be a player character. ActorB may be a player character or NPC.

**Example:**

```
		Function Main()
			OpenTrading(Actor(), ContextActor())
			Return()
		End Function

```

### PartyMember

**Usage:**

```
		PartyMember(Actor, MemberNumber)

```

**Description:**
The PartyMember command will return the handle to an
actor from a given actor's party. For more information see CountPartyMembers.

**Example:**

```
		// Send a message to a player's party
		Function Main()
			// Count party members
			Player = Actor()
			Result = CountPartyMembers(Player)
			Count = 1

			// Send to each in turn
			.Loop
			If (Count > Result)
				GoTo(Done)
			EndIf

			Ac = PartyMember(Player, Count)
			Output(Ac, "Hello party member!")

			Count = Count + 1
			GoTo(Loop)

			// Finished
			.Done
			Return()
		End Function

```

### PlaySound

**Usage:**

```
		PlaySound(Actor, SoundID, Global)

```

**Description:**
The PlaySound command plays a sound effect once. If a
3D sound is specified, it will be played as though from the position of the
specified actor.
The Actor parameter specifies two things - the source of a
sound if a 3D sound is used, and the player or players who will hear the sound.
The SoundID parameter is the ID number of the sound effect to use. This can be
found in the Media tab of the main editor. The Global parameter should be 0 to
play the sound only to the specified actor, or 1 to play the sound to all actors
in the same zone as the specified actor.

**Example:**

```
		Function Main()
			PlaySound(Actor(), 11, 1)
			Return()
		End Function

```

### PlaySpeech

**Usage:**

```
		PlaySpeech(Actor, Speech)

```

**Description:**
The PlaySpeech command plays an actor speech sound to
all players within hearing range. The Speech parameter should be one of the
following:

0 - Greeting 1
1 - Greeting 2
2 - Goodbye 1
3 -
Goodbye 2
4 - Attack 1
5 - Attack 2
6 - Hit 1
7 - Hit 2
8 -
Request help
9 - Death 1
10 - Footstep (dry)
11 - Footstep (wet)

**Example:**

```
		Function Main()
			// Say hello
			PlaySpeech(Actor(), Rand(0, 1))
			Return()
		End Function

```

### Race

**Usage:**

```
		Race(Actor)

```

**Description:**
The Race command returns the name of an actor's race
(e.g. Elf or Human).

**Example:**

```
		Function Main()
			MyRace = Race(Actor())
			Output(Actor(), "Your race is " $+ MyRace)
			Return()
		End Function

```

### Reputation

**Usage:**

```
		Reputation(Actor)

```

**Description:**
The Reputation command returns the level of an
actor's reputation.

**Example:**

```
		Function Main()
			MyRep = Reputation(Actor())
			Output(Actor(), "You have a reputation of: " $+ MyRep)
			Return()
		End Function

```

### Resistance

**Usage:**

```
		Resistance(Actor, Name)

```

**Description:**
The Resistance command returns the level of a given
damage type resistance for an actor.

**Example:**

```
		Function Main()
			MyRst = Resistance(Actor(), "Piercing")
			Output(Actor(), "You have " $+ MyRst $+ " resistance to piercing damage!")
			Return()
		End Function

```

### RotateActor

**Usage:**

```
		RotateActor(Actor, Angle)

```

**Description:**
The RotateActor command sets an actor's exact
orientation. This is useful in NPC spawn scripts to set an direction for
non-moving NPCs to face. Values should be between -180 and 180.

**Example:**

```
		Function Main()
			Result = RotateActor(Actor(), 0)
			Output(Actor(), "Returned to default orientation")
			Return()
		End Function

```

### SetActorAIState

**Usage:**

```
		SetActorAIState(Actor, State)

```

**Description:**
The SetActorAIState command allows you to control the
current AI mode of NPCs, and alter their behaviour. There are various possible
states:
0 - Wait in current position, attack any valid targets who come into
range
1 - Patrol - walk to destination, then set destination to new waypoint
if available
2 - Run - same as Patrol but running instead of walking
3 -
Chase and attack target
4 - For actors who are paused at a waypoint while on
patrol
5 - Pet mode - actor will follow leader and attack leader's target
(actor MUST have a leader to use this)
6 - Pet attack mode - actor is
chasing and attacking the leader's target
7 - Pet wait mode - actor waits in
current position and does absolutely nothing

**Example:**

```
		Function Main()
			// Make NPC attack player
			SetActorTarget(ContextActor(), Actor())
			SetActorAIState(ContextActor(), 3)
			Return()
		End Function

```

### SetActorBeard

**Usage:**

```
		SetActorBeard(Actor, Beard)

```

**Description:**
The SetActorBeard command allows you to change the
beard mesh of an actor in mid game. You might use this to customise NPCs after
creation. NPCs always use beard mesh #1 when first created.
The Beard
parameter should be an integer between 1 and 5.

**Example:**

```
		Function Main()
			// Change actor's beard
			SetActorBeard(Actor(), 2)
			Return()
		End Function

```

### SetActorClothes

**Usage:**

```
		SetActorClothes(Actor, Clothes)

```

**Description:**
The SetActorClothes command allows you to change the
body texture of an actor in mid game. You could use this to allow players to
change their clothes, or to retexture NPCs after creation. NPCs always use body
texture #1 when first created.
The Clothes parameter should be an integer
between 1 and 5.

**Example:**

```
		Function Main()
			// Change player's clothes
			SetActorClothes(Actor(), 3)
			Return()
		End Function

```

### SetActorDestination

**Usage:**

```
		SetActorDestination(Actor, X, Z)

```

**Description:**
The SetActorDestination command allows you to make an
NPC walk to a specific point in its zone. This would be useful when creating
custom AI systems, or as a scripted event as part of a quest. It will not work
on player characters. The required X and Z positions can be determined in the
"Zones" tab of the GE by looking at the camera position displayed in the lower
right-hand corner.

**Example:**

```
		Function Main()
			// Make the NPC walk to -5, 10
			SetActorDestination(ContextActor(), -5, 10)
			Return()
		End Function

```

### SetActorFace

**Usage:**

```
		SetActorFace(Actor, Face)

```

**Description:**
The SetActorFace command allows you to change the
face texture of an actor in mid game. You might use this to retexture NPCs after
creation. NPCs always use face texture #1 when first created.
The Face
parameter should be an integer between 1 and 5.

**Example:**

```
		Function Main()
			// Change actor's face
			SetActorFace(Actor(), 2)
			Return()
		End Function

```

### SetActorGender

**Usage:**

```
		SetActorGender(Actor, Gender)

```

**Description:**
The SetActorGender command allows you to switch an
actor between male and female. The Gender parameter should be 1 for male, or 2
for female. If the specified gender is not allowed by the actor (e.g. it has no
genders, or it is male only and you specify female), then there will be no
change.

**Example:**

```
		// Used as a spawn script, this would make the NPC female (all NPCs are male initially)
		Function Main()
			SetActorGender(Actor(), 2)
			Return()
		End Function

```

### SetActorGlobal

**Usage:**

```
		SetActorGlobal(Actor, ID, Value)

```

**Description:**
The SetActorGlobal command allows you to set the
value of a given actor global variable. IDs range from 0 to 9. Each actor has 10
global variables, which can be accessed from any script. This is useful for
storing data on a per-actor basis.

**Example:**

```
		Function Main()
			SetActorGlobal(Actor(), 2, 5)
			Result = ActorGlobal(Actor(), 2)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### SetActorGroup

**Usage:**

```
		SetActorGroup(Actor, GroupID)

```

**Description:**
The SetActorGroup command allows you to change the
group an actor is in, for the /g in-game command. When a player sends a /g
message, it will be sent to all other players with the same GroupID. An ID of
zero means that the actor is not in a group. This command can be used in the
creation of guild systems or similar.
GroupID should be an integer between 0
and 65535.

**Example:**

```
		Function Main()
			// Add the player to group 5
			SetActorGroup(Actor(), 5)
			Return()
		End Function

```

### SetActorHair

**Usage:**

```
		SetActorHair(Actor, Hair)

```

**Description:**
The SetActorHair command allows you to change the
hair mesh of an actor in mid game. You might use this to customise NPCs after
creation. NPCs always use hair mesh #1 when first created.
The Hair
parameter should be an integer between 1 and 5.

**Example:**

```
		Function Main()
			// Change actor's hair
			SetActorHair(Actor(), 2)
			Return()
		End Function

```

### SetActorLevel

**Usage:**

```
		SetActorLevel(Actor, Level)

```

**Description:**
The SetActorLevel command sets the level of an actor.
All actors start at level one and increase in levels as they gain experience.
See GiveXP.

**Example:**

```
		Function Main()
			SetActorLevel(Actor(), 2)
			Output(Actor(), "You advanced to level 2!")
			Return()
		End Function

```

### SetActorTarget

**Usage:**

```
		SetActorTarget(Actor, [TargetActor])

```

D**escription:**
The SetActorTarget command allows you to change the
current target of an actor. When combined with SetActorAIState, this allows you to make NPCs
attack any other actor who is a valid target. Not providing a target actor will
set the target to nobody.

**Example:**

```
		Function Main()
			// Make NPC attack player
			SetActorTarget(ContextActor(), Actor())
			SetActorAIState(ContextActor(), 3)
			Return()
		End Function

```

### SetAttribute

**Usage:**

```
		SetAttribute(Actor, Name, Value)

```

**Description:**
The SetAttribute command allows you to change the
level of an attribute.

**Example:**

```
		Function Main()
			MyStr = Attribute(Actor(), "Strength")
			SetAttribute(Actor(), "Strength", MyStr + 5)
			Output(Actor(), "You received a bonus of 5 strength!")
			Return()
		End Function

```

### SetLeader

**Usage:**

```
		ActorLeader(Actor, Leader)

```

**Description:**
The SetActorLeader command sets the 'owner' of an
specified actor. To make the actor free (i.e. no leader), specify 0 for the
Leader parameter. Otherwise, you should provide a valid actor handle for the
leader. When an actor has a leader, it will follow it around, attack what it
attacks, and so on. When a player logs off, any actors who have that player as
their leader will be removed from the game as well, and will reappear when the
player logs back in. Only NPCs can be given a leader, but the leader itself can
be an NPC.

**Example:**

```
		Function Main()
			SetLeader(ContextActor(), Actor())
			Output(Actor(), "You gained a pet!")
			Return()
		End Function

```

### SetMaxAttribute

**Usage:**

```
		SetMaxAttribute(Actor, Name, Value)

```

**Description:**
The SetAttribute command allows you to change the
maximum level of an attribute.

**Example:**

```
		Function Main()
			MyStrMax = MaxAttribute(Actor(), "Strength")
			SetMaxAttribute(Actor(), "Strength", MyStrMax + 5)
			Output(Actor(), "You received a bonus of 5 to maximum strength!")
			Return()
		End Function

```

### SetMoney

**Usage:**

```
		SetMoney(Actor, Amount)

```

**Description:**
The SetMoney command sets the total money level of an
actor to the amount specified. The amount is in base units (the lowest tier).

**Example:**

```
		Function Main()
			SetMoney(Actor(), 5)
			Output(Actor(), "You have a total of 5 copper pieces!")
			Return()
		End Function

```

### SetName

**Usage:**

```
		SetName(Actor, Name)

```

**Description:**
The SetName command allows you to change the name of
an actor. This is mainly useful for giving NPCs a custom name, rather than the
default (the actor's race).

**Example:**

```
		Function Main()
			SetName(Actor(), "Ivan the Blacksmith")
			Return()
		End Function

```

### SetReputation

**Usage:**

```
		SetReputation(Actor, Value)

```

**Description:**
The SetReputation command allows you to change an
actor's reputation.

**Example:**

```
		Function Main()
			MyRep = Reputation(Actor())
			SetReputation(Actor(), MyRep + 10)
			Output(Actor(), "Your reputation increased by 10!")
			Return()
		End Function

```

### SetResistance

**Usage:**

```
		SetResistance(Actor, Name, Value)

```

**Description:**
The SetResistance command allows you to change the
level of a damage type resistance.

**Example:**

```
		Function Main()
			MyRst = Attribute(Actor(), "Piercing")
			SetResistance(Actor(), "Piercing", MyRst + 5)
			Output(Actor(), "You received a bonus of 5 resistance to piercing damage!")
			Return()
		End Function

```

### SetTag

**Usage:**

```
		SetTag(Actor, Tag)

```

**Description:**
The SetTag command allows you to change the tag of an
actor. The tag is a special addition to a character's nametag which can only be
changed using this command. You can use it for whatever you want -- one possible
use is to display a player's guild affiliation.

**Example:**

```
		Function Main()
			SetTag(Actor(), "Guild of Merchants")
			Return()
		End Function

```

### Spawn

**Usage:**

```
		Spawn(ActorID, ZoneName, X, Y, Z, [RightClickScript], [DeathScript], [Instance])

```

**Description:**
The Spawn command allows you to create new NPCs. The
ActorID is the unique identifier for the type of actor you wish to create. This
is displayed in the "Actors" tab of the GE, or can be found with the ActorID script command. The ZoneName parameter lets you
specify an intial zone to create the actor in. The X, Y, and Z parameters
specify the position within the zone. The next two optional parameters let you
set a script to run when the actor is right clicked, and when it dies. This
mimics the functionality of the spawn points created in the "Zones" tab of the
GE.
The final optional Instance parameter allows you to spawn the actor in
any extra instance of the zone created with CreateZoneInstance.
The Spawn command
also returns the handle of the created actor instance, which may be used in the
same way as actor handles returned with the Actor and
ContextActor commands.

**Example:**

```
		Function Main()
			// Spawn an elf merchant
			ID = ActorID("Elf", "Mage")
			Ac = Spawn(ID, "Town", -65, 5, -55, "Merchant")
			GiveItem(Ac, "Mage Staff", 1)
			Return()
		End Function

```

### Tag

**Usage:**

```
		Tag(Actor)

```

D**escription:**
The Tag command returns an actor's tag. The tag is a
special addition to a character's nametag which can only be set using the SetTag command.

**Example:**

```
		Function Main()
			MyTag = Tag(Actor())
			Output(Actor(), "You are a member of the " $+ MyTag $+ " guild")
			Return()
		End Function

```

### UpdateXPBar

**Usage:**

```
		UpdateXPBar(Actor, Amount)

```

**Description:**

The UpdateXPBar command changes the position of a
player's XP progress bar. The Amount parameter should be from 0 to 255 where 0
is empty and 255 is full.

**Example:**

```
		Function Main()
			// Reward for quest completion
			GiveXP(Actor(), 150)
			Return()
		End Function

```

### Warp

**Usage:**

```
		Warp(Actor, ZoneName, PortalName, [Instance])

```

**Description:**
The Warp command moves an actor to any zone. It works
on both player characters and NPCs. The optional Instance parameter allows you
to warp an actor to any extra instance of the zone created with CreateZoneInstance.

**Example:**

```
		Function Main()
			// Send actor to the caves
			Warp(Actor(), "Caves", "Start")
			Return()
		End Function

```

## Dialog Commands

### CloseDialog

**Usage:**

```
		CloseDialog(Actor, Dialog)

```

**Description:**
The CloseDialog command closes a dialog window. The
Dialog parameter should be a valid dialog handle returned from OpenDialog().

**Example:**

```
		Function Main()
			Player = Actor()
			D = OpenDialog(Player, ContextActor(), "Blacksmith")
				DialogOutput(Player, D, "Welcome to my shop! Which item do you require?", 255, 255, 255)
				Result = DialogInput(Player, D, "A mace (40 gold)", "Nothing")
				If (Result == 1)
					GiveItem(Player, "Razor mace", 1)
				ElseIf (Result == 2)
					DialogOutput(Player, D, "Right you are, bye then!", 255, 255, 255)
					DialogInput(Player, D, "Bye")
					CloseDialog(Player, D)
					Return()
				EndIf
				DialogOutput(Player, D, "Thank you! Come back when you want something else...", 255, 255, 255)
				DialogInput(Player, D, "Bye")
			CloseDialog(Player, D)
			Return()
		End Function

```

### CreateProgressBar

**Usage:**

```
		CreateProgressBar(Actor, R, G, B, X, Y, Width, Height, Maximum, Value, [Label])

```

**Description:**
The CreateProgressBar command displays a progress bar
on screen for the player actor specified. The R, G and B parameters allow it to
be given a colour. The X, Y, Width and Height parameters specify the position
and size of the bar. Values should range from 0 to 1 where 0 is the left/top
edge of the screen and 1 is the right/bottom edge. The Maximum parameter is the
maximum value which can be applied to the progress bar, and the Value is the
initial value to apply. The Label parameter is optional and allows text to be
displayed over the top of the bar.
This command returns a handle to the
created progress bar, to be used with the other progress bar commands.

**Example:**

```
		Function Main()
			Player = Actor()
			// Create a red progress bar displaying time remaining, count down 10 seconds
			P = CreateProgressBar(Player, 255, 0, 0, 0.01, 0.48, 0.2, 0.04, 10, 10, "Time left")
				Clicks = 10
				.UpdateBar
					Clicks = Clicks - 1
					Delay(1000)
					UpdateProgressBar(Player, P, Clicks)
				GoToIf(Clicks > 0, UpdateBar)
			DeleteProgressBar(Player, P)
			Return()
		End Function

```

### DeleteProgressBar

**Usage:**

```
		DeleteProgressBar(Actor, BarHandle)

```

**Description:**
The DeleteProgressBar command removes a progress bar
previously created with CreateProgressBar.

**Example:**

```
		Function Main()
			Player = Actor()
			// Create a red progress bar displaying time remaining, count down 10 seconds
			P = CreateProgressBar(Player, 255, 0, 0, 0.01, 0.48, 0.2, 0.04, 10, 10, "Time left")
				Clicks = 10
				.UpdateBar
					Clicks = Clicks - 1
					Delay(1000)
					UpdateProgressBar(Player, P, Clicks)
				GoToIf(Clicks > 0, UpdateBar)
			DeleteProgressBar(Player, P)
			Return()
		End Function

```

### DialogInput

The DialogInput offers the player a set of options, and returns which one they
clicked. You may specify up to 12 options, although five or less is recommended
for most purposes. The value returned is a number between 1 and 12.

**Example:**

```
		Function Main()
			Player = Actor()
			D = OpenDialog(Player, ContextActor(), "Blacksmith")
				DialogOutput(Player, D, "Welcome to my shop! Which item do you require?", 255, 255, 255)
				Result = DialogInput(Player, D, "A mace (40 gold)", "Nothing")
				If (Result == 1)
					GiveItem(Player, "Razor mace", 1)
				ElseIf (Result == 2)
					DialogOutput(Player, D, "Right you are, bye then!", 255, 255, 255)
					DialogInput(Player, D, "Bye")
					CloseDialog(Player, D)
					Return()
				EndIf
				DialogOutput(Player, D, "Thank you! Come back when you want something else...", 255, 255, 255)
				DialogInput(Player, D, "Bye")
			CloseDialog(Player, D)
			Return()
		End Function

```

### DialogOutput

[The original documentation messed this part up and had DialogInput instead. This is pretty self explanatory and if you've created even the most basic script in RealmCrafter, you'll probably already know this part].

### OpenDialog

**Usage:**

```
		OpenDialog(Actor, ContextActor, Title, [Background])

```

**Description:**
The OpenDialog command opens a dialog window for the
player actor specified. ContextActor is used to specify another actor (i.e. who
the player is speaking to). If this does not apply, specify 0 as the context
actor. However, if specify a context actor, the player will turn to face them
during the dialog, and the dialog will close if that actor dies.
Title is
the title of the dialog window. The optional Background parameter allows you to
specify a texture ID (which can be found from the Media Manager) for the
background of the dialog window. If you do not provide one, the default window
background will be used.
This command returns a handle to the created
dialog, to be used with the other dialog commands.

**Example:**

```
		Function Main()
			Player = Actor()
			D = OpenDialog(Player, ContextActor(), "Blacksmith")
				DialogOutput(Player, D, "Welcome to my shop! Which item do you require?", 255, 255, 255)
				Result = DialogInput(Player, D, "A mace (40 gold)", "Nothing")
				If (Result == 1)
					GiveItem(Player, "Razor mace", 1)
				ElseIf (Result == 2)
					DialogOutput(Player, D, "Right you are, bye then!", 255, 255, 255)
					DialogInput(Player, D, "Bye")
					CloseDialog(Player, D)
					Return()
				EndIf
				DialogOutput(Player, D, "Thank you! Come back when you want something else...", 255, 255, 255)
				DialogInput(Player, D, "Bye")
			CloseDialog(Player, D)
			Return()
		End Function

```

### Output

**Usage:**

```
		Output(Actor, Message[, Red, Green, Blue])

```

**Description:**
The Output commands allows you to display a short
message to a player. The message will appear in gold in the player's chat area.
The optional Red, Green and Blue parameters allow you to specifiy a colour other
than gold for the message, and should have a value between 0 and 255.

**Example:**

```
		Function Main()
			Output(Actor(), "Hello world!") // Displays Hello World!
			Return()
		End Function

```

### UpdateProgressBar

**Usage:**

```
		UpdateProgressBar(Actor, BarHandle, Value)

```

**Description:**
The UpdateProgressBar command updates the value of a
progress bar previously created with CreateProgressBar.

**Example:**

```
		Function Main()
			Player = Actor()
			// Create a red progress bar displaying time remaining, count down 10 seconds
			P = CreateProgressBar(Player, 255, 0, 0, 0.01, 0.48, 0.2, 0.04, 10, 10, "Time left")
				Clicks = 10
				.UpdateBar
					Clicks = Clicks - 1
					Delay(1000)
					UpdateProgressBar(Player, P, Clicks)
				GoToIf(Clicks > 0, UpdateBar)
			DeleteProgressBar(Player, P)
			Return()
		End Function

```

## Faction Commands

### DefaultFactionRating

**Usage:**

```
		DefaultFactionRating(FactionName, FactionName)

```

**Description:**
The DefaultFactionRating command returns the default
rating of a faction with another faction. The value returned is between -100 and

**Example:**

```
		Function Main()
			// Reset the players faction rating with the Elves faction to default
			Player = Actor()
			Rating = DefaultFactionRating(HomeFaction(Player), "Elves")
			SetFactionRating(Player, "Elves", Rating)
			Return()
		End Function

```

### ChangeFactionRating

**Usage:**

```
		ChangeFactionRating(Actor, FactionName, Amount)

```

**Description:**
The ChangeFactionRating command modifies an actor's
rating with a particular faction. You cannot cause a faction rating to go above
100 or below -100.

**Example:**

```
		Function Main()
			ChangeFactionRating(Actor(), "Elves", 10)
			Output(Actor(), "Added 10 to your popularity with elves.")
			Return()
		End Function

```

### FactionRating

**Usage:**

```
		FactionRating(Actor, FactionName)

```

D**escription:**
The FactionRating command returns an actor's rating
with a particular faction. The value returned is between -100 and 100.

**Example:**

```
		Function Main()
			MyRating = FactionRating(Actor(), "Elves")
			Output(Actor(), "Your popularity with elves is " $+ MyRating)
			Return()
		End Function

```

### HomeFaction

**Usage:**

```
		HomeFaction(Actor)

```

**Description:**
The HomeFaction command returns the name of the
faction an actor belongs to.

**Example:**

```
		Function Main()
			MyFaction = HomeFaction(Actor())
			Output(Actor(), "Your faction is " $+ MyFaction)
			Return()
		End Function

```

### SetHomeFaction

**Usage:**

```
		SetHomeFaction(Actor, FactionName)

```

**Description:**
The SetHomeFaction command allows you to change the
home faction an actor belongs to.

**Example:**

```
		Function Main()
			// Make the actor join the temple faction
			SetHomeFaction(Actor(), "Temple")
			Return()
		End Function

```

### SetFactionRating

[Another part Solstar messed up in the documentation].

## File Commands

### CloseFile

**Usage:**

```
		CloseFile(Handle)

```

**Description:**
The CloseFile command closes a previously opened
file, and should always be called when you have finished reading from/writing to
a file.
The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = OpenFile("Test.txt")
				// Read in current first line and display to user
				FileData = ReadLine(F)
				Output(Actor(), FileData)
				// Return to the beginning of the file and write a new line
				SeekFile(F, 0)
				WriteLine(F, "This text will be readable in Notepad")
			CloseFile(F)
			Return()
		End Function

```

### DeleteFile

**Usage:**

```
		DeleteFile(Name)

```

**Description:**
The DeleteFile command permanently deletes a file
from the **Data\Server Data\Script Files\** folder.
The Name parameter is
the filename (e.g. "Data" or "MyFile.txt").

**Example:**

```
		Function Main()
			DeleteFile("Test.txt")
			Return()
		End Function

```

### Eof

**Usage:**

```
		Eof(Handle)

```

**Description:**
The Eof returns the 1 if the current file offset is
at the end of the file, otherwise 0 is returned. The file position is changed by
the SeekFile command, or by file read/write
commands.
The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = OpenFile("Test.txt")
				If (Eof(F))
					Output(Actor(), "The file is empty!")
				Else
					Output(Actor(), "The file is not empty!")
				EndIf
			CloseFile(F)
			Return()
		End Function

```

### FilePos

**Usage:**

```
		FilePos(Handle)

```

**Description:**
The FilePos returns the current position in the file
for read/write operations. The value returned is an offset, starting from 0 (the
beginning of the file). The file position is changed by the SeekFile command, or by file read/write commands.

The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = OpenFile("Test.txt")
				// Read in current first line and display to user
				FileData = ReadLine(F)
				Output(Actor(), FileData)
				// Return to the beginning of the file and write a new line
				SeekFile(F, 0)
				WriteLine(F, "This text will be readable in Notepad")
			CloseFile(F)
			Return()
		End Function

```

### FileSize

**Usage:**

```
		FileSize(Filename)

```

**Description:**
The FileSize command returns the size in bytes of a
given file.

**Example:**

```
		Function Main()
			F = OpenFile("Test.txt")
				// Move to the end of the file, so we can add data instead of overwriting
				SeekFile(F, FileSize("Test.txt"))
				// Add a line to the file
				WriteLine(F, "This is an extra line added to the file.")
			CloseFile(F)
			Return()
		End Function

```

### OpenFile

**Usage:**

```
		OpenFile(Name)

```

**Description:**
The OpenFile command opens a file for random access,
and returns a handle to it for use with the file reading/writing commands. All
files are stored in the **Data\Server Data\Script Files\** folder. Make sure
to call CloseFile after you are finished with the
file, to prevent memory leaks.
Name is the filename (e.g. "Data" or
"MyFile.txt").

**Example:**

```
		Function Main()
			F = OpenFile("Test.txt")
				// Read in current first line and display to user
				FileData = ReadLine(F)
				Output(Actor(), FileData)
				// Return to the beginning of the file and write a new line
				SeekFile(F, 0)
				WriteLine(F, "This text will be readable in Notepad")
			CloseFile(F)
			Return()
		End Function

```

### ReadByte

**Usage:**

```
		ReadByte(Handle)

```

**Description:**
The ReadByte reads a byte from the current file
position and returns the value. The file position is then advanced by one byte.

The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = ReadFile("Test.dat")
				FileData = ReadByte(F)
				Output(Actor(), "First byte value: " $+ FileData)
			CloseFile(F)
			Return()
		End Function

```

### ReadFile

**Usage:**

```
		ReadFile(Name)

```

**Description:**
The ReadFile command opens a file as read-only, and
returns a handle to it for use with the file reading commands. All files are
stored in the **Data\Server Data\Script Files\** folder. Make sure to call CloseFile after you are finished with the file, to
prevent memory leaks.
Name is the filename (e.g. "Data" or "MyFile.txt").

**Example:**

```
		Function Main()
			F = ReadFile("Test.txt")
				FileData = ReadLine(F)
				Output(Actor(), FileData)
			CloseFile(F)
			Return()
		End Function

```

### ReadFloat

**Usage:**

```
		ReadFloat(Handle)

```

**Description:**
The ReadFloat reads a float (four byte real number)
from the current file position and returns the value. The file position is then
advanced by four bytes.
The Handle parameter is the file handle returned by
ReadFile, WriteFile or
OpenFile.

**Example:**

```
		Function Main()
			F = ReadFile("Test.dat")
				FileData = ReadFloat(F)
				Output(Actor(), "First float value: " $+ FileData)
			CloseFile(F)
			Return()
		End Function

```

### ReadInt

**Usage:**

```
		ReadInt(Handle)

```

**Description:**
The ReadInt reads an integer (4 bytes) from the
current file position and returns the value. The file position is then advanced
by four bytes.
The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = ReadFile("Test.dat")
				FileData = ReadInt(F)
				Output(Actor(), "First integer value: " $+ FileData)
			CloseFile(F)
			Return()
		End Function

```

### ReadLine

**Usage:**

```
		ReadLine(Handle)

```

**Description:**
The ReadLine reads a line from the current file
position and returns the text. The file position is then advanced to the end of
the line. A line is any amount of text, terminated by the CRLF (Carriage Return,
Line Feed) characters. This is used to read in data from files readable by
humans, such as .txt files.
The Handle parameter is the file handle returned
by ReadFile, WriteFile
or OpenFile.

**Example:**

```
		Function Main()
			F = ReadFile("Test.txt")
				FileData = ReadLine(F)
				Output(Actor(), "First line text: " $+ FileData)
			CloseFile(F)
			Return()
		End Function

```

### ReadShort

**Usage:**

```
		ReadShort(Handle)

```

**Description:**
The ReadShort reads a short (two bytes) from the
current file position and returns the value. The file position is then advanced
by two bytes.
The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = ReadFile("Test.dat")
				FileData = ReadShort(F)
				Output(Actor(), "First short value: " $+ FileData)
			CloseFile(F)
			Return()
		End Function

```

### ReadString

**Usage:**

```
		ReadString(Handle)

```

**Description:**
The ReadString reads a string (four bytes plus string
length) from the current file position and returns the string text. The file
position is then advanced to where the string ends in the file.
The Handle
parameter is the file handle returned by ReadFile,
WriteFile or OpenFile.

**Example:**

```
		Function Main()
			F = ReadFile("Test.dat")
				FileData = ReadString(F)
				Output(Actor(), "First string value: " $+ FileData)
			CloseFile(F)
			Return()
		End Function

```

### SeekFile

**Usage:**

```
		SeekFile(Handle, Offset)

```

**Description:**
The SeekFile command changes the current file
position for read/write operations. The current position can be retrieved using
the FilePos command.
The Handle parameter is the
file handle returned by ReadFile, WriteFile or OpenFile. The
Offset parameter is the new position in bytes, starting from 0.

**Example:**

```
		Function Main()
			F = OpenFile("Test.txt")
				// Read in current first line and display to user
				FileData = ReadLine(F)
				Output(Actor(), FileData)
				// Return to the beginning of the file and write a new line
				SeekFile(F, 0)
				WriteLine(F, "This text will be readable in Notepad")
			CloseFile(F)
			Return()
		End Function

```

### WriteByte

**Usage:**

```
		WriteByte(Handle, Value)

```

**Description:**
The WriteByte command writes a value to a file as a
single byte, at the current file position. The file position is then advanced by
one byte.
The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile. Value is the number to write to the file, and
should be between 0 and 255.

**Example:**

```
		Function Main()
			F = WriteFile("Test.dat")
				WriteByte(F, 100)
			CloseFile(F)
			Return()
		End Function

```

### WriteFile

**Usage:**

```
		WriteFile(Name)

```

**Description:**
The WriteFile command opens a file as write-only, and
returns a handle to it for use with the file writing commands. All files are
stored in the **Data\Server Data\Script Files\** folder. Make sure to call CloseFile after you are finished with the file, to
prevent memory leaks.
Name is the filename (e.g. "Data" or "MyFile.txt").

**Example:**

```
		Function Main()
			F = WriteFile("Test.txt")
				WriteLine(F, "This text will be readable in Notepad")
			CloseFile(F)
			Return()
		End Function

```

### WriteFloat

**Usage:**

```
		WriteFloat(Handle, Value)

```

**Description:**
The WriteFloat command writes a value to a file as a
float (four bytes), at the current file position. The file position is then
advanced by four bytes.
The Handle parameter is the file handle returned by
ReadFile, WriteFile or
OpenFile. Value is the number to write to the file,
and can be any real number.

**Example:**

```
		Function Main()
			F = WriteFile("Test.dat")
				WriteFloat(F, 3.1415926536)
			CloseFile(F)
			Return()
		End Function

```

### WriteInt

**Usage:**

```
		WriteInt(Handle, Value)

```

**Description:**
The WriteInt command writes a value to a file as an
integer (four bytes), at the current file position. The file position is then
advanced by four bytes.
The Handle parameter is the file handle returned by
ReadFile, WriteFile or
OpenFile. Value is the number to write to the file,
and should be between -2147483648 and 2147483647.

**Example:**

```
		Function Main()
			F = WriteFile("Test.txt")
				WriteInt(F, 10000000)
			CloseFile(F)
			Return()
		End Function

```

### WriteLine

**Usage:**

```
		WriteLine(Handle, Value)

```

**Description:**
The WriteLine command writes a line (some text
followed by the CRLF (Carriage Return, Line Feed) characters) to a file, at the
current file position. The file position is then advanced to where the line ends
in the file.
The Handle parameter is the file handle returned by ReadFile, WriteFile or OpenFile. Value is the text to write to the file.

**Example:**

```
		Function Main()
			F = WriteFile("Test.txt")
				WriteLine(F, "This text will be readable in Notepad")
			CloseFile(F)
			Return()
		End Function

```

### WriteShort

**Usage:**

```
		WriteShort(Handle, Value)

```

**Description:**
The WriteShort command writes a value to a file as a
short (two bytes), at the current file position. The file position is then
advanced by two bytes.
The Handle parameter is the file handle returned by
ReadFile, WriteFile or
OpenFile. Value is the number to write to the file,
and should be between 0 and 65535.

**Example:**

```
		Function Main()
			F = WriteFile("Test.dat")
				WriteShort(F, 10000)
			CloseFile(F)
			Return()
		End Function

```

### WriteString

**Usage:**

```
		WriteString(Handle, Value)

```

**Description:**
The WriteString command writes a string (four bytes
plus string length) to file at the current file position. The file position is
then advanced to where the string ends in the file.
The Handle parameter is
the file handle returned by ReadFile, WriteFile or OpenFile.
Value is the string to write to the file. Note that strings written in this way
cannot be edited by a human (e.g. using Notepad, or a similar program), and then
read successfully again by your script. If you need to do this, use WriteLine.

**Example:**

```
		Function Main()
			F = WriteFile("Test.dat")
				WriteString(F, "Some text")
			CloseFile(F)
			Return()
		End Function

```

## Item Commands

### ActorAmulet

**Usage:**

```
		ActorAmulet(Actor, Number)

```

**Description:**
The ActorAmulet command returns the handle to the
item in the specified actor's inventory amulet slot. If there is no item in the
slot, zero is returned. The handle can then be used with other item commands,
such as ItemName to see which item is being worn.

The Number parameter is the amulet number to retrieve, and should be between
one and two.

**Example:**

```
		Function Main()
			Result = ActorAmulet(Actor(), 2)
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorBackpack

**Usage:**

```
		ActorBackpack(Actor, ItemNumber)

```

**Description:**
The ActorBackpack command returns the handle to the
item in the specified actor's inventory backpack slot. The backpack is actually
made up of multiple slots, numbered 1 - 36. You must specify which slot you wish
to retrieve the item from. If there is no item in the specified slot, zero is
returned. The handle can then be used with other item commands, such as ItemName to see which item is being carried.

**Example:**

```
		Function Main()
			Result = ActorBackpack(Actor(), 1)
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorBelt

**Usage:**

```
		ActorBelt(Actor)

```

**Description:**
The ActorBelt command returns the handle to the item
in the specified actor's inventory belt slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorBelt(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorChest

**Usage:**

```
		ActorChest(Actor)

```

**Description:**
The ActorChest command returns the handle to the item
in the specified actor's inventory chest slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorChest(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorFeet

**Usage:**

```
		ActorFeet(Actor)

```

**Description:**
The ActorFeet command returns the handle to the item
in the specified actor's inventory feet slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorFeet(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorHands

**Usage:**

```
		ActorHands(Actor)

```

**Description:**
The ActorHands command returns the handle to the item
in the specified actor's inventory hands slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorHands(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorHat

**Usage:**

```
		ActorHat(Actor)

```

**Description:**
The ActorHat command returns the handle to the item
in the specified actor's inventory hat slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorHat(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorLegs

**Usage:**

```
		ActorLegs(Actor)

```

**Description:**
The ActorLegs command returns the handle to the item
in the specified actor's inventory legs slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorLegs(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorRing

**Usage:**

```
		ActorRing(Actor, Number)

```

**Description:**
The ActorRing command returns the handle to the item
in the specified actor's inventory ring slot. If there is no item in the slot,
zero is returned. The handle can then be used with other item commands, such as
ItemName to see which item is being worn.
The
Number parameter is the ring number to retrieve, and should be between one and
four.

**Example:**

```
		Function Main()
			Result = ActorRing(Actor(), 2)
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorShield

**Usage:**

```
		ActorShield(Actor)

```

**Description:**
The ActorShield command returns the handle to the
item in the specified actor's inventory shield slot. If there is no item in the
slot, zero is returned. The handle can then be used with other item commands,
such as ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorShield(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ActorWeapon

**Usage:**

```
		ActorWeapon(Actor)

```

**Description:**
The ActorWeapon command returns the handle to the
item in the specified actor's inventory weapon slot. If there is no item in the
slot, zero is returned. The handle can then be used with other item commands,
such as ItemName to see which item is being worn.

**Example:**

```
		Function Main()
			Result = ActorWeapon(Actor())
			If (Result == 0)
				Output(Actor(), "No item in slot!")
			Else
				Output(Actor(), "Item: " $+ ItemName(Result))
			EndIf
			Return()
		End Function

```

### ItemArmor

**Usage:**

```
		ItemArmor(Item)

```

**Description:**
The ItemArmor command returns the armor level of an
item retrieved using ActorHat, and similar commands.
This value is meaningless for items which are not some type of armour.

**Example:**

```
		Function Main()
			MyDefence = ItemArmor(ActorHat(Actor()))
			Output(Actor(), "Your hat has an armour level of" $+ MyDefence)
			Return()
		End Function

```

### ItemAttribute

**Usage:**

```
		ItemAttribute(Item, Name)

```

**Description:**
The ItemAttribute command returns the level of a
given attribute for an item.

**Example:**

```
		Function Main()
			ItemStr = ItemAttribute(ActorHat(Actor()), "Strength")
			Output(Actor(), "Your helmet adds " $+ ItemStr $+ " strength!")
			Return()
		End Function

```

### ItemDamage

**Usage:**

```
		ItemDamage(Item)

```

**Description:**
The ItemDamage command returns the weapon damage of
an item retrieved using ActorWeapon, and similar
commands. This value is meaningless for items which are not weapons.

**Example:**

```
		Function Main()
			MyDamage = ItemDamage(ActorWeapon(Actor()))
			Output(Actor(), "Your weapon does " $+ MyDamage $+ " points of damage")
			Return()
		End Function

```

### ItemDamageType

**Usage:**

```
		ItemDamageType(Item)

```

D**escription:**
The ItemDamageType command returns the weapon damage
type of an item retrieved using ActorWeapon, and
similar commands. This value is meaningless for items which are not weapons.

**Example:**

```
		Function Main()
			MyDamageType = ItemDamageType(ActorWeapon(Actor()))
			Output(Actor(), "Your weapon does " $+ MyDamageType $+ " damage")
			Return()
		End Function

```

### ItemHealth

**Usage:**

```
		ItemHealth(Item)

```

**Description:**
The ItemHealth command returns the health (as a
percentage) of an item retrieved using ActorHat, and
similar commands.

**Example:**

```
		Function Main()
			MyHat = ItemHealth(ActorHat(Actor()))
			Output(Actor(), "Your hat is " $+ (100 - MyHat) $+ "% damaged")
			Return()
		End Function

```

### ItemMass

**Usage:**

```
		ItemMass(Item)

```

**Description:**
The ItemMass command returns the mass of an item
retrieved using ActorHat, and similar commands.

**Example:**

```
		Function Main()
			MyHat = ItemMass(ActorHat(Actor()))
			Output(Actor(), "Your hat weighs " $+ MyHat $+ "kg")
			Return()
		End Function

```

### ItemMiscData

**Usage:**

```
		ItemMiscData(Item)

```

**Description:**
The ItemMiscData command returns the miscellaneous
data of an item, as set in GE. It is returned in the form of a string.

### ItemName

**Usage:**

```
		ItemName(Item)

```

**Description:**
The ItemName command returns the name of an item
retrieved using ActorHat, and similar commands.

**Example:**

```
		Function Main()
			MyHat = ItemName(ActorHat(Actor()))
			Output(Actor(), "Your hat is a " $+ MyHat)
			Return()
		End Function

```

### ItemRange

**Usage:**

```
		ItemRange(Item)

```

**Description:**
The ItemRange command returns the weapon range of an
item retrieved using ActorWeapon, and similar
commands. This value is meaningless for items which are not ranged weapons.

**Example:**

```
		Function Main()
			MyRange = ItemRange(ActorWeapon(Actor()))
			Output(Actor(), "Your weapon has a range of " $+ MyRange)
			Return()
		End Function

```

### ItemValue

**Usage:**

```
		ItemValue(Item)

```

**Description:**
The ItemValue command returns the value (in base
currency units) of an item retrieved using ActorHat,
and similar commands.

**Example:**

```
		Function Main()
			MyHat = ItemValue(ActorHat(Actor()))
			Output(Actor(), "Your hat is worth " $+ MyHat)
			Return()
		End Function

```

### SetItemHealth

**Usage:**

```
		SetItemHealth(Item, Health)

```

**Description:**
The SetItemHealth command sets the health (as a
percentage) of an item retrieved using ActorHat, and
similar commands.

**Example:**

```
		Function Main()
			SetItemHealth(ActorHat(Actor()), 100)
			Output(Actor(), "Your hat is repaired!")
			Return()
		End Function

```

### SpawnItem

**Usage:**

```
		SpawnItem(Item, Quantity, Zone, X, Y, Z, [Instance])

```

**Description:**
The SpawnItem command allows you to create new items
on the ground, which work in the same way as items dropped by players. They can
be picked up by any player. Items without a mesh set will appear as the
\Data\Meshes\Loot Bag.b3d model, others will display whatever mesh has been set.

The optional Instance parameter allows you to spawn the item in any extra
instance of the zone created with CreateZoneInstance.

**Example:**

```
		Function Main()
			// Create 5 mushrooms on the ground
			SpawnItem("Mushroom", 5, "Mushroom Farm", 10, 0, 5)
			Return()
		End Function

```

## Math Commands

### Abs

**Usage:**

```
		Abs(Value)

```

**Description:**
The Abs command returns the magnitude of a value.

**Example:**

```
		Function Main()
			Result = Abs(-52)
			Output(Actor(), Result) // Displays 52
			Return()
		End Function

```

### ACos

**Usage:**

```
		ACos(c)

```

**Description:**
The ACos command returns the angle in degrees which
has cosine c. The angle returned will be between 0 and 180.

**Example:**

```
		Function Main()
			Result = ACos(0.5)
			Output(Actor(), Result) // Displays 60
			Return()
		End Function

```

### ASin

**Usage:**

```
		ASin(s)

```

**Description:**
The ASin command returns the angle in degrees which
has sine s. The angle returned will be between -90 and 90.

**Example:**

```
		Function Main()
			Result = ASin(0.5)
			Output(Actor(), Result) // Displays 30
			Return()
		End Function

```

### ATan

**Usage:**

```
		ATan(t)

```

**Description:**
The ATan command returns the angle in degrees which
has tangent t. The angle returned will be between -90 and 90.

**Example:**

```
		Function Main()
			Result = ATan(1)
			Output(Actor(), Result) // Displays 45
			Return()
		End Function

```

### ATan2

**Usage:**

```
		ATan2(x, y)

```

**Description:**
The ATan2 command returns the angle in degrees
between the X axis and the line between points (0, 0) and (x, y). The angle
returned will be between -180 and 180.

**Example:**

```
		Function Main()
			Result = ATan2(1, 1)
			Output(Actor(), Result) // Displays 45
			Return()
		End Function

```

### Cos

**Usage:**

```
		Cos(Angle)

```

**Description:**
The Cos command returns the cosine of an angle, using
degrees.

**Example:**

```
		Function Main()
			Result = Cos(60)
			Output(Actor(), Result) // Displays 0.5
			Return()
		End Function

```

### Exp

**Usage:**

```
		Exp(Value)

```

**Description:**
The Exp command returns e to the power of the value
given.

**Example:**

```
		Function Main()
			Result = Exp(1)
			Output(Actor(), Result) // Displays 2.718281828 (e)
			Return()
		End Function

```

### Int

**Usage:**

```
		Int(Value)

```

**Description:**
The Int command returns the nearest integer to the
value given.

**Example:**

```
		Function Main()
			Result = Int(1.5)
			Output(Actor(), Result) // Displays 2
			Return()
		End Function

```

### Log

**Usage:**

```
		Log(Value)

```

**Description:**
The Log command returns the natural logarithm of a
value.

**Example:**

```
		Function Main()
			Result = Log(2.718281828)
			Output(Actor(), Result) // Displays 1 (or 0.999999999)
			Return()
		End Function

```

### Log10

**Usage:**

```
		Log10(Value)

```

**Description:**
The Log10 command returns the common logarithm of a
value.

**Example:**

```
		Function Main()
			Result = Log10(100)
			Output(Actor(), Result) // Displays 2
			Return()
		End Function

```

### Pi

**Usage:**

```
		Pi()

```

**Description:**
The Pi command returns the value of Pi to 6 decimal
places (3.141592).

**Example:**

```
		Function Main()
			Result = Pi()
			Output(Actor(), Result) // Displays 3.141592
			Return()
		End Function

```

### Rand

**Usage:**

```
		Rand(Min, Max)

```

**Description:**
The Rand command returns a random integer between the
Min and Max values.

**Example:**

```
		Function Main()
			Result = Rand(1, 2)
			Output(Actor(), Result) // Displays either 1 or 2
			Return()
		End Function

```

### Rnd

**Usage:**

```
		Rnd(Min, Max)

```

**Description:**
The Rnd command returns a random real number between
the Min and Max values.

**Example:**

```
		Function Main()
			Result = Rnd(0, 1)
			Output(Actor(), Result) // Displays anything between 0.0 and 1.0
			Return()
		End Function

```

### Sign

**Usage:**

```
		Sign(Value)

```

**Description:**
The Sign command returns 1 or -1, depending on the
sign of the variable given.

**Example:**

```
		Function Main()
			Result = Sign(-52)
			Output(Actor(), Result) // Displays -1
			Return()
		End Function

```

### Sin

**Usage:**

```
		Sin(Angle)

```

**Description:**
The Sin command returns the sine of an angle, using
degrees.

**Example:**

```
		Function Main()
			Result = Sin(30)
			Output(Actor(), Result) // Displays 0.5
			Return()
		End Function

```

### Sqrt

**Usage:**

```
		Sqrt(Value)

```

**Description:**
The Sqrt command returns the square root of a value.

**Example:**

```
		Function Main()
			Result = Sqrt(25)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### Tan

**Usage:**

```
		Tan(Angle)

```

**Description:**
The Tan command returns the tangent of an angle,
using degrees.

**Example:**

```
		Function Main()
			Result = Tan(45)
			Output(Actor(), Result) // Displays 1
			Return()
		End Function

```

## Network Commands

### CreateUDPStream

**Usage:**

```
		CreateUDPStream([Port])

```

**Description:**
The CreateUDPStream command opens a UDP port for
network communication and returns a stream handle. If no port is specified, a
free port will be allocated and you can then use UDPStreamPort to find out the allocated port.

### CloseUDPStream

**Usage:**

```
		CloseUDPStream(Stream)

```

**Description:**
The CloseUDPStream command closes a UDP port opened
using the CreateUDPStream command. This should
always be done when you are finished with the port.

### SendUDPMsg

**Usage:**

```
		SendUDPMsg(Stream, DestinationIP, [DestinationPort])

```

**Description:**
The SendUDPMsg command transmits all data written to
the UDP stream to a specified IP address and port. Data should be written using
the standard stream commands (e.g. WriteByte). If
no destination port is specified, the port used to create the stream will be
used.
Note that IP addresses must be in integer format. Use CountHostIPs to get an integer IP from a host in
string format.

### RecvUDPMsg

**Usage:**

```
		RecvUDPMsg(Stream)

```

**Description:**
The RecvUDPMsg command receives a UDP message into
the specified UDP stream. Standard stream commands (e.g. ReadByte) can then be used to examine the message. The
value returned is the integer IP address of the message source, or 0 if no
message was available. You can use UDPMsgPort to
find the port number of the message source.

### UDPStreamPort

**Usage:**

```
		UDPStreamPort(Stream)

```

**Description:**
The UDPStreamPort command returns the port number of
the specified UDP stream. This can be useful if you've created the UDP stream
without specifying a port number.

### UDPMsgIP

**Usage:**

```
		UDPMsgIP(Stream)

```

**Description:**
The UDPMsgIP command returns the integer IP address
of the sender of the last UDP message received. This value is also returned by
RecvUDPMsg.

### UDPMsgPort

**Usage:**

```
		UDPMsgPort(Stream)

```

**Description:**
The UDPMsgPort command returns the port of the sender
of the last UDP message received.

### UDPTimeouts

**Usage:**

```
		UDPTimeouts(Time)

```

**Description:**
The UDPTimeouts command allows you to control how
long (in milliseconds) the RecvUDPMsg function
will wait for a new message. By default, this is set to 0, meaning RecvUDPMsg will return immediately if there is no
message to be received. It is strongly recommended that this is left alone
unless you know what you are doing, as it can affect normal server performance
even when the script has ended.

### CountHostIPs

**Usage:**

```
		CountHostIPs(HostName)

```

**Description:**
The CountHostIPs command will enumerate all available
IP addresses for a specified host, and return how many are available. You can
then use the HostIP command to retrieve each one in
integer format. You will need to use this to obtain integer format IP addresses
for use with SendUDPMsg.
The HostName
parameter should be a string containing either a dotted IP address (e.g.
"127.0.0.1") or a host name (e.g. "realmcrafter.com").

### HostIP

**Usage:**

```
		HostIP(Index)

```

**Description:**
The HostIP command returns an integer IP address for
the host specified in the last call to CountHostIPs. The Index parameter should be in the
range 1 - CountHostIPs.

### DottedIP

**Usage:**

```
		DottedIP(IP)

```

**Description:**
The DottedIP acceps an integer IP address, and
returns the IP in dotted (human readable) format.

## Other Commands

### CallDLL

**Usage:**

```
		CallDLL(DLLName, FunctionName)

```

**Description:**
The CallDLL command runs a function from a DLL.
Currently there is no way to pass parameters or receive return values. In order
to work the DLL must be present in the same folder as Server.exe, or installed
in the system32 folder. The function called must also have been exported in the
following way:

```
		extern "C"
		{
			_declspec(dllexport) int _cdecl MyDLLFunction(const void* in, int InSize, void* out, int OutSize);
		}

```

**Example:**

```
		Function Main()
			CallDLL("MyDLL", "MyDLLFunction")
			Return()
		End Function

```

### DoEvents

**Usage:**

```
		DoEvents([Time])

```

**Description:**
The DoEvents command will yield the CPU to allow
other scripts and server events to update. This is useful for scripts which poll
something constantly, to avoid locking up the server. You may also use it to
pause your script for a certain length of time.
The optional Time parameter
is the minimum time (in milliseconds) which must elapse before the script may
continue running. If this is ignored or set to zero, the script will continue
running as soon as all other events have been processed by the server.

**Example:**

```
		Function Main()
			Output(Actor(), "Hello!")
			DoEvents(1000) // Pause for a second
			Output(Actor(), "Hello again!")
			Return()
		End Function

```

### End

**Usage:**

```
		End([Message])

```

**Description:**
The End command stops the script from any function.
The optional message parameter sets the script return value. If you set this to
a string beginning with **Error:**, the return value will be written to the
server log.

**Example:**

```
		Function Main()
			End()
		End Function

```

### Global

**Usage:**

```
		Global(ID)

```

**Description:**
The Global command returns the value of a given
global variable. IDs range from 0 to 99. Globals are local to each script and
their values are lost when the script ends or the server is shut down. They are
useful for variables which should be shared between all functions in a script.
Note that they are not shared between multiple instances of the same script.

**Example:**

```
		Function Main()
			SetGlobal(25, 5)
			Result = Global(25)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### GoTo

**Usage:**

```
		GoTo(Label)

```

**Description:**
The GoTo command allows you to jump to another point
in the script. It is necessary to make loops and other useful control
structures. Labels are defined by a dot (.) followed by the label name, as in
the example below. You can only jump to labels within the current function. This
means that you can use the same label name twice in different functions without
a clash.

**Example:**

```
		Function Main()
			GoTo(MyLabel)
			Output(Actor(), "You will never see this text!")
			.MyLabel
			Output(Actor(), "But you will see this bit.")
			Return()
		End Function

```

### MilliSecs

**Usage:**

```
		MilliSecs()

```

**Description:**
The MilliSecs command returns the system milliseconds
counter, and can be used for accurate timing if required.

**Example:**

```
		Function Main()
			Output(Actor(), "System milliseconds: " $+ MilliSecs())
			Return()
		End Function

```

### Parameter

**Usage:**

```
		Parameter(Number)

```

**Description:**
The Parameter command allows you to retrieve command
line parameters for scripts. The main use of this command is in custom in-game
command scripts, where it allows you to get user input. For instance, if you had
a custom command named "test", and a player entered "/test Paul, 17", there
would be two valid parameters which you would retrieve using Parameter(1) and
Parameter(2). Parameter(3) and upwards would return nothing.

It is also
used in the following:

Ability scripts - there is one parameter: the
player's level in the ability.
NPC death scripts - there are 15 parameters:
the race and class of the dead actor, followed by the X, Y and Z positions,
followed by its ten actor globals.
ThreadExecute - ThreadExecute can pass a set of
parameters to the script it runs, which can then be accessed with this command.

Triggered scripts - these scripts receive one parameter containing the ID of
the trigger which called the script

**Example:**

```
		Function Main()
			// Get damage of spell
			SpellLvl = Parameter(1)
			Damage = 10 + SpellLvl

			// Tell player
			Output(Actor(), "You do " $+ Damage $+ " damage...")

			Return()
		End Function

```

### Persistent

**Usage:**

```
		Persistent(Flag)

```

**Description:**
The Persistent command allows you to toggle the
persistence flag for the current script. If this flag is true, and the main
actor logs off while the script is still running, it will be paused until they
log back on. It does not apply to scripts where the actor is an NPC, where there
is no actor, or to the context actor.
This is useful for quest scripts which
may be running for a long time and should not end until the quest is completed.

**Example:**

```
		Function Main()
			// Make script persist
			Persistent(1)
			// Wait for player to kill a wolf, even between logging off/on
			WaitKill(Actor(), ActorID("Wolf", "Creature"), 1)
			Return()
		End Function

```

### RealDate

**Usage:**

```
		RealDate()

```

**Description:**
The RealDate command returns the current date
according to the server computer's system clock, as a string value.

**Example:**

```
		Function Main()
			Output(Actor(), "Date at server computer: " $+ RealDate())
			Return()
		End Function

```

### RealTime

**Usage:**

```
		RealTime()

```

**Description:**
The RealTime command returns the current time
according to the server computer's system clock, as a string value.

**Example:**

```
		Function Main()
			Output(Actor(), "Time at server computer: " $+ RealTime())
			Return()
		End Function

```

### Return

**Usage:**

```
		Return([Value])

```

**Description:**
The Return command returns from a function,
optionally returning a value. If called from the Main function (or whichever
function the script started in), it causes the script to end.

**Example:**

```
		Function Main()
			Result = Add(5, 2)
			Output(Actor(), Result) // Displays 7
			Return()
		End Function

		Function Add(a, b)
			Return(a + b)
		End Function

```

### RuntimeError

**Usage:**

```
		RuntimeError(Message)

```

**Description:**
The RuntimeError command is for serious errors, or to
debug scripts. It shuts down the entire server and displays an error message.

**Example:**

```
		Function Main()
			RuntimeError("This is a test message!")
		End Function

```

### ScriptLog

**Usage:**

```
		ScriptLog(Message)

```

**Description:**
The ScriptLog command writes a string to the server
log. This is useful for script debugging.

**Example:**

```
		Function Main()
			ScriptLog("This is an example log message from a script")
		End Function

```

### SetGlobal

**Usage:**

```
		SetGlobal(ID, Value)

```

**Description:**
The SetGlobal command allows you to set the value of
a given global variable. IDs range from 0 to 99. Globals are local to each
script and their values are lost when the script ends or the server is shut
down. They are useful for variables which should be shared between all functions
in a script. Note that they are not shared between multiple instances of the
same script.

**Example:**

```
		Function Main()
			SetGlobal(25, 5)
			Result = Global(25)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### SetSuperGlobal

**Usage:**

```
		SetSuperGlobal(ID, Value)

```

**Description:**
The SetSuperGlobal command allows you to set the
value of a given superglobal variable. IDs range from 0 to 99. Superglobals are
shared by running scripts and their values are not lost when the script ends or
the server is shut down. This makes them useful for storing values which affect
something everywhere in your world.

**Example:**

```
		Function Main()
			SetSuperGlobal(25, 5)
			Result = SuperGlobal(25)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### SuperGlobal

**Usage:**

```
		SuperGlobal(ID)

```

**Description:**
The SuperGlobal command returns the value of a given
superglobal variable. IDs range from 0 to 99. Superglobals are shared by running
scripts and their values are not lost when the script ends or the server is shut
down. This makes them useful for storing values which affect something
everywhere in your world.

**Example:**

```
		Function Main()
			SetSuperGlobal(25, 5)
			Result = SuperGlobal(25)
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### ThreadExecute

**Usage:**

```
		ThreadExecute(Name, EntryFunction, Actor, ContextActor[, Parameters])

```

**Description:**
The ThreadExecute command allows you to run another
script. The script will execute in parallel with other running scripts. Once
started, you cannot communicate between the scripts, except via files (not
recommended), or super-global variables.
The Name parameter is the name of
the script to run. EntryFunction is the function to start the script in (usually
Main). Actor and ContextActor allow you to pass an actor and context actor of
your choice to the script being called. These may be set to zero for none. The
optional Parameters is a string which can contain extra data to pass to the
script being called. Multiple items may be passed, seperated with commas. These
can then be accessed in the new script using the Parameter command.

**Example:**

```
		Function Main()
			// Say hello to the player via a seperate script
			ThreadExecute("Hello World", "Main", Actor(), 0)
			Return()
		End Function

```

## Player Commands

### PlayerAccountEmail

**Usage:**

```
		PlayerAccountEmail(Actor)

```

**Description:**
The PlayerAccountEmail command returns the account
email address for the specified actor.

**Example:**

```
		Function Main()
			Output(Actor(), "Your username is " $+ PlayerAccountName(Actor()))
			Output(Actor(), "Your email address is " $+ PlayerAccountEmail(Actor()))
			Return()
		End Function

```

### PlayerAccountName

**Usage:**

```
		PlayerAccountName(Actor)

```

**Description:**
The PlayerAccountName command returns the account
username for the specified actor.

**Example:**

```
		Function Main()
			Output(Actor(), "Your username is " $+ PlayerAccountName(Actor()))
			Output(Actor(), "Your email address is " $+ PlayerAccountEmail(Actor()))
			Return()
		End Function

```

### PlayerInGame

**Usage:**

```
		PlayerInGame(Actor)

```

**Description:**
The PlayerInGame command returns 1 if the specified
player actor is currently logged into the game, and 0 if it is an NPC or logged
off.

**Example:**

```
		Function Main()
			Human = PlayerInGame(Actor())
			If (Human == 1)
				Output(Actor(), "You are an online human player.")
			Else
				// Don't bother sending a message, NPCs or offline humans can't read them anyway!
			EndIf
			Return()
		End Function

```

### PlayerIsBanned

**Usage:**

```
		PlayerIsBanned(Actor)

```

**Description:**
The PlayerIsBanned command returns 1 if the specified
actor has a banned account, or 0 if not. 0 is also returned if the actor
specified is an NPC rather than a human player.

**Example:**

```
		Function Main()
			Ban = PlayerIsBanned(Actor())
			If (Ban == 1)
				// No point sending a message, the player is banned!
			Else
				Output(Actor(), "You are not banned, of course.")
			EndIf
			Return()
		End Function

```

### PlayerIsDM

**Usage:**

```
		PlayerIsDM(Actor)

```

**Description:**
The PlayerIsDM command returns 1 if the specified
actor has a DM account, or 0 if not. 0 is also returned if the actor specified
is an NPC rather than a human player.

**Example:**

```
		Function Main()
			DM = PlayerIsDM(Actor())
			If (DM == 1)
				Output(Actor(), "You have a DM account.")
			Else
				Output(Actor(), "You have a normal player account.")
			EndIf
			Return()
		End Function

```

## Quest Commands

### CompleteQuest

**Usage:**

```
		CompleteQuest(Actor, Name)

```

**Description:**
The CompleteQuest command sets the status of a quest
to Complete. This allows the user to hide it from the quest log display, if they
wish. You may also delete completed quests if you prefer, using DeleteQuest.

**Example:**

```
		Function Main()
			// Update the quest status
			CompleteQuest(Actor(), "The Flour Shipment")
			Return()
		End Function

```

### DeleteQuest

**Usage:**

```
		DeleteQuest(Actor, Name)

```

**Description:**
The DeleteQuest command removes a quest from the
player's quest log.

**Example:**

```
		Function Main()
			// Remove the quest
			DeleteQuest(Actor(), "The Flour Shipment")
			Return()
		End Function

```

### NewQuest

**Usage:**

```
		NewQuest(Actor, Name, Status, StatusRed, StatusGreen, StatusBlue)

```

**Description:**
The NewQuest command adds a new quest to an actor's
quest log. The actor must be a player, not an AI actor. Name is the quest name
and cannot be changed once created. Status is the initial quest status
description. The final three parameters let you specify a colour for the status
to be displayed as, and should be between 0 and 255. There is a limit of 500
quests at any one time, if you require more you must delete some old quests.

This function will return 1 if the quest is added successfully.

**Example:**

```
		Function Main()
			// Add a quest to the player's log
			NewQuest(Actor(), "The Flour Shipment", "Find 10 bags of flour!", 255, 255, 255)
			Return()
		End Function

```

### QuestComplete

**Usage:**

```
		QuestComplete(Actor, Name)

```

**Description:**
The QuestStatus command returns 1 if a quest has been
completed, or 0 if it is not started or still in progress. The actor must be a
player character, not an NPC. Name is the name of the quest you want to check.

**Example:**

```
		Function Main()
			MyQStatus = QuestComplete(Actor(), "The Flour Shipment")
			If (MyQStatus == 1)
				Output(Actor(), "You have completed the flour shipment quest")
			EndIf
			Return()
		End Function

```

### QuestStatus

**Usage:**

```
		QuestStatus(Actor, Name)

```

**Description:**
The QuestStatus command returns the current status
text of a certain quest. The actor must be a player character, not an NPC. Name
is the name of the quest whose status you want to retrieve.

**Example:**

```
		Function Main()
			MyQStatus = QuestStatus(Actor(), "The Flour Shipment")
			Output(Actor(), "Flour shipment status: " $+ MyQStatus)
			Return()
		End Function

```

### UpdateQuest

**Usage:**

```
		UpdateQuest(Actor, Name, Status, StatusRed, StatusGreen, StatusBlue)

```

**Description:**
The UpdateQuest command alters the status of a quest
in the quest log. The actor must be a player character, not an NPC. Name is the
name of the quest to alter. Status is the new quest status description. The
final three parameters let you alter the colour for the status to be displayed
as, and should be between 0 and 255.

**Example:**

```
		Function Main()
			// Update the quest status
			UpdateQuest(Actor(), "The Flour Shipment", "Return the flour to Mr Cravat", 0, 255, 0)
			Return()
		End Function

```

### WaitItem

**Usage:**

```
		WaitItem(Actor, Item, Number)

```

**Description:**
The WaitItem command pauses the script until an actor
has in their inventory a certain amount of an item. This is useful for creating
quest scripts.
The Item parameter is the name of the item which the actor
must get. The Number parameter is the amount which the actor needs before the
script will continue.

**Example:**

```
		Function Main()
			// Wait for player to get 5 mushrooms
			WaitItem(Actor(), "Odd Mushroom", 5)
			Return()
		End Function

```

### WaitKill

**Usage:**

```
		WaitKill(Actor, ActorID, Number)

```

**Description:**
The WaitKill command pauses the script until an actor
has killed a certain number of other actors. This is useful for creating quest
scripts.
The ActorID parameter is a handle, retrieved using the ActorID command, which represents the race/class which
the actor must kill. Number is the amount which must be killed before the script
will continue.

**Example:**

```
		Function Main()
			// Wait for player to kill 5 Orcs
			ID = ActorID("Orc", "Warrior")
			WaitKill(Actor(), ID, 5)
			Return()
		End Function

```

### WaitSpeak

**Usage:**

```
		WaitSpeak(ActorA, ActorB)

```

**Description:**
The WaitSpeak command pauses the script until ActorA
speaks to ActorB, by right clicking on him. This is useful for creating quest
scripts.

**Example:**

```
		Function Main()
			// Wait for player to speak to an NPC
			WaitSpeak(Actor(), ContextActor())
			Return()
		End Function

```

## String Commands

### Asc

**Usage:**

```
		Asc(String)

```

**Description:**
The Asc command returns the ASCII code number for the
first character in a string.

**Example:**

```
		Function Main()
			Output(Actor(), Asc("2")) // Displays 50

			Return()
		End Function

```

### Chr

**Usage:**

```
		Chr(Char)

```

**Description:**
The Chr command returns the string representation of
a character. The Char parameter is the ASCII code for the character.

**Example:**

```
		Function Main()
			Output(Actor(), Chr(50)) // Displays 2

			Return()
		End Function

```

### FullTrim

**Usage:**

```
		FullTrim(String)

```

**Description:**
The FullTrim command strips all leading and trailing
spaces, tabs, and other control characters from a string and returns the result.

**Example:**

```
		Function Main()
			Result = FullTrim(Chr(15) $+ "   Hello")
			Output(Actor(), Result) // Displays Hello
			Return()
		End Function

```

### Instr

**Usage:**

```
		Instr(String, Find, [From])

```

**Description:**
The Instr command returns the first position in a
string at which the Find string is found. If the Find string is nowhere within
the initial string, the value returned will be zero.
The optional From
parameter allows you to only look for instances of the Find string after a
certain position in the string.

**Example:**

```
		Function Main()
			Result = Instr("Hello", "l")
			Output(Actor(), Result) // Displays 3
			Return()
		End Function

```

### Left

**Usage:**

```
		Left(String, n)

```

**Description:**
The Left command returns a string containing the
leftmost **n** characters of a string.

**Example:**

```
		Function Main()
			Result = Left("Hello", 1)
			Output(Actor(), Result) // Displays H
			Return()
		End Function

```

### Len

**Usage:**

```
		Len(String)

```

**Description:**
The Len command returns the total number of
characters in a string.

**Example:**

```
		Function Main()
			Result = Len("Hello")
			Output(Actor(), Result) // Displays 5
			Return()
		End Function

```

### Lower

**Usage:**

```
		Lower(String)

```

**Description:**
The Lower command returns the lowercase version of a
string.

**Example:**

```
		Function Main()
			Result = Lower("Hello")
			Output(Actor(), Result) // Displays hello
			Return()
		End Function

```

### Mid

**Usage:**

```
		Mid(String, Offset, [Length])

```

**Description:**
The Mid command returns a section of a string,
starting from any offset.
The String parameter is the string to take a
section from. The Offset parameter is the position in the string to begin. The
optional Length parameter is the number of characters to return. If you ignore
the Length parameter, or set it to zero, the returned string will be from the
specified offset to the end of the initial string.

**Example:**

```
		Function Main()
			Result = Mid("Hello", 2, 2)
			Output(Actor(), Result) // Displays el

			Result = Mid("Hello", 2)
			Output(Actor(), Result) // Displays ello

			Return()
		End Function

```

### Right

**Usage:**

```
		Right(String, n)

```

**Description:**
The Right command returns a string containing the
rightmost **n** characters of a string.

**Example:**

```
		Function Main()
			Result = Right("Hello", 1)
			Output(Actor(), Result) // Displays o
			Return()
		End Function

```

### Replace

**Usage:**

```
		Replace(String, From, To)

```

**Description:**
The Replace command returns the specified String,
after replacing all instances of the From string contained in it, with the To
string.

**Example:**

```
		Function Main()
			Result = Replace("Hello", "e", "33")
			Output(Actor(), Result) // Displays H33llo
			Return()
		End Function

```

### Split

**Usage:**

```
		Split(String, ItemNumber[, Delimiter])

```

D**escription:**
The Split command returns an item from a string made
up from multiple items seperated by a delimiter. This is useful for storing and
extracting multiple values in global variables.
The String parameter is the
string from which you wish to extract an item. The ItemNumber parameter
specifies which item to extract. The optional Delimiter parameter allows you to
change the string used to seperate the items. The default value is a comma, as
shown in the example below.

**Example:**

```
		Function Main()
			MyString = "item 1,item 2,item 3"

			Item = Split(MyString, 2)
			Output(Actor(), Item) // Displays item 2

			Return()
		End Function

```

### Trim

**Usage:**

```
		Trim(String)

```

**Description:**
The Trim command strips all leading and trailing
spaces from a string and returns the result.

**Example:**

```
		Function Main()
			Result = Trim("   Hello")
			Output(Actor(), Result) // Displays Hello
			Return()
		End Function

```

### Upper

**Usage:**

```
		Upper(String)

```

**Description:**
The Upper command returns the uppercase version of a
string.

**Example:**

```
		Function Main()
			Result = Upper("Hello")
			Output(Actor(), Result) // Displays HELLO
			Return()
		End Function

```

## Visual Commands

### CreateEmitter

**Usage:**

```
		CreateEmitter(Actor, Emitter, TextureID, Time, [OffsetX], [OffsetY], [OffsetZ], [DisplayActor])

```

**Description:**
The CreateEmitter command spawns a particles emitter.
It can be attached to an actor or set to a fixed position in space. This is
useful for spell casting and other visual effects. The emitter will be visible
to all nearby players.
The Actor parameter is the handle of an actor to
attach the emitter to. If this is zero, the emitter will be set to the offset
co-ordinates and will not move. If an actor handle is supplied, the emitter will
be attached to that actor and move where it moves. The Emitter parameter is the
name of the emitter to create. The TextureID is the texture to use for the
particles. You can see a texture's ID number in the Media tab of the main
editor. The Time parameter is the amount of time (in milliseconds) that the
emitter will last before disappearing. The optional offsets are the position in
the zone, or the offsets from the centre of the actor, that the emitter will
appear at. You can find the position of points in a zone by looking at the
camera position in the lower right corner of the Zones tab in the main editor.

The final optional DisplayActor parameter allows you to specify a single
player actor to whom the emitter will appear, rather than appearing to all
players in a zone. The emitter can still be attached to other actors as usual
with the Actor parameter.

**Example:**

```
		Function Main()
			// Create an aura around the character for two seconds
			CreateEmitter(Actor(), "Aura", 11, 2000)
			Return()
		End Function

```

### ScreenFlash

**Usage:**

```
		ScreenFlash(Actor, R, G, B, Alpha, Time, TextureID)

```

**Description:**
The ScreenFlash command is used to create a visual
effect for a player. It could be used to indicate damage, spell effects, a
transition between places, or anything else you can think of. It causes the
player's screen to flash a certain colour before fading back to normal.
The
Actor parameter should specifiy a player actor, not an NPC. The R, G and B
parameters are the flash colour and should each be between 0 and 255. The Alpha
parameter controls how transparent the flash is to begin with. An alpha value of
255 is fully opaque, and an alpha value of 0 is fully transparent. The Time
parameter is the length of time in milliseconds that the flash should last. A
Time value of 1000 will therefore make the flash last for one second before
fading out completely. The TextureID parameter allows the flash to take on a
certain texture, or you can set it to 65535 to not use a texture.

**Example:**

```
		Function Main()
			// Flash the screen blue for one second
			ScreenFlash(Actor(), 0, 0, 255, 255, 1000, 65535)
			Return()
		End Function

```

## World Commands

### CreateZoneInstance

**Usage:**

```
		CreateZoneInstance(Zone, [Instance])

```

**Description:**
The CreateZoneInstance command creates an extra
instance of a zone. Instances are given IDs from 0 to 99, with #0 being the
default instance, which always exists. Extra instances of a zone all look and
behave exactly like the default instance, but have their own seperate players,
NPCs, dropped items, and player owned scenery. This means that a player in
instance #2 of a zone would effectively be in a different zone to a player in
instance #1, even though they are both in the same zone.
There are many uses
for this command. For example; to split players up when zones become too densely
populated, to avoid overloading the server, clients or network, and keep
performance at an acceptable level.
This command will return the ID of the
newly created instance, or 0 if a new instance could not be created.
The
optional Instance parameter allows you to request a specific instance ID for the
new instance. If it is not available, the instance will not be created and 0
will be returned.
Once created, an instance will continue to exist until
either it is removed with RemoveZoneInstance, or the server is
restarted while the instance contains no dropped items or owned scenery.
Instances which do have dropped items, player owned scenery, or scenery
containing items, will be saved when the server is closed and reloaded at
startup.

**Example:**

```
		Function Main()
			ID = CreateZoneInstance("Caves")
			Warp(Actor(), "Caves", "Start", ID)
			Return()
		End Function

```

### Day

**Usage:**

```
		Day()

```

**Description:**
The Day command returns the current day of the year.
This may be useful for events which only happen at certain times of year. The
value returned is a number between 1 and the year length set in the World
Editor.

**Example:**

```
		Function Main()
			Output(Actor(), "Day: " $+ Day()) // Displays the current game day
			Return()
		End Function

```

### Hour

**Usage:**

```
		Hour()

```

D**escription:**
The Hour command returns the current hour of the
24-hour game clock. Combined with the Minute() command you can get the full time
of day. This may be useful for events which only happen at certain times of day.

**Example:**

```
		Function Main()
			Time = Hour() $+ ":" $+ Minute()
			Output(Actor(), Time) // Displays the current game time
			Return()
		End Function

```

### Minute

**Usage:**

```
		Minute()

```

**Description:**
The Minute command returns the current minutes of the
24-hour game clock. Combined with the Hour() command you can get the full time
of day. This may be useful for events which only happen at certain times of day.

**Example:**

```
		Function Main()
			Time = Hour() $+ ":" $+ Minute()
			Output(Actor(), Time) // Displays the current game time
			Return()
		End Function

```

### RemoveZoneInstance

**Usage:**

```
		RemoveZoneInstance(ZoneName, Instance)

```

**Description:**
The RemoveZoneInstance command will remove an
instance previously created with CreateZoneInstance. The default instance (#0)
cannot be removed.

**Example:**

```
		Function Main()
			If (ZoneInstanceExists("Caves", 1))
				RemoveZoneInstance("Caves", 1)
			EndIf
			Return()
		End Function

```

### SaveState

**Usage:**

```
		SaveState()

```

**Description:**
The SaveState command forces the server to pause and
save the state of all dynamic data such as player characters, superglobals, zone
object ownerships, time and date, and dropped/spawned items. These saved data
will be reloaded when the server is restarted after closing abnormally (e.g. in
the event of a crash). This command is useful to make regular backups, or
backups after important events, but should not be called too frequently as the
server will pause for a moment as it accesses the disk, which may briefly
interrupt players.

**Example:**

```
		// Save state every in-game day at midnight
		Function Main()
			// Wait for 12:00
			.MidnightLoop
			DoEvents(500)
			If (Hour() != 0 | Minute() != 0)
				GoTo(MidnightLoop)
			EndIf

			// Save
			SaveState()

			// Wait for 12:01, then return to the beginning
			.MidnightOneLoop
				DoEvents(500)
				If (Minute() > 0)
					GoTo(MidnightLoop)
				EndIf
			GoTo(MidnightOneLoop)

		End Function

```

### SceneryOwner

**Usage:**

```
		SceneryOwner(ZoneName, SceneryID, [Instance])

```

**Description:**
The SceneryOwner command returns the handle of the
actor who 'owns' a specified scenery object. If no actor owns the scenery, the
returned value will be zero. Scenery IDs are set in the zones editor - scenery
must be set to 'ownable' before this command can be used. The optional Instance
parameter allows you to get the owner of the object in any extra instance of the
zone created with CreateZoneInstance.

See SetOwner for more information.

**Example:**

```
		Function Main()
			// Find out who owns house number 22
			Player = Actor()
			If (SceneryOwner("Tilbury Town", 22) == Player)
				Output(Player, "You own the house!")
			Else
				Output(Player, "You do not own the house!")
			EndIf
			Return()
		End Function

```

### Season

**Usage:**

```
		Season()

```

**Description:**
The Season command returns the current season. This
may be useful for events which only happen at certain times of year. The value
returned is a number between 1 and the number of seasons created in the World
Editor.

**Example:**

```
		Function Main()
			Output(Actor(), "Season: " $+ Season()) // Displays the current game season
			Return()
		End Function

```

### SetOwner

**Usage:**

```
		SetOwner(Actor, ZoneName, SceneryID, [Instance])

```

**Description:**
The SetOwner command sets the actor who 'own' a
specified scenery object. Scenery IDs are set in the zones editor - scenery must
be set to 'ownable' before this command can be used. The optional Instance
parameter allows you to set the object owner in any extra instance of the zone
created with CreateZoneInstance.

When an actor owns some scenery, only that actor has access to the
scenery inventory, and if it is set to animate when selected, only that actor
may select the scenery and cause it to animate. This command is useful to allow
players to buy houses, storage chests etc. which only they can use.

**Example:**

```
		Function Main()
			// Give house number 22 to the actor
			SetOwner(Actor(), "Tilbury Town", 22)
			Return()
		End Function

```

### Year

**Usage:**

```
		Year()

```

**Description:**
The Year command returns the current game year. This
may be useful for events which only happen once.

**Example:**

```
		Function Main()
			Output(Actor(), "Year: " $+ Year()) // Displays the current game year
			Return()
		End Function

```

### ZoneInstanceExists

**Usage:**

```
		ZoneInstanceExists(ZoneName, Instance)

```

**Description:**
The ZoneInstanceExists command returns 1 if the
specified zone instance exists, or 0 if it does not. The default instance (#0)
always exists.

**Example:**

```
		Function Main()
			// Warp actor to Caves instance #5
			Result = ZoneInstanceExists("Caves", 5)
			If (Result == 0)
				CreateZoneInstance("Caves", 5)
			EndIf
			Warp(Actor(), "Caves", "Start", 5)
			Return()
		End Function

```

### ZoneOutdoors

**Usage:**

```
		ZoneOutdoors(ZoneName)

```

**Description:**
The ZoneOutdoors command returns 1 if the specified
zone is flagged as outdoors, or 0 if it is indoors.

**Example:**

```
		Function Main()
			Result = ZoneOutdoors("Caves")
			If (Result == 0)
				Output(Actor(), "Zone is indoors")
			Else
				Output(Actor(), "Zone is outdoors")
			EndIf
			Return()
		End Function

```