Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Script reference

The functions and commands of the game’s script language. Each signature is written as a TypeScript declaration. A function returns a value; a command returns void. The types are number, string, object and group; name? is an argument a call may leave out, and ...name may be given again and again. Names ignore ASCII case. A condition is a number: 0 is false.

Entries tagged eix are added or changed by eix: the functions and commands that addon.dll adds, and the changes that SpellAddon options make to the game’s own. The others are the original game’s. A note headed Differs from the original says where eix behaves differently.

Sections:

Script flow

Waiting, stopping and looping over groups.

Any

function Any(variable: object, group: group, condition: number): number

Returns 1 if the condition is nonzero for at least one object of the group, with the variable set to each object in turn; otherwise 0.

Every

function Every(variable: object, group: group, condition: number): number

Returns 1 if the condition is nonzero for every object of the group, with the variable set to each object in turn; otherwise 0.

For

function For(variable: object, group: group): void

Runs the loop body once for every object of the group, with the global variable set to that object. The group can be a diplomatic group, a game group, or the result of GroupAdd or GroupCross.

ForIf

function ForIf(variable: object, group: group, condition: number): void

Like For, but runs the body only for the objects for which the condition is nonzero.

KillScript

function KillScript(): void

Stops the running script. Map script modules only; the first command of a script body, as a rule.

Sleep

function Sleep(ticks: number): void

Pauses the script for the given time, in 1/15 s units. Works in map script modules only.

SleepUntil

function SleepUntil(condition: number): void

Pauses the script until the condition becomes nonzero.

SleepUntilIdle

function SleepUntilIdle(unit: object): void

Pauses the script until the unit has no order left.

Sum

function Sum(variable: object, group: group, expression: number): number

Evaluates the expression once for every object of the group, with the variable set to that object, and returns the sum of the results.

WaitSegment

function WaitSegment(segments: number): void

Pauses the called procedure for the given number of segments, 15 to the second. Map script modules only.

Numbers and logic

Arithmetic, comparisons and rounding. A condition is a number: 0 is false, any other value true.

Abs

function Abs(value: number): number

eix Added by addon.dll.

Returns the absolute value.

Add

function Add(a: number, ...b: number[]): number

eix Added by addon.dll.

Returns the sum of two or more numbers. Replaces the game’s function of two numbers.

And

function And(a: number, ...b: number[]): number

eix Added by addon.dll.

Returns the logical conjunction of two or more values.

Ceil

function Ceil(value: number): number

eix Added by addon.dll.

Rounds up.

Cos

function Cos(value: number): number

eix Added by addon.dll.

Returns the cosine of a value in radians.

DistancePointPoint

function DistancePointPoint(x: number, y: number): number

eix Added by addon.dll.

Returns the distance from the point (x, y) to the origin: the two implicit coordinates are zero.

Differs from the original: the last two values are 0 (the original reads past its arguments)

Div

function Div(a: number, b: number): number

Returns a divided by b.

Floor

function Floor(value: number): number

eix Added by addon.dll.

Rounds down.

IsEqual

function IsEqual(a: number, b: number): number

Returns 1 if the two numbers are equal, otherwise 0.

IsEqualString

function IsEqualString(a: string, b: string): number

Returns 1 if the two strings are equal, case included, otherwise 0.

IsGreater

function IsGreater(a: number, b: number): number

Returns 1 if a is greater than b, otherwise 0.

IsLess

function IsLess(a: number, b: number): number

Returns 1 if a is less than b, otherwise 0.

Max

function Max(a: number, ...b: number[]): number

eix Added by addon.dll.

Returns the largest of two or more numbers.

Min

function Min(a: number, ...b: number[]): number

eix Added by addon.dll.

Returns the smallest of two or more numbers.

Mul

function Mul(a: number, ...b: number[]): number

eix Added by addon.dll.

Returns the product of two or more numbers. Replaces the game’s function of two numbers.

Not

function Not(value: number): number

Returns 1 if the value is 0, otherwise 0.

Or

function Or(a: number, ...b: number[]): number

eix Added by addon.dll.

Returns the logical disjunction of two or more values.

Pow

function Pow(base: number, exponent: number): number

eix Added by addon.dll.

Returns the base raised to the exponent.

Random

function Random(a: number, b?: number): number

eix Added by addon.dll.

Random(max) is the game’s random function. Random(min, max) returns a random value in the range, or min if max is not above min. Replaces the game’s function of one number.

Round

function Round(value: number): number

eix Added by addon.dll.

Rounds half away from zero.

Differs from the original: Round is exact (the original gives 8388610 for 8388609 and 1 for 0.49999997)

Sin

function Sin(value: number): number

eix Added by addon.dll.

Returns the sine of a value in radians.

Sub

function Sub(a: number, b: number): number

Returns a minus b.

Text and console

Strings, and output to the console and the chat.

ConsoleFloat

function ConsoleFloat(value: number): void

Prints a number to the console. Synonym: #.

ConsoleString

function ConsoleString(...text: string[]): void

eix Added by addon.dll.

Joins the strings and prints them as one console line. Replaces the game’s command of one string.

FloatToStr

function FloatToStr(value: number, precision?: number): string

eix Added by addon.dll.

Converts a number to text. precision defaults to 3 and is clamped to 0 to 8; the fraction’s trailing zeros are removed.

Differs from the original: FloatToStr(100, 0) is 100 (the original removes the integer part’s zeros too, giving 1)

RandStr

function RandStr(text: string, ...more: string[]): string

eix Added by addon.dll.

Returns one of two or more strings at random.

Differs from the original: RandStr stops on a missing object (the original crashes)

Say

function Say(...text: string[]): void

eix Added by addon.dll.

Joins the strings and sends them to the multiplayer server chat.

SendEvent

function SendEvent(player: number, event: number): void

Debug command: broadcasts a number to the engine’s players.

SendStringEvent

function SendStringEvent(player: number, event: string): void

Sends a text command to the engine. say sNN Name starts an NPC line (the text say sNN of texts.res, with the sound from the unit’s Acks field); say_block does the same and blocks the speaker. Other commands: tutorial zt1, briefing, autosave, endofgame.

StrCat

function StrCat(text: string, ...more: string[]): string

eix Added by addon.dll.

Joins two or more strings.

StrHas

function StrHas(text: string, fragment: string): number

eix Added by addon.dll.

Returns 1 if the fragment occurs in the text, otherwise 0.

StrLen

function StrLen(text: string): number

eix Added by addon.dll.

Returns the length of a string in bytes.

StrLower

function StrLower(text: string): string

eix Added by addon.dll.

Converts a string to lowercase by the active code page.

StrMid

function StrMid(text: string, start: number, count: number): string

eix Added by addon.dll.

Returns part of a string, by the active code page. start counts bytes from 1, and from the end when negative; a count of 0 takes the rest of the string.

StrToFloat

function StrToFloat(text: string): number

eix Added by addon.dll.

Converts text to a number.

StrUpper

function StrUpper(text: string): string

eix Added by addon.dll.

Converts a string to uppercase by the active code page.

Groups

Sets of objects: diplomatic groups, game groups and the results of group functions.

AddObject

function AddObject(group: group, unit: object): void

Adds a unit to a game group, a global variable of the script.

GetObjectsOnMap

function GetObjectsOnMap(...class: number[]): group

eix Added by addon.dll.

Returns the group of the objects of the listed classes. -1 selects all.

GetPlayerUnits

function GetPlayerUnits(diplomacyGroup: number): group

Returns the group of the units of a diplomatic group.

GroupAdd

function GroupAdd(a: group, b: group): group

Returns the group of the objects that are in either group.

GroupCross

function GroupCross(a: group, b: group): group

Returns the group of the objects that are in both groups.

GroupHas

function GroupHas(group: group, unit: object): number

Returns 1 if the group contains the unit, otherwise 0.

GroupSee

function GroupSee(group: group): group

Returns the group of the objects that the members of the group see at this moment. The members see each other.

GroupSee - SpellAddon groupseetrans

function GroupSee(group: group, mode: number): group

eix SpellAddon option [gameplay] groupseetrans.

Accepts an extra numeric mode argument. The group traversal itself stays the game’s.

GroupSize

function GroupSize(group: group): number

Returns the number of units in the group.

GroupSub

function GroupSub(a: group, b: group): group

Returns the group of the objects of the first group that are not in the second.

PlayerSee

function PlayerSee(player: number): group

Returns the group of the units that the units of the player’s party see.

RandObj

function RandObj(group: group): object

eix Added by addon.dll.

Returns a random member of the group.

RemoveObject

function RemoveObject(group: group, unit: object): void

Removes a unit from a game group. Not usable from the console.

UnitSee

function UnitSee(unit: object): group

Returns the group of the units the unit sees. A unit does not see itself.

UnitSee - SpellAddon unitseetrans

function UnitSee(unit: object, mode: number): group

eix SpellAddon option [gameplay] unitseetrans.

Selects the visibility list: positive zero is the visible living units, a negative sign bit (negative zero included) the second list, any other value the nearby-units list.

UnitsNearPoint

function UnitsNearPoint(x: number, y: number, radius: number, filter: number): group

eix Added by addon.dll.

Returns the group of the objects within the radius that pass the filter. Filter bits: 1 units, 2 other objects, 4 living named objects.

Objects and positions

Finding objects, reading their positions and placing them on the map.

AddMob

function AddMob(file: string): void

Loads a .mob file from the MAPS folder; the name includes the extension.

AddMob - SpellAddon infiniteaddmobspawn

function AddMob(file: string): void

eix SpellAddon option [gameplay] infiniteaddmobspawn.

Can load the same file repeatedly, except case-sensitive names that begin with Auto, which still load once. Active for values 1 and up.

AddMobEx

function AddMobEx(file: string, skipScripts?: number): void

eix Added by addon.dll.

Adds the objects of a .mob file without a loading movie, and optionally skips its scripts.

AddUnitToServer

function AddUnitToServer(mapName: string, prototype: string, displayName: string, x: number, y: number, z: number): void

Places a unit of the given prototype on the map at (x, y, z). mapName is its internal name, case-sensitive; displayName is the name shown in info windows.

DistanceUnitPoint

function DistanceUnitPoint(unit: object, x: number, y: number): number

Returns the straight distance between an object and a point.

DistanceUnitUnit

function DistanceUnitUnit(unitA: object, unitB: object): number

Returns the straight distance between two objects.

GetBSZValue

function GetBSZValue(x: number, y: number): number

Returns the height of the surface at the point: like GetZValue, except that an unfrozen pool of water or lava gives the height of its surface, not of its bottom.

GetFutureX

function GetFutureX(object: object, ticks: number): number

Returns the x coordinate the object is predicted to have after the given time, in 1/15 s units. The shorter the time, the better the prediction.

GetFutureY

function GetFutureY(object: object, ticks: number): number

Returns the y coordinate the object is predicted to have after the given time, in 1/15 s units.

GetLeader

function GetLeader(): object

Returns the leader of the current party: Zak in single player, the player’s current character in multiplayer.

GetObject

function GetObject(id: number): object

Returns the object with the given ID. Does not work with ten-digit IDs: use GetObjectByID.

GetObjectByID

function GetObjectByID(id: string): object

Returns the object with the given ID, written as a string. Accepts ten-digit IDs.

GetObjectByName

function GetObjectByName(name: string): object

Returns the object with the given in-game name.

GetObjectID

function GetObjectID(object: object): number

Returns the ID of an object, a unit or any other object such as a chest.

GetObjectStringID

function GetObjectStringID(object: object): string

eix Added by addon.dll.

Returns the ID of an object as a decimal string.

GetObjectTypeID

function GetObjectTypeID(object: object): number

eix Added by addon.dll.

Returns the class ID of an object, or -1.

GetPrototype

function GetPrototype(unit: object): string

eix Added by addon.dll.

Returns the name of the unit’s prototype.

Differs from the original: stops on a missing object (the original crashes)

GetRace

function GetRace(unit: object): string

eix Added by addon.dll.

Returns the model name of the unit.

Differs from the original: stops on a missing object (the original crashes)

GetX

function GetX(object: object): number

Returns the x coordinate of an object.

GetY

function GetY(object: object): number

Returns the y coordinate of an object.

GetZ

function GetZ(object: object): number

Returns the z coordinate of an object.

GetZValue

function GetZValue(x: number, y: number): number

Returns the height of the solid ground at the point, whatever water or lava lies over it.

HideObject

function HideObject(object: object, hide: number): void

Hides the object if hide is nonzero, shows it if 0. Works in briefing zones only.

IsInArea

function IsInArea(area: number, x: number, y: number): number

Returns 1 if the point (x, y) lies in a part of the quest area, otherwise 0.

IsInSquare

function IsInSquare(x: number, y: number, x1: number, y1: number, x2: number, y2: number): number

Returns 1 if the point (x, y) lies in the rectangle (x1, y1)-(x2, y2), otherwise 0.

IsUnitInWater

function IsUnitInWater(unit: object): number

Returns 1 if the unit is in water, otherwise 0.

IsUnitVisible

function IsUnitVisible(unit: object): number

Returns 1 if the player can see the unit in the zone, otherwise 0. HideObject does not change the result.

NearestUnit

function NearestUnit(x: number, y: number, radius: number, filter: number): object

eix Added by addon.dll.

Returns the nearest object within the radius that passes the filter, or no object. Filter bits: 1 units, 2 other objects, 4 living named objects.

RemoveObjectFromServer

function RemoveObjectFromServer(object: object): void

Removes the object from the server. Same as RemoveUnitFromServer.

RemoveUnitFromServer

function RemoveUnitFromServer(unit: object): void

Removes the object from the server. Same as RemoveObjectFromServer.

SetCP

function SetCP(object: object, x: number, y: number, z: number): void

Moves any map object, not only a unit, to (x, y). A unit loses its orders, and the passability graph is recalculated, which is slower than SetCPFast.

SetCPFast

function SetCPFast(object: object, x: number, y: number, z: number): void

Like SetCP, but the AI passability graph is not recalculated.

UnitInSquare

function UnitInSquare(unit: object, x1: number, y1: number, x2: number, y2: number): number

Returns 1 if the unit stands in the rectangle (x1, y1)-(x2, y2), otherwise 0.

Units and statistics

Health, mana, attributes, skills and experience.

BlockUnit

function BlockUnit(unit: object, block: number): void

Blocks the player’s control of a unit if block is nonzero, gives it back if 0. A unit can be controlled from the moment it joins a party.

GetActions

function GetActions(unit: object): number

eix Added by addon.dll.

Returns the current action count of a unit.

GetActionsBase

function GetActionsBase(unit: object): number

eix Added by addon.dll.

Returns the base action count of a unit.

GetAIClass

function GetAIClass(unit: object): number

Returns what the unit is doing: 0 calm, 1 moving, 2 turning, 3 attacking, 4 casting, 5 using a skill, 6 following.

GetAIClass - SpellAddon getaiclasstrans

function GetAIClass(unit: object): number

eix SpellAddon option [gameplay] getaiclasstrans.

Reads the AI class field of the unit’s server controller.

GetArmor

function GetArmor(unit: object, kind: number, part: number): number

eix Added by addon.dll.

Returns the protection of a unit. kind 0 to 5 selects a body slot’s layers and part 0 to 6 a damage type; a negative kind uses the computed protection.

GetDexterity

function GetDexterity(unit: object): number

eix Added by addon.dll.

Returns the dexterity of a unit.

GetEncumbrance

function GetEncumbrance(unit: object): number

eix Added by addon.dll.

Returns the load a unit carries.

GetIntelligence

function GetIntelligence(unit: object): number

eix Added by addon.dll.

Returns the intelligence of a unit.

GetMaxEncumbrance

function GetMaxEncumbrance(unit: object): number

eix Added by addon.dll.

Returns the load a unit can carry.

GetPerk

function GetPerk(unit: object, name: string): number

eix Added by addon.dll.

Returns the level of a perk of a unit. Names: sword, axe, dagger, spear, hammer, bow, crossbow, fire, lightning, acid, illusion, divination, enchantments, healing, domination, infra, health, mana, vitality, spirit, quickness, lift, backstab, strength, dexterity, intelligence.

GetSkill

function GetSkill(unit: object, name: string): number

eix Added by addon.dll.

Returns a skill or attribute of a unit: science, melee, archery, elemental, sense or astral.

GetStrength

function GetStrength(unit: object): number

eix Added by addon.dll.

Returns the strength of a unit.

GetUnitExp

function GetUnitExp(unit: object, what?: string): number

eix Added by addon.dll.

Returns the experience of a unit: max (the default), spent, penalty (the experience not yet added) or real (experience plus penalty).

GiveDexterity

function GiveDexterity(unit: object, amount: number): void

Adds dexterity points to a unit. Zones only; works on enemies as well.

GiveExp

function GiveExp(player: number, amount: number): void

eix Added by addon.dll.

Awards experience to a player’s party.

GiveIntelligence

function GiveIntelligence(unit: object, amount: number): void

Adds intelligence points to a unit. Zones only; works on enemies as well.

GiveSkill

function GiveSkill(unit: object, skill: string, amount: number): void

Raises a skill (science, melee, archery, and so on) by amount points. The experience needed is added to the unit, not to the party, and spent on the skill, so health and stamina follow.

GiveStrength

function GiveStrength(unit: object, amount: number): void

Adds strength points to a unit. Zones only; works on enemies as well.

GiveUnitExp

function GiveUnitExp(unit: object, amount: number): void

eix Added by addon.dll.

Awards experience to one unit.

Differs from the original: GiveUnitExp stops on a missing object (the original crashes)

HP

function HP(unit: object): number

Returns the unit’s current health, with the effects of weakening and strengthening spells.

HP - SpellAddon hptrans

function HP(unit: object, index: number): number

eix SpellAddon option [gameplay] hptrans.

Reads a float by index from the unit’s vitals. Valid indices are 0 to 29; the fields are listed under indexed stat readers.

InflictDamage

function InflictDamage(unit: object, amount: number): void

Deals damage to the unit, ignoring its armor. Experience is granted for a kill.

IsAlive

function IsAlive(unit: object): number

eix Added by addon.dll.

Returns 1 if the unit is alive. Returns 0 for a missing object or a non-unit. Replaces the game’s function.

IsDead

function IsDead(unit: object): number

eix Added by addon.dll.

Returns 1 if the unit is dead. Returns 0 for a missing object or a non-unit. Replaces the game’s function.

IsUnitBlocked

function IsUnitBlocked(unit: object): number

Returns 1 if the player’s control of the unit is blocked, otherwise 0.

KillUnit

function KillUnit(unit: object): void

Kills the unit. The party gets no experience for it.

Mana

function Mana(unit: object): number

Returns the unit’s current mana.

Mana - SpellAddon mptrans

function Mana(unit: object, index: number): number

eix SpellAddon option [gameplay] mptrans.

Reads a float from the unit’s stats, indices 0 to 448; an invalid object, controller or index returns 0. The fields are listed under indexed stat readers. Also adds the index argument to HP, which keeps its reader unless hptrans is 1.

MaxHP

function MaxHP(unit: object): number

Returns the unit’s maximum health, with the effects of weakening and strengthening spells.

MaxHP - SpellAddon legendaryspellsystem

function MaxHP(unit: object, index: number): number

eix SpellAddon option [gameplay] legendaryspellsystem.

Reads a byte, starting at the skill-byte area of the unit, indices 0 to 631; outside it returns 0.

Differs from the original: stays inside the unit (the original reads any address)

MaxMana

function MaxMana(unit: object): number

Returns the unit’s maximum mana.

MaxMana - SpellAddon legendaryspellsystem

function MaxMana(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number, extra: number): number

eix SpellAddon option [gameplay] legendaryspellsystem.

Takes seven numeric arguments, but the option supplies no working path-query implementation.

WasLooted

function WasLooted(unit: object): number

Returns whether the unit was robbed or its corpse searched: 0 if not. Stealing a quest item does not change the result.

WasLooted - SpellAddon waslootedtrans

function WasLooted(unit: object, bit?: number): number

eix SpellAddon option [gameplay] waslootedtrans.

Value 1: returns the full flag word. Value 2: WasLooted(unit, bit) returns the selected bit. Known bits: 15 moving, 19 knocked out, 20 looted, 24 stunned, 28 feebleminded.

Orders and behaviour

Orders to units, their stances, and the behaviours of the AI.

AlarmPosX

function AlarmPosX(alarm: number): number

Returns the x coordinate of the point set for the alarm number by InvokeAlarm.

AlarmPosY

function AlarmPosY(alarm: number): number

Returns the y coordinate of the point set for the alarm number by InvokeAlarm.

AlarmTime

function AlarmTime(alarm: number): number

Returns the time counter of the alarm number, in 1/15 s units. The counter runs while the alarm is the active one.

Attack

function Attack(unit: object, target: object): void

Orders the unit to attack the target.

Crawl

function Crawl(unit: object): void

Sets the unit’s stance to crouching.

Crawl - SpellAddon crawltrans

function Crawl(unit: object, slot: number): void

eix SpellAddon option [gameplay] crawltrans.

Requests a weapon slot instead of setting the crawl style.

Follow

function Follow(unit: object, target: object): void

Orders the unit to follow the target once. The order ends after a fight. See UMFollow.

Guard

function Guard(unit: object, x: number, y: number, radius: number): void

Orders the unit to guard the area of the given radius around (x, y), moving about in it.

Idle

function Idle(unit: object): void

Drops all behaviours and the current order of the unit: it stands and does nothing.

InvokeAlarm

function InvokeAlarm(alarm: number, x: number, y: number): void

Raises the alarm with the given number at the point (x, y). Only one alarm is active at a time: a new number replaces the previous one. Enemies with that alarm number in their .mob go to the point and guard it. InvokeAlarm(0, 0, 0) clears the alarm, and they return to their places.

IsAlarm

function IsAlarm(alarm: number): number

Returns 1 if the alarm number has been raised, otherwise 0.

Lie

function Lie(unit: object): void

Sets the unit’s stance to lying down.

MoveToObject

function MoveToObject(unit: object, target: object): void

Orders the unit to walk, in its current stance, to the place where the target stands at this moment. The unit does not follow the target.

MoveToObject - SpellAddon movetoobjecttrans

function MoveToObject(unit: object, target: object, skill?: number, unused?: number, run?: number, slot?: number): void

eix SpellAddon option [gameplay] movetoobjecttrans.

Value 1: MoveToObject(unit, target) performs thieving while walking. Value 2: runs instead. Value 3 and up: the four numbers after the target supply the thieving order.

MoveToPoint

function MoveToPoint(unit: object, x: number, y: number): void

Orders the unit to move to the point (x, y).

PlayAnimation

function PlayAnimation(unit: object, animation: string): void

Plays an animation from the unit’s .adb file (res/database.res/<mask name>.adb; the mask is in RaceModels.txt). The first letter of the name sets the kind: u plays once, then back to normal; c loops, and the unit ignores everything until the next order; s is one step of a movement. Families: uattack01..09, udeath01..31, cidle01..09, ucast01..04, uhit01..21, crun01..02, cwalk01..09, ccrawl01, ucross01..09, scross01..09, crest; humans also have ubriefing##, uspecial## and cspecial##. An unknown name does nothing.

ResetTarget

function ResetTarget(unit: object): void

eix Added by addon.dll.

Resets the unit’s perception and reapplies its alarm state. Resets all guard, patrol and aggression behaviours: call it before building a patrol or guard list. Replaces the game’s command.

Differs from the original: refuses a negative slot or a unit without a controller

Rest

function Rest(unit: object): void

Orders the unit to rest. It sits down when it can.

RotateTo

function RotateTo(unit: object, x: number, y: number): void

Turns the unit to face the point (x, y). Does nothing right after AddUnitToServer: the unit has to exist on the map first.

Run

function Run(unit: object): void

Sets the unit’s stance to running.

Run - SpellAddon runtrans

function Run(unit: object, style: number): void

eix SpellAddon option [gameplay] runtrans.

Sets the requested movement style instead of always selecting run.

Sentry

function Sentry(unit: object, x: number, y: number): void

Orders the unit to guard the point (x, y) and attack the enemies it sees. It returns to the point afterwards.

SetEnemy

function SetEnemy(unit: object, diplomacyGroup: number): void

Makes the diplomatic group hostile to the unit, as if one of its members had attacked it. Units only.

SetPlayerAggression

function SetPlayerAggression(a: number, b: number): void

Does nothing.

SetSpellAggression

function SetSpellAggression(unit: object, aggression: number): void

Does nothing.

Stand

function Stand(unit: object): void

Sets the unit’s stance to walking, as Walk.

Stand - SpellAddon standtrans

function Stand(unit: object): void

eix SpellAddon option [gameplay] standtrans.

Also revives the unit. A non-unit argument causes no revival.

Differs from the original: does nothing for an argument that is not a unit (the original crashes)

StartAnimation

function StartAnimation(unit: object, path: string): void

Not implemented in game.exe: does nothing. Use PlayAnimation.

UMAg

function UMAg(unit: object, preset: number): void

Replaces the unit’s fear, aggression and suspicion behaviours with a preset: 0 always afraid (flees), 1 afraid (fear without the “always” flag), 2 revenge plus fear. Each preset also adds suspicion and corpse watching.

UMAggression

function UMAggression(unit: object): void

Adds aggression: the unit attacks the enemies it sees.

UMClear

function UMClear(unit: object): void

Removes all independent behaviours of the unit. The current order stays.

UMCorpseWatcher

function UMCorpseWatcher(unit: object): void

Adds corpse watching: the unit reacts to dead bodies.

UMFear

function UMFear(unit: object, always: number): void

Makes the unit never attack and try to hide from enemies, the default of neutral beasts. If always is nonzero, the unit fears the player for good.

UMFollow

function UMFollow(unit: object, target: object): void

Orders the unit to follow the target for good. The order survives a fight. See Follow.

UMGuard

function UMGuard(unit: object, x: number, y: number, radius: number): void

Makes the unit guard the point (x, y) within the radius.

UMGuardEx

function UMGuardEx(unit: object, x: number, y: number, radius: number, delay: number): void

Makes the unit guard the point (x, y) within the radius, pausing for delay at random stopping points.

UMPatrol

function UMPatrol(unit: object): void

Adds a patrol behaviour. The command raises an error in the game. To make a unit patrol, call ResetTarget, then UMPatrolAddPoint.

UMPatrolAddPoint

function UMPatrolAddPoint(unit: object, x: number, y: number): void

Adds the patrol point (x, y). Does nothing when the unit has no patrol behaviour. Add UMPatrolAddPointLook after it to make the unit wait there.

UMPatrolAddPointLook

function UMPatrolAddPointLook(unit: object, x: number, y: number, delay: number): void

Sets the point (x, y) the unit looks at, and the time delay it stays, at the last patrol point.

UMPatrolClear

function UMPatrolClear(unit: object): void

Removes all patrol points of the unit. ResetTarget also resets the other behaviours.

UMPlayer

function UMPlayer(unit: object): void

Makes the unit obey the rules of a player’s unit, which gives sensible behaviour. Briefing zones use it for scripted NPCs. Clears the unit’s other behaviours and orders.

UMRevenge

function UMRevenge(unit: object): void

Gives the unit conditional fear: it runs away from everyone hostile and fights only when wounded or cornered.

UMSentry

function UMSentry(unit: object, x: number, y: number): void

Makes the unit guard the point (x, y) and attack the enemies it sees. It returns to the point afterwards.

UMStandard

function UMStandard(unit: object): void

Gives the unit the behaviour of a standard enemy: aggression, suspicion and corpse watching.

UMSuspection

function UMSuspection(unit: object): void

Adds suspicion: the unit goes to the nearest enemy it sees.

WaitEndAnimation

function WaitEndAnimation(): void

Not implemented in game.exe: does nothing.

Walk

function Walk(unit: object): void

Sets the unit’s stance to walking.

Spells

Casting spells and giving them to units.

Cast

function Cast(unit: object, x: number, y: number): void

Makes the unit cast its active area spell at the point (x, y). The spell must be one meant for a place, not for targets.

Cast - SpellAddon castscripttrans

function Cast(unit: object, x: number, y: number, spell: number, target?: object): void

eix SpellAddon option [gameplay] castscripttrans.

Value 1: Cast(unit, x, y, spell) uses the numbered spell. Value 2: with target, casts on the target if there is one, otherwise at the point.

Differs from the original: value 2 reads its target from the running command (the original: a stale value)

CastSpellPoint

function CastSpellPoint(spell: string, x1: number, y1: number, x2: number, y2: number): void

Casts a terrain spell by its name: the effect starts at (x1, y1) and lands at (x2, y2). Area spells only.

CastSpellPoint - SpellAddon castspellpointtrans

function CastSpellPoint(spell: string, x1: number, y1: number, x2: number, y2: number, caster: object): void

eix SpellAddon option [gameplay] castspellpointtrans.

Adds a caster unit to the named-spell command.

CastSpellUnit

function CastSpellUnit(spell: string, x: number, y: number, unit: object): void

Casts a spell on a unit. The visual effect starts at (x, y).

CastSpellUnit - SpellAddon castspellunittrans

function CastSpellUnit(spell: string, x: number, y: number, target: object, caster: object): void

eix SpellAddon option [gameplay] castspellunittrans.

Adds a caster unit to the named-spell command.

GiveUnitSpell

function GiveUnitSpell(unit: object, spell: string): void

Puts the spell into the unit’s set of active spells. Nothing happens when the set is full. Does not work in the shop; in a zone the spell is given, but the panel does not refresh.

GiveUnitSpell - SpellAddon giveunitspelltrans

function GiveUnitSpell(unit: object, name: string): void

eix SpellAddon option [gameplay] giveunitspelltrans.

Creates and adds a quick item instead of a spell, from the same unit and name arguments.

Players, parties and diplomacy

Players, their parties, and the relations between diplomatic groups.

AddUnitToParty

function AddUnitToParty(player: number, name: string, unit: string): void

Adds a localized character to a party; name is PartyName::NamePersRes.

AddUnitUnderControl

function AddUnitUnderControl(player: number, unit: object): void

Adds the unit’s icon to the player’s control panel. Diplomacy does not change.

CopyItems

function CopyItems(player: number, from: string, to: string): void

Copies the equipment (not the wagon, not the backpack) of a member of the current party to a member of another party of the same player. to is PartyName::Name.

CopyStats

function CopyStats(player: number, from: string, to: string): void

Copies the skills, abilities and parameters of a member of the current party to a member of another party of the same player. to is PartyName::Name.

CreateParty

function CreateParty(player: number, name: string): void

Creates a party for the player. A party of the same name is replaced. The name is case-sensitive.

GetDiplomacy

function GetDiplomacy(groupA: number, groupB: number): number

Returns what group A is to group B: 1 ally, 0 neutral, -1 enemy.

GetMercsNumber

function GetMercsNumber(player: number): number

Returns the number of mercenaries in the player’s current party, the leader not counted.

GetPlayer

function GetPlayer(unit: object): number

Returns the diplomatic group of the unit.

GetPlayer - SpellAddon getplayertrans

function GetPlayer(unit: object, index: number): number

eix SpellAddon option [gameplay] getplayertrans.

Reads a 32-bit integer at four times the index within the unit (0 to 310); returns 0 outside it.

Differs from the original: returns 0 outside the unit (the original reads any address)

GetPlayerOfUnit

function GetPlayerOfUnit(unit: object): number

eix Added by addon.dll.

Returns the number of the player the unit belongs to, or -1.

GetUnitOfPlayer

function GetUnitOfPlayer(player: number, index: number): object

Returns the unit at position index in the player’s current party, in the order the units joined.

IsEnemy

function IsEnemy(unit: object, diplomacyGroup: number): number

Returns 1 if the unit is an enemy of the diplomatic group, otherwise 0.

IsPlayer

function IsPlayer(unit: object): number

eix Added by addon.dll.

Returns 1 if the named unit belongs to a player, otherwise 0.

IsPlayerInDanger

function IsPlayerInDanger(player: number): number

Returns 1 if the player’s danger state is “in danger”, otherwise 0 (also for a player that does not exist). The state has three values: safe, an in-between value, and in danger; at the in-between value both this and IsPlayerInSafety return 0.

IsPlayerInSafety

function IsPlayerInSafety(player: number): number

Returns 1 if the player’s danger state is “safe”, otherwise 0 (also for a player that does not exist). Not the opposite of IsPlayerInDanger: at the state’s in-between value both return 0.

PlayerExists

function PlayerExists(player: number): number

eix Added by addon.dll.

Returns 1 if the player exists, otherwise 0.

RedeployParty

function RedeployParty(player: number): void

Finishes the change of the current party.

RemoveParty

function RemoveParty(player: number, name: string): void

Removes the party.

RemoveUnitFromControl

function RemoveUnitFromControl(player: number, unit: object): void

Removes the unit’s icon from the player’s control panel.

RemoveUnitFromParty

function RemoveUnitFromParty(player: number, name: string): void

Removes a character from its party. PartyName::Name reaches a party other than the current one.

SendCurrentParty

function SendCurrentParty(player: number): void

eix Added by addon.dll.

Resends the player’s party state.

Differs from the original: SendCurrentParty stops on a missing object (the original crashes)

SetCurrentParty

function SetCurrentParty(player: number, name: string): void

Makes the party the player’s current one.

SetDiplomacy

function SetDiplomacy(groupA: number, groupB: number, relation: number): void

Sets the relation between two diplomatic groups: 1 ally, 0 neutral, -1 enemy. The player’s party is always group 0.

SetPlayer

function SetPlayer(unit: object, diplomacyGroup: number): void

Assigns the unit to a diplomatic group.

SetPlayer - SpellAddon setplayertrans

function SetPlayer(unit: object, value: number, field: number): void

eix SpellAddon option [gameplay] setplayertrans.

Writes a rounded 32-bit integer at four times field within the unit (0 to 310). Fields 132 to 148 keep the game’s normal player-setting path; a write outside the unit is ignored.

Differs from the original: stores nothing outside the unit (the original writes any address)

Items and money

Items, quest items, wagons and money.

AddLoot

function AddLoot(player: number, from: string, to: string): void

Moves all items and gold from the wagon of a party to the wagon of another party of the same player.

CopyLoot

function CopyLoot(player: number, from: string, to: string): void

Copies the wagon (items and gold) of a party to the wagon of another party, which is emptied first. Do not confuse wagon and backpack: RedeployParty empties the sender’s backpack, and the new party’s one stays empty, though its items still show in the window.

EraseQuestItem

function EraseQuestItem(player: number, id: number): void

Removes a quest item from the player’s wagon.

FixItems

function FixItems(): void

Repairs every item of the current party: wagon, backpack, worn equipment and weapons.

GetLootItemsCount

function GetLootItemsCount(player: number): number

Returns how many item lines the current party has picked up in the zone, found, stolen or taken from enemies and corpses, quest items included. Money does not count, and identical items picked up one at a time each count.

GetMoney

function GetMoney(player: number): number

Returns the money of the player’s current party.

GiveItem

function GiveItem(player: number, item: string): void

Gives a regular item to the player’s backpack.

GiveMoney

function GiveMoney(player: number, amount: number): void

Adds money to the player’s party. Does not work in a shop.

GiveQuestItem

function GiveQuestItem(player: number, item: string): void

Gives a quest item to the player.

GiveQuestItem - SpellAddon legendaryspellsystem

function GiveQuestItem(unit: object, value: number): void

eix SpellAddon option [gameplay] legendaryspellsystem.

Writes byte 10 of the unit’s skill-byte area.

GiveUnitArmor

function GiveUnitArmor(unit: object, name: string, override: number): void

eix Added by addon.dll.

Creates an armor and equips the unit with it. override 1 also updates a non-named unit’s natural protection.

Differs from the original: stops on a missing object (the original crashes)

GiveUnitQuestItem

function GiveUnitQuestItem(unit: object, item: string): void

Puts a quest item into the unit’s backpack, such as a chest’s contents. For a member of the player’s party it goes to the party’s wagon.

GiveUnitWeapon

function GiveUnitWeapon(unit: object, name: string, override: number): void

eix Added by addon.dll.

Creates a weapon and equips the unit with it. override 1 also updates a non-named unit’s natural attack.

Differs from the original: stops on a missing object (the original crashes)

HaveItem

function HaveItem(player: number, id: number): number

Returns 1 if the player has the quest item in the wagon or the backpack, otherwise 0.

Loot

function Loot(player: number, unit: object): void

eix Added by addon.dll.

Loots the dead unit and removes it.

RemoveQuestItem

function RemoveQuestItem(unit: object, id: number): void

Removes a quest item from the unit’s backpack. Only items given by GiveUnitQuestItem or listed in the .mob file’s QuestItems are removed.

Quests

Dynamic quests of multiplayer zones.

QFinish

function QFinish(): void

Completes the quest started by QStart. In single player the quest’s experience is paid too.

QObjArea

function QObjArea(area: number): void

Quest objective: enter the area. The area is a virtual object made of all the parts with that ID, usually area 1.

QObjGetItem

function QObjGetItem(id: number): void

Quest objective: get the quest item with the ID. A macro for ordinary commands.

QObjKillGroup

function QObjKillGroup(group: string): void

Quest objective: kill the whole game group, given by the name of its global variable.

QObjKillUnit

function QObjKillUnit(unitName: string): void

Quest objective: kill the named unit. A macro for ordinary commands.

QObjSeeObject

function QObjSeeObject(objectName: string): void

Quest objective: see the named object, a chest and not a unit. A macro for ordinary commands.

QObjSeeUnit

function QObjSeeUnit(unitName: string): void

Quest objective: see the named unit. A macro for ordinary commands.

QObjUse

function QObjUse(lever: string, state: number): void

Quest objective: put the lever into the state. A macro for ordinary commands.

QStart

function QStart(name: string): void

Starts a dynamic multiplayer quest and opens its list of objectives, which ends with QFinish.

QuestComplete

function QuestComplete(player: number, name: string): void

Completes the quest and pays its experience, like QFinish but without the message in the info window.

Player variables

Named numeric variables that belong to a player.

GSDelVar

function GSDelVar(player: number, name: string): void

Deletes a variable of the player.

GSGetPlayerVar

function GSGetPlayerVar(player: number, name: string): number

eix Added by addon.dll.

Returns a numeric variable of a player.

GSGetVar

function GSGetVar(player: number, name: string): number

Returns the value of a variable of the player. Works differently in single and multiplayer.

Differs from the original: a name ini.<file>.<section>.<key> reads that value of <file>.ini in the mod or game folder, 0 when missing (INI variables)

GSGetVar - SpellAddon gsgetvar

function GSGetVar(player: number, name: string): number

eix SpellAddon option [speed] gsgetvar.

Returns the difficulty for names that begin with Diff, and the update period for names whose characters 4 to 7 (zero-based) are peed, such as SetSpeed.

Differs from the original: reads the variable’s name before freeing it

GSListPlayerVars

function GSListPlayerVars(player: number): void

eix Added by addon.dll.

Prints the variables of a player.

Differs from the original: stops on a missing object (the original crashes)

GSSetPlayerVar

function GSSetPlayerVar(player: number, name: string, value: number): void

eix Added by addon.dll.

Sets a numeric variable of a player.

Differs from the original: GSSetPlayerVar stops on a missing object (the original crashes)

GSSetVar

function GSSetVar(player: number, name: string, value: number): void

Sets a variable of the player. Works differently in single and multiplayer.

GSSetVar - SpellAddon gssetvar

function GSSetVar(player: number, name: string, value: number): void

eix SpellAddon option [speed] gssetvar.

Also sets the update period for names with peed at characters 4 to 7. The variable is still stored normally.

GSSetVarMax

function GSSetVarMax(player: number, name: string, value: number): void

Sets a variable of the player only when the new value is higher than the stored one.

World, effects and sound

Levers, areas, time, weather, lights, particles, sound, music, movies and the camera.

ActivateTrap

function ActivateTrap(trap: object, activate: number): void

Activates a trap on the map if activate is nonzero, deactivates it if 0. Traps attack only diplomatic group 0.

AddRectToArea

function AddRectToArea(area: number, x1: number, y1: number, x2: number, y2: number): void

Adds a rectangle, given by two opposite corners, to a quest area.

AddRoundToArea

function AddRoundToArea(area: number, x: number, y: number, radius: number): void

Adds a circle to a quest area.

AttachParticles

function AttachParticles(id: number, unit: object): void

Attaches the particle source to the unit. It follows the unit with the offset given in CreateParticleSource.

AttachParticleSource

function AttachParticleSource(id: number, unitId: number): void

Attaches the particle source to the unit with the ID unitId. It follows the unit with the offset given in CreateParticleSource.

CreateFX

function CreateFX(x: number, y: number, z: number, volume: number, radius: number, wav: string): void

Plays a WAV file once at (x, y, z), audible within the radius.

CreateFXSource

function CreateFXSource(id: number, x: number, y: number, z: number, volume: number, radius: number, wav: string): void

Creates a looping sound source at (x, y, z).

CreateLightning

function CreateLightning(id: number, x1: number, y1: number, z1: number, x2: number, y2: number, z2: number, intensity: number): void

Creates a lightning that stays, from (x1, y1, z1) to (x2, y2, z2). A positive intensity ends the bolt in a ball, as if it hit an object.

CreateParticleSource

function CreateParticleSource(id: number, x: number, y: number, z: number, radius: number, type: string): void

Creates a particle source of the given type at (x, y, z). A negative radius flips the source upside down.

CreatePointLight

function CreatePointLight(id: number, x: number, y: number, z: number, radius: number, r: number, g: number, b: number): void

Creates a point light of the given color at (x, y, z). A torch or a campfire at night is a light; a dim one darkens a dense forest by day.

CreateRandomizedFXSource

function CreateRandomizedFXSource(id: number, x1: number, x2: number, y1: number, y2: number, z1: number, z2: number, volume: number, radius: number, wav: string): void

Creates a looping sound source placed at random inside the box x1..x2, y1..y2, z1..z2. Remove it with DeleteFXSource.

DeleteArea

function DeleteArea(area: number): void

Deletes every part of the quest area.

DeleteFXSource

function DeleteFXSource(id: number): void

Deletes all sound sources with the ID.

DeleteLightning

function DeleteLightning(id: number): void

Deletes all lightnings with the ID.

DeleteParticleSource

function DeleteParticleSource(id: number): void

Deletes all particle sources with the ID.

DeletePointLight

function DeletePointLight(id: number): void

Deletes all point lights with the ID.

EnableLever

function EnableLever(lever: object, enable: number): void

Lets the player use a lever (1) or not (0). A usable lever shows the grabbing-hand cursor.

FixWorldTime

function FixWorldTime(time: number): void

Sets the time of day and stops the clock.

FixWorldTime - SpellAddon fixworldtimetrans

function FixWorldTime(time: number, speed: number): void

eix SpellAddon option [gameplay] fixworldtimetrans.

Adds an explicit time-speed argument.

GetLeverState

function GetLeverState(lever: object): number

Returns 1 if the lever is on, 0 if it is off.

GetWorldTime

function GetWorldTime(): number

Returns the time of day, in hours.

IsCameraPlaying

function IsCameraPlaying(): number

Returns 1 if a camera path file is playing now, otherwise 0.

IsNight

function IsNight(): number

Returns how dark it is, from 0 to 1, by the game’s hour of day: 0 from 8:00 to 20:00, rising evenly from 0 at 20:00 to 1 at 24:00, and 1 from 0:00 until 8:00, when it drops to 0 at once. The server updates it every tick.

MoveParticleSource

function MoveParticleSource(id: number, x: number, y: number, z: number, time: number, remove: number): void

Moves the particle source to (x, y, z) over the time, in 1/15 s units. If remove is nonzero, the source is deleted on arrival.

MovePointLight

function MovePointLight(id: number, x: number, y: number, z: number, time: number, remove: number): void

Moves the point light to (x, y, z) over the time, in 1/15 s units. If remove is nonzero, the light is deleted on arrival.

PlayCamera

function PlayCamera(name: string): void

Starts the automatic camera path in the file CAMERA\<name>.

PlayFX

function PlayFX(x: number, y: number, z: number, radius: number, wav: string): void

Not implemented in game.exe: does nothing.

PlayMovie

function PlayMovie(name: string): void

Plays the video MOVIES\<name>, the name with its extension.

PlayMusic

function PlayMusic(player: number, name: string): void

Plays the piece STREAM\<name> for the player, the name without its extension. The name 0 turns the zone’s music off, 1 on.

PlayMusic - SpellAddon playmusictrans

function PlayMusic(player: number, name: string): void

eix SpellAddon option [gameplay] playmusictrans.

Values 1 and 2: the name "0" or "1" re-selects the local map’s music theme and sets the music system’s level to the digit. The first character selects this behavior. Value 1 uses the map’s theme, value 2 its alternative name field. Other text, or no map or music system, uses normal handling.

Differs from the original: without a map or a music system, does what the game does (the original crashes)

RunWorldTime

function RunWorldTime(hour: number): void

Sets the time of day and lets the clock run at normal speed.

SetBackGroundColor

function SetBackGroundColor(r: number, g: number, b: number): void

Sets the color the screen is cleared to, which is the sky behind everything. Each value is 0 to 255.

SetCameraOrientation

function SetCameraOrientation(angle: number): void

Not implemented in game.exe: does nothing.

SetCameraPosition

function SetCameraPosition(x: number, y: number, z: number): void

Not implemented in game.exe: does nothing.

SetDirectionToObject

function SetDirectionToObject(unit: number): void

Not implemented in game.exe: does nothing.

SetParticleSourceSize

function SetParticleSourceSize(id: number, radius: number): void

Changes the radius of the particle source.

SetScience

function SetScience(lever: object, questItem: number, skill: number, hands: number, lockpick: number, crowbar: number, key: number): void

Sets how a lever can be switched: with the quest item, with that much Sleight of hand, and by hands, lockpick, crowbar or key (1 allowed, 0 not).

SetSunLight

function SetSunLight(sunR: number, sunG: number, sunB: number, ambientR: number, ambientG: number, ambientB: number, skyR: number, skyG: number, skyB: number): void

Not implemented in game.exe: does nothing.

SetWaterLevel

function SetWaterLevel(basin: number, level: number, delay: number): void

Sets the water level of a basin, relative to its bottom, after the delay. Does not change where the party can wade.

SetWeather

function SetWeather(name: string): void

eix Added by addon.dll.

Sets the weather: rain or snow, exact and lowercase. Any other text clears the weather.

SetWind

function SetWind(x: number, y: number, z: number, force: number): void

Makes a gust of wind blow toward the point (x, y, z) with the given force.

ShowBitmap

function ShowBitmap(id: number, bitmap: string): void

Not implemented in game.exe: does nothing.

ShowCredits

function ShowCredits(text: string): void

Does nothing.

SwitchLeverState

function SwitchLeverState(lever: object, state: number): void

Puts the lever into the off (0) or on (1) position. GetLeverState reads it.

SwitchLeverStateEx

function SwitchLeverStateEx(lever: object, state: number, delay: number): void

Like SwitchLeverState, with a delay before the animation.

Game and system

Zone changes, game modes, game end and files.

GameOver

function GameOver(): void

eix Added by addon.dll.

Ends player 0’s game with the default title and text, the text keys game_over and game_over_msg.

GameOverMSG

function GameOverMSG(title: string, text: string): void

eix Added by addon.dll.

Ends player 0’s game with the given text keys for title and text.

GodMode

function GodMode(player: number, mode: number): void

Sets the mode of the player’s current party: 0 normal, 1 invulnerable when running and mana is free, 2 like 1, and every hit kills.

IsFileExists

function IsFileExists(path: string): number

eix Added by addon.dll.

Tests whether a file exists under the mod folder. A path that climbs to a parent folder is refused.

GSGetIniNumber

function GSGetIniNumber(file: string, section: string, key: string, default: number): number

eix Added by addon.dll.

Reads a value from an INI file of the mod folder, at the call, as a number; default when the file, section or key is missing or the value is not a number. The file is a path below the mod folder, with / or \ as separators; an absolute path, a drive letter or a .. component is refused and gives default. The decimal point is . or ,. File, section and key are matched without regard to case. A missing value or a refusal is logged once per file, section and key.

GSGetIniString

function GSGetIniString(file: string, section: string, key: string, default: string): string

eix Added by addon.dll.

Reads a value from an INI file of the mod folder, at the call, as text; default when the file, section or key is missing. The path and matching rules are those of GSGetIniNumber. A key with an empty value gives an empty string.

KillUnit - SpellAddon killunittrans

function KillUnit(kind: number, strength: number): void

eix SpellAddon option [gameplay] killunittrans.

Sets the weather with two rounded numbers instead of killing a unit.

LeaveToZone

function LeaveToZone(player: number, zone: string, entry: number): void

Moves the player, every party and the wagon, to the zone, at its entry place entry (the numbers are in Res/texts.res/map.txt).

PauseGame

function PauseGame(value: number): void

eix Added by addon.dll.

Outside multiplayer, 0 requests a pause and any other value unpauses.

RecalcMercBriefings

function RecalcMercBriefings(): void

Single player: recalculates which dialogues the companions and candidates offer.

ShowAllUnits

function ShowAllUnits(value: number): void

eix Added by addon.dll.

0 draws all units; any other value restores normal visibility.

StartCameraSave

function StartCameraSave(file: string): void

eix Added by addon.dll.

Starts recording a camera path to a file.

StopCameraSave

function StopCameraSave(): void

eix Added by addon.dll.

Stops recording the camera path.