# OBSE v0021 Command Documentation

OBSE @ Oblivion Construction Set Wiki - follow the links throughout this documentation to gain access to additional information on the official Oblivion Construction Set Wiki. Users are encouraged to add to the wiki.

## Table of Contents

- New Features
- Function Syntax Format
- Function Calling Conventions
- Qualities
- Types
- General Functions
- Cloning Functions
- Flow Control Functions
- Ref Walking Functions
- Console Functions
- Input Functions
- Math Functions
- Trig Functions
- Linear Algebra Functions
- Bitwise Manipulation Functions
- Output Functions
- Spam-Blocking Functions
- Mod Functions
- Hotkey Functions
- File Functions
- UI Functions
- Text Input Functions
- String Variables
- Format Specifiers
- Array Variables
- OBSE Expressions
- User-Defined Functions
- Event Handlers
- Inventory References
- Temporary Functions
- Physics Functions
- Type Codes
- Deprecated Functions

## New Features

OBSE v0021 introduces new event types, support for user-defined events, and includes the following new commands:

- HasTail
- GetLuckModifiedSkill
- SetCellMusicType
- GetSoundAttenuation
- SetSoundAttenuation
- GetStageIDs
- GetStageEntries
- SetStageText
- UnsetStageText
- SetStageDate
- GetTailModelPath
- UpdateContainerMenu
- UpdateSpellPurchaseMenu
- LinkToDoor
- sv_ToUpper
- sv_ToLower
- CopyRace
- SetCreatureType
- DispatchEvent
- GetGroundSurfaceMaterial
- GetSkillSpecializationC
- SetSkillSpecializationC
- GetRequiredSkillExpC
- GetAVSkillMasteryLevel
- GetAVSkillMasteryLevelC

## Function Syntax Format

    (returnValueName:returnValueType)    reference.FunctionName    parameter1:type  parameter2:type

optional - optional parameters or references are in italics

Parameter Types: designated after colon
float | a positive or negative decimal number | 3.1415
int | a positive or negative integer | 100, -98765
ref | a ref | objectID
chars | a 4 character magic effect code | FIDG, Z001
string | a set of characters in quotes | "Uriel Septim"
bool | a short with only 2 values: 1 for true and 0 for false | 1, 0

Additional OBSE parameter types
formatString | a string containing zero or more format specifiers followed by up totwenty variables
string_var | a variable defined as a string_var, with a unique ID representing a string of characters
array_var | an array_var variable, with a unique ID representing an array of keys and values
array | an array, not necessarily stored in a variable. (ex: someArr[1:4] is an array but not an array_var)
arrayKey | an array key (either a string, integer, or float)
Array | an array of type Array, with integer keys
StringMap | an array of type StringMap, with string keys
Map | an array of type Map, with floating point keys
expr | an OBSE expression
multi | a value of any type float, short, string, or array, e.g. an array element or a function return value

## Function Calling Conventions:

### By Reference or ObjectID

reference.FunctionName someParameters objectID:ref

#### Examples:

    	(health:int) reference.GetObjectHealth objectID:ref
    	(oldEnchantment:ref) reference.SetEnchantment nuEnchantment:ref objectID:ref

These functions can either be called on a reference or have an objectID passed in as an argument. The optional reference is there for the scripter's convenience. If the function is called on a reference, the objectID will be retrieved from the reference. If an objectID is passed in, it takes precedence over a calling reference.

The following are equivalent:

    	ref.doSomething

and

    	base = ref.getBaseObject
    	doSomething base

These functions always perform their operations on the base object.

### By Reference Only

reference.FunctionName someParameters

#### Examples:

    	(oldPoison:ref) reference.SetEquippedWeaponPoison nuPoison:ref

These functions must be called on a reference.

### By ObjectID Only

FunctionName someParamters objectID:ref

#### Examples:

    	(masterLevel:int) GetSpellMasteryLevel spell:ref	(effectCode:int) GetNthEffectItemCode magicItem:ref  whichEffect:int

These functions must have an ObjectID passed as an argument.

## Qualities

Qualities are a set of related values and functions which apply to multiple Oblivion object types. For documentation purposes I have gathered the related values together. Any type which has a given quality has all of the values listed and all of the quality's functions may be applied to the type.

- Actor
- Actor Values
- Attacking
- Audible
- Breakable
- Class
- Container
- Description
- Edible
- Enchantable
- Equippable
- Inventory
- Lockable
- Magic
- Magic Target
- Named
- Ownable
- Race
- Scriptable
- Simple
- Wearable

### Actor

Includes creatures and NPCs. All changes to actor flags such as Respawn and Low Level Processing are saved in the savegame.

#### Functions:

IsRefEssential - returns whether the referenced actor is essential
`(isEssential:bool) reference.IsRefEssential`

SetRefEssential - sets the calling ref to be essential or not
`reference.SetRefEssential isEssential:bool`

GetActorLightAmount - returns a float describing the amount of light falling on an actor, or 100 if the actor is not in high/medium-high process.
`(lightAmount:float) reference.GetActorLightAmount`

CanCorpseCheck - returns 1 if the Can Corpse Check flag is set on the actor
`(canCoprseCheck:bool) reference.CanCorpseCheck actor:ref`

SetCanCorpseCheck - changes the Can Corpse Check flag on the actor
`(nothing) reference.SetCanCorpseCheck flag:int actor:ref`

GetActorMinLevel - returns the minimum level of the actor if the PC Level Offset flag is set
`(minLevel:int) reference.GetActorMinLevel actor:ref`
`(minLevel:int) reference.GetMinLevel actor:ref`

GetActorMaxLevel - returns the maximum level of the actor if the PC Level Offset flag is set
`(maxLevel:int) reference.GetActorMaxLevel actor:ref`
`(maxLevel:int) reference.GetMaxLevel actor:ref`

GetNumFactions - returns the number of factions to which the actor belongs
`(numFactions:int) reference.GetNumFactions actor:ref`

GetNthFaction - returns the nth faction to which the actor belongs
`(faction:ref) reference.GetNthFaction whichFaction:short actor:ref`

GetActorSoulLevel - returns the soul level of any actor. If an NPC it returns Grand, otherwise if a creature it returns the creature's soul level.
`(soulLevel:int) reference.GetActorSoulLevel actor:ref`

HasLowLevelProcessing - returns 1 if the actor has low level processing enabled
`(hasLowProc:bool) reference.HasLowLevelProcessing actor:ref`

HasNoPersuasion - returns 1 if the No Persuasion flag is set on the actor
`(hasNoPers:bool) reference.HasNoPersuasion actor:ref`

SetNoPersuasion - changes the No Persuasion flag on the actor
`(nothing) reference.SetNoPersuasion flag:int actor:ref`

IsActorRespawning - returns 1 if the Respawn flag is set on the actor
`(respawns:bool) reference.IsActorRespawning actor:ref`

IsPCLevelOffset - returns 1 if the actor's level is calculated relative to the player's level
`(isLevOffset:bool) reference.IsPCLevelOffset actor:ref`

GetActorBaseLevel - returns the level of the base actor. In the editor, for creatures this is the "Level Offset" field; for NPCs it is the "Level" field. For either, the meaning of the return value depends on whether or not the PC Level Offset flag is set for the base actor.
`(level:int) reference.GetActorBaseLevel actorBase:ref`

IsSummonable - returns 1 if the Summonable flag is set on the actor
`(isSummonable:bool) reference.IsSummonable actor:ref`

SetSummonable - changes the Summonable flag on the actor
`(nothing) reference.SetSummonable flag:int actor:ref`

SetActorRespawns - changes the Respawn flag on the actor
`(nothing) reference.SetActorRespawns flag:int actor:ref`

SetFemale - changes the Female flag on the actor. Changes are saved but may not be immediately visible.
`(nothing) reference.SetFemale flag:int actor:ref`

SetLowLevelProcessing - turns low level processing on or off for the actor. Note that this sets the No Low Level Processing flag to the opposite of the passed value.
`(nothing) reference.SetLowLevelProcessing flag:int actor:ref`

SetPCLevelOffset - changes the PC Level Offset flag on the actor, and optionally specifies the minimum andmaximum levels. If minLevel or maxLevel is omitted or passed as -1, the existing value will be retained. Note that changes to the min/max levels are not saved in the savegame.
`(nothing) reference.SetPCLevelOffset flag:int minLevel:int maxLevel:int actor:ref`

GetNumPackages - returns the number of AI packages in the actor's package list
`(numPackages:int) reference.GetNumPackages actor:ref`

GetNthPackage - returns the Nth AI package in the NPC's package list, in the order in which they were added in the editor.
`(package:ref) reference.GetNthPackage whichPackage:short actor:ref`

GetSpellEffectiveness - returns the actor's spell effectiveness based on the armor he or she has equipped as a floating point value from 0 to 1.0. The return value is always 1.0 for creatures and NPCs other than the player. When calledon the player, this command returns the player's base spell effectiveness as calculated by the game plus any script modifier applied by ModPCSpellEffectiveness.
`(spellEffectiveness:float) reference.GetSpellEffectiveness`

CanCastPower - returns false if the calling actor has already used the specified greater power within the last 24 hours. This command does not check for the presence of the greater power in the actor's spellbook.
`(CanCast:bool) ref.CanCastPower spell:ref`

SetCanCastPower - indicates whether the calling actor can cast the specified greater power. Passing 1 allows the actor to cast the power even if he has already used it within the past 24 hours. Passing 0 disallows the actor from casting the spell for the next 24 hours, unless the actor has already cast the power, in which case the power will become usable as normal 24 hours after the last casting.
`(nothing) ref.SetCanCastPower spell:ref allowCasting:bool`

SetPowerTimer - sets the amount of time that must pass until the calling actor can cast the specified power. The time is a float representing the number of real-time seconds until the power becomes usable. When an actor uses a power, the game calculates the 24-hour timer as 3600 / TimeScale 24 where TimeScale is a global variable representing the number of game-time minutes which elapse per real-tme minute. The timer value passed to this function should similarly take TimeScale into account. Passing a value of zero or less will cause the power to become usable the very next frame.
`(nothing) ref.SetPowerTimer spell:ref timer:float`

GetUsedPowers - returns an Array containing information about all greater powers which the calling actor has used. This includes powers cast by the actor within the last 24 hours as well as any powers flagged as used by SetCanCastPower and SetPowerTimer. The return value is an Array of StringMaps:
GetUsedPowers[n]["power"] := ref ; the greater power
GetUsedPowers[n]["timer"] := float ; number of real-time seconds until the power becomes usable again
`(powers:Array) ref.GetUsedPowers`

HasSpell - returns whether the actor has the specified spell
`(hasSpell:bool) reference.HasSpell spell:ref`

RemoveBaseSpell - the game's RemoveSpell removes a spell from a base actor but must be called on a reference. This command does the same thing as RemoveSpell but takes a base object as an argument, returning 1 if the spell was removed.
`(bRemoved:bool) RemoveBaseSpell actor:ref`

GetLeveledSpells - returns an Array containing all of the leveled spells in the base actor's spell list.
`(spells:Array) reference.GetLeveledSpells actorBase:ref`

GetActorPackages - returns an Array containing the AI packages defined in the base actor's package list, in the order in which they are listed in the editor.
`(packages:Array) reference.GetActorPackages actorBase:ref`

GetCurrentPackage - returns the actor ref's currently executing package
`(package:ref) reference.GetCurrentPackage`

GetCurrentPackageProcedure - returns the name of the AI procedure currently being executed by the calling actor, or "NONE".
`(procedure:string) reference.GetCurrentPackageProcedure`

GetCurrentEditorPackage - returns the actor ref's executing non-dynamic package
`(package:ref) reference.GetCurrentEditorPackage`

EquipItem2 - duplicates the behavior of the vanilla `EquipItem` command, but also causes the object's `OnEquip` script block to run if one exists
`(nothing) ref.EquipItem2 item:ref lockEquip:bool`

EquipItem2NS - behaves identically to `EquipItem2`, but suppresses the UI message generated by that command
`(nothing) ref.EquipItem2NS item:ref lockEquip:bool`

GetSpecialAnims - returns an Array containing the filenames of any special animations for the actor. Animations for creatures, and those in the SpecialAnims folder for NPCs, can be toggled on and off in the actor's animation list in the editor.
`(anims:Array) reference.GetSpecialAnims actorBase:ref`

ToggleSpecialAnim - adds or removes an animation from the base actor's animation list. For creatures, the animations must appear in the creature's model folder; for NPCs they must be located in the Special Anims folder. Changes made using this command have no effect on the animations of reference's to the base actor which are currently in middle-high or high process.
`(bSucceeded:bool) reference.ToggleSpecialAnim animFileName:string toggleOn:bool actorBase:ref`

GetGroundSurfaceMaterial - returns the surface type that the actor ref is currently standing on. Returns -1 if the ref is not in middle-high or high process.
`(surfaceType:int) reference.GetGroundSurfaceMaterial`

### Actor Value Functions

Actor values are determined by several factors including the attributes defined for the base actor, several dynamic modifiers, and the effects of game settings. For a detailed description of how actor values are calculated see the wiki entry. OBSE provides commands to retrieve and modify the modifiers applied to an actor value, retrieve the actor value as defined for a base actor, and retrieve the maximum value of an actor value.

GetAVMod - returns one of the calling actor's modifiers for the specified actor value. The modifier is specified as a string: "script" refers to the script (or "offset") modifier applied by the script versions of ModAV and ForceAV; "max" refers to the modifier applied by magic effects like feather, drain, and fortify; and "damage" refers to that applied by effects like damage and restore, and by the console version of ModAV/ForceAV as well as ModAV2.
`(modifierValue:float) ref.GetAVMod actorValueName:string whichModifier:string`
`(modifierValue:float) ref.GetAVModC actorValueCode:int whichModifier:string`

SetAVMod - sets the value of one of the calling actor's modifiers for the specified actor value. The modifier is specified as a string: "script" refers to the script (or "offset") modifier applied by the script versions of ModAV and ForceAV; "max" refers to the modifier applied by magic effects like feather, drain, and fortify; and "damage" refers to that applied by effects like damage and restore, and by the console version of ModAV/ForceAV as well as ModAV2. To encourage compatibility between mods, prefer using ModAVMod over SetAVMod.
`(nothing) ref.SetAVMod actorValueName:string whichModifier:string amount:float`
`(nothing) ref.SetAVModC actorValueCode:int whichModifier:string amount:float`

ModAVMod - modifies the value of one of the calling actor's modifiers for the specified actor value by the specified amount. The modifier is specified as a string: "script" refers to the script (or "offset") modifier applied by the script versions of ModAV and ForceAV; "max" refers to the modifier applied by magic effects like feather, drain, and fortify; and "damage" refers to that applied by effects like damage and restore, and by the console version of ModAV/ForceAV as well as ModAV2.
`(nothing) ref.ModAVMod actorValueName:string whichModifier:string amount:float`
`(nothing) ref.ModAVModC actorValueCode:int whichModifier:string amount:float`

GetMaxAV - returns the maximum possible value of the specified actor value for the calling actor.
`(maxValue:float) ref.GetMaxAV actorValueName:string`
`(maxValue:float) ref.GetMaxAVC actorValueCode:int`

GetAVForBaseActor - returns the value of the specified actor value as defined for the base actor. If the second argument is omitted, the base object for the calling actor is used. Note that not all actor values are defined for base actors, in which case this command returns 0.
`(value:int) ref.GetAVForBaseActor actorValueName:string actorBase:ref`
`(value:int) ref.GetAVForBaseActorC actorValueCode:int actorBase:ref`

GetActorValueC - returns the actor value specified by the actor value code
`(actorValue:int) reference.GetActorValueC actorValueCode:int`
`(actorValue:int) reference.GetAVC actorValueCode:int`

ModActorValueC - modifies the actor value without changing the base value. Acts like a spell: a negative number reduces the value which can be restored and a positive value restores values without exceeding the maximum of the stat.
`(nothing) reference.ModActorValueC actorValueCode:int value:int`
`(nothing) reference.ModAVC actorValueCode:int value:int`

SetActorValueC - sets the actor value specified by the actor value code
`(nothing) reference.SetActorValueC actorValueCode:int value:int`
`(nothing) reference.SetAVC actorValueCode:int value:int`

ModActorValue2 - modifies the current value without changing the base value. Acts like a spell: a negative number reduces the value which can be restored and a positive value restores values without exceeding the maximum of the stat.
`(nothing) reference.ModActorValue2 actorValueName:string value:int`
`(nothing) reference.ModAV2 actorValueName:string value:int`

GetLuckModifiedSkill - the game applies a modifier to all skills based on an actor's luck attribute. This command takes an actual skill value and a luck attribute value and calculates the effective level of the skill after the luck modifier has been applied. The third parameter can be used to return an uncapped value - The result is capped at 100 by default.
`(modifiedSkill:int) GetLuckModifiedSkill skillLevel:int luck:int capped:bool`

GetAVSkillMasteryLevel - returns the current mastery level of an actor's skill. The mastery level is an integer from 0 (Novice) to 4 (Master).
`(masteryLevel:int) reference.GetAVSkillMasteryLevel skill:actorValue`

GetAVSkillMasteryLevelC - alternate version of GetAVSkillMasteryLevel taking an actor value for the skill.
`(masteryLevel:int) reference.GetAVSkillMasteryLevelC skillCode:int`

### Attacking

Types with this quality are used for attacks.

#### Values:

Attack Damage (long) - the base damage of the type; used in a forumla with the appropriate skill to determine damage actually done
Speed (float) - the speed factor of the type; used in a forumla to determine the rate of attack
Ignores Resistance (bool) - determines whether the type will ignore normal damage resistance.

#### Functions:

GetAttackDamage - returns the base attack damage
`(damage:int) reference.GetAttackDamage objectID:ref`

SetAttackDamage - sets the base attack damage
`(nothing) reference.SetAttackDamage nuDamage:int objectID:ref`

ModAttackDamage - modifies the base attack damage up or down
`(nothing) reference.ModAttackDamage modifyBy:float objectID:ref`

GetWeaponSpeed - returns the weapon speed
`(speed:float) reference.GetWeaponSpeed objectID:ref`

SetWeaponSpeed - sets the weapon speed
`(nothing) reference.SetWeaponSpeed nuSpeed:float obejctID:ref`

ModWeaponSpeed - modifies the weapon speed up or down
`(nothing) reference.ModWeaponSpeed modifyBy:float obejctID:ref`

GetIgnoresResistance - returns whether the object ignores normal damage resistance
`(ignores:bool) reference.GetIgnoresResistance objectID:ref`

SetIgnoresResistance - sets whether the object ignores normal damage resistance
`(nothing) reference.SetIgnoresResistance shouldIgnore:bool objectID:ref`

### Audible

Types with this quality have one or more sounds associated with them.

#### Values:

Open Sound (ref) - the sound played upon opening. (Containers and Doors)
Close Sound (ref) - the sound played upon closing. (Containers and Doors)
Loop Sound (ref) - the looping sound associated with an object. (Doors, Lights, and Activators)

#### Functions:

GetOpenSound - Returns the "open" sound
`(sound:ref) reference.GetOpenSound baseObject:ref`

GetCloseSound - Returns the "close" sound
`(sound:ref) reference.GetCloseSound baseObject:ref`

GetLoopSound - Returns the looping sound
`(sound:ref) reference.GetLoopSound baseObject:ref`

SetOpenSound - Sets the "open" sound
`(nothing) reference.SetOpenSound sound:ref baseObject:ref`

SetCloseSound - Sets the "close" sound
`(nothing) reference.SetCloseSound sound:ref baseObject:ref`

SetLoopSound - Sets the looping sound
`(nothing) reference.SetLoopSound sound:ref baseObject:ref`

### Breakable

Types with this quality can be broken.

#### Values:

Health (long) - the base health of the object. Cannot be negative.
Current Health (float) - the current health of the object. The object is damaged when the current value is less than the base object value and is broken when the current health reaches 0. The effectiveness of the object may be decreased as damage increases.

#### Functions:

GetObjectHealth - returns the base object health
`(health:int) reference.GetObjectHealth objectID:ref`

SetObjectHealth - sets the base object health
`(nothing) reference.SetObjectHealth nuHealth:int objectID:ref`

ModObjectHealth - modifies the base object health up or down
`(nothing) reference.ModObjectHealth modifyBy:float objectID:ref`

GetCurrentHealth - returns the current health of the calling reference
`(health:float) reference.GetCurrentHealth`

SetCurrentHealth - sets the current health of the calling reference
`(nothing) reference.SetCurrentHealth nuHealth:float`

GetEquippedCurrentHealth - gets the current health of the object in the specified equipment slot
`(health:float) reference.GetEquippedCurrentHealth slot:int`

SetEquippedCurrentHealth - sets the current health of the object in the specified equipment slot
`(nothing) reference.SetEquippedCurrentHealth nuHealth:int slot:int`

ModEquippedCurrentHealth - modifies the current health of the object in the specified equipment slot up or down
`(nothing) reference.ModEquippedCurrentHealth modifyBy:float slot:int`

### Class

Types with this quality have a player class.

#### Qualities:

Description

#### Values:

Attributes (short) - the two attributes of the class
Skills (short) - the five major skills of the class
Specialization (short) - the specialization of the class

#### Functions:

GetClass - returns the class of the NPC
`(class:ref) reference.GetClass npc:ref`

GetClassAttribute - returns the Nth attribute of the class. If called on a reference it will attempt to find the class from that referenced NPC and use that. If a class FormID is passed, that takes precedence.
`(attribute:int) reference.GetClassAttribute whichAttribute:int class:ref`

GetClassSkill - returns the Nth skill of the class. If called on a reference it will attempt to find the class from that referenced NPC and use that. If a class FormID is passed, that takes precedence.
`(skill:int) reference.GetClassSkill whichSkill:int class:ref`

GetClassSpecialization - returns the class specialization. If called on a reference it will attempt to find the class from that referenced NPC and use that. If a class FormID is passed, that takes precedence.
`(specialization:int) reference.GetClassSpecialization class:ref`

IsClassSkill - returns whether the passed skill is a skill of the class. If called on a reference it will attempt to find the class from that referenced NPC and use that. If a class FormID is passed, that takes precedence.
`(isClassSkill:bool) reference.IsClassSkill skill:string class:ref`
`(isClassSkill:bool) reference.IsMajor skill:string class:ref`

IsClassSkillC - alternate version of IsClassSkill taking a skill code instead of the name of a skill.
`(isClassSkill:bool) reference.IsClassSkillC skill:int class:ref`
`(isClassSkill:bool) reference.IsMajorC skill:int class:ref`

IsClassAttribute - returns whether the passed attribute is an attribute of the class. If called on a reference it will attempt to find the class from that referenced NPC and use that. If a class FormID is passed, that takes precedence. (available in v0011)
`(isClassAttribute:bool) reference.IsClassAttribute attribute:int class:ref`

IsClassAttributeC - alternate version of `IsClassAttribute` taking an actor value code instead of the name of an actor value
`(isClassAttribute:bool) reference.IsClassAttributeC actorValueCode:int class:ref`

GetClassSkills - returns an Array containing the seven major skills associated with the class. If the parameter is omitted, the class of the calling NPC is used.
`(skills:Array) reference.GetClassSkills class:ref`

SetClassSkills - accepts an Array of seven different skill codes and sets them as the class's major skills. If fewer or more than seven skills are found in the array or duplicate skills are found, the function will return zero with no changes made to the class. If the class argument is omitted, the calling NPC's class is used.
`(bSkillsSet:bool) reference.SetClassSkills skills:Array class:ref`

SetClassSkills2 - Identical to SetClassSkills, except it allows duplicate skills.
`(bSkillsSet:bool) reference.SetClassSkills2 skills:Array class:ref`

SetClassSpecialization - sets the class specialization. If the class argument is omitted thecalling NPC's class is used.
`(nothing) reference.SetClassSpecialization specialization:int class:ref`

SetClassAttribute - sets one of the two favored attributes for the class. Both class attributes must be unique. If the class argument is omitted the calling NPC's class is used.
`(bAttributeSet:bool) reference.SetClassAttribute which:int attribute:string class:ref`

SetClassAttributeC - as SetClassAttribute but takes an actor value code instead of an actor value string.
`(bAttributeSet:bool) reference.SetClassAttributeC which:int attribute:int class:ref`

### Container

Something that holds inventory items.

#### Functions:

GetNumItems - returns the number of different object types in the container
`(count:int) reference.GetNumItems`

GetInventoryObject - returns the objectID of the Nth item type in the container
`(objectID:ref) reference.GetInventoryObject whichObject:int`

IsContainer - returns whether the reference or passed objectID is a container
`(isContainer:bool) reference.IsContainer objectID:ref`

GetContainerRespawns - returns whether the container's contents repawn
`(respawns:bool) reference.GetContainerRespawns objectID:ref`
`(respawns:bool) reference.IsUnsafeRespawns objectID:ref`

SetContainerRespawns - sets whether the container's contents respawn. Note - this change is not persisted in the save game.
`(nothing) reference.SetContainerRespawns respawns:bool objectID:ref`
`(nothing) reference.SetUnsafeContainer respawns:bool objectID:ref`

GetItems - returns an Array containing all of the items in a container's or actor's inventory. Up to 10 form types may be passed in to restrict the returned items to only include items matching those type(s).
`(items:Array) reference.GetItems type1:int type2:int ... type10:int`

GetBaseItems - returns an Array of StringMaps containing the items present in a base container or actor inventory and the quantity of each. These are the items added to the base object in the editor and may include leveled items. Some, all, or none of the items may be present in the inventory of a specific reference to the base object. Each element of the returned Array is a StringMap with two elements:
"item" : ref ; the item
"count" : short ; the quantity of this item
`(items:Array) reference.GetBaseItems baseContainer:ref`

Values are accessed like:

    	array_var baseItems
    	let baseItems := someChestRef.GetBaseItems
    	Print "First item: " + (GetName baseItems[0][item] + " Quantity: " + ToString baseItems[0][count]

### Description

Types with this quality have descriptive text and include objects like books, skills, races, classes, and effect settings. Skills are unique in possessing five descriptions: one describing the skill and four associated with the text displayed when attaining a new rank in the skill.

#### Values:

Description (string) - the text of the description

#### Functions:

GetDescription - returns the text of the description for the object. In the case of skills, an optional second parameter indicates the skill rank (0-3); if omitted, the skill's general description is returned.
`(description:string) ref.GetDescription object:ref skillrank:int`

SetDescription - modifies the text of a TESDescription (e.g. book, class, skill, skill level, etc). The modified description will be used for the remainder of the game session. To modify the text displayed when achieving a new level of mastery (Apprentice, Journeyman, etc) in a skill, pass the skill as the second argument and a skill level as the third, where skill level ranges from 0 (Apprentice) to 3 (Master)
`(success:bool) reference.SetDescription description:string form:ref skillLevel:int`

### Edible

Types with this quality may be considered food.

#### Values:

Is Food flag (bool) - is the object considered to be food

#### Functions:

IsFood - returns whether the object is considered to be food
`(isFood:bool) reference.IsFood objectID:ref`

SetIsFood - sets whether the object is considered to be food
`(nothing) reference.SetIsFood isFood:bool objectID:ref`

### Enchantable

Types with this quality may be enchanted. A couple notes: Enchantments and the ranges of their effects need to be appropriate for the enchantable object's type. The Enchantment Type needs to match the object the enchantment applies to. Also, when adding an enchantment to an object, be sure that the object has a charge, or the enchantment cannot work. If the object was not previously enchanted, call SetObjectCharge to assign a charge to the object.

#### Values:

Enchantment (ref) - the specific enchantment on the enchantable item
Charge (long) - the maximum charge available on the enchantable item
Current Charge (float) - the current charge of the enchantable item

#### Functions:

GetEnchantment - returns the specific enchantment on the object
`(enchantment:ref) reference.GetEnchantment objectID:ref`

SetEnchantment - sets the specific enchantment on the object and returns any previous enchantment
`(oldEnchantment:ref) reference.SetEnchantment nuEnchantment:ref objectID:ref`

RemoveEnchantment - removes the enchantment from the object and returns any previous enchantment
`(oldEnchantment:ref) reference.RemoveEnchantment objectID:ref`

GetObjectCharge - returns the max charge of the object
`(charge:int) reference.GetObjectCharge objectID:ref`

SetObjectCharge - sets the max charge of the object
`(nothing) reference.SetObjectCharge nuCharge:int objectID:ref`

ModObjectCharge - modifies the max charge of the object up or down
`(nothing) reference.ModObjectCharge modifyBy:float objectID:ref`

GetCurrentCharge - returns the current charge of the calling reference
`(charge:float) reference.GetCurrentCharge`

GetEquippedCurrentCharge - returns the current charge of the object in the specified slot
`(charge:float) reference.GetEquippedCurrentCharge slot:int`

SetEquippedCurrentCharge - sets the current charge of the object in the specified slot
`(nothing) reference.SetEquippedCurrentCharge nuCharge:int slot:int`

ModEquippedCurrentCharge - modifies the current charge of the object in the specified slot up or down
`(nothing) reference.ModEquippedCurrentCharge modifyBy:float slot:int`

SetCurrentCharge - sets the current charge of the calling reference if it is less than or equal to the maximum charge
`(nothing) reference.SetCurrentCharge newCharge:int`

ModCurrentCharge - modifies the current charge of the calling reference by the specified amount. Will not modify the charge past its maximum or below zero.
`(nothing) reference.ModCurrentCharge modBy:int`

### Equippable

Types with this quality can be equipped by a character.

#### Values:

Slot (short) - the equipment slot of the object

#### Functions:

GetEquipmentSlot - returns the equipment slot or slots taken by the object
`(slot:int) reference.GetEquipentSlot objectID:ref`

SetEquipmentSlot - sets the equipment slot or slots taken by the object.
`(nothing) reference.SetEquipmentSlot slot:int objectID:ref`

See also: GetEquippedObject

EquipMe - when called on an object in an actor's inventory, attempts to equip the object on the actor and runs the object's `OnEquip` script block if applicable. If called on an inventory reference with a count greater than one, equips only one unless the item is a stack of arrows, in which case the entire stack is equipped.
`(nothing) ref.EquipMe`

UnequipMe - when called on an object in an actor's inventory, attempts to unequip the object on the actor and runs the object's `OnUnequip` script block if applicable
`(nothing) ref.UnequipMe`

### Inventory

Types with this quality are objects that can be either stored in an inventory or exist as a reference outside of an inventory.

#### Values:

Object (long) - the base object id of a reference
Weapon Type (short) - the type of weapon
Weight (float) - the weight of one object of this type
Gold Value (long) - the gold value of one object of this type. This value may not match the value displayed in the interface as that could include additional value from an enchantment.
Is Quest Item (bool) - whether the type is a quest item. Quest items cannot be activated and cannot be dropped.

#### Functions:

GetBaseObject - returns the base object of the reference
`(objectID:ref) reference.GetBaseObject`

GetObjectType - returns a type code for each type of object
`(type:int) reference.GetObjectType objectID:ref`

IsWeapon - returns whether the object is a weapon
`(isWeapon:bool) reference.IsWeapon objectID:ref`

IsAmmo - returns whether the object is ammunition
`(isAmmo:bool) reference.IsAmmo objectID:ref`

IsArmor - returns whether the object is armor
`(isArmor:bool) reference.IsArmor objectID:ref`

IsBook - returns whether the object is a book
`(isBook:bool) reference.IsBook objectID:ref`

IsClothing - returns whether the object is clothing
`(isClothing:bool) reference.IsClothing objectID:ref`

IsIngredient - returns whether the object is an ingredient
`(isIngredient:bool) reference.IsIngredient objectID:ref`

IsKey - returns whether the object is a key
`(isKey:bool) reference.IsKey objectID:ref`

IsAlchemyItem - returns whether the object is an alchemy item (potion)
`(isAlchemyItem:bool) reference.IsAlchemyItem objectID:ref`
`(isPotion:bool) reference.IsPotion objectID:ref`

IsApparatus - returns whether the object is an alchemy apparatus
`(isApparatus:bool) reference.IsApparatus objectID:ref`

IsSoulGem - returns whether the object is a soul gem
`(isSoulGem:bool) reference.IsSoulGem objectID:ref`

IsSigilStone - returns whether the object is a sigil stone
`(isSigilStone:bool) reference.IsSigilStone objectID:ref`

IsLight - returns whether the object is a light source
`(isLight:bool) reference.IsLight objectID:ref`

IsFlora - returns 1 if the object is a harvestable plant.
`(isFlora:bool) reference.IsFlora objectID:ref`

GetWeight - returns the weight of the type
`(weight:float) reference.GetWeight objectID:ref`

SetWeight - sets the weight of the type
`(nothing) reference.SetWeight nuWeight:float objectID:ref`

ModWeight - modifies the weight of the type up or down
`(nothing) reference.ModWeight modifyBy:float objectID:ref`

GetGoldValue - returns the base gold value of the type
`(goldValue:int) reference.GetGoldValue objectID:ref`

GetFullGoldValue - returns the full gold value of an item, including the value added by enchantments.
`(goldValue:int) reference.GetFullGoldValue objectID:ref`

SetGoldValue - sets the base gold value of the type
`(nothing) reference.SetGoldValue nuGoldValue:int objectID:ref`

ModGoldValue - modifies the base gold value of the type up or down
`(nothing) reference.ModGoldValue modifyBy:float objectID:ref`

IsQuestItem - returns whether the type is a quest item
`(isQuestItem:bool) reference.IsQuestItem objectID:ref`

SetQuestItem - sets whether the type is a quest item
`(nothing) reference.SetQuestItem isQuestItem:bool objectID:ref`

SetCurrentSoulLevel - sets the current soul level of the calling soulgem reference.
`(nothing) reference.SetCurrentSoulLevel newLevel:int`

### Lockable

Types with this quality can be locked.

#### Functions:

GetOpenKey - returns the key used to unlock the calling reference.
`(key:ref) reference.GetOpenKey`

SetOpenKey - sets the key used to unlock the reference to the specified key.
`(nothing) reference.SetOpenKey key:ref`

### Magic

Types with this quality have a group of magical effects

#### Values:

Magic Item Type (short) - the type of magic item (Spell, Enchantment, AlchemyItem, Ingredient)
Effect Count (long) - the number of magic effect items in the type
IsAutocalc (bool) - whether the cost is autocalculated or set to a specific amount
EffectItem Code (long) - the magic effect code for the effect item
EffectItem Magnitude (long) - the magnitude of the magic effect item
EffectItem Area (long) - the area affected by the magic effect item
EffectItem Duration long - the time in seconds the magic effect lasts
EffectItem Range (short) - the range of the effect (Self, Touch, Target)
EffectItem Actor Value (long) - a code for the attribute or skill affected by the effect item
EffectItemScripted (bool) - whether the effect item is a ScriptEffect (SEFF)
EffectItemScript (refID) - the refID of the script used by the scripted effect item
EffectItemScriptVisualEffect (long) - the magic effect code used for the visual effects of the scripted effect item
EffectItemScriptSchool (short) - the magic school assigned to the scripted effect
EffectItemScriptIsHostile (bool) - whether the scripted effect is hostile

#### Functions:

GetMagicItemType - returns the magic item type.
`(magicItemType:int) GetMagicItemType magicItem:ref`
`(magicItemType:int) GetMIType magicItem:ref`

GetMagicItemEffectCount - returns the number of magic effect items.
`(count:int) GetMagicItemEffectCount magicItem:ref`
`(count:int) GetMIEffectCount magicItem:ref`

MagicItemHasEffect - returns whether the magic item has an effect item with the specifed effect. Uses the 4 letter codes for the magic effects listed in the CS. Uses an optional actor value name for use with effects like fortify skill and fortify attribute.
`(hasEffect:bool) MagicItemHasEffect effect:chars magicItem:ref actorValue:chars`
`(hasEffect:bool) MagicHasEffect effect:chars magicItem:ref actorValue:chars`

MagicItemHasEffectCode - returns whether the magic item has an effect item with the specified effect code. Uses a long value returned from GetNthEffectItemCode or GetMagicEffectCode. Uses an optional actor value code for use with effects like fortify skill and fortify attribute.
`(hasEffect:bool) MagicItemHasEffectCode effectCode:int magicItem:ref actorValueCode:int`
`(hasEffect:bool) MagicHasEffectC effectCode:int magicItem:ref actorValueCode:int`

MagicItemHasEffectCount - returns the count of the specified effects on the magic item. Has an optional actorValue name for use with effects like fortify skill and fortify attribute.
`(effectCount:int) MagicItemHasEffectCount effect:chars magicItem:ref actorValueName:chars`

MagicItemHasEffectCountCode - returns the count of effects with the specified effect code on the magic item. Uses a long value returned from GetNthEffectItemCode or GetMagicEffectCode. Has an optional actorValueCode for use with effects like fortify skill and fortify attribute.
`(effectCount:int) MagicItemHasEffectCountCode effectCode:int magicItem:ref actorValueCode:int`
`(effectCount:int) MagicItemHasEffectCountC effectCode:int magicItem:ref actorValueCode:int`

GetNthEffectItemCode - returns the magic effect code of the specified effect item.
`(code:int) GetNthEffectItemCode magicItem:ref whichEffect:int`
`(code:int) GetNthEICode magicItem:ref whichEffect:int`

GetNthEffectItemMagnitude - returns the magnitude of the specified effect item.
`(magnitude:int) GetNthEffectItemMagnitude magicItem:ref whichEffect:int`
`(magnitude:int) GetNthEIMagnitude magicItem:ref whichEffect:int`

SetNthEffectItemMagnitude - sets the magnitude of the specified effect item.
`(nothing) SetNthEffectItemMagnitude nuMagnitude:int magicItem:ref whichEffect:int`
`(nothing) SetNthEIMagnitude nuMagnitude:int magicItem:ref whichEffect:int`

ModNthEffectItemMagnitude - modifies the magnitude of the specified effect item up or down.
`(nothing) ModNthEffectItemMagnitude modifyBy:float magicItem:ref whichEffect:int`
`(nothing) ModNthEIMagnitude modifyBy:float magicItem:ref whichEffect:int`

GetNthEffectItemArea - returns the area of the specified effect item.
`(area:int) GetNthEffectItemArea magicItem:ref whichEffect:int`
`(area:int) GetNthEIArea magicItem:ref whichEffect:int`

SetNthEffectItemArea - sets the area of the specified effect item.
`(nothing) SetNthEffectItemArea nuArea:int magicItem:ref whichEffect:int`
`(nothing) SetNthEIArea nuArea:int magicItem:ref whichEffect:int`

ModNthEffectItemArea - modifies the effect area of the specified effect item up or down.
`(nothing) ModNthEffectItemArea modifyBy:float magicItem:ref whichEffect:int`
`(nothing) ModNthEIArea modifyBy:float magicItem:ref whichEffect:int`

GetNthEffectItemDuration - returns the duration of the specified effect item.
`(duration:int) GetNthEffectItemDuration magicItem:ref whichEffect:int`
`(duration:int) GetNthEIDuration magicItem:ref whichEffect:int`

SetNthEffectItemDuration - sets the duration of the specified effect item.
`(nothing) SetNthEffectItemDuration nuDuration:int magicItem:ref whichEffect:int`
`(nothing) SetNthEIDuration nuDuration:int magicItem:ref whichEffect:int`

ModNthEffectItemDuration - modifies the duration of the specified effect item up or down.
`(nothing) ModNthEffectItemDuration modifyBy:float magicItem:ref whichEffect:int`
`(nothing) ModNthEIDuration modifyBy:float magicItem:ref whichEffect:int`

GetNthEffectItemRange - gets the range of the specified effect item.
`(range:int) GetNthEffectItemrange magicItem:ref whichEffect:int`
`(range:int) GetNthEIRange magicItem:ref whichEffect:int`

SetNthEffectItemRange - sets the range of the specified effect item.
`(nothing) SetNthEffectItemRange nuRange:int magicItem:ref whichEffect:int`
`(nothing) SetNthEIRange nuRange:int magicItem:ref whichEffect:int`

GetNthEffectItemActorValue - gets the actor value of the specified effect item.
`(actorValueCode:int) GetNthEffectItemActorValue magicItem:ref whichEffect:int`
`(actorValueCode:int) GetNthEIAV magicItem:ref whichEffect:int`

SetNthEffectItemActorValue - sets the actor value of the specified effect item.
`(nothing) SetNthEffectItemActorValue actorValue:string magicItem:ref whichEffect:int`
`(nothing) SetNthEIAV actorValue:string magicItem:ref whichEffect:int`

SetNthEffectItemActorValueC - sets the actor value of the specified effect item.
`(nothing) SetNthEffectItemActorValueC nuActorValue:int magicItem:ref whichEffect:int`
`(nothing) SetNthEIAVC nuActorValue:int magicItem:ref whichEffect:int`

RemoveNthEffectItem - removesthe specified effect item.
`(nothing) RemoveNthEffectItem magicItem:ref whichEffect:int`
`(nothing) RemoveNthEffect magicItem:ref whichEffect:int`

RemoveAllEffectItems - removes all effect items from the magic item.
`(nothing) RemoveAllEffectItems magicItem:ref`

CopyNthEffectItem - copies the specified effect item from one magic item to another.
`(index:int) CopyNthEffectItem fromObjectID:ref toObjectID:ref whichEffect:int`

CopyAllEffectItems - copies all effect items from one magic item to another.
`(nothing) CopyAllEffectItems fromObjectID:ref toObjectId:ref`

AddEffectItem - adds a basic, empty EffectItem of the specified MagicEffect to the magic item.
`(index:int) AddEffectItem nuEffect:chars magicItem:ref`
`(index:int) AddEffectItemC nuEffectCode:int magicItem:ref`

AddFullEffectItem - adds a fully defined EffectItem to the magic item with the specified MagicEffect, magnitude, area, duration and range.
`(index:int) AddFullEffectItem nuEffect:chars magnitude:int area:int duration:int range:int magicItem:ref`
`(index:int) AddFullEffectItemC nuEffectCode:int magnitude:int area:int duration:int range:int magicItem:ref`

IsMagicItemAutoCalc - returns 1 if the MagicItem determines magicka cost by autocalculation. Now works on all Magic Items (spells, alchemy, ingredients, enchantments).
`(isAutocalc:bool) IsMagicItemAutoCalc magicItem:ref`

SetMagicItemAutoCalc - sets whether the Magic Item determines cost by autocalculation. Currently works for Spells, AlchemyItems, Ingredients and Enchantments.
`(nothing) SetMagicItemAutoCalc isAutocalc:bool objectID:ref`

IsNthEffectItemScripted - returns whether the specified effect item is scripted.
`(isScriptEffect:bool) IsNthEffectItemScripted magicItem:ref whichEffect:int`

GetNthEffectItemScript - returns the refID of the script associated with the specified scripted effect.
`(script:ref) GetNthEffectItemScript objectID:ref whichEffect:int`
`(script:ref) GetNthEIScript objectID:ref whichEffect:int`

SetNthEffectItemScript - sets the script for the specified scripted effect item. Note that the CS doesn't have a variable type for a script, so you must assign the script editor id to a ref variable to use this function.
`(nothing) SetNthEffectItemScript scriptObjectID:ref magicItem:ref whichEffect:int`
`(nothing) SetNthEIScript scriptObjectID:ref magicItem:ref whichEffect:int`

GetNthEffectItemScriptVisualEffect - returns the magic effect code for the scripted effect item's visual effect.
`(magicEffectCode:int) GetNthEffectItemScriptVisualEffect magicItem:ref whichEffect:int`
`(magicEffectCode:int) GetNthEISVisualEffect magicItem:ref whichEffect:int`

SetNthEffectItemScriptVisualEffect - sets the scrited effect item's visual effect.
`(nothing) SetNthEffectItemScriptVisualEffect magicEffect:chars magicItem:ref whichEffect:int`
`(nothing) SetNthEISVisualEffect magicEffect:chars magicItem:ref whichEffect:int`
`(nothing) SetNthEffectItemScriptVisualEffectC magicEffectCode:int magicItem:ref whichEffect:int`
`(nothing) SetNthEISVisualEffectC magicEffectCode:int magicItem:ref whichEffect:int`

GetNthEffectItemScriptSchool - returns the school of the scripted effect item.
`(magicSchool:int) GetNthEffectItemScriptSchool magicItem:ref whichEffect:int`
`(magicSchool:int) GetNthEISSchool magicItem:ref whichEffect:int`

SetNthEffectItemScriptSchool - sets the school of the scripted effect item.
`(nothing) SetNthEffectItemScriptSchool magicSchool:int magicItem:ref whichEffect:int`
`(nothing) SetNthEISSchool magicSchool:int magicItem:ref whichEffect:int`

IsNthEffectItemScriptHostile - returns whether the scripted effect is hostile.
`(isHostile:bool) IsNthEffectItemScriptHostile magicItem:ref whichEffect:int`
`(isHostile:bool) IsNthEISHostile magicItem:ref whichEffect:int`

SetNthEffectItemScriptHostile - sets whether the scripted effect is hostile.
`(nothing) SetNthEffectItemScriptHostile isHostile:bool magicItem:ref whichEffect:int`
`(nothing) SetNthEISHostile isHostile:bool magicItem:ref whichEffect:int`

GetNthEffectItemScriptName - returns the name of the nth effect item, provided that effect item is a script effect.
`(name:string_var) GetNthEffectItemScriptName magicItem:ref whichEffect:int`

SetNthEffectItemScriptName - sets the name of the scripted effect.
`(nothing) SetNthEffectItemScriptName name:string magicItem:ref whichEffect:int`
`(nothing) SetNthEISName name:string magicItem:ref whichEffect:int`

SetNthEffectItemScriptNameEX - sets the name of the scripted effect.
`(nothing)SetNthEffectItemScriptNameEX name:formatString magicItem:ref whichEffect:int`

ModNthEffectItemScriptName - modifies the name of the scripted effect. The `toReplaceAndReplaceWith` string has the following format: "`toReplace|replaceWith`". We will do a case insensitve search for the `toReplace` portion and if found will replace it with the `replaceWith` portion. The `|` character is used to separate the portions of the string. If there is nothing before the `|` character, the `replaceWith` string is prepended to the name. If called from the console, use `@` instead of `|`.
`(nothing) ModNthEffectItemScriptName toReplaceAndReplaceWith:string magicItem:ref whichEffect:int`
`(nothing) ModNthEISName toReplaceAndReplaceWith:string magicItem:ref whichEffect:int`

MagicItemHasEffectItemScript - returns 1 if the magic effect has a scripted item with the specified script.
`(hasScript:bool) MagicItemHasEffectItemScript script:ref magicItem:ref`

GetNthEffectItemName - returns the name of the specified active effect, i.e. "Fortify Strength".
`(name:string_var) GetNthEffectItemName magicItem:ref whichEffect:int`
`(name:string_var) GetNthEIName magicItem:ref whichEffect:int`

GetNthEffectItem - returns a StringMap fully describing the specified effect item. The StringMap has the following key-value pairs:

    		(numeric) effectCode, area, magnitude, duration, range, cost
    		(string) name
    		(numeric) actorValue - an actor value code, if applicable to the effect
    		(StringMap) SEFF - for script effects, additional data about the effect:
    			(numeric) school, visualEffectCode - "school" is a magic skill actor value code
    			(ref) script
    			(bool) hostile

`(effectItem:StringMap) GetNthEffectItem whichEffect:int`

### Magic Target

Types with this quality can be the target of magic. They can have Active Effects working on them.

#### Values:

Count (long) - the number of active effects on the target
ActiveEffect Code (long) - the effect code of the given ActiveEffect
ActiveEffect Magnitude (long) - the magnitude of the given ActiveEffect
ActiveEffect Duration (float) - the duration of the total ActiveEffect
ActiveEffect TimeElapsed (float) - the time in seconds since the ActiveEffect was applied to the target
ActiveEffect MagicItem (ref) - the magic item which applied the ActiveEffect
ActiveEffect Caster (ref) - the caster of the ActiveEffect
ActiveEffect Data (ref) - the extra data (summoned creature, armor, etc.) of the ActiveEffect
ActiveEffect MagicItemIndex (long) - the index of the EffectItem on the magic item which applied the ActiveEffect

#### Functions:

GetActiveEffectCount - returns the number of ActiveEffects on the target
`(count:int) reference.GetActiveEffectCount`

GetNthActiveEffectCode - returns the effect of the Nth ActiveEffect on the target
`(effectCode:int) reference.GetNthActiveEffectCode whichEffect:int`
`(effectCode:int) reference.GetNthAECode whichEffect:int`

GetNthActiveEffectMagnitude - returns the magnitude of the Nth ActiveEffect on the target
`(magnitude:int) reference.GetNthActiveEffectMagnitude whichEffect:int`
`(magnitude:int) reference.GetNthAEMagnitude whichEffect:int`

GetNthActiveEffectDuration - returns the total duration of the Nth ActiveEffect on the target
`(duration:float) reference.GetNthActiveEffectDuration whichEffect:int`
`(duration:float) reference.GetNthAEDuration whichEffect:int`

GetNthActiveEffectTimeElapsed - returns the time that the Nth ActiveEffect has been applied to the target
`(timeElapsed:float) reference.GetNthActiveEffectTimeElapsed whichEffect:int`
`(timeElapsed:float) reference.GetNthAETime whichEffect:int`

GetNthActiveEffectMagicItem - returns the magic item which applied theNth ActiveEffect to the target
`(magicItem:ref) reference.GetNthActiveEffectMagicItem whichEffect:int`
`(magicItem:ref) reference.GetNthAEMagicItem whichEffect:int`

GetNthActiveEffectCaster - return the caster of the Nth ActiveEffect on the target
`(caster:ref) reference.GetNthActiveEffectCaster whichEffect:int`
`(caster:ref) reference.GetNthAECaster whichEffect:int`

GetNthActiveEffectData - return the data of the NthActiveEffect on the target
`(data:ref) reference.GetNthActiveEffectData whichEffect:int`
`(data:ref) reference.GetNthAEData whichEffect:int`

GetNthActiveEffectMagicItemIndex - returns the index on its magic item of the Nth ActiveEffect on the target
`(index:int) reference.GetNthActiveEffectMagicItemIndex whichEffect:int`
`(index:int) reference.GetNthAEIndex whichEffect:int`

GetNthActiveEffectEnchantObject - returns the equipped enchanted object, if any, responsible for the specified active effect
`(object:ref) reference.GetNthActiveEffectMagicEnchantObject whichEffect:int`
`(object:ref) reference.GetNthAEMagicEnchantObject whichEffect:int`

SetNthActiveEffectMagnitude - sets the magnitude of the corresponding ActiveEffect
`(nothing) SetNthActiveEffectMagnitude magnitude:float whichEffect:int`
`(nothing) SetNthAEMagnitude magnitude:float whichEffect:int`

ModNthActiveEffectMagnitude - modifies the magnitude of the corresponding ActiveEffect
`(nothing) ModNthActiveEffectMagnitude magnitude:float whichEffect:int`
`(nothing) ModNthAEMagnitude magnitude:float whichEffect:int`

GetTotalActiveEffectMagnitude - returns the total magnitude of all ActiveEffects with a given code on the target
`(totalMag:int) reference.GetTotalActiveEffectMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEMagnitude effectCode:chars actorValue:chars` ignoreUnappliedEffects:bool
`(totalMag:int) reference.GetTotalActiveEffectMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAENonAbilityMagnitude - returns the total magnitude of all non-ability ActiveEffects with a given code on the target
`(totalMag:int) reference.GetTotalAENonAbilityMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAENonAbilityMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAEAbilityMagnitude - returns the total magnitude of all ability ActiveEffects with a given code on the target
`(totalMag:int) reference.GetTotalAEAbilityMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEAbilityMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAESpellMagnitude - returns the total magniude of all spell ActiveEffects with a given code on the target
`(totalMag:int) reference.GetTotalAESpellMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAESpellMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAEDiseaseMagnitude - returns the total magnitude of all disease ActiveEffects with a given code on the target.
`(totalMag:int) reference.GetTotalAEDiseaseMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEDiseaseMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAELesserPowerMagnitude - returns the total magnitude of all lesser power ActiveEffects with a given code on the target
`(totalMag:int) reference.GetTotalAELesserPowerMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAELesserPowerMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAEPowerMagnitude - retuns the total magnidue of all greater power ActiveEffects with a given code on the target
`(totalMag:int) reference.GetTotalAEPowerMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEPowerMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAEAllSpellsMagnitude - returns the total magnitude of all spells (Spell, Ability, Disease, Lesser Power, Power) with a given code on the target.
`(totalMag:int) reference.GetTotalAEAllSpellsMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEAllSpellsMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAEEnchantmentMagnitude - retuns the total magnitude of all enchantments with a given code on the target.
`(totalMag:int) reference.GetTotalAEEnchantmentMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEEnchantmentMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetTotalAEAlchemyMagnitude - returns the total magnitude of all potions with a given code on the target.
`(totalMag:int) reference.GetTotalAEAlchemyMagnitude effectCode:chars actorValue:chars ignoreUnappliedEffects:bool`
`(totalMag:int) reference.GetTotalAEAlchemyMagnitudeC effectCode:int actorValueCode:int ignoreUnappliedEffects:bool`

GetScriptActiveEffectIndex - returns the index of the corresponding ActiveEffect for the running script effect. Prior to OBSE 0019, this command returned 0 if the script effect could not be found, and could not distinguish between multiple instances of the same script effect. As of 0019, the command returns -1 on failure, and otherwise returns the index corresponding to the unique active effect associated with the calling script.
`(index:int) GetScriptActiveEffectIndex`

DispelNthActiveEffect - dispels the effects of the specified active effect and removes it from the actor's active effect list. Note that the effect will not be removed until the next gamemode frame, so the indexes into an actor's effect list do not change immediately.
`(effectWasRemoved:bool) reference.DispelNthActiveEffect whichEffect:int`
`(effectWasRemoved:bool) reference.DispelNthAE whichEffect:int`

GetActiveEffectCodes - returns an Array containing the effect code of each of the calling actor's active effects, in the order in which they appear in his active effect list. An effect code's index in the returned Array can therefore be passed to the Get/SetNthActiveEffectXXX functions to operate on its associated active effect.
`(codes:Array) reference.GetActiveEffectCodes`

GetActiveEffectCasters - returns an Array containing the casters of each of the calling actor's active effects, in the order in which they appear in his active effect list. A caster's index in the returned Array can therefore be passed to the Get/SetNthActiveEffectXXX functions to operate on its associated active effect. If an active effect has no caster its associated value will be zero.
`(casters:Array) reference.GetActiveEffectCasters`

GetNthActiveEffectSummonRef - returns a reference to the creature associated with the specified Summon Creature active effect
`(creature:ref) reference.GetNthActiveEffectSummonRef whichEffect:int`
`(creature:ref) reference.GetNthAESummonRef whichEffect:int`

GetNthActiveEffectBoundItem - returns the base object associated with the specified Bound Item active effect
`(object:ref) reference.GetNthActiveEffectBoundItem whichEffect:int`
`(object:ref) reference.GetNthAEBoundItem whichEffect:int`

IsNthActiveEffectApplied - returns 1 if the active effect at the specified index is currently applied to the target. An active effect may exist on the target before its effects are applied (typically for one frame after a spell is cast), in which case this command would return zero.
`(isApplied:bool) reference.IsNthActiveEffectApplied whichEffect:short`

GetNthActiveEffectActorValue - returns the actor value associated with the active effect, if any.
`(actorValueCode:int) reference.GetNthActiveEffectActorValue whichEffect:int`
`(actorValueCode:int) reference.GetNthAEAV whichEffect:int`

### Named

Types with this quality have a setable name

#### Values:

Name (string) - the display name of the type

#### Functions:

SetName - sets the display name of the type. SetName is a special function. It is defined to work on Inventory items, but it can be used with any form. To use with a non-Inventory item you must first assign the objectID to a ref. For most forms the name is part of the base form and changing the name will change it for all instances of the type.
`(nothing) reference.SetName name:string objectID:ref`

GetName - returns the name of an object.
`(name:string_var) reference.GetName object:ref`

CompareName - returns 1 if stringToFindInName is found in the name of the object
`(nameContainsString) reference.CompareName toFindInName:string objectID:ref`
`(nameContainsString) reference.NameIncludes toFindInName:string objectID:ref`

CompareNames - compares the names of two objects and returns -1 if the first occurs alphabetically before the second, 1 if the first occurs after the second, or 0 for equality. Comparison is case-insensitive.
`(comparison:int) reference.CompareNames compareTo:ref compare:ref`

CopyName - copies the name from the source to the target. It is defined to work on Inventory items, but it can be used with any form. To use with a non-Inventory item you must first assign the objectID to a ref. For most forms the name is part of the base form and changing the name will change it for all instances of the type.
`(nothing) CopyName srcObjectID:ref targetObjectID:ref`

ModName - modifies the name of the calling reference or passed objectID. The toReplaceAndReplaceWith string has the following format: "toReplace|replaceWith". We will do a case insensitve search for the toReplace portion and if found will replace it with the replaceWith portion. The | character is used to separate the portions of the string. If there is nothing before the | character, the replaceWith string is prepended to the name. In the console, use @ instead of |.
`(nothing) reference.ModName toReplaceAndReplaceWith:string toObject:ref`

AppendToName - appends the passed string to the end of the name of the calling reference or passed objectID.
`(nothing) reference.AppendToName toAppend:string toObject:ref`

HasName - returns 1 if the object has a id consisting of at least one character.
`(hasName:bool) reference.HasName objectID:ref`

SetNameEx - sets the name of the base object. The new name is a string constructed from a format string using the same format specifiers used by OBSE's output functions.
`(nothing) reference.SetNameEx formatString:string var1 var2 ... var20 object:ref`

### Ownable

Types with this quality can be owned by an NPC or faction.

#### Values:

Owner (ref) - NPC or faction owner of the reference.
Required Rank (short) - the rank a member of the owning faction must hold in order to legally activate the reference.
Global Variable (global) - a global variable which, when set to a value other than zero, allows legal activation of the reference.

#### Functions:

GetOwner - returns the NPC or faction which owns the calling reference.
`(owner:ref) reference.GetOwner`

GetParentCellOwner - returns the NPC or faction which owns the calling reference's parent cell.
`(owner:ref) reference.GetParentCellOwner`

GetOwningFactionRequiredRank - returns the rank in the owning faction required to legally activate the calling reference.
`(rank:int) reference.GetOwningFactionRequiredRank`
`(rank:int) reference.GetOwningFactionRank`

GetParentCellOwningFactionRequiredRank - returns the rank required for ownership of the calling reference's parent cell.
`(rank:int) reference.GetParentCellOwningFactionRequiredRank`
`(rank:int) reference.GetCellFactionRank`

IsOffLimits - returns 1 if it is illegal for the specified actor to activate the calling reference, based on the calling reference's ownership. If the argument is omitted, the player is used by default.
`(isOffLimits:bool) reference.IsOffLimits actor:ref`

### Race

Types with this quality have a race.

#### Additional Qualities:

Description, Named

#### Values:

Base Attribute (short) - each sex of a race has base values for all eight attributes
Bonus Skill (bool) - each race has seven attributes which get a bonus
Reactions (long) - reaction values towards other races
Scale (float) - the relative scale factor of the males and females of the race

#### Functions:

GetRaceAttribute - returns the specified base attribute value. If passed a raceFormID you must also pass whether you want the female value or not. If called directly on a reference the function will determine the race and sex of the reference and the raceFormID and isFemale are not needed. The C version of the function takes a number rather than the actorvalue name (ie. 0 instead of Strength).
`(value:int) reference.GetRaceAttribute attributeActorValue:chars raceFormID:ref isFemale:bool`
`(value:int) reference.GetRaceAttributeC attributeActorValueCode:int raceFormID:ref isFemale:bool`

GetRaceSkillBonus - returns the bonus for the specified skill for the race. If called on a reference the function will determine the race of the reference. Returns 0 if there is no bonus for that skill. The C version specifies the specific skill by number rather than by name.
`(value:int) reference.GetRaceSkillBonus skillActorValue:chars raceFormID:ref`
`(value:int) reference.GetRaceSkillBonusC skillActorValueCode:int raceFormID:ref`

IsRaceBonusSkill - returns whether the specified skill is a bonus for the race. If called on a reference the function will determine the race of the reference. The C version specifies the skill by number rather than by name.
`(isBonusSkill:bool) reference.IsRaceBonusSkill skillActorValue:chars raceFormID:ref`
`(isBonusSkill:bool) reference.IsRaceBonusSkillC skillActorValueCode:int raceFormID:ref`

GetNthRaceBonusSkill - returns the actor value code for the specified index into the bonus skills. Can be followed up with a call to GetRaceSkillBonusC to determine the actual bonus to the skill. If called on a reference the function will determine the race of the reference.
`(skill:int) reference.GetNthRaceBonusSkill whichSkill:int raceFormID:ref`

GetRaceSpellCount - returns the number of spells provided by the race. If no race is specified, the race of the calling NPC is used.
`(numSpells:int) reference.GetRaceSpellCount race:ref`

GetNthRaceSpell - returns the nth spell provided by the race, using the race of the calling NPC if none is specified.
`(spell:ref) reference.GetNthRaceSpell whichSpell:int race:ref`

SetRaceAlias - creates an alias for a race. If a race has an alias, then calling `GetIsRace aliasRace` will return true for any actor of that race. For example, `SetRaceAlias Nord Argonian` will cause GetIsRace to recognize Nords as Argonians. However, Argonians will not be recognized as Nords. The third argument defaults to 1; pass 0 to clear a previously created alias.
`(nothing) SetRaceAlias actualRace:ref aliasRace:ref enableAlias:bool`

GetRaceVoice - returns the race which is used to provide the voice of the specified race and gender. Pass 0 for male or 1 for female.
`(voiceRace:ref) GetRaceVoice race:ref whichGender:int`

SetRaceVoice - changes the voice of a race to the specified race. Specify 0 for male, 1 for female, or 2 for both genders.
`(nothing) SetRaceVoice actualRace:ref voiceRace:ref whichGender:int`

SetRacePlayable - flags a race as playable or unplayable. Unplayable races cannot speak most of the dialog defined in the game.
`(nothing) SetRacePlayable race:ref isPlayable:bool`

IsRacePlayable - returns 1 if the specified race is flagged as playable in the editor.
`(isPlayable:bool) IsRacePlayable race:ref`

GetRaceReaction - returns the race reaction between the target NPC/Race and the calling NPC reference or passed race. The target and from races are declared as NPCs, but you can also place a Race name into a ref variable and pass those in.
`(reaction:int) reference.GetRaceReaction targetNPC:ref fromNPC:ref`

GetRaceScale - returns the default scale of the male or female members of the specified race.
`(scale:float) GetRaceScale race:ref forFemale:bool`

SetRaceScale - sets the scale for male or female members of the specified race.
`(nothing) SetRaceScale race:ref forFemale:bool scale:float`

GetRaceWeight - returns the default weight for male or female members of the specified race as defined in the editor.
`(weight:float) GetRaceWeight race:ref forFemale:bool`

SetRaceWeight - sets the weight for male or female members of the specified race.
`(nothing) SetRaceWeight race:ref forFemale:bool weight:float`

GetRaceDefaultHair - returns the default hair for male or female members of the specified race.
`(hair:ref) GetRaceDefaultHair race:ref forFemale:bool`

GetRaceHairs - returns an Array of all hairs (male and female) available to actors of the specified race as defined in the editor.
`(hairs:Array) GetRaceHairs race:ref`

GetRaceEyes - returns an Array of all eyes available to actors of the specified race as defined in the editor.
`(eyes:Array) GetRaceEyes race:ref`

HasTail - returns true if the specified race or the race of the calling npc ref or specified base npc has a tail.
`(hasTail:bool) reference.HasTail raceOrNPC:ref`

GetTailModelPath - returns the path to the tail model used by the specified gender of the specified race or the race of the specified NPC or calling reference, if the race has a tail.
`(tailPath:string) reference.GetTailModelPath female:bool raceOrNPC:ref`

### Scriptable

Types with this quality can have a script associated with them.

#### Functions:

IsScripted - returns whether the scriptable object has a script attached to it or not.
`(isScripted:bool) reference.IsScripted targetObjectID:ref`

GetScript - returns the refID of the script attached to the object
`(script:refID) reference.GetScript targetObjectID:ref`

RemoveScript - removes and returns the script attached to the object. The object is no longer scripted
`(script:refID) reference.RemoveScript targetObjectID:ref`

SetScript - sets the specified script onto the calling object and returns any previous script. Note that Oblivion doesn't have a script variable type so you must assign the script to a ref variable for this to work. NOTE: If the specified object already has a script attached to it, after changing the script the stored values of local variables for references to that object will not match the variables in the new script. If called on a reference, the variable list for the calling reference will be updated to match the new script, but other references to the same base object will not be updated. Summary: SetScript is safe to use with quests, with previously unscripted objects, and on unique references (for which no other references exist to the same base object). Using the command on base objects for which non-unique references exist may result in undefined behavior.
`(script:refID) reference.SetScript scriptID:ref targetObjectID:ref`

IsFormValid - returns 1 if the specified ref variable contains a valid object or reference.
`(valid:bool) IsFormValid refVar:var`

IsReference - returns 1 if the specified ref variable contains a reference, as opposed to a base object.
`(isReference:bool) IsReference refVar:var`

HasVariable - returns 1 if the calling reference or specified quest has a variable with the specified name.
`(hasVariable:bool) reference.HasVariable varName:string questID:ref`

GetVariable - returns the value of a numeric variable by name, either from the calling reference's script or the specified quest.
`(variableValue:float) reference.GetVariable varName:string questID:ref`

GetRefVariable - returns the reference stored in a ref variable by name, either from the calling reference's script or the specified quest.
`(reference:ref) reference.GetRefVariable varName:string questID:ref`

GetArrayVariable (GetArrayVar) - returns the value of an array variable by name, either from the calling reference's script or the specified quest.
`(array) reference.GetArrayVariable varName:string questID:ref`

CompareScripts - compares the compiled code of two scripts and returns 1 if they are identical. Note that this doesn't mean the text of the scripts are identical, only that they call the same functions in the same order with the same parameters.
`(scriptsAreIdentical:bool) CompareScripts script:ref script:ref`

ResetAllVariables - sets all variables in the calling script to zero.
`(numVars:int) ResetAllVariables`

GetNumExplicitRefs - returns the number of explicit references in the calling object's script or in the passed script object. Explicit references are any objects mentioned by name in the script; for instance, if a script contains an "OnHit Player" block or a "Player.AddItem" command, its explicit references will include the player.
`(numRefs:int) reference.GetNumExplicitRefs script:ref`

GetNthExplicitRef - returns the nth explicit ref in the calling object's script or the passed script object. See GetNumExplicitRefs are a description of explicit references.
`(object:ref) reference.GetNthExplicitRef index:int script:ref`

GetCurrentScript - returns the script which is currently executing.
`(script:ref) GetCurrentScript`

### Simple

Types with this quality have a single model path and a single icon texture.

#### Values:

Model Path (string) - the path to the NIF model for the type
Icon Path (string) - the path to the DDS icon texture for the type

#### Functions:

SetModelPath - sets the model path for the type.
`(nothing) reference.SetModelPath modelPath:string objectID:ref`

GetModelPath - returns the model path for the object.
`(path:string_var) reference.GetModelPath object:ref`

SetIconPath - sets the icon path for the type.
`(nothing) reference.SetIconPath iconPath:string objectID:ref`

GetIconPath - returns the icon path for the object.
`(path:string_var) reference.GetIconPath object:Ref`

CompareModelPath - returns whether the passed string is part of the model path. This is a case insensitive search.
`(found:bool) reference.CompareModelPath toFind:string objectID:ref`
`(found:bool) reference.ModelPathIncludes toFind:string objectID:ref`

CompareIconPath - returns whether the passed string is part of the icon path. This is a case insensitive search.
`(found:bool) reference.CompareIconPath toFind:string objectID:ref`
`(found:bool) reference.IconPathIncludes toFind:string objectID:ref`

CopyModelPath - sets the model path of the calling reference or passed objectID to the model path offromObject
`(nothing) reference.CopyModelPath fromObject:ref toObject:ref`

CopyIconPath - sets the icon path of the calling reference or passed objectID to the icon path of fromObject
`(nothing) reference.CopyIconPath fromObject:ref toObject:ref`

ModModelPath - modifies the model path of the calling reference or passed objectID. The `toReplaceAndReplaceWith` string has the following format: `"toReplace|replaceWith"`. `ModModelPath` will do a case insensitve search for the `toReplace` portion and if found will replace it with the `replaceWith` portion. The `|` character is used to separate the portions of the string. If there is nothing before the `|` character, the `replaceWith` string is prepended to the model path. In the console, use `@` instead of `|`.
`(nothing) reference.ModModelPath toReplaceAndReplaceWith:string toObject:ref`

ModIconPath - modifies the icon path of the calling reference or passed objectID. The `toReplaceAndReplaceWith` string has the following format: `"toReplace|replaceWith"`. `ModIconPath` will do a case insensitve search for the `toReplace` portion and if found will replace it with the `replaceWith` portion. The `|` character is used to separate the portions of the string. If there is nothing before the `|` character, the `replaceWith` string is prepended to the icon path. In the console, use `@` instead of `|`.
`(nothing) reference.ModIconPath toReplaceAndReplaceWith:string toObject:ref`

IsModelPathValid - returns 1 if the model path for the object exists in the user's Data folder or within one of the BSA archives.
`(isPathValid:bool) reference.IsModelPathValid object:ref`

IsIconPathValid - returns 1 if the icon path for the object exists in the user's Data folder or within one of the BSA archives.
`(isPathValid:bool) reference.IsIconPathValid object:ref`

GetTexturePath - returns the texture path of an object. This command is identical to GetIconPath, but also works for other object types such as skills, classes, and miscellaneous objects.
`(string) reference.GetTexturePath object:ref`

SetTexturePath - sets the texture path of an object. This command works for a broader set of objects than SetIconPathEX.
`(nothing) reference.SetTexturePath path:string object:ref`

GetEditorSize - returns the value contained in the hidden 'size' field of the editor's object window for the specified object. This is a rough scalar approximation of the dimensions of the object. Return value is typically similar to that of GetBoundingRadius. The game only calculates and stores this value for objects for which at least one reference exists in the game world.
`(size:float) reference.GetEditorSize object:ref`

### Wearable

Types with this quality can be worn by actors and can have different models and textures for males and females

#### Qualities

Equippable

#### Values

Slot (short) - the equipment slot or slots taken by the object
Male Model Path (string) - the path to the NIF file for the male or only model while worn
Female Model Path (string) - the path to the NIF file for the female model while worn
Male Ground Path (string) - the path to the NIF for the male or only model when dropped
Female Ground Path (string) - the path to the NIF for the female model when dropped
Male Icon Path (string) - the path to the DDS icon file for the male or only model
Female Icon Path (string) - the path to the DDS icon file for the female model
Playable (bool) - whether the item is useable by the player or not

#### Functions:

SetMaleBipedPath - sets the male NIF model path when worn
`(nothing) reference.SetMaleBipedPath modelPath:string objectID:ref`

SetFemaleBipedPath - sets the female NIF model path when worn
`(nothing) reference.SetFemaleBipedPath modelPath:string objectID:ref`

SetMaleGroundPath - sets the male model path when dropped
`(nothing) reference.SetMaleGroundPath modelPath:string objectID:ref`

SetFemaleGroundPath - sets the female model path when dropped
`(nothing) reference.SetFemaleGroundPath modelPath:string objectID:ref`

SetMaleIconPath - sets the male icon texture
`(nothing) reference.SetMaleIconPath iconPath:string objectID:ref`

SetFemaleIconPath - sets the female icon texture
`(nothing) reference.SetFemaleIconPath iconPath:string objectID:ref`

ModXXXPath - modifies the specified path of the calling reference or passed obectID. The `toReplaceAndReplaceWith` string has the following format: `"toReplace|replaceWith"`. `ModXXXPath` will do a case insensitve search for the `toReplace` portion and if found will replace it with the `replaceWith` portion. The `|` character is used to separate the portions of the string. If there is nothing before the `|` character, the `replaceWith` string is prepended to the specified path. In the console, use `@` instead of `|`.
`(nothing) reference.ModMaleBipedPath toReplaceAndReplaceWith:string toObject:ref`
`(nothing) reference.ModFemaleBipedPath toReplaceAndReplaceWith:string toObject:ref`
`(nothing) reference.ModMaleGroundPath toReplaceAndReplaceWith:string toObject:ref`
`(nothing) reference.ModFemaleGroundPath toReplaceAndReplaceWith:string toObject:ref`
`(nothing) reference.ModMaleIconPath toReplaceAndReplaceWith:string toObject:ref`
`(nothing) reference.ModFemaleIconPath toReplaceAndReplaceWith:string toObject:ref`

CompareXXXPath - returns whether the specified path of the calling reference or objectID contains the toFind string. This does a case insensitive search.
`(found:bool) reference.CompareMaleBipedPath toFind:string objectID:ref`
`(found:bool) reference.CompareFemaleBipedPath toFind:string objectID:ref`
`(found:bool) reference.CompareMaleGroundPath toFind:string objectID:ref`
`(found:bool) reference.CompareFemaleGroundPath toFind:string objectID:ref`
`(found:bool) reference.CompareMaleIconPath toFind:string objectID:ref`
`(found:bool) reference.CompareFemaleIconPath toFind:string objectID:ref`
`(found:bool) reference.MaleBipedPathIncludes toFind:string objectID:ref`
`(found:bool) reference.FemaleBipedPathIncludes toFind:string objectID:ref`
`(found:bool) reference.MaleGroundPathIncludes toFind:string objectID:ref`
`(found:bool) reference.FemaleGroundPathIncludes toFind:string objectID:ref`
`(found:bool) reference.MaleIconPathIncludes toFind:string objectID:ref`
`(found:bool) reference.FemaleIconPathIncludes toFind:string objectID:ref`

CopyXXXPath - sets the specified path of the calling reference or objectID to the same path from the fromObject.
`(nothing) reference.CopyMaleBipedPath fromObject:ref toObject:ref`
`(nothing) reference.CopyFemaleBipedPath fromObject:ref toObject:ref`
`(nothing) reference.CopyMaleGroundPath fromObject:ref toObject:ref`
`(nothing) reference.CopyFemaleGroundPath fromObject:ref toObject:ref`
`(nothing) reference.CopyMaleIconPath fromObject:ref toObject:ref`
`(nothing) reference.CopyFemaleIconPath fromObject:ref toObject:ref`

IsPlayable - returns whether the specified object is playable or not. Returns true only if the object is of a type which can be flagged as playable in the editor.
`(isPlayable:bool) reference.IsPlayable objectID:ref`

SetIsPlayable - specifies whether the object can be used by the player
`(nothing) reference.SetIsPlayable isPlayable:bool objectID:ref`

IsPlayable2 - returns whether the specified object is playable or not. If the object is of a type which cannot be flagged as playable in the editor, this function returns true.
`(isPlayable:bool) reference.IsPlayable2 objectID:ref`

IsBipedIconPathValid - returns 1 if the icon path for the object exists in the user's Data folder or within one of the BSA archives.
`(isPathValid:bool) reference.IsBipedIconPathValid bipedPathCode:int object:ref`

IsBipedModelPathValid - returns 1 if the model path for the object exists in the user's Data folder or within one of the BSA archives.
`(isPathValid:bool) reference.IsBipedModelPathValid bipedPathCode:int object:ref`

GetBipedModelPath - returns the file path of one of the models for the specified biped object.
`(path:string_var) reference.GetBipedModelPath bipedPathCode:int object:ref`

SetBipedModelPathEX - sets the file path of the male or female model for the specified biped object.
`(nothing) reference.SetBipedModelPathEX path:formatString bipedPathCode:int object:ref`

GetBipedIconPath - returns the file path of one of the icons for the specified biped object.
`(path:string_var) reference.GetBipedIconPath bipedPathCode:int object:ref`

SetBipedIconPathEX - sets the file path of the male or female icon for the specified biped object.
`(nothing) reference.SetBipedIconPathEX path:formatString bipedPathCode:int object:ref`

GetHidesRings - returns 1 if the "hides rings" flag is set for the biped object.
`(hidesRings:bool) reference.GetHidesRings object:ref`

GetHidesAmulet - returns 1 if the "hides amulet" flag is set for the biped object.
`(hidesAmulet:bool) reference.GetHidesAmulet object:Ref`

SetHidesRings - modifies the "hides rings" flag.
`(nothing) reference.SetHidesRings hidesRings:bool object:ref`

SetHidesAmulet - modifies the "hides amulet" flag.
`(nothing) reference.SetHidesAmulet hidesAmulet:bool object:ref`

GetBipedSlotMask - returns the slots occupied by a biped object.
`(slotMask:int) reference.GetBipedSlotMask object:ref`

SetBipedSlotMask - sets the slots occupied by a biped object.
`(nothing) reference.SetBipedSlotMask slotMask:int object:ref`

See also: GetEquipmentSlot

See also: SetEquipmentSlot

## Oblivion Types

Oblivion Types are the various forms available to fill out in the CS. They correspond to real objects or concepts in Oblivion. Types are a collection of values and functions which can be applied to them. Frequently they have Qualities which encapsulate common values and functions across the various types. If a type has a quality listed, that type has all of the values and functions of that quality in addition to any listed directly with the type itself.

- Actor Reference
- AI Package
- Alchemy Item
- Ammo
- Apparatus
- Armor
- Birthsign
- Book
- Cell
- Climate
- Clothing
- Combat Style
- Creature
- Door
- Enchantment
- Faction
- Flora
- Ingredient
- Leveled List
- Light
- Magic Effect Setting
- Magic Target
- Map Marker
- Pathgrid
- NPC
- Player
- Projectile
- Quest
- Reference
- Sigil Stone
- Skill
- Soul Gem
- Sound
- Spell
- Weapon
- Weather

### Actor Reference

A reference to a creature or NPC in the game world. Actor references have AI, animations, and havok states.

#### Qualities:

Actor, Inventory, Magic Target, NPC or Creature

#### Functions:

GetNumDetectedActors - returns the number of other actors of which the calling actor may detect. This includes actors detected at "Lost" or "Unseen" level.
`(numDetectedActors:int) reference.GetNumDetectedActors`

GetNthDetectedActor - returns the Nth actor in the calling actor's detection list
`(actor:ref) reference.GetNthDetectedActor index:short`

SetDetectionState - sets the detection state of the calling actor toward the specified actor reference. Note that Oblivion recalculates this value frequently for actors in high process; the function's main purpose is to reset the detection state of unconscious actors.
`(nothing) reference.SetDetectionState actor:ref detection state:int`

IsBlocking - returns 1 if the calling actor is blocking
`(isBlocking:bool) reference.IsBlocking`

IsAttacking - returns 1 if the calling actor is attacking
`(isAttacking:bool) reference.IsAttacking`

IsRecoiling - returns 1 if the calling actor is recoiling
`(isRecoiling:bool) reference.IsRecoiling`

IsDodging - returns 1 if the calling actor is dodging
`(isDodging:bool) reference.IsDodging`

IsStaggered - returns 1 if the calling actor is staggered
`(isStaggered:bool) reference.IsStaggered`

IsMovingForward - returns 1 if the calling actor is attempting to move forward, even if his path is blocked.
`(isMovingForward:bool) reference.IsMovingForward`

IsMovingLeft - returns 1 if the calling actor is attempting to strafe left
`(isMovingLeft:bool) reference.IsMovingLeft`

IsMovingRight - returns 1 if the calling actor is attempting to strafe right
`(isMovingRight:bool) reference.IsMovingRight`

IsMovingBackward - returns 1 if the calling actor is attempting to move backwards
`(isMovingBackwards:bool) reference.IsMovingBackwards`

IsTurningLeft - returns 1 if the calling actor is turning left
`(isTurningLeft:bool) reference.IsTurningLeft`

IsTurningRight - returns 1 if the calling actor is turning right
`(isTurningRight:bool) reference.IsTurningRight`

IsInAir - returns 1 if the calling actor is airborne, whether jumping or falling
`(isInAir:bool) reference.IsInAir`

IsJumping - returns 1 if the calling actor is beginning to jump (playing the JumpStart anim group)
`(isJumping:bool) reference.IsJumping`

IsOnGround - returns 1 if the calling actor is on the ground
`(isOnGround:bool) reference.IsOnGround`

IsFlying - returns 1 if the calling actor is flying. Only creatures can fly.
`(isFlying:bool) reference.IsFlying`

IsPowerAttacking - returns 1 if the calling actor is executing a power attack
`(isPowerAttacking:bool) reference.IsPowerAttacking`

IsCasting - returns 1 if the calling actor is casting a spell
`(isCasting:bool) reference.IsCasting`

GetFallTimer - returns the length of time for which the actor has been falling
`(fallTimer:float) reference.GetFallTimer`

IsAnimGroupPlaying - returns 1 if the specified animation group is currently being played by the calling actor
`(playing:bool) reference.IsAnimGroupPlaying animationGroup:chars`

AnimPathIncludes - returns 1 if one of the calling actor's currently playing animation paths includes the specified substring
`(includes:bool) reference.AnimPathIncludes pathString:string`

GetProcessLevel - returns the actor's current process level, or -1 if called on a non-actor. Process level determines how frequently the game updates an actor's AI. In general, high process actors are in the same cell as the player, while more distant actors are kept at a lower process level.
`(processLevel:int) reference.GetProcessLevel`

GetEquippedItems - returns an array containing all items currently equipped by the calling actor
`(items:Array) reference.GetEquippedItems`

GetSpells - returns an array containing all of the spells in an actor's spell list.
`(spells:Array) reference.GetSpells baseActor:ref`

GetActorAlpha - actor references can be made more or less opaque or transparent by changing their alpha property via SetActorAlpha. This function returns the calling actor's current alpha as a floating point number between 0.0 and 1.0, with 0.0 corresponding to fully transparent and 1.0 to fully opaque.
`(alpha:float) reference.GetActorAlpha`

GetBaseActorValueC - identical to the game's GetBaseAV command, but accepts an integer actor value code.
`(baseAV:int) reference.GetBaseActorValueC actorValueCode:int`

`(baseAV:int) reference.GetBaseAVC actorValueCode:int`

GetBaseAV2 - returns the same value as the game's GetBaseAV command, but does not include the effects of Fortify abilities.
`(baseAV:int) reference.GetBaseAV2 actorValue:string`

GetBaseAV2C - as GetBaseAV2, but takes an actor value code instead of an actor value name.
`(baseAV:int) reference.GetBaseAV2C actorValueCode:int`

GetAllies - for an actor in combat, returns an Array of other actors which the game considers allies of the calling actor at that particular moment.
`(allies:Array) reference.GetAllies`

GetTargets - for an actor in combat, returns an Array of actors which the game considers potential targets of the calling actor at that particular moment.
`(targets:Array) reference.GetTargets`

GetSelectedSpells - for an actor in combat, returns an Array containing zero to seven spells which the actor has selected from his full spell list (including spells resolved from leveled spell lists) for use. The list contains a maximum of one spell from each of the following categories: bound armor, bound weapon, "buff", melee, ranged, restorative, and summon spells.
`(spells:Array) reference.GetSelectedSpells`

GetCombatSpells - for an actor in combat, returns an Array of all the spells in the actor's spellbook, including spells resolved from leveled spells lists (which are resolved into actual spells when the actor enters combat). The actor will use a subset of these spells during combat; use GetSelectedSpells to determine which of these spells have been selected for use.
`(spells:Array) reference.GetCombatSpells`

PlayIdle - attempts to make the calling actor play the specified idle animation. The animation must be one defined in the editor's Gameplay > Idle Animations window. Pass 1 for the forceIdle parameter to force the actor to play the idle regardless of any other animations currently playing.
`(idlePlayed:bool) ref.PlayIdle idleAnim:ref forceIdle:bool`

### AI Package

A set of information defining actor behavior. Commands which modify AI packages operate on the base package and may have no effect or unpredictable effects on actor references currently executing that package.

SetPackageTarget - sets the target of the specified package. Target can be of several types, leading to several syntaxes for this command. The first listed usage sets the target to a specific reference. The second sets it to a particular base object with a specified quantity; when the package executes the actor will look for references to that base object to use as the target(s). The third usage sets the target to a code representing the type(s) of objects to be used as targets, along with a quantity. This command does not change the targets of actor references currently executing the package unless they re-evaluate their package after the change has been made.
`(nothing) SetPackageTarget package:ref targetReference:ref`
`(nothing) SetPackageTarget package:ref baseObject:ref quantity:int`
`(nothing) SetPackageTarget package:ref objectCode:int quantity:int`

GetPackageData - returns a stringmap containing info about a package. The returned stringmap contains the following keys:

- "Type" - a string indicating the type of the package (e.g. "Eat", "Wander")
- "Schedule" - a stringmap of the same format as the returned by GetPackageScheduleData
- "Target" - a stringmap of the same format as the returned by GetPackageTargetData
- "Location" - a stringmap of the same format as the returned by GetPackageLocationData

`(StringMap) GetPackageData package:ref`

GetPackageScheduleData - returns a stringmap containing info about a package schedule. The returned stringmap contains the following keys:

- "Day" - a string, e.g. "Sunday"
- "Month" - a string, e.g. "January"
- "Date" - integer, 1-30
- "Time" - integer, 0-23
- "Duration" - integer

`(StringMap) GetPackageScheduleData package:ref`

GetPackageLocationData - returns a stringmap containing info about a package location. The returned stringmap contains the following keys:

- "Type" - string ("Reference", "Cell", "Current", "Editor", "Object", "ObjectType")
- "Radius" - int
- "Object" - form (for types Reference, Cell, and Object) OR
- "ObjectType" - string as in editor, e.g. "Books", "Spells: School Illusion" (for ObjectType)

`(StringMap) GetPackageLocationData package:ref`

GetPackageTargetData - returns a stringmap containing info about a package target. The returned stringmap contains the following keys:

- "Type" - string ("Reference", "Object", "ObjectType")
- "Value" - integer
- "Object" - form (for types Reference and Object) OR
- "ObjectType" - string as in editor, e.g. "Books", "Spells: School Illusion" (for ObjectType)

`(StringMap) GetPackageTargetData package:ref`

SetPackageData - sets the target, schedule, and/or location of a package. It accepts a stringmap consisting of one or more stringmaps with keys "Location", "Target", or "Schedule", each following the formats listed above. If any data is omitted, the existing package data will be retained.
`(success:bool) SetPackageData package:ref data:StringMap`

SetPackageTargetData - sets the target of a package. Accepts a stringmap of the same format as that returned by GetPackageTargetData. Omitted fields retain their existing values.
`(success:bool) SetPackageTargetData package:ref data:StringMap`

SetPackageLocationData - sets the location of a package based on the passed stringmap of the same format as that returned by GetPackageLocationData. Omitted fields retain their existing values.
`(success:bool) SetPackageLocationData package:ref data:StringMap`

SetPackageScheduleData - sets the schedule of a package. Accepts a stringmap of the same format as that returned by GetPackageScheduleData. Omitted fields retain their existing values.
`(success:bool) SetPackageScheduleData package:ref data:StringMap`

Package Flag Commands - gets or sets the state of one of the flags on the specified package. Syntax is identical for all commands; sample usage is given for Get/SetPackageOffersServices
`(offersServices:bool) GetPackageOffersServices package:ref`
`(nothing) SetPackageOffersServices package:ref offersServices:bool`

- Get/SetPackageOffersServices
- Get/SetPackageMustReachLocation
- Get/SetPackageMustComplete
- Get/SetPackageLockDoorsAtStart
- Get/SetPackageLockDoorsAtEnd
- Get/SetPackageLockDoorsAtLocation
- Get/SetPackageUnlockDoorsAtStart
- Get/SetPackageUnlockDoorsAtEnd
- Get/SetPackageUnlockDoorsAtLocation
- Get/SetPackageContinueIfPCNear
- Get/SetPackageOncePerDay
- Get/SetPackageSkipFalloutBehavior
- Get/SetPackageAlwaysRun
- Get/SetPackageAlwaysSneak
- Get/SetPackageAllowSwimming
- Get/SetPackageAllowFalls
- Get/SetPackageArmorUnequipped
- Get/SetPackageWeaponsUnequipped
- Get/SetPackageDefensiveCombat
- Get/SetPackageUseHorse
- Get/SetPackageNoIdleAnims

### Alchemy Item

Alchemy Items are potions and poisons.

#### Qualities:

Edible, Inventory, Magic, Named, Scriptable, Simple

#### Values:

Is Poison Flag (bool) - whether the alchemy item is considered a poison. A poison is an alchemy item with all hostile effects. An alchemy item with even a single non-hostile effect is not a poison.

#### Functions

IsPoison - returns whether the alchemy item is a poison.
`(isPoison:bool) reference.IsPoison objectID:ref`

MatchPotion - Oblivion keeps track of potions created by the player and reuses them if another potion is created with the same effects as one created previously. This command takes a potion and returns a previously-created potion bearing the same effects, if one exists. Note that in some cases it may return the same potion that was passed as the argument. Mainly useful during potion creation in the Alchemy menu, or when dynamically modifying potion effects via script.
`(matchedPotion:ref) MatchPotion potionToMatch:ref`

### Ammo

Ammo includes all ammunition like arrows.

#### Qualities:

Attacking, Enchantable, Equippable, Inventory, Named, Simple

#### Functions:

No additional functions have been defined.

### Apparatus

Apparatus are used for Alchemy and the creation of alchemy items.

#### Values:

Type (short) - the type of alchemy apparatus
Quality (float) - the level of the alchemy apparatus quality. The ApparatusQuality list shows the basic levels, but any value between 0 and 1.0 is valid.

#### Functions:

GetApparatusType - returns the alchemy apparatus type of the calling reference or passed objectID
`(apparatusType:int) reference.GetApparatusType objectID:ref`

SetApparatusType - sets the alchemy type of the calling reference or passed objectID
`(nothing) reference.SetApparatusType apparatusType:int objectID:ref`

GetQuality - returns the quality level of the calling reference or passed objectID
`(quality:float) reference.GetQuality objectID:ref`

SetQuality - sets the quality level of the calling reference or passed objectID
`(nothing) reference.SetQuality quality:float objectID:ref`

ModQuality - modifies the quality of the calling reference or passed objectID
`(nothing) reference.ModQuality modQualityBy:float objectID:ref`

### Armor

Armor is any type of wearable object that provides protection against damage.

#### Qualities:

Breakable, Enchantable, Inventory, Named, Wearable

#### Values:

Armor Rating (long) - the value of protection provided by the armor
Armor Type (short) - the type of the armor. Armor Type Codes

#### Functions:

GetArmorAR - returns the armor rating of the object
`(armorRating:int) reference.GetArmorAR objectID:ref`

SetArmorAR - sets the armor rating of the object
`(nothing) reference.SetArmorAR nuArmorRating:int objectID:ref`

ModArmorAR - modifies the armor rating of the object up or down
`(nothing) reference.ModArmorAR modifyBy:float objectID:ref`

GetArmorType - returns 0 if light armor and 1 if heavy armor
`(armorType:int) reference.GetArmorType objectID:ref`

SetArmorType - sets whether the armor is heavy or light
`(nothing) reference.SetArmorType nuArmorType:int objectID:ref`

### Birthsign

A set of magic items associated with a birthsign.

#### Functions:

GetBirthsignSpells - returns an Array containing the spells associated with the specified birthsign
`(spells:Array) GetBirthsignSpells birthsign:ref`

### Book

Includes books and scrolls.

#### Qualities:

Inventory, Description, Enchantable, Named, Simple

#### Values:

Can Be Taken (bool) whether the book can be taken
IsScroll (bool) whether the book is a scroll
SkillTaught (bool) whether the book teaches a skill or not

#### Functions:

GetBookCantBeTaken - returns 1 if the book cannot be taken
`(cantBeTaken:bool) reference.GetBookCantBeTaken objectID:ref`

GetBookIsScroll - returns whether the book is a scroll or not
`(isScroll:bool) reference.GetBookIsScroll objectID:ref`

GetBookSkillTaught - returns the skill taught by the book. If no skill is taught, returns -1.
`(skillTaught:int) reference.GetBookSkillTaught objectID:ref`

SetBookCantBeTaken - sets whether the book can be taken
`(nothing) reference.SetBookCantBeTaken cantBeTaken:bool objectID:ref`

SetBookIsScroll - sets whether the book is a scroll
`(nothing) reference.SetBookIsScroll isScroll:bool objectID:ref`

SetBookSkillTaught - sets the skill the book teaches. The the skillTaught value is not one of the skills, sets the value to 255.
`(nothing) reference.SetBookSkillTaught skillTaught:int objectID:ref`

GetBookText - returns the text of a book as a string. The result must be assigned to a string variable.
`(bookText:string_var) reference.GetBookText book:ref`

GetBookLength - returns the number of characters in a book's text.
`(length:int) reference.GetBookLength book:ref`

### Cell

There are two types of cells: interior and exterior. Exterior cells exist as parts of worldspaces and often inherit the name of their parent worldspace. Interior cells are isolated from other parts of the world and have their own names. When the player visits and then exits an interior cell, the game records the number of total hours elapsed in the game at the moment the player exits; this value is the cell's "detach time." The next time he visits that cell, if the difference between the current number of game hours passed and the detach time is greater than the game setting iHoursToRespawnCell, the cell will be reset.

#### Qualities:

Named

#### Values:

Music Type (short) - the music type for the cell

#### Functions:

GetCellMusicType - returns the music type of the player's current cell.
`(musicType:int) GetCellMusicType`

SetCellMusicType - sets the music type used in the specified cell.
`(nothing) SetCellMusicType cell:ref musicType:int`

SetCellWaterHeight - changes the water height of the specified cell. In order for the command to take full effect, the cell must be reloaded (con_PurgeCellBuffers can be used to forcibly unload it if it is still in memory). If used to alter the water height in a loaded cell, the water shader will reflect the new height and actors will switch between swimming and walking animations appropriately. However, floating physics and the water surface will not be updated until the cell is reloaded. This command has no effect in exteriors or in cells which have no water.
`(waterHeightChanged:bool) SetCellWaterHeight cell:ref newHeight:float`

GetCellDetachTime - returns the cell's detach time, described above.
`(detachTime:int) GetCellDetachTime cell:ref`

GetCellResetHours - returns the number of hours which must pass in the game before the cell is reset.
`(hours:int) GetCellResetHours cell:ref`

SetCellResetHours - sets the number of hours which mustpass before the cell is reset. This value must be less than the game setting iHoursToRespawnCell. Using this function to modify the reset hours for the current cell, or for exterior cells, has no effect.
`(bSucceeded:bool) SetCellResetHours cell:ref hours:int`

GetCellBehavesAsExterior - returns true if the "behaves as exterior" cell is checked for the specified interior cell.
`(behavesAsExterior:bool) GetCellBehavesAsExterior cell:ref`

IsCellPublic - returns 1 if the cell is marked as 'public'.
`(isPublic:bool) IsCellPublic`

SetCellIsPublic - sets the 'public' flag for the cell.
`(nothing) SetCellIsPublic cell:ref isPublic:bool`

SetCellHasWater - sets the flag indicating whether or not the interior cell has water. Only affects interior cells, and changes are not visible until the cell is reloaded. Has no effect if called while the player is inside the specified cell.
`(nothing) SetCellHasWater cell:ref hasWater:bool`

SetCellBehavesAsExterior - sets the 'behaves like exterior' flag for the interior cell. Has no effect if called while the player is inside the specified cell.
`(nothing) SetCellBehavesAsExterior cell:ref behavesAsExterior:bool`

GetCellClimate - returns the climate for the specified cell.
`(climate:ref) GetCellClimate cell:ref`

SetCellClimate - sets the climate for the specified cell.
`(nothing) SetCellClimate cell:ref climate:ref`

GetCellLighting - returns a StringMap describing the lighting properties for the interior cell. The StringMap contains the following key-value pairs corresponding to the fields in the editor's Cell Lighting tab, where 'RGB Array' is a 3-element Array with values from 0-255 in the order {red, green, blue}:

    		"ambient" (RGB Array)
    		"directional" (RGB Array)
    		"fog" (RGB Array)
    		"rotxy" (float)
    		"rotz" (float)
    		"fognear" (float)
    		"fogfar" (float)
    		"clip" (float)
    		"fade" (float)

`(lighting:StringMap) GetCellLighting cell:ref`

SetCellLighting - alters one or more of an interior cell's lighting fields, taking a StringMap of the same format as that returned by GetCellLighting. Include only the elements you wish to change; if a key is not found its value will not be modified.
`(nothing) SetCellLighting cell:ref newValues:StringMap`

GetTerrainHeight - returns the height of the terrain mesh at the specified x and y coordinates within the current exterior worldspace. X and Y are worldspace coordinates (e.g. as returned by GetPos). If the coordinates are outside of any loaded cells, returns 0.0. Note that this command does not check for collision with surfaces other than terrain.
`(height:float) GetTerrainHeight x:float y:float`

IsOblivionInterior - returns 1 if the "Oblivion interior" flag has been checked for the specified interior cell.
`(oblivionInterior:bool) IsOblivionInterior cell:ref`

IsOblivionWorld - returns 1 if the "Oblivion World" flag has been checked for the specified world space.
`(oblivionWorld:bool) IsOblivionWorld worldspace:ref`

CanFastTravelFromWorld - returns 1 if the player is allowed to fast-travel from the specified world space.
`(canFastTravel:bool) CanFastTravelFromWorld worldspace:ref`

SetCanFastTravelFromWorld - sets whether the player can fast-travel from the specified world space.
`(nothing) SetCanFastTravelFromWorld worldspace:ref canFastTravel:bool`

GetCellWaterType - returns the Water used by the interior cell. Returns zero if the cell has no water, or if the cell uses the default water type.
`(waterType:ref) GetCellWaterType cell:ref`

SetCellWaterType - sets the Water used by the interior cell. Changes will not be visible until the cell is reloaded.
`(nothing) SetCellWaterType cell:ref waterType:ref`

GetCellNorthRotation - returns the rotation on the Z axis of the north marker within the specified interior cell, if one is present. The game uses the north marker's Z rotation to determine what direction is considered "north". Rotation returned is in degrees and is 0.0 if no north marker is present in the specified cell.
`(rotation:float) GetCellNorthRotation cell:ref`

### Climate

Climate settings define weather, sun, and moon settings for a worldspace. Additional information about these settings can be found at the Construction Set Wiki.

#### Values:

Sunrise Begin, Sunrise End, Sunset Begin, Sunset End (short) - these values are the number of 10 minute increments since midnight the given event occurs
MoonPhaseLength (short) - the number of days in a moon's phase
HasMasser, HasSecunda (bool) - which moons the climate will show
Volatility (short) - the volatility of the climate, or how often the weather is likely to change

#### Functions:

GetCurrentClimateID - returns the refID of the current climate
`(currentClimate:ref) GetCurrentClimateID`

GetClimateSunriseBegin - returns the time sunrise begins specified as a number of 10 minute units since midnight
`(sunriseBegin:int) GetSunriseBegin climate:ref`

GetClimateSunriseEnd - returns the time sunrise ends specified as a number of 10 minute units since midnight
`(sunriseEnd:int) GetSunriseEnd climate:ref`

GetClimateSunsetBegin - returns the time sunset begins specified as a number of 10 minute units since midnight
`(sunsetBegin:int) GetSunsetBegin climate:ref`

GetClimateSunsetEnd - returns the time sunset ends specified as a number of 10 minute units since midnight
`(sunsetEnd:int) GetSunsetEnd climate:ref`

GetClimateMoonPhaseLength - returns the number of days in the phase of the moons. The total moon cycle length is 8 x PhaseLength according to the CS.
`(phaseLength:int) GetClimateMoonPhaseLength climate:ref`

GetClimateHasMasser - returns 1 if the current climate shows the moon Masser
`(hasMasser:bool) GetClimateHasMasser climate:ref`

GetClimateHasSecunda - returns 1 if the current climate shows the moon Secunda
`(hasSecunda:bool) GetClimateHasSecunda climate:ref`

RefreshCurrentClimate - refreshes the climate info to reflect changes made by the SetClimateXXX functions
`(nothing) RefreshCurrentClimate`

SetClimateSunriseBegin - sets the time sunrise begins as a number of 10 minute units since midnight
`(nothing) SetClimateSunriseBegin time:int climate:ref`

SetClimateSunriseEnd - sets the time sunrise ends as a number of 10 minute units since midnight
`(nothing) SetClimateSunriseEnd time:int climate:ref`

SetClimateSunsetBegin - sets the time sunset begins as a number of 10 minute units since midnight
`(nothing) SetClimateSunsetBegin time:int climate:ref`

SetClimateSunsetEnd - sets the time sunset ends as a number of 10 minute units since midnight
`(nothing) SetClimateSunsetEnd time:int climate:ref`

SetClimateMoonPhaseLength - sets the number of days in the phase of the moons
`(nothing) SetClimateMoonPhaseLength nuPhaseLength:int climate:ref`

SetClimateHasMasser - sets whether the climate shows the moon Masser
`(nothing) SetClimateHasMasser hasMasser:bool climate:ref`

SetClimateHasSecunda - sets whether the climate shows the moon Secunda
`(nothing) SetClimateHasSecunda hasSecunda:bool climate:ref`

GetClimateVolatility - returns the volatility of the climate
`(volatility:int) GetClimateVolatility climate:ref`

SetClimateVolatility - sets the volatility of the climate
`(nothing) SetClimateVolatility volatility:int climate:ref`

### Clothing

Clothing is any wearable object that does not provide armor protection. Includes amulets and rings.

#### Qualities:

Enchantable, Inventory, Named, Wearable

#### Functions:

No additional functions have been defined.

### Creature

Creatures are one of two types of actors.

#### Qualities:

Actor, Attacking (only attack damage), Inventory, Magic Target

#### Values:

Creature Type (short) - the type of creature
Combat Skill (short) - the value for all combat skills for the creature
Magic Skill (short) - the value for all magic skills for the creature
Stealth Skill (short) - the value for all stealth skills for the creature
Reach (short) - the attack reach of the creature
Soul Level (short) - the soul level of the creature
Base Scale (float) - the base scale of the creature

#### Functions:

IsCreature - returns whether the reference or passed id is a creature
`(isCreature:bool) reference.IsCreature creature:ref`

GetCreatureType - returns the type of the creature (Undead, Humanoid, Daedrea etc)
`(creatureType:int) reference.GetCreatureType creature:ref`

SetCreatureType - attempts to change the type of the creature. This changes the type for the base object, so it affects all references to that object. If used to change the type of a "horse"-type creature to something else, the creature will no longer be ridable until its type is set back to "horse". The command will not allow you to set the creature's type to "horse" unless the creature's model contains the ActorParent node which allows it to be ridden, and it will not allow you to change the type of a ridable creature while it is being ridden.
`(typeSet:bool) reference.SetCreatureType creatureType:int`

GetCreatureCombatSkill - returns the combat skill for the creature
`(combatSkill:int) reference.GetCreatureCombatSkill creature:ref`

GetCreatureMagicSkill - returns the magic skill for the creature
`(magicSkill:int) reference.GetCreatureMagicSkill creature:ref`

GetCreatureStealthSkill - returns the stealth skill for the creature
`(stealthSkill:int) reference.GetCreatureStealthSkill creature:ref`

GetCreatureReach - returns the reach of the creature
`(reach:int) reference.GetCreatureReach creature:ref`

GetCreatureSoulLevel - returns the soul level of the creature
`(soulLevel:int) reference.GetCreatureSoulLevel creature:ref`

GetCreatureBaseScale - retuns the base scale of the creature
`(scale:float) reference.GetCreatureBaseScale creature:ref`

GetCreatureWalks - returns 1 if the Walks flag is set on the creature
`(walks:bool) reference.GetCreatureWalks creature:ref`

GetCreatureSwims - returns 1 if the Swims flag is set on the creature
`(swims:bool) reference.GetCreatureSwims creature:ref`

GetCreatureFlies - returns 1 if the Flies flag is set on the creature
`(flies:bool) reference.GetCreatureFlies creature:ref`

IsCreatureBiped - returns 1 if the Biped flag is set on the creature
`(biped:bool) reference.isCreatureBiped creature:ref`

CreatureHasNoMovement - returns 1 if the No Movement flag is set on the creature
`(noMovement:bool) reference.CreatureHasNoMovement creature:ref`

CreatureHasNoHead - returns 1 if the No Head flag is set on the creature
`(noHead:bool) reference.CreatureHasNoHead creature:ref`

CreatureHasNoLeftArm - returns 1 if the No Left Arm flag is set on the creature
`(noLeftArm:bool) reference.CreatureHasNoLeftArm creature:ref`

CreatureHasNoRightArm - returns 1 if the No Right Arm flag is set on the creature
`(noRightArm:bool) reference.CreatureHasNoRightArm creature:ref`

CreatureNoCombatInWater - returns 1 if the No Combat In Water flag is set on the creature
`(noCombat:bool) reference.CreatureNoCombatInWater creature:ref`

CreatureUsesWeaponAndShield - returns 1 if the Uses Weapon and Shield flag is set on the creature
`(weaponAndShield:bool) reference.CreatureUsesWeaponAndShield creature:ref`

GetRider - returns the NPC currently riding the calling horse.
`(rider:ref) reference.GetRider`

GetCreatureSoundBase - returns the creature from which the specified creature's sounds are derived, if any.
`(creature:ref) reference.GetCreatureSoundBase creature:ref`

SetCreatureSoundBase - "sets the creature from which the creature inherits its sounds. The inheriting creature must not itself be a sound base (mustn't define its own sounds), and the creature specified as the sound base must be a sound base (defining its own sounds) or null."
`(success:bool) reference.SetCreatureSoundBase soundBase:ref creature:ref`

HasModel - returns 1 if the creature's model list includes the specified .nif file. The file must appear in the creature's meshes folder. String must include the ".nif" extension and is case-insensitive.
`(hasModel:bool) reference.HasModel model:string creature:ref`

GetCreatureSound - returns the creature's sound associated with the specified action
`(sound:ref) reference.GetCreatureSound whichSound:actorSound creature:ref`

ToggleCreatureModel - toggles a model within a creature's model list on or off. The model path must be relative to the creature's model folder and include the ".nif" extension. When called on a reference which is currently being rendered, the reference must be disabled and then enabled before the change is visible.
`(nothing) reference.ToggleCreatureModel modelPath:string enableModel:bool creature:ref`

GetCreatureModelPaths - returns an Array containing the set of model paths in the creature's model list. Only those models which are toggled on are included.
`(modelPaths:Array) reference.GetCreatureModelPaths creature:ref`

SetCreatureSkill - sets the value of one of the creature's skills. Pass "stealth", "magic", or "combat" as the skill name. The skill value must be between 0 and 255.
`(nothing) reference.SetCreatureSkill skillName:string skillValue:int creature:ref`

### Combat Style

Combat styles are used by NPCs and creatures to determine behavior in combat.

#### Functions:

GetCombatStyle - returns the combat style assigned to the calling reference. Note that many actors are assigned no combat style in the editor (i.e. "DEFAULT" appears in the selection box); in that case this function returns zero.
`(combatStyle:ref) reference.GetCombatStyle`

#### Additional Combat Style Functions

Most of these functions get or set the values of properties defined in the Combat Style window for each combat style and follow the same syntax conventions.

Syntax:
`(value:numeric) GetCombatStyleXXX combatStyle:ref`
`(nothing) SetCombatStyleXXX newValue:numeric combatStyle:ref`

- Get/SetCombatStyleAcrobaticsDodgeChance
- Get/SetCombatStyleAttackChance
- Get/SetCombatStyleAttackDuringBlockMult
- Get/SetCombatStyleAttackNotUnderAttackMult
- Get/SetCombatStyleAttackSkillModBase
- Get/SetCombatStyleAttackSkillModMult
- Get/SetCombatStyleAttackUnderAttackMult
- Get/SetCombatStyleBlockChance
- Get/SetCombatStyleBlockNotUnderAttackMult
- Get/SetCombatStyleBlockSkillModBase
- Get/SetCombatStyleBlockSkillModMult
- Get/SetCombatStyleBlockUnderAttackMult
- Get/SetCombatStyleBuffStandoffDist
- Get/SetCombatStyleDodgeBackNotUnderAttackMult
- Get/SetCombatStyleDodgeBackTimerMax
- Get/SetCombatStyleDodgeBackTimerMin
- Get/SetCombatStyleDodgeBackUnderAttackMult
- Get/SetCombatStyleDodgeChance
- Get/SetCombatStyleDodgeFatigueModBase
- Get/SetCombatStyleDodgeFatigueModMult
- Get/SetCombatStyleDodgeFWAttackingMult
- Get/SetCombatStyleDodgeFWNotAttackingMult
- Get/SetCombatStyleDodgeFWTimerMax
- Get/SetCombatStyleDodgeFWTimerMin
- Get/SetCombatStyleDodgeLRChance
- Get/SetCombatStyleDodgeLRTimerMax
- Get/SetCombatStyleDodgeLRTimerMin
- Get/SetCombatStyleDodgeNotUnderAttackMult
- Get/SetCombatStyleDodgeUnderAttackMult
- Get/SetCombatStyleEncumberedSpeedModBase
- Get/SetCombatStyleEncumberedSpeedModMult
- Get/SetCombatStyleFleeingDisabled
- Get/SetCombatStyleGroupStandoffDist
- Get/SetCombatStyleH2HBonusToAttack
- Get/SetCombatStyleHoldTimerMax
- Get/SetCombatStyleHoldTimerMin
- Get/SetCombatStyleIdleTimerMax
- Get/SetCombatStyleIdleTimerMin
- Get/SetCombatStyleIgnoreAlliesInArea
- Get/SetCombatStyleKOBonusToAttack
- Get/SetCombatStyleKOBonusToPowerAttack
- Get/SetCombatStyleMeleeAlertOK
- Get/SetCombatStylePowerAttackChance
- Get/SetCombatStylePowerAttackFatigueModBase
- Get/SetCombatStylePowerAttackFatigueModMult
- Get/SetCombatStylePrefersRanged
- Get/SetCombatStyleRangedStandoffDist
- Get/SetCombatStyleRangeMaxMult
- Get/SetCombatStyleRangeOptimalMult
- Get/SetCombatStyleRejectsYields
- Get/SetCombatStyleRushAttackChance
- Get/SetCombatStyleRushAttackDistMult
- Get/SetCombatStyleStaggerBonusToAttack
- Get/SetCombatStyleStaggerBonusToPowerAttack
- Get/SetCombatStyleSwitchDistMelee
- Get/SetCombatStyleSwitchDistRanged
- Get/SetCombatStyleWillYield

### Door

Doors are used to move between interior cells and exterior worldspaces.

#### Qualities:

Audible

#### Functions:

IsLoadDoor - returns 1 if the calling reference is a load door
`(isLoadDoor:bool) reference.IsLoadDoor`

GetLinkedDoor - returns the door to which the calling load door is linked
`(linkedDoor:ref) reference.GetLinkedDoor`

GetTeleportCell - returns the cell to which the calling load door teleports
`(cell:ref) reference.GetTeleportCell`

IsOblivionGate -returns true if the door is flagged as an Oblivion gate in the editor.
`(isOBGate:bool) reference.IsOblivionGate door:ref`

IsHiddenDoor - returns 1 if the "hidden" flag is set for the door.
`(isHidden:bool) reference.IsHiddenDoor door:ref`

IsAutomaticDoor - returns 1 if the "Automatic" flag is set for the door.
`(isAutomatic:bool) reference.IsAutomaticDoor door:ref`

IsMinimalUseDoor - returns 1 if the "Minimal Use" flag is set for the door.
`(isMinimalUse:bool) reference.IsMinimalUseDoor door:ref`

SetIsHiddenDoor - sets or clears the "hidden" flag for the door.
`(nothing) reference.SetIsHiddenDoor setFlag:bool door:ref`

SetIsAutomaticDoor - sets or clears the "Automatic" flag for the door.
`(nothing) reference.SetIsAutomaticDoor setFlag:bool door:ref`

SetIsMinimalUseDoor - sets or clears the "Minimal Use" flag for the door.
`(nothing) reference.SetIsMinimalUseDoor setFlag:bool door:ref`

SetIsOblivionGate - sets or clears the "Oblivion Gate" flag for the door.
`(nothing) reference.SetIsOblivionGate setFlag:bool door:ref`

SetDoorTeleport - sets the reference, coordinates, and rotation to which the calling door teleports. Only the reference argument is required; the values for the others will be taken from the specified reference's coordinates and rotation if omitted. The bTemporary argument specifies that the change should not be saved in the savegame; by default, or if the argument is zero, the change will be saved.
`(nothing) reference.SetDoorTeleport teleportTo:ref x:float y:float z:float rot:float bTemporary:bool`

LinkToDoor - links the calling door reference to the specified door reference. This causes each of the doors to teleport to the other when activated. Both doors must be persistent references and neither can already be linked to another door. Actors will use the doors in their pathfinding. The change persists in the savegame.
`(linked:bool) reference.LinkToDoor otherDoor:ref`

GetDoorTeleportX - returns the x coordinate to which the calling door teleports.
`(coord:float) reference.GetDoorTeleportX`

GetDoorTeleportY - returns the y coordinate to which the calling door teleports.
`(coord:float) reference.GetDoorTeleportY`

GetDoorTeleportZ - returns the z coordinate to which the calling door teleports.
`(coord:float) reference.GetDoorTeleportZ`

GetDoorTeleportRot - returns the rotation to which the calling door teleports. This is the angle the player will be facing after activatingthe load door.
`(coord:float) reference.GetDoorTeleportRot`

GetTeleportCellName - when called on a teleporting door reference, returns the name of the cell or worldspace to which the door teleports
`(cellName:string) ref.GetTeleportCellName`

### Enchantment

An Enchantment is a group of magical effects that can be applied to enchantable objects.

#### Value:

Enchantment Type (short) - the type of object to which an enchantment may be applied
Charge (long) - the charge of the enchantment. Of unknown and dubious use - the number sometimes does not correspond to the value listed in the CS. The CS seems to list cost and charge both from the Cost value on the enchantment item.
Cost (long) - the cost in magicka charge consumed by each use of the enchantment

#### Functions:

GetEnchantmentType - returns the type of the enchantment
`(enchantType:int) GetEnchantmentType objectID:ref`

SetEnchantmentType - sets the type of the enchantment
`(nothing) SetEnchantmentType enchantType:int objectID:ref`

GetEnchantmentCharge - returns the charge of the enchantment. Of unknown and dubious use.
`(charge:int) GetEnchantmentCharge objectID:ref`

SetEnchantmentCharge - sets the charge of the enchantment. Of unknown and dubious use.
`(nothing) SetEnchantmentCharge nuCharge:int objectID:ref`

ModEnchantmentCharge - modifies the charge of the enchantment. Of unknown and dubious use.
`(nothing) ModEnchantmentCharge modifyBy:float objectID:ref`

GetEnchantmentCost - returns the magicka charge cost for using the enchantment
`(cost:int) GetEnchantmentCost objectID:ref`

SetEnchantmentCost - sets the cost for using the enchantment
`(nothing) SetEnchantmentCost nuCost:int objectID:ref`

ModEnchantmentCost - modifies the cost for using the enchantment up or down
`(nothing) ModEnchantmentCost modifyBy:float objectID:ref`

### Faction

#### Qualities:

Named

#### Functions:

FactionHasSpecialCombat - returns 1 if the Special Combat flag is set on the faction
`(hasSpecialCombat:bool) FactionHasSpecialCombat faction:ref`

IsFactionEvil - returns 1 if the faction is marked as evil
`(isEvil:bool) IsFactionEvil faction:ref`

IsFactionHidden - returns 1 if the faction is not shown on the player's faction sheet
`(isHidden:bool) IsFactionHidden faction:ref`

SetFactionEvil - changes the Evil flag on the faction. Changes are saved in the savegame
`(nothing) SetFactionEvil faction:ref isEvil:int`

SetFactionHidden - changes the Hidden flag on the faction. Changes are saved in the savegame
`(nothing) SetFactionHidden faction:ref isHidden:int`

SetFactionHasSpecialCombat - changes the Special Combat flag on the faction. Changes are saved in the savegame
`(nothing) SetFactionHasSpecialCombat faction:ref hasSpecialCombat:int`

GetNumRanks - returns the number of ranks in the faction.
`(numRanks:int) GetNumRanks faction:ref`

GetNthFactionRankName - returns the title of the nth rank in a faction. Optionally returns the female rank name.
`(rankName:string_var) GetNthFactionRankName faction:ref whichRank:int female:bool`

SetNthFactionRankNameEX - sets the title of the nth rank in a faction. Optionally sets the female rank name.
`(nothing)SetNthFactionRankNameEX path:formatString faction:ref whichRank:int female:bool`

### Flora

Plants which can be harvested for alchemical ingredients

#### Functions:

IsHarvested - returns 1 if the calling reference's ingredient has been harvested
`(isHarvested:bool) reference.IsHarvested`

SetHarvested - mark or unmark the calling reference as having been harvested. Changes are saved in the savegame.
`(nothing) reference.SetHarvested isHarvested:int`

GetIngredient - returns the ingredient contained in a plant.
`(ingredient:ref) reference.GetIngredient flora:ref`

SetIngredient - sets the ingredient contained in a plant. Omit the ingredient parameter or pass an empty ref variable to set it to "no ingredient."
`(nothing) reference.SetIngredient ingredient:ref flora:ref`

GetIngredientChance - returns the % chance of harvesting an ingredient from the plant for a specific season where 0 = spring, 1 = summer, 2 = autumn, and 3 = winter. Return value ranges from 0 to 100.
`(chance:int) reference.GetIngredientChance whichSeason:int flora:ref`

SetIngredientChance - sets the %chance of harvesting an ingredient based on the specified season.
`(nothing) reference.SetIngredientChance whichSeason:int newChance:int flora:ref`

### Ingredient

Ingredients are items that may be used to create Alchemy Items.

#### Qualities:

Edible, Inventory, Magic, Named, Scriptable, Simple

#### Functions

No additional functions have been defined.

### Leveled List

A list of creatures, NPCs, items, or spells. Changes made to lists using OBSE functions are not saved in the savegame, but persist for the duration of the game session after they are made. To make effectively "permanent" changes to a leveled list, include code similar to the following in a quest script:

    if ( GetGameRestarted ) ; runs once each time Oblivion is started
    	AddToLeveledList list object level
    	RemoveFromLeveledList list object
    endif

#### Functions:

AddToLeveledList - adds an object to a leveled creature, spell, or item list. Count defaults to 1 if unspecified.
`(nothing) AddToLeveledList leveledList:ref object:ref level:int count:int`

RemoveFromLeveledList - removes all occurences of an object from a leveled list and returns the number of occurences removed.
`(numRemoved:int) RemoveFromLeveledList leveledList:ref object:ref`

CalcLeveledItem - returns one item from a leveled item list, selected randomly for a character of the specified level. Oblivion selects a level range from which to choose using the game setting iLevItemLevelDifferenceMax. The item chosen is within the range [minLevel...maxLevel], where maxLevel is the level in the list closest to but not exceeding the character's level, and minLevel = maxLevel - levelDiff. If the "Calculate for all item <= level" flag is set for the leveled list, minLevel is always zero. This function checks the "Chance None" property of the leveled list, so it may return nothing based on that chance; pass 0 for the third parameter to override this behavior. In the case of leveled lists containing nested leveled lists, the function recurses through each list until it finds a non-leveled item. Omit the levelDiff parameter to use the current value of iLevItemLevelDifferenceMax.
`(randomItem:ref) CalcLeveledItem leveledList:ref level:int useChanceNone:bool levelDiff:int`

CalcLevItemNR - does the same thing as CalcLeveledItem but will not recurse through nested leveled lists. This means that unlike CalcLeveledItem, CalcLevItemNR can return another leveled list rather than a real object.
`(randomItem:ref CalcLevItemNR leveledList:ref level:int useChanceNone:bool levelDiff:int`

CalcLevItems - returns an Array of StringMaps representing items selected randomly from a leveled item list. This command uses the game code to select items, which means the items returned are the same as those the game would select for an actor of the specified level. Does not work with leveled spells or creatures. Each entry in the returned Array is a StringMap with the key-value pairs: "item":item (form) and "count":count (integer). The optional "count" parameter is 1 by default.
`(items:Array) CalcLevItems levItemList:ref level:int count:int`

GetCalcAllLevels - returns 1 if the "calculate for all levels <= PC level" flag is checked.
`(calcAllLevels:bool) GetCalcAllLevels leveledList:ref`

GetCalcEachInCount - returns 1 if the "calculate for each item in count" flag is checked.
`(calcEach:bool) GetCalcEachInCount leveledList:ref`

GetChanceNone - returns the chance from 0 to 100 that a leveled list returns no item.
`(chanceNone:int) GetChanceNone leveledList:ref`

GetNthLevItem - returns the Nth element in a leveled list, as ordered in the Construction Set.
`(element:ref) GetNthLevItem index:int leveledList:ref`

GetNthLevItemCount - returns the count of the Nth element of a leveled list.
`(count:int) GetNthLevItemCount index:int leveledList:ref`

GetNthLevItemLevel - returns the level of the Nth element of a leveled list.
`(level:int) GetNthLevItemLevel index:int leveledList:ref`

GetNumLevItems - returns the number of elements in a leveled list.
`(numItems:int) GetNumLevitems leveledList:ref`

GetLevItemByLevel - returns the first element of the specified level in the leveled list.
`(element:ref) GetLevItemByLevel whichLevel:int leveledList:ref`

RemoveLevItemByLevel - removes any elements of the specified level from a leveled list
`(numRemoved:int) RemoveLevItemByLevel whichLevel:int leveledList:ref`

ClearLeveledList - removes all elements from a leveled list.
`(nothing) ClearLeveledList leveledList:ref`

RemoveNthLevItem - removes the nth item from a leveled list.
`(nothing) RemoveNthLevItem index:int leveledList:ref`

GetLevItemIndexByLevel - returns the index of the first item of the specified level within a leveled list, or -1 if no item exists for that level.
`(index:int) GetLevItemIndexByLevel level:int leveledList:ref`

GetLevItemIndexByForm - returns the index of the first occurrence of the specified form in a leveled list, or -1 if the form is not found.
`(index:int) GetLevItemIndexByForm leveledList:ref formToFind:ref`

SetChanceNone - sets the chance that a leveled list generates no item.
`(nothing) SetChanceNone chance:int levlist:ref`

### Light

Objects which emit light. They may or may not have a visible model associated with them and may or may not be carriable.

#### Qualities:

Equippable, Inventory, Named, Simple, Audible

#### Value:

Radius (short) - the radius illuminated by the light

#### Functions:

IsLightCarriable - returns 1 if the light may be placed in an inventory.
`(isCarriable:bool) reference.IsLightCarriable light:ref`

GetLightRadius - returns the radius of the light.
`(radius:int) reference.GetLightRadius light:ref`

SetLightRadius - sets the radius of the light. Changes are not saved in the savegame.
`(nothing) reference.SetLightRadius radius:int light:ref`

GetLightRGB - returns the red, green, and blue components of the light's color as an Array of 3 elements of values 0 through 255. The first element corresponds to the red value, the second to green, and the third to blue.
`(rgb:Array) reference.GetLightRGB light:ref`

SetLightRGB - sets the red, green, and blue components of the light's color, accepting the components as an Array of 3 elements of values 0 through 255. The first element corresponds to the red value, the second to green, and the third to blue.
`(colorChanged:bool) reference.SetLightRGB rgb:Array light:ref`

GetLightDuration - returns the duration of the light as defined in the editor.
`(duration:int) reference.GetLightDuration light:ref`

SetLightDuration - sets the duration of the light.
`(nothing) reference.SetLightDuration duration:int light:ref`

GetTimeLeft - returns the amount of time left before the calling light reference expires.
`(timeLeft:float) reference.GetTimeLeft`

GetEquippedTorchTimeLeft - returns the amount of time before the torch equipped by the calling actor expires.
`(timeLeft:float) reference.GetEquippedTorchTimeLeft`

SetTimeLeft - sets the amount of time before the calling light reference expires.
`(nothing) reference.SetTimeLeft timeLeft:float`

### Magic Effect Setting

#### Qualities:

Description

#### Values:

Code (chars or long) - the magic effect code. In the CS this is a 4 character code (like FIDG or Z001). As a return value from OBSE functions it is a long with the same numerical value.
Base Cost (float) - the base cost multiplier for the effect
School (short) - the spell skill controlling the effect
Projectile Speed (float) - the projectile speed of the magic effect
Enchant Factor (float) - the constant effect enchantment factor which helps determine the maximum magnitude of the effect when enchanting
Barter Factor (float) - the constant effect barter factor which helps determine the increase in value when enchanting
Is Hostile flag (bool) - determines if the effect is hostile. Only hostile effects may be in a poison.

#### Functions:

GetMagicEffectCode - returns the magic effect code of the effect.
`(magicEffectCode:int) GetMagicEffectCode effect:chars`

GetMagicEffectChars - returns the 4-character code for a magic effect
`(chars:string) GetMagicEffectChars magicEffect:ref`

GetMagicEffectCharsC - returns the 4-character code for a magic effect
`(chars:string) GetMagicEffectCharsC effectCode:integer`

MagicEffectFromCode - given an effect code, returns the effect setting matching that code.
`(magicEffect:ref) MagicEffectFromCode effectCode:int`

MagicEffectFromChars - given a string representing a four-letter effect code (e.g. "REHE"), returns the effect setting matching that code
`(magicEffect:ref) MagicEffectFromChars effectChars:String`

MagicEffectCodeFromChars (MECodeFromChars) - given a string representing a four-letter effect code (e.g. "REHE"), returns the effect code for the associated effect setting.
`(effectCode:int) MagicEffectCodeFromChars effectChars:String`

GetMagicEffectBaseCost - returns the base cost of the magic effect
`(baseCost:float) GetMagicEffectBaseCost effect:chars`
`(baseCost:float) GetMEBaseCost effect:chars`
`(baseCost:float) GetMagicEffectBaseCostC effect:int`
`(baseCost:float) GetMEBaseCostC effect:int`

GetMagicEffectSchool - returns the controlling school of the magic effect
`(magicSchool:int) GetMagicEffectSchool effect:chars`
`(magicSchool:int) GetMESchool effect:chars`
`(magicSchool:int) GetMagicEffectSchoolC effect:int`
`(magicSchool:int) GetMESchoolC effect:int`

GetMagicEffectProjectileSpeed - returns the projectile speed of the magic effect
`(projectileSpeed:float) GetMagicEffectProjectileSpeed effect:chars`
`(projectileSpeed:float) GetMEProjSpeed effect:chars`
`(projectileSpeed:float) GetMagicEffectProjectileSpeedC effect:int`
`(projectileSpeed:float) GetMEProjSpeedC effect:int`

GetMagicEffectEnchantFactor - returns the constant effect enchantment factor of the magic effect
`(enchantFactor:float) GetMagicEffectEnchantFactor effect:chars`
`(enchantFactor:float) GetMEEnchant effect:chars`
`(enchantFactor:float) GetMagicEffectEnchantFactorC effect:int`
`(enchantFactor:float) GetMEEnchantC effect:int`

GetMagicEffectBarterFactor - returns the constant effect barter factor of the magic effect
`(enchantFactor:float) GetMagicEffectBarterFactor effect:chars`
`(enchantFactor:float) GetMEEBarter effect:chars`
`(enchantFactor:float) GetMagicEffectBarterFactorC effect:int`
`(enchantFactor:float) GetMEBarterC effect:int`

IsMagicEffectHostile - returns whether the magic effect is hostile
`(isHostile:bool) IsMagicEffectHostile effect:chars`
`(isHostile:bool) IsMEHostile effect:chars`
`(isHostile:bool) IsMagicEffectHostileC effect:int`
`(isHostile:bool) IsMEHostileC effect:int`

IsMagicEffectForSpellmaking - returns whether the magic effect can be used for spell making
`(isForSpellMaking:bool) IsMagicEffectForSpellmaking effect:chars`
`(isForSpellMaking:bool) IsMEForSpellmaking effect:chars`
`(isForSpellMaking:bool) IsMagicEffectForSpellmakingC effect:int`
`(isForSpellMaking:bool) IsMEForSpellmakingC effect:int`

IsMagicEffectForEnchanting - returns whether the magic effect can be used when enchanting
`(isForEnchanting:bool) IsMEForEnchanting effect:chars`
`(isForEnchanting:bool) IsMagicEffectForEnchantingC effect:int`
`(isForEnchanting:bool) IsMEForEnchantingC effect:int`

IsMagicEffectDetrimental - returns whether the magic effect harms the receipient
`(isDetrimental:bool) IsMagicEffectDetrimental effect:chars`
`(isDetrimental:bool) IsMEDetrimental effect:chars`
`(isDetrimental:bool) IsMagicEffectDetrimentalC effect:int`
`(isDetrimental:bool) IsMEDetrimentalC effect:int`

IsMagicEffectCanRecover - returns whether the target can recover from the effect
`(isCanRecover:bool) IsMagicEffectCanRecover effect:chars`
`(isCanRecover:bool) IsMECanRecover effect:chars`
`(isCanRecover:bool) IsMagicEffectCanRecoverC effect:int`
`(isCanRecover:bool) IsMECanRecoverC effect:int`

IsMagicEffectMagnitudePercent - returns whether the magic effect's magnitude is a percentage
`(isMagPercent:bool) IsMagicEffectMagnitudePercent effect:chars`
`(isMagPercent:bool) IsMEMagnitudePercent effect:chars`
`(isMagPercent:bool) IsMagicEffectMagnitudePercentC effect:int`
`(isMagPercent:bool) IsMEMagnitudePercentC effect:int`

MagicEffectFXPersists - returns whether the magic effect's graphics effects persist
`(FXPersists:bool) MagicEffectFXPersists effect:chars`
`(FXPersists:bool) MagicEffectFXPersistsC effect:int`

IsMagicEffectOnSelfAllowed - returns whether the magic effect can be cast on self
`(onSelfAllowed:bool) IsMagicEffectOnSelfAllowed effect:chars`
`(onSelfAllowed:bool) IsMEOnSelfAllowed effect:chars`
`(onSelfAllowed:bool) IsMagicEffectOnSelfAllowedC effect:int`
`(onSelfAllowed:bool) IsEOnSelfAllowedC effect:int`

IsMagicEffectOnTouchAllowed - returns whether the magic effect can be cast on touch
`(onTouchAllowed:bool) IsMagicEffectOnTouchAllowed effect:chars`
`(onTouchAllowed:bool) IsMagicEffectOnTouchAllowed effect:chars`
`(onTouchAllowed:bool) IsMagicEffectOnTouchAllowedC effect:int`
`(onTouchAllowed:bool) IsMagicEffectOnTouchAllowedC effect:int`

IsMagicEffectOnTargetAllowed - returns whether the magic effect can be cast on target
`(onTargetAllowed:bool) IsMagicEffectOnTargetAllowed effect:chars`
`(onTargetAllowed:bool) IsMEOnTargetAllowed effect:chars`
`(onTargetAllowed:bool) IsMagicEffectOnTargetAllowedC effect:int`
`(onTargetAllowed:bool) IsMEOnTargetAllowedC effect:int`

MagicEffectHasNoDuration - returns whether the magic effect doesn't use the duration value
`(hasNoDuration:bool) MagicEffectHasNoDuration effect:chars`
`(hasNoDuration:bool) MEHasNoDuration effect:chars`
`(hasNoDuration:bool) MagicEffectHasNoDurationC effect:int`
`(hasNoDuration:bool) MEHasNoDurationC effect:int`

MagicEffectHasNoMagnitude - returns whether the magic effect doesn't use the magnitude value
`(hasNoMag:bool) MagicEffectHasNoMagnitude effect:chars`
`(hasNoMag:bool) MEHasNoMagnitude effect:chars`
`(hasNoMag:bool) MagicEffectHasNoMagnitudeC effect:int`
`(hasNoMag:bool) MEHasNoMagnitudeC effect:int`

MagicEffectHasNoArea - returns whether the magic effect doesn't use the area value
`(hasNoArea:bool) MagicEffectHasNoArea effect:chars`
`(hasNoArea:bool) MEHasNoAreaC effect:int`
`(hasNoArea:bool) MagicEffectHasNoArea effect:chars`
`(hasNoArea:bool) MEHasNoAreaC effect:int`

MagicEffectHasNoIngredient - returns whether the magic effect has no ingredient
`(hasNoIngredient:bool) MagicEffectHasNoIngredient effect:chars`
`(hasNoIngredient:bool) MEHasNoIngredient effect:chars`
`(hasNoIngredient:bool) MagicEffectHasNoIngredientC effect:int`
`(hasNoIngredient:bool) MEHasNoIngredientC effect:int`

MagicEffectHasNoHitEffect - returns whether the magic effect has a graphic effect when it hits
`(hasNoHitEffect:bool) MagicEffectHasNoHitEffect effect:chars`
`(hasNoHitEffect:bool) MEHasNoHitEffect effect:chars`
`(hasNoHitEffect:bool) MagicEffectHasNoHitEffectC effect:int`
`(hasNoHitEffect:bool) MEHasNoHitEffectC effect:int`

MagicEffectUsesWeapon - returns whether the magic effect summons a weapon
`(usesWeapon:bool) MagicEffectUsesWeapon effect:chars`
`(usesWeapon:bool) MEUsesWeapon effect:chars`
`(usesWeapon:bool) MagicEffectUsesWeaponC effect:int`
`(usesWeapon:bool) MEUsesWeaponC effect:int`

MagicEffectUsesArmor - returns whether the magic effect summons armor
`(usesArmor:bool) MagicEffectUsesArmor effect:chars`
`(usesArmor:bool) MEUsesArmorC effect:int`
`(usesArmor:bool) MagicEffectUsesArmor effect:chars`
`(usesArmor:bool) MEUsesArmorC effect:int`

MagicEffectUsesCreature - returns whether the magic effect summons a creature
`(usesCreature:bool) MagicEffectUsesCreature effect:chars`
`(usesCreature:bool) MEUsesCreature effect:chars`
`(usesCreature:bool) MagicEffectUsesCreatureC effect:int`
`(usesCreature:bool) MEUsesCreatureC effect:int`

MagicEffectUsesSkill - returns whether the magic effect affects a skill
`(usesSkill:bool) MagicEffectUsesSkill effect:chars`
`(usesSkill:bool) MagicEffectUsesSkillC effect:int`
`(usesSkill:bool) MagicEffectUsesSkill effect:chars`
`(usesSkill:bool) MagicEffectUsesSkillC effect:int`

MagicEffectUsesAttribute - returns whether the magic effect affects an attribute
`(usesAttribute:bool) MagicEffectUsesAttribute effect:chars`
`(usesAttribute:bool) MEUsesAttribute effect:chars`
`(usesAttribute:bool) MagicEffectUsesAttributeC effect:int`
`(usesAttribute:bool) MEUsesAttributeC effect:int`

MagicEffectUsesOtherActorValue - returns whether the magic effect affects an actor value that is not a skill or an attribute
`(usesOtherActorVal:bool) MagicEffectUsesOtherActorValue effect:chars`
`(usesOtherActorVal:bool) MEUsesOtherActorValue effect:chars`
`(usesOtherActorVal:bool) MagicEffectUsesOtherActorValueC effect:int`
`(usesOtherActorVal:bool) MEUsesOtherActorValueC effect:int`

GetMagicEffectOtherActorValue - returns the actor value (skill, attribute or other) affected by the magic effect
`(actorValue:int) GetMagicEffectOtherActorValue effect:chars`
`(actorValue:int) GetMEOtherActorValue effect:chars`
`(actorValue:int) GetMagicEffectOtherActorValueC effect:int`
`(actorValue:int) GetMEOtherActorValueC effect:int`

GetMagicEffectUsedObject - returns the weapon, armor or creature summoned by the magic effect
`(objectID:ref) GetMagicEffectUsedObject effect:chars`
`(objectID:ref) GetMEUsedObject effect:chars`
`(objectID:ref) GetMagicEffectUsedObjectC effect:int`
`(objectID:ref) GetMEUsedObjectC effect:int`

RemoveNthMagicEffectCounter(C) - removes the nth counter-effect for the magic effect. A 'C' version is also provided.
`(nothing) RemoveNthMagicEffectCounter whichCounter:int magicEffect:ref`
`(nothing) RemoveNthMagicEffectCounterC whichCounter:int magicEffectCode:int`

AddMagicEffectCounter(C) - adds a counter-effect to the magic effect. The 'C' version accepts magic effect codes for both arguments.
`(nothing) AddMagicEffectCounter counterEffect:ref magicEffect:ref`
`(nothing) AddMagicEffectCounterC counterEffectCode:int magicEffectCode:int`

GetMagicEffectCounters(C) - returns an Array containing the effect codes of all counter-effects for the specified magic effect.
`(counters:Array) GetMagicEffectCounters magicEffect:ref`
`(counters:Array) GetMagicEffectCountersC magicEffectCode:int`

SetMagicEffectCounters(C) - accepts an Array of effect codes and assigns those effects as counter-effects for the specified magic effect, overriding any existing counter-effects. The user must guarantee that the passed array contains valid effect codes and nothing else. The function returns 1 if the new counter-effects were successfully applied, 0 otherwise.
`(effectsApplied:bool) SetMagicEffectCounters counterEffects:Array magicEffect:Ref`
`(effectsApplied:bool) SetMagicEffectCountersC counterEffects:Array magicEffectCode:int`

### Additional Magic Effect Functions

These functions can be used to retrieve or modify the properties of magic effect settings as defined in the Magic Effects window of the editor. Because they all follow similar syntax conventions and are largely self-explanatory, most are not documented individually. Versions of the commands ending in 'C' take a numeric magic effect code rather than a Magic Effect form as the argument to indicate the effect. All of these functions have abbreviated alternate names in which "MagicEffect" is replaced by "ME", i.e. GetMagicEffectName can also be written as GetMEName.

#### String functions:

Get versions of these commands return a string; Set versions take a string as an argument.

##### Syntax:

`(string) GetMagicEffectXXX effect:refOrCode`
`(nothing) SetMagicEffectXXX newValue:string effect:refOrCode`

- GetMagicEffectName
- GetMagicEffectNameC
- GetMagicEffectIcon
- GetMagicEffectIconC
- GetMagicEffectModel
- GetMagicEffectModelC
- SetMagicEffectName
- SetMagicEffectNameC
- SetMagicEffectIcon
- SetMagicEffectIconC
- SetMagicEffectModel
- SetMagicEffectModelC

#### Form functions:

Get versions of these commands return a form (i.e. an effect shader, sound, etc); Set versions take a form as an argument.

##### Syntax:

`(object:ref) GetMagicEffectXXX effect:refOrCode`
`(nothing) SetMagicEffectXXX newValue:ref effect:refOrCode`

- GetMagicEffectHitShader
- GetMagicEffectHitShaderC
- GetMagicEffectEnchantShader
- GetMagicEffectEnchantShaderC
- GetMagicEffectLight
- GetMagicEffectLightC
- GetMagicEffectCastingSound
- GetMagicEffectCastingSoundC
- GetMagicEffectBoltSound
- GetMagicEffectBoltSoundC
- GetMagicEffectHitSound
- GetMagicEffectHitSoundC
- GetMagicEffectAreaSound
- GetMagicEffectAreaSoundC
- SetMagicEffectCastingSound
- SetMagicEffectCastingSoundC
- SetMagicEffectBoltSound
- SetMagicEffectBoltSoundC
- SetMagicEffectHitSound
- SetMagicEffectHitSoundC
- SetMagicEffectAreaSound
- SetMagicEffectAreaSoundC
- SetMagicEffectLight
- SetMagicEffectLightC
- SetMagicEffectUsedObject
- SetMagicEffectUsedObjectC
- SetMagicEffectHitShader
- SetMagicEffectHitShaderC
- SetMagicEffectEnchantShader
- SetMagicEffectEnchantShaderC

#### Numeric Functions:

These get or set numeric/boolean properties of Magic Effects.

##### Syntax:

`(value:numeric) GetMagicEffectXXX effect:refOrCode`
`(nothing) SetMagicEffectXXX newValue:numeric effect:refOrCode`

- GetMagicEffectNumCounters - returns the number of counter-effects for the magic effect
- GetMagicEffectNumCountersC
- GetMagicEffectResistValue - returns an actor value
- GetMagicEffectResistValueC
- GetNthMagicEffectCounter
- GetNthMagicEffectCounterC
- SetMagicEffectIsHostile
- SetMagicEffectIsHostileC
- SetMagicEffectCanRecover
- SetMagicEffectCanRecoverC
- SetMagicEffectIsDetrimental
- SetMagicEffectIsDetrimentalC
- SetMagicEffectMagnitudePercent
- SetMagicEffectMagnitudePercentC
- SetMagicEffectOnSelfAllowed
- SetMagicEffectOnSelfAllowedC
- SetMagicEffectOnTouchAllowed
- SetMagicEffectOnTouchAllowedC
- SetMagicEffectOnTargetAllowed
- SetMagicEffectOnTargetAllowedC
- SetMagicEffectNoDuration
- SetMagicEffectNoDurationC
- SetMagicEffectNoMagnitude
- SetMagicEffectNoMagnitudeC
- SetMagicEffectNoArea
- SetMagicEffectNoAreaC
- SetMagicEffectFXPersists
- SetMagicEffectFXPersistsC
- SetMagicEffectForSpellmaking
- SetMagicEffectForSpellmakingC
- SetMagicEffectForEnchanting
- SetMagicEffectForEnchantingC
- SetMagicEffectNoIngredient
- SetMagicEffectNoIngredientC
- SetMagicEffectUsesWeapon
- SetMagicEffectUsesWeaponC
- SetMagicEffectUsesArmor
- SetMagicEffectUsesArmorC
- SetMagicEffectUsesCreature
- SetMagicEffectUsesCreatureC
- SetMagicEffectUsesSkill
- SetMagicEffectUsesSkillC
- SetMagicEffectUsesAttribute
- SetMagicEffectUsesAttributeC
- SetMagicEffectUseActorValue
- SetMagicEffectUseActorValueC
- SetMagicEffectNoHitEffect
- SetMagicEffectNoHitEffectC
- SetMagicEffectSchool
- SetMagicEffectSchoolC
- SetMagicEffectBaseCost
- SetMagicEffectBaseCostC
- SetMagicEffectResistValue
- SetMagicEffectResistValueC
- SetMagicEffectEnchantFactor
- SetMagicEffectEnchantFactorC
- SetMagicEffectBarterFactor
- SetMagicEffectBarterFactorC
- SetMagicEffectProjectileSpeed
- SetMagicEffectProjectileSpeedC
- SetMagicEffectOtherActorValue
- SetMagicEffectOtherActorValueC

### Map Marker

A map marker is a reference to a static object of the type "mapmarker" defined as a default object in the editor. Map marker references have additional information such as a id, type of location, etc.

#### Qualities:

Named

#### Functions:

IsMapMarkerVisible - returns 1 if the map marker can be seen on the player's map
`(visible:bool) reference.IsMapMarkerVisible`

SetMapMarkerVisible - sets whether the map marker can be seen on the player's map
`(nothing) reference.SetMapMarkerVisible visible:bool`

CanTravelToMapMarker - returns 1 if the player can travel to the map marker by clicking on it in the map menu
`(canTravel:bool) reference.CanTravelToMapMarker`

SetCanTravelToMapMarker - sets whether the player can travel to the map marker by clicking it in the map menu
`(nothing) reference.SetCanTravelToMapMarker canTravel:bool`

GetMapMarkerType - returns the type of icon used to represent the location on the map.
`(markerType:int) reference.GetMapMarkerType`

SetMapMarkerType - sets the type of icon used to represent the location on the map.
`(nothing) reference.SetMapMarkerType markerType:int`

GetMapMarkers - returns an Array containing all map marker references. The filter argument can be used to filter out markers based on their visibility and accessibility: pass 0 to include only visible markers which can be fast-traveled to, 1 to include all visible markers, and 2 to include all markers, including those which are not visible. The default filter value is 1. Pass a markerType parameter to include only markers of the specified type; omit it or pass zero to include all types.
`(markers:Array) GetMapMarkers filter:int markerType:int`

### NPC

#### Qualities:

Actor, Class, Container, Magic Target

#### Values:

Equipped Items - NPC can equip and use items
Merchant Container - NPCS may have a merchant container which holds items they sell and buy

#### Functions:

GetEquippedObject - returns the base object of the item equipped in the specified slot
`(objectID:ref) reference.GetEquippedObject slot:int`

GetEquipmentSlotMask - Returns the base object of the first equipped object to match the specified equipment slot mask. If no 'value' parameter is specified, it is assumed to be the same value as the 'mask' parameter. For example, an object taking up the UpperBody, LowerBody, and Foot slots would have a mask of 4 + 8 + 32 = 44. See the "equipment slot bit assignments" list for more info.
`(objectID:ref) reference.GetEquipmentSlotMask slotMask:int value:int`

See also:

- GetEquippedCurrentCharge
- ModEquippedCurrentCharge
- SetEquippedCurrentCharge
- GetEquippedCurrentHealth
- ModEquippedCurrentHealth
- SetEquippedCurrentHealth
- GetEquippedWeaponPoison
- SetEquippedWeaponPoison
- RemoveEquippedWeaponPoison

GetMerchantContainer - returns the reference to the NPC's merchant container
`(containerReference:ref) npc.GetMerchantContainer`

SetMerchantContainer - replaces the specified mechant's container and returns the old container. If the specified NPC does not have a merchant container, or if the passed reference is not a container the function does nothing and will return 0.
`(oldContainerRef:ref) npc.SetMerchantContainer nuContainer:ref`

GetHorse - returns the horse currently ridden by the calling NPC. Note that this function returns a reference while the NPC is in the process of walking toward a horse with the intention of mounting it.
`(horse:ref) reference.GetHorse`

GetTravelHorse - returns a reference to the travel horse used by the calling reference.
`(horse:ref) reference.GetTravelHorse`

IsFemale - returns 1 if the NPC is female.
`(isFemale:bool) reference.IsFemale npc:ref`

SetTravelHorse - Sets the travel horse used by the calling reference to the horse reference specified. Changes are not saved in the savegame.
`(nothing) reference.SetTravelHorse horse:ref`

CopyHair - Copies the hair style, length, and color from one NPC to another. Changes alter the base actor and are not saved in the savegame unless called on the player. Changes will not be visible until the actor is reloaded; calling disable followed by enable a frame later will force the NPC to reload, updating the hair. Changes do appear to be saved for the player, but may not be visible until the game is reloaded.
`(nothing) reference.CopyHair copyFrom:ref copyTo:ref`

CopyEyes - Copies the eyes used by one npc onto another, with the same caveats as CopyHair.
`(nothing) reference.CopyEyes copyFrom:ref copyTo:ref`

SetHair - Sets the hair on the NPC to a hairstyle predefined in the CS, with the same caveats as CopyHair.
`(nothing) reference.SetHair hairStyle:ref npc:ref`

SetEyes - Sets the eyes on the NPC to a set of eyes predefined in the CS, with the same caveats as CopyHair.
`(nothing) reference.SetEyes eyes:ref npc:ref`

GetRace - returns the race of an NPC.
`(race:ref) reference.GetRace npc:ref`

CopyRace - modifies the calling NPC reference to be the same race as the passed base NPC. The calling NPC gets the same skeleton, textures, and other race attributes of the specified base NPC. Its facial parameters, hear, and eyes do not change. This command affects the base object of the calling NPC, and should only be used on references which are unique (no other references share the same base form). Note that if the NPC's new race uses a different voice than its old voice, it may not audibly speak any race-specific dialog which has not been recorded for the new voice.
`(nothing) reference.CopyRace sourceNPC:ref`

GetHair - returns the NPC's hairstyle
`(hair:ref) reference.GetHair npc:ref`

GetEyes - returns the NPC's eyes
`(eyes:ref) reference.GetEyes npc:ref`

GetHairColor - returns the RGB value of the NPC's hair color
`(color:int) reference.GetHairColor rgb:int npc:ref`

GetTrainerLevel - returns the level at which the NPC offers training
`(level:int) reference.GetTrainerLevel npc:ref`

GetTrainerSkill - returns the skill in which the NPC offers training as an actor value code
`(skill:int) reference.GetTrainerSkill npc:ref`

SetTrainerLevel - sets the level at which an NPC offers training
`(nothing) reference.SetTrainerLevel newLevel:int npc:ref`

SetTrainerSkill - sets the skill in which an NPC offers training
`(nothing) reference.SetTrainerSkill newSkill:actorValue npc:ref`

GetServicesMask - returns an integer code representing the services offered by an NPC. The code is obtained by ORing (adding) service flags
`(servicesMask:int) reference.GetServicesMask npc:ref`

OffersServicesC - returns 1 if the NPC offers all of the services specified by the services mask
`(offersServices:bool) reference.OffersServicesC serviceFlags:int npc:ref`

SetOffersServicesC - sets the services offered by the NPC to the specified services mask.
`(nothing) reference.SetOffersServicesC serviceFlags:int npc:ref`

OffersXXX - these functions return 1 if the NPC offers the specified service
`(offersService:bool) reference.OffersXXX npc:ref`

- OffersWeapons
- OffersArmor
- OffersClothing
- OffersBooks
- OffersLights
- OffersIngredients
- OffersApparatus
- OffersMiscItems
- OffersMagicItems
- OffersSpells
- OffersPotions
- OffersTraining
- OffersRecharging
- OffersRepair

SetOffersXXX - these functions toggle the specified service offered by the NPC.
`(nothing) reference.SetOffersXXX offersService:bool npc:ref`

- SetOffersWeapons
- SetOffersArmor
- SetOffersClothing
- SetOffersBooks
- SetOffersIngredients
- SetOffersSpells
- SetOffersLights
- SetOffersMiscItems
- SetOffersMagicItems
- SetOffersApparatus
- SetOffersPotions
- SetOffersTraining
- SetOffersRecharging
- SetOffersRepair

### Pathgrid

A pathgrid is a set of nodes connected by edges which is used by actors to navigate the world. Path nodes are not references, so commands cannot be called on them directly. Instead, OBSE provides an integer NodeID type uniquely describing a node; this ID can be passed to pathgrid commands to retrieve or modify the properties of a pathgrid. Note that a NodeID is only valid for as long as the player remains in the same cell; for practical purposes they should be considered valid only for one frame. Path nodes can be disabled, in which case actors will ignore them while pathfinding.

#### Functions:

GetPathNodesInRadius - returns an Array of all path nodes located within the circular area described by the center point (x, y) and the radius. By default, disabled nodes are ignored; pass 1 for the optional fourth argument to include them.
`(nodes:Array) GetPathNodesInRadius centerX:float centerY:float radius:float includeDisabledNodes:bool`

GetPathNodesInRect - returns an Array of all path nodes located within the rectangular area described by the center point (x, y) and the extents along the x and y axes (i.e. half-width and half-height). An angle of rotation in radians can optionally be specified; if omitted the rectangle is assumed to be aligned with the world axes. By default, disabled nodes are ignored; pass 1 for the optional sixth argument to include them.
`(nodes:Array) GetPathNodesInRect centerX:float centerY:float extentX:float extentY:float angle:float includeDisabledNodes:bool`

GetPathNodePos - returns the x, y, or z coordinate of the specified path node.
`(pos:float) GetPathNodePos nodeID:int whichPos:axis`

IsPathNodeDisabled - returns 1 if the path node is disabled.
`(disabled:bool) IsPathNodeDisabled nodeID:int`

SetPathNodeDisabled - enables or disables the specified path node. This node will no longer be used in future pathfinding attempts, but actors who have already built a path including this node may continue along it normally. If this is undesirable, calling EvaluatePackage on the actor will force it to build a new path.
`(nothing) SetPathNodeDisabled nodeID:int disable:bool`

GetPathNodeLinkedRef - returns the persistent reference linked to this node in the editor, if any.
`(linked:ref) GetPathNodeLinkedRef nodeID:int`

PathEdgeExists - returns 1 if the two nodes are connected.
`(exists:bool) PathEdgeExists nodeID:int nodeID:int`

### Player

#### Qualities:

Actor, Class, Container, Magic Target

#### Functions:

GetCrosshairRef - returns a reference to whatever is currently under the player's crosshair. Generally returns zero when called during menumode. Note that this function will return non-activatable references as well; use IsActivatable to determine if the reference can be activated normally.
`(crosshairRef:ref) GetCrosshairRef`

GetPlayersLastRiddenHorse - returns a reference to the horse most recently ridden by the player
`(horse:ref) GetPlayersLastRiddenHorse`
`(horse:ref) GetPCLastHorse`

SetPlayersLastRiddenHorse - marks the specified horse as the horse most recently ridden by the player. This is the horse that will accompany the player when fast traveling while dismounted. The argument must be a Creature of type Horse. Additionally, in order for the new horse to fast travel with the player it must not be owned by anyone other than the player.
`(successfullySet:bool) SetPlayersLastRiddenHorse horse:ref`

ClearPlayersLastRiddenHorse - clears the game's memory of the horse last ridden by the player. This prevents any horse from accompanying the player when fast traveling, provided the player is not mounted on a horse when he travels.
`(nothing) ClearPlayersLastRiddenHorse`

GetPlayersLastActivatedLoadDoor - returns a reference to the load door most recently activated by the player.
`(loadDoor:ref) GetPlayersLastActivatedLoadDoor`
`(loadDoor:ref) GetPCLastLoadDoor`

GetGodMode - returns 1 if the player has toggled god mode on
`(godMode:bool) GetGodMode`

SetPCAMurderer - sets whether the PC is a murderer or not
`(nothing) SetPCAMurderer isMurderer:bool`

GetPlayerSpell - returns the objectID of the player's current spell
`(spell:ref) GetPlayerSpell`

GetPlayerSpellCount - returns the player spell count
`(count:int) GetSpellCount`

GetNthPlayerSpell - returns the nth player spell. whichSpell is an index that starts at 0 for the first spell in the list. Note that the CS compiler doesn't expect spells to be returned as a ref. If you are calling this function multiple times to set the same ref variable you need to assign that variable to some other type (say a weapon) in between your calls to this function. Otherwise the ref will continue to keep the value from the first call.
`(spell:ref) GetNthPlayerSpell whichSpell:int`
`(spell:ref) GetNthSpell whichSpell:int`

GetPCMajorSkillUps - returns the number of major skill advancements toward the player's next level.
`(skillUps:int) GetPCMajorSkillUps`

SetPCMajorSkillUps - sets the number of major skill advancements toward the player's next level
`(nothing) SetPCMajorSkillUps skillUps:int`

GetPCAttributeBonus - returns the number of skill advancements contributing to the specified attribute's bonus for the next level. Note that game setting multipliers applied to these values determine the actual bonus at level-up. Returns -1 if passed an invalid actor value, including Luck.
`(bonus:int) GetPCAttributeBonus actorValue:string`

SetPCAttributeBonus - sets the number of skill advancements contributing to the specified attribute's bonus for the next level. Note that game setting multipliers applied to these values determine the actual bonus at level-up. Does not affect Luck bonus.
`(bonus:int) GetPCAttributeBonus actorValue:string bonus:int`

GetTotalPCAttributeBonus - returns the sum of the player's attribute bonuses
`(bonus:int) GetTotalPCAttributeBonus`

ModPCSpellEffectiveness - alters the script modifier applied to the player's spell effectiveness. This works similarly to Oblivion's ModAV command. Positive values increases the modifier, negative values decrease it. Any game calculations involving player spell effectiveness will use the modified value (base effectiveness + modifier). By default, the effects of this command persist until the end of the current game session. Pass 1 for the second parameter to save the amount modified in the savegame; it will then be applied every time the savegame is reloaded, and removed when reloading a different savegame.
`(nothing) ModPCSpellEffectiveness modBy:float persist:bool`

GetPCSpellEffectivenessModifier - returns the current value of the script modifier for player spell effectiveness. Subtract this value from the return value of Player.GetSpellEffectiveness to get the player's base spell effectiveness.
`(modifier:float) GetPCSpellEffectivenessModifier`

GetPCTrainingSessionsUsed - returns the number of times the player has trained during his current level
`(numSessions:int) GetPCTrainingSessionsUsed`

SetPCTrainingSessionsUsed - sets the number of times the player has trained during his current level
`(nothing) SetPCTrainingSessionsUsed numSessions:int`

ModPCMovementSpeed - applies a positive or negative modifier to the player's speed attribute as used in calculating his movement speed while swimming, walking, or running. The actual attribute is not modified, but movement calculations use the attribute value plus the modifier. Positive modifiers well above the maximum value of the speed attribute are permitted and effective; minimum speed including the modifier is limited to zero. By default, the effects of this command persist until the end of the current game session. Pass 1 for the second parameter to save the amount modified in the savegame; it will then be applied every time the savegame is reloaded, and removed when reloading a different savegame.
`(nothing) ModPCMovementSpeed modBy:float persist:bool`

GetPCMovementSpeedModifier - returns the current modifier applied to the player's speed for use in movement speed calculations. Because multiple mods may change the modifier this command returns the sum of all calls to ModPCMovementSpeed.
`(modifier:float) GetPCMovementSpeedModifier`

GetPlayerBirthsign - returns the birthsign chosen by the player
`(birthsign:ref) GetPlayerBirthsign`

SetPlayerBirthsign - changes the player's birthsign to the one specified. This removes all effects of the previous birthsign and applies the effects of the new one.
`(nothing) SetPlayerBirthsign birthsign:ref`

GetTelekinesisRef - returns a reference to the object being manipulated by the player through telekinesis, if any
`(telekinesisRef:ref) GetTelekinesisRef`

GetCurrentRegions - returns an Array of all the regions in which the player is currently located, if any. In interior cells generally returns 0. Regions in exterior cells can overlap, therefore it's possible for the player to be in several regions simultaneously.
`(regions:Array) GetCurrentRegions`

GetPCLastDroppedItem - returns the base object of the item most recently dropped by the player
`(item:ref) GetPCLastDroppedItem`

GetPCLastDroppedItemRef - returns the reference of the item most recently dropped by the player
`(item:ref) GetPCLastDroppedItemRef`

GetPCAttributeBonusC - returns the level-up bonus for the specified attribute
`(short) GetPCAttributeBonusC actorValueCode:integer`

SetPCAttributeBonusC - sets the level-up bonus for the specified attribute
`(nothing) SetPCAttributeBonusC actorValueCode:integer`

GetLastUsedSigilStone (GetLastSS) - returns the sigil stone most recently used to enchant an item during the current game session
`(ref) GetLastUsedSigilStone`

GetLastSigilStoneEnchantedItem (GetLastSSItem) - returns the unenchanted item most recently enchanted with a sigil stone during the current game session
`(ref) GetLastSigilStoneEnchantedItem`

GetLastSigilStoneCreatedItem (GetLastSSCreated) - returns the enchanted item most recently created with a sigil stone during the current game session
`(ref) GetLastSigilStoneCreatedItem`

### Projectile

A reference to an arrow or magic projectile in the gameworld. Note that these references are destroyed by the game after a certain period of time. If stored in a reference variable, make sure the reference is still valid before using it in a function. Also note that calling GetBaseObject on a magic projectile will return the same reference; in other words, magic projectile references are their own base objects.

#### Functions:

GetProjectileType - returns the type of the projectile
`(projectileType:int) reference.GetProjectileType`

GetProjectileSource - returns the caster of a magic projectile or the archer who fired an arrow projectile
`(source:ref) reference.GetProjectileSource`

GetMagicProjectileSpell - returns the spell attached to a magic projectile
`(spell:ref) reference.GetMagicProjectileSpell`
`(spell:ref) reference.GetMPSpell`

SetMagicProjectileSpell - changes the spell attached to a magic projectile
`(nothing) reference.SetMagicProjectileSpell newSpell:ref`
`(nothing) reference.SetMPSpell newSpell:ref`

GetArrowProjectileEnchantment - returns the enchantment on an arrow projectile
`(enchantment:ref) reference.GetArrowProjectileEnchantment`
`(enchantment:ref) reference.GetAPEnch`

GetArrowProjectileBowEnchantment - returns the enchantment on an arrow derived from the bow from which it was fired
`(enchantment:ref) reference.GetArrowProjectileBowEnchantment`
`(enchantment:ref) reference.GetAPBowEnch`

GetArrowProjectilePoison - returns the poison on an arrow projectile
`(poison:ref) reference.GetArrowProjectilePoison`
`(poison:ref) reference.GetAPPoison`

SetPlayerProjectile - sets the player as the source of the projectile. Actors hit by the projectile will react as if the player had cast the spell or fired the arrow.
`(nothing) reference.SetPlayerProjectile`

SetProjectileSource - sets the source of a projectile. If an actor other than the player is set as the source, the target of the projectile will not necessarily respond to the attack.
`(nothing) reference.SetProjectileSource actor:ref`

SetArrowProjectileEnchantment - sets the arrow enchantment associated with the calling projectile
`(nothing) reference.SetArrowProjectileEnchantment enchantment:ref`

SetArrowProjectileBowEnchantment - sets the bow enchantment associated with the calling projectile
`(nothing) reference.SetArrowProjectileBowEnchantment enchantment:ref`

SetArrowProjectilePoison - sets the poison on the calling projectile
`(nothing) reference.SetArrowProjectilePoison poison:ref`

GetProjectileSpeed - returns the speed of the projectile
`(speed:float) reference.GetProjectileSpeed`

GetProjectileDistanceTraveled - returns the total distance traveled by the calling projectile. Currently does not work for arrow projectiles.
`(distance:float) reference.GetProjectileDistanceTraveled`

GetProjectileLifetime - returns the number of seconds for which the calling projectile has existed
`(lifetime:float) reference.GetProjectileLifetime`

SetProjectileSpeed - sets the speed of the projectile. Note that other factors affect the movement of a projectile so a speed of zero does not necessarily completely halt the projectile.
`(nothing) reference.SetProjectileSpeed speed:float`

GetProjectile - returns the projectile most recently fired by the calling actor. Optionally specify the type (1 for arrows, 2 for magic, 0 for either) and the arrow, spell, or staff enchantment to match. The minLifetime parameter specifies how old (in seconds) a projectile can be before it is ignored.
`(projectile:ref) reference.GetProjectile type:int minLifetime:float arrowOrMagicItemID:ref`

### Quest

#### Functions

SetActiveQuest - sets the players active quest
`(nothing) SetActiveQuest quest:ref`

GetActiveQuest - returns the player's active quest, if any
`(ref) GetActiveQuest`

ClearActiveQuest - clears the player's active quest, if any.
`(nothing) ClearActiveQuest`

GetCurrentQuests - returns a list of all currently active (uncompleted) quests. Note that this list includes quests which do not appear in the journal
`(Array) GetCurrentQuests`

GetCompletedQuests - returns a list of all completed quests
`(Array) GetCompletedQuests`

IsQuestComplete - returns 1 if the specified quest is marked as 'completed'.
`(completed:bool) IsQuestComplete quest:ref`

UncompleteQuest - removes the 'completed' flag from the specified quest
`(nothing) UncompleteQuest quest:ref`

QuestExists - returns 1 if a quest exists with the specified editorID
`(questExists:bool) QuestExists questEditorID:string`

GetStageIDs - returns an Array containing the numeric index of each quest stage associated with the specified quest
`(stageIDs:array) GetStageIDs quest:ref`

GetStageEntries - returns an Array of all of the entries associated with the specified quest stage. Each element of the array is a Stringmap containing the following fields: "day" (1-31), "month" (1-12), and "year", representing the date at which the entry was added to the player's journal, and "text" containing the log text for the entry. If the entry has not been added to the player's journal, the date fields will all be zero.
`(entries:Array) GetStageEntries quest:ref stageID:int`

SetStageText - sets the log text associated with the specified quest stage entry for the specified quest. The change remains in effect for the duration of the game session or until undone with UnsetStageText.
`(textModified:bool) SetStageText quest:ref stageIndex:int entryIndex:int text:string`

UnsetStageText - reverses any modification made to the specified log entry text using SetStageText.
`(nothing) UnsetStageText quest:ref stageIndex:int entryIndex:int`

SetStageDate - for a quest stage entry which has already been added to the player's journal, modifies the date at which the entry was added. Specify the day of the month (1-31), month (1-12), and year.
`(dateSet:bool) SetStageDate quest:ref stageIndex:int entryIndex:int day:int month:int year:int`

### Reference

An instance of an object in the gameworld. In general, a reference has access to the functions associated with its base type as well.

#### Qualities:

Lockable, Ownable

#### Functions:

GetParentCell - returns the objectID of the parent cell of the calling reference
`(parentCell:ref) reference.GetParentCell`

GetParentWorldspace - returns the worldspace to which the calling reference's cell belongs, if any. In interior cells this generally returns 0.
`(parentWorldspace:ref) reference.GetParentWorldspace`

ParentCellHasWater - returns 1 if the reference's parent cell can contain water
`(hasWater:bool) reference.ParentCellHasWater`
`(hasWater:bool) reference.HasWater`

GetParentCellWaterHeight - returns the water height of the references parent cell
`(waterHeight:float) reference.GetParentCellWaterHeight`
`(waterHeight:float) reference.GetWaterHeight`

IsActivatable - returns 1 if the calling reference can be activated under normal circumstances
`(activatable:bool) reference.IsActivatable`

IsUnderWater - returns 1 if the calling reference's Z position is less than 120 units under its parent cell's water height
`(isUnderWater:bool) reference.IsUnderWater`

GetNumChildRefs - returns the number of reference for which the calling reference behaves as an enable-state parent
`(numChildren:int) reference.GetNumChildRefs`

GetNthChildRef - returns the nth child reference associated with the calling reference. Child references are stored in no particular order.
`(childRef:ref) reference.GetNthChildRef whichChild:int`

GetNumFollowers - returns the number of actors currently following the calling actor. Summoned creatures are excluded.
`(numFollowers:int) reference.GetNumFollowers`

GetNthFollower - returns a reference to the nth actor currently following the calling actor. Does not include summoned creatures.
`(follower:ref) reference.GetNthFollower whichFollower:int`

GetFollowers - returns an array containing all actors currently following the calling actor, including summoned creatures
`(followers:array) reference.GetFollowers`

IsPersistent - returns 1 if the calling reference is a persistent reference
`(isPersistent:bool) reference.IsPersistent`

SetScaleEX - sets the scale of the calling reference. Unlike SetScale, the scale is not limited to a certain range. The reference should be disabled and then enabled after calling this function in order to update its scale and collision properties. The new scale is saved in the savegame.
`(nothing) reference.SetScaleEX scale:float`

HasBeenPickedUp - returns true if the calling reference is currently inactive due to having been picked up by an actor or otherwise transferred to an inventory
`(pickedUp:bool) reference.HasBeenPickedUp`
`(pickedUp:bool) reference.IsTaken`

SetHasBeenPickedUp - toggles the flag that marks a reference as having been picked up by an actor. When called on a reference which was previously picked up, causes the reference to "respawn". The reference must be disabled and then enabled for the change to become visible.
`(nothing) reference.SetHasBeenPickedUp pickedUp:bool`
`(nothing) reference.SetTaken pickedUp:bool`

GetRefCount - returns the number of items in a stack of items in the world
`(refCount:int) reference.GetRefCount`

SetRefCount - sets the number of items in a stack of items in the world. Note that while this function will change the count of any type of reference, it may have unpredictable results when used on references like NPCs which are not logically stackable.
`(nothing) reference.SetRefCount newCount:int`

SetBaseForm - changes the base object associated with a reference, with the limitation that the new base form must be of the same type as the old one (i.e. you can swap a weapon reference's base form only with another weapon). Does not work on actors or on items in containers. The reference must be disabled and then enabled in order for the change to be visible. This function is considered beta.
`(nothing) reference.SetBaseForm newBaseForm:ref`

Activate2 - like the existing Activate command, causes a reference to be activated. The only difference is that this command circumvents the limit on recursive scripted activations of an object, allowing unlimited repeated processing of the target's OnActivate script block. Use with care as performance may degrade if a large number of calls to this command occur within a single frame.
`(nothing) reference.Activate2 activator:ref runOnActivate:bool`

IsRefDeleted - returns 1 if the passed object reference has been marked as deleted by a mod or the game. Deleted references should not be used in scripts. Note that the reference is passed as a parameter - this function should not be called on a potentially deleted reference directly.
`(isDeleted:bool) IsRefDeleted reference:ref`

DeleteReference - attempts to delete the calling object from the game and returns true if successful. In order for a reference to be deleted, it must:

- - be disabled
- - not be an actor
- - not be contained in an inventory
- - be dynamic (i.e. generated via PlaceAtMe or dropped from an inventory, having a mod index of 0xFF)

The primary aim of this function is to combat the savegame bloat resulting from generation of large numbers of dynamic references. In most cases, it is better to avoid creating such bloat in the first place. (Note: IsRefDeleted is not related to this command in any way).
`(wasRefDeleted:bool) reference.DeleteReference`

GetBoundingBox - returns a stringmap representing the calling objects axis-aligned bounding box. This command only works for mobile objects (projectiles and actors). The stringmap returned contains two stringmaps: "center" has keys "x", "y", and "z" representing the coordinates of the center of the bounding box, and "extent" has the same keys representing the extent of the box along each axis. For example, the height of the box is equal to GetBoundingBox->extent->z * 2. Similarly the bottom of the box is equal to GetBoundingBox->center->z - GetBoundingBox->extent->z
`(StringMap) reference.GetBoundingBox`

GetBoundingRadius - returns the radius of a sphere large enough to entirely contain the 3D geometry of the calling object.
`(radius:float) reference.GetBoundingRadius`

Update3D - updates the visual representation of the calling actor or object reference. This can be called immediately after commands like SetModelPath and SetEyes to make the changes visible. This command does not currently work correctly on the player
`(nothing) reference.Update3D`

HasEffectShader - checks if the specified effect shader is playing on the calling reference, and if so returns the number of instances of that shader playing on it. Otherwise returns zero. Note that this command may return true for a short period after calling StopMagicShaderVisuals because the shader is not fully removed until its ending sequence has played out.
`(instanceCount:int) ref.HasEffectShader effectShader:ref`

IsInOblivion - returns 1 if the calling reference is in a cell or worldspace marked as belonging to the realm of Oblivion.
`(inOblivion:bool) reference.IsInOblivion`

### Sigil Stone

#### Functions:

GetSigilStoneUses - returns the number of uses for a sigil stone
`(short) reference.GetSigilStoneUses sigilStone:ref`

SetSigilStoneUses - sets the number of uses for a sigil stone
`(nothing) reference.SetSigilStoneUses uses:integer sigilStone:ref`

ModSigilStoneUses - mods the number of uses for a sigil stone
`(nothing) reference.ModSigilStoneUses modBy:integer sigilStone:ref`

### Skill

#### Qualities:

Description

#### Values:

Attribute (short) - the controlling character attribute
Specialization (short) - the corresponding specialization
UseValue (float) - One of two values used to increment the experience toward the next skill level based on an action
Experience (float) - the current player experience points for the skill
Advances (long) - the number of times the skill has been advanced by the character

#### Functions:

GetPlayerSkillUse - returns the current experience towards the next level of the skill
`(skillExperience:float) GetPlayerSkillUse skill:actorValue`

GetPlayerSkillUseC - alternatve version of GetPlayerSkillUse taking an actor value code for the skill
`(skillExperience:float) GetPlayerSkillUseC skillCode:int`

IncrementPlayerSkillUse - records some additional uses of one of the skill actions
`(nuSkillExperience:float) IncrementPlayerSkillUse skill:int whichAction:inthowManyTimes:float`

GetSkillUseIncrement - gets the experience point increase for one use of a skill action
`(useRate:float) GetSkillUseIncrement skill:int whichAction:int`

SetSkillUseIncrement - sets the experience point increase for one use of a skill action
`(nothing) SetSkillUseIncrement nuRate:float skill:int whichAction:int`

IncrementPlayerSkillUseC - records some additional uses of one of the skill actions
`(nuSkillExperience:float) IncrementPlayerSkillUse skill:actorValueCode whichAction:int howManyTimes:float`

TriggerPlayerSkillUse - records positive or negative uses of one of the specified skill actions. Enough skill uses will increment or decrement the skill itself, and adjust the log of the number of increases for that skill.
`(nuSkillExperience:float) TriggerPlayerSkillUse skill:actorValueCode whichAction:int howManyTimes:float`
`(nuSkillExperience:float) TriggerPlayerSkillUseC skill:int whichAction:int howManyTimes:float`

ModPlayerSkillExp - directly adjusts the experience for a skill. A large enough adjustment will increment or decrement the skill itself, and adjust the log of the number of increase for that skill.
`(nuSkillExperience:float) ModPlayerSkillExp skill:actorValueCode amount:float`
`(nuSkillExperience:float) ModPlayerSkillExpC skill:int amount:float`

GetSkillUseIncrementC - gets the experience point increase for one use of a skill action
`(useRate:float) GetSkillUseIncrement skill:actorValueCode whichAction:int`

SetSkillUseIncrementC - sets the experience point increase for one use of a skill action
`(nothing) SetSkillUseIncrement nuRate:float skill:actorValueCode whichAction:int`

GetSkillGoverningAttribute - returns the governing attribute for the skill as an actor value code
`(skillCode:int) GetSkillGoverningAttribute skillName:string`

SetSkillGoverningAttribute - sets the governing attribute for the skill
`(nothing) SetSkillGoverningAttribute skillName:string attributeName:string`

GetSkillGoverningAttributeC - alternate version of GetSkillGoverningAttribute taking an actor value code for the skill
`(skillCode:int) GetSkillGoverningAttributeC skillCode:int`

SetSkillGoverningAttributeC - alternate version of SetSkillGoverningAttribute taking actor value codes for the skill and attribute
`(nothing) SetSkillGoverningAttributeC skillCode:int attributeCode:int`

GetPlayerSkillAdvances - returns the number of times the skill level has advanced for that skill
`(advances:int) GetPlayerSkillAdvances skillCode:int`
`(advances:int) GetPlayerSkillAdvancesC skillCode:int`

SetPlayerSkillAdvances - sets the number of times the skill has been advanced
`(nothing) SetPlayerSkillAdvances skillCode:int advances:int`
`(nothing) SetPlayerSkillAdvancesC skillCode:int advances:int`

GetRequiredSkillExp - returns the total skill use required for the player to advance the specified skill. To get the remaining skill use required, subtract the value of GetPlayerSkillUse from this value.
`(skillUse:float) GetRequiredSkillExp skill:actorValue`

GetRequiredSkillExpC - alternate version of GetRequiredSkillExp taking an actor value code for the skill.
`(skillUse:float) GetRequiredSkillExpC skillCode:int`

GetSkillSpecialization - returns the skill's specialization as an integer. 0: Combat, 1: Magic, or 2: Stealth.
`(specialization:int) GetSkillSpecialization skill:actorValue`

GetSkillSpecializationC - alternate version of GetSkillSpecialization taking an actor value code for the skill.
`(specialization:int) GetSkillSpecializationC skillCode:int`

SetSkillSpecialization - sets the skill's specialization as an integer. 0: Combat, 1: Magic, or 2: Stealth.
`(nothing) SetSkillSpecialization skill:actorValue specialization:int`

SetSkillSpecializationC - alternate version of SetSkillSpecialization taking an actor value code for the skill
`(specialization:int) SetSkillSpecializationC skillCode:int specialization:int`

ToggleSkillPerk - turns the perk associated with the specified skill at the specified mastery level on or off. Currently, this command only supports toggling the Journeyman Block perk. Support for additional perks and skills may be added in the future. The mastery level is an integer from 0 (Novice) to 4 (Master).
`(perkToggled:bool) ToggleSkillPerk skill:actorValue masteryLevel:int bEnablePerk:bool`

### Soul Gem

#### Qualities:

Inventory, Named, Simple

#### Values:

Soul Level - the soul level currently captured in the soul gem
Capacity - the maximum soul level that can be captured in the soul gem

#### Functions:

GetSoulLevel - returns the soul level currently in the soul gem
`(soulLevel:int) GetSoulLevel objectID:ref`

GetSoulGemCapacity - returns the max soul level the soul gem can contain
`(soulLevel:int) GetSoulGemCapacity objectID:ref`

SetSoulLevel - set the soul level of the soul gem
`(nothing) SetSoulLevel soulLevel:int objectID:ref`

SetSoulGemCapacity - set the capacity level of the soul gem
`(nothing) SetSoulGemCapacity soulLevel:int objectID:ref`

GetCurrentSoulLevel - returns the current soul level of the calling actor reference
`(soulLevel:int) GetCurrentSoulLevel`

### Sound

#### Functions:

GetSoundAttenuation - returns the specified attenuation value for the specified sound, where the attenuation is "max", "min", or "static"
`(attenuation:float) GetSoundAttenuation sound:ref whichAttenuation:string`

SetSoundAttenuation - sets the specified attenuation value for the specified sound, where the attenuation is "max", "min", or "static"
`(nothing) SetSoundAttenuation sound:ref whichAttenuation:string attenuation:float`

### Spell

#### Qualities:

Magic, Named

#### Value:

Spell Type (short) - the kind of spell. Spell Types
Magicka Cost (long) - the cost in magicka for casting the spell
Mastery Level (short) - the skill mastery level needed to cast the spell. Spell Mastery Levels

#### Functions:

GetSpellType - returns the spell type
`(spellType:int) GetSpellType spell:ref`

SetSpellType - sets the spell type
`(nothing) SetSpellType nuType:int spell:ref`

GetSpellMagickaCost - returns the magicka casting cost according to the Oblivion formula. If called on a reference it will use the reference's magic skill values to determine the actual magicka cost of the spell. Without a reference it will return the base cost of the spell as reported in the CS.
`(magickaCost:int) reference.GetSpellMagickaCost spell:ref`

SetSpellMagickaCost - sets the magicka casting cost
`(nothing) SetSpellMagickaCost nuMagickaCost:int spell:ref`

ModSpellMagickaCost - modifies the magicka casting cost up or down
`(nothing) ModSpellMagickaCost modifyBy:float spell:ref`

GetSpellMasteryLevel - returns the mastery level of the spell
`(masteryLevel:int) GetSpellMasteryLevel spell:ref`

SetSpellMasteryLevel - sets the mastery level of the spell
`(nothing) SetSpellMasteryLevel masteryLevel:int objectID:ref`

GetSpellSchool - returns the school of the spell, determined by the most expensive effect item
`(magicSchool:int) GetSpellSchool spell:ref`

GetSpellExplodesWithNoTarget - returns whether the touch spell explodes without a target
`(spellExplodesWithNoTarget:bool) GetSpellExplodesWithNoTarget spell:ref`

SetSpellExplodesWithNoTarget - sets whether the touch spell will explode without a target
`(nothing) SetSpellExplodesWithNoTarget doesSpellExpode:bool spell:ref`

IsSpellHostile - returns 1 if the spell is considered hostile
`(isHostile:bool) IsSpellHostile spell:ref`

SetSpellHostile - toggles whether or not a spell is considered hostile
`(nothing) SetSpellHostile spell:ref isHostile:bool`

GetSpellPCStart - returns true if the PC Start flag is set for the specified spell
`(bool) GetSpellPCStart spell:ref`

GetSpellImmuneToSilence - returns true if the Immune to Silence flag is set for the specified spell
`(bool) GetSpellImmuneToSilence spell:ref`

GetSpellAreaEffectIgnoresLOS - returns true if the AE Ignores LOS flag is set for the specified spell
`(bool) GetSpellAreaEffectIgnoresLOS spell:ref`

GetSpellScriptEffectAlwaysApplies - returns true if the SEFF Always Applies flag is set for the specified spell
`(bool) GetSpellScriptEffectAlwaysApplies spell:ref`

GetSpellDisallowAbsorbReflect - returns true if the Disallow Absorb Reflect flag is set for the specified spell
`(bool) GetSpellDisallowAbsorbReflect spell:ref`

SetSpellPCStart - sets the PC Start flag for the specified spell
`(nothing) SetSpellPCStart value:integer spell:ref`

SetSpellImmuneToSilence - sets the Immune to Silence flag for the specified spell
`(nothing) SetSpellImmuneToSilence value:integer spell:ref`

SetSpellAreaEffectIgnoresLOS - sets the AE Ignores LOS flag for the specified spell
`(nothing) SetSpellAreaEffectIgnoresLOS value:integer spell:ref`

SetSpellScriptEffectAlwaysApplies - sets the SEFF Always Applies flag for the specified spell
`(nothing) SetSpellScriptEffectAlwaysApplies value:integer spell:ref`

SetSpellDisallowAbsorbReflect - sets the Disallow Absorb Reflect flag for the specified spell
`(nothing) SetSpellDisallowAbsorbReflect value:integer spell:ref`

### Weapon

#### Qualities:

Attacking, Breakable, Enchantable, Equippable, Inventory, Named, Simple

#### Values:

Reach (float) - the distance from the wielder the weapon can reach
Weapon Type (short) - the type of weapon
Poison (ref) - the poison currently applied to the weapon

#### Functions:

GetWeaponReach - returns the reach of the weapon
`(reach:float) reference.GetWeaponReach objectID:ref`

SetWeaponReach - sets the reach of the weapon
`(nothing) reference.SetWeaponReach nuReach:float objectID:ref`

ModWeaponReach - modifies the reach of the weapon up or down
`(nothing) reference.ModWeaponReach modifyBy:float objectID:ref`

GetWeaponType - retuns the weapon type
`(weaponType:int) reference.GetWeaponType objectID:ref`

SetWeaponType - sets the weapon type
`(nothing) reference.SetWeaponType weaponType:int objectID:ref`

GetEquippedWeaponPoison - returns the poison applied to the equipped weapon. Called on the weapon holder.
`(poison:ref) reference.GetEquippedWeaponPoison`

SetEquippedWeaponPoison - sets the poison applied to the equipped weapon and returns the previous poison.Called on the weapon holder.
`(oldPoison:ref) reference.SetEquippedWeaponPoison nuPoison:ref`

RemoveEquippedWeaponPoison - removes and returns the poison applied to the equipped weapon. Called on the weapon holder.
`(oldPoison:ref) reference.RemoveEquippedWeaponPoison`

### Weather

#### Values:

Wind Speed (short float) - how windy it is; affects cloud and tree movement
Cloud Speed (shortfloat) - how fast the clouds move; modified by wind speed
Trans Delta (short float) - in game hours, how long it takes to fully transition into this weather type once a transition begins
Sun Glare (short float) - how much glare there is around the sun disc
Sun Damage (short float) - how much damage the sun does to vampires during daytime hours
Fog Distances (float) - near and far clip planes for fog during different times of day
HDR Values (float) - see the CS Wiki page for more information about these settings
Weather Colors (float) - the color of the weather for different weather times
Lightning Frequency (short) - a value which determines the rate of lightning flashes; scaled from 1(high) to 255 (low)
*Note - short floats are stored internally as 0-255 but are exposed in the CS and through the API as a float

#### Functions:

GetCurrentWeatherID - returns the refID of the current weather
`(currentWeather:ref) GetCurrentWeatherID`

GetWeatherOverride - returns the weather which is overriding the current weather as a result of the ForceWeather or SetWeather command with a non-zero "override" argument (for example, in the scripts which control weather near Oblivion gates), or zero if the weather is not being overridden.
`(override:ref) GetWeatherOverride`

GetWeatherWindSpeed - returns the wind speed of the specified weather
`(windSpeed:float) GetWeatherWindSpeed weather:ref`
`(windSpeed:float) GetWindSpeed weather:ref`

SetWeatherWindSpeed - sets the wind speed of the specified weather
`(nothing) SetWeatherWindSpeed speed:float weather:ref`
`(nothing) SetWindSpeed speed:float weather:ref`

GetWeatherCloudSpeedLower - returns the speed of the lower cloud layer
`(speed:float) GetWeatherCloudSpeedLower weather:ref`
`(speed:float) GetCloudSpeedLower weather:ref`

SetWeatherCloudSpeedLower - sets the speed of the lower cloud layer
`(nothing) SetWeatherCloudSpeedLower speed:float weather:ref`
`(nothing) SetCloudSpeedLower speed:float weather:ref`

GetWeatherCloudSpeedUpper - returns the speed of the upper cloud layer
`(speed:float) GetWeatherCloudSpeedUpper weather:ref`
`(speed:float) GetCloudSpeedUpper weather:ref`

SetWeatherCloudSpeedUpper - sets the speed of the upper cloud layer
`(nothing) SetWeatherCloudSpeedUpper speed:float weather:ref`
`(nothing) SetCloudSpeedUpper speed:float weather:ref`

GetWeatherTransDelta - returns the transition delta of the weather
`(transDelta:float) GetWeatherTransDelta weather:ref`
`(transDelta:float) GetTransDelta weather:ref`

SetWeatherTransDelta - sets the transition delta of the weather
`(nothing) SetWeatherTransDelta transDelta:float weather:ref`
`(nothing) SetTransDelta transDelta:float weather:ref`

GetWeatherSunGlare - returns the sun glare
`(sunGlare:float) GetWeatherSunGlare weather:ref`
`(sunGlare:float) GetSunGlare weather:ref`

SetWeatherSunGlare - sets the sun glare
`(nothing) SetWeatherSunGlare sunGlare:float weather:ref`
`(nothing) SetSunGlare sunGlare:float weather:ref`

GetWeatherSunDamage - returns the sun damage
`(sunDamage:float) GetWeatherSunDamage weather:ref`
`(sunDamage:float) GetSunDamage weather:ref`

SetWeatherSunDamage - sets the sun damage
`(nothing) SetWeatherSunDamage sunDamage:float weather:ref`
`(nothing) SetSunDamage sunDamage:float weather:ref`

GetWeatherFogDayNear - returns the daytime near fog distance
`(fogDistance:float) GetWeatherFogDayNear weather:ref`
`(fogDistance:float) GetFogDayNear weather:ref`

SetWeatherFogDayNear - sets the daytime near fog distance
`(nothing) SetWeatherFogDayNear fogDistance:float weather:ref`
`(nothing) SetFogDayNear fogDistance:float weather:ref`

GetWeatherFogDayFar - returns the daytime far fog distance
`(fogDistance:float) GetWeatherFogDayFar weather:ref`
`(fogDistance:float) GetFogDayFar weather:ref`

SetWeatherFogDayFar- sets the daytime far fog distance
`(nothing)SetWeatherFogDayFar fogDistance:float weather:ref`
`(nothing)SetFogDayFar fogDistance:float weather:ref`

GetWeatherFogNightNear - returns the nighttime near fog distance
`(fogDistance:float)GetWeatherFogNightNear weather:ref`
`(fogDistance:float)GetFogNightNear weather:ref`

SetWeatherFogNightNear - sets the nighttime near fog distance
`(nothing)SetWeatherFogNightNear fogDistance:float weather:ref`
`(nothing)SetFogNightNear fogDistance:float weather:ref`

GetWeatherFogNightFar - returns the nighttime far fog distance
`(fogDistance:float)GetWeatherFogNightFar weather:ref`
`(fogDistance:float)GetFogNightFar weather:ref`

SetWeatherFogNightFar - sets the nighttime far fog distance
`(nothing)SetWeatherFogNightFar fogDistance:float weather:ref`
`(nothing)SetFogNightFar fogDistance:float weather:ref`

GetWeatherHDRValue - returns the specified HDR value for the weather
`(hdrValue:float) GetWeatherHDRValue whichHDRValue:int weather:ref`
`(hdrValue:float) GetHDRValue whichHDRValue:int weather:ref`

SetWeatherHDRValue - sets the specified HDR value for the weather
`(oldHDRValue:float) SetWeatherHDRValue nuVal:float whichHDRValue:int weather:int`
`(oldHDRValue:float) SetHDRValue nuVal:float whichHDRValue:int weather:int`

GetWeatherColor - returns the red, green or blue value of the specified weather color at the specified weather time
`(color:int) GetWeatherColor rgb:int whichColor:int weather:ref whichTime:int`

SetWeatherColor - sets the red, green and blue values for the specified weather color at the specified weather time
`(nothing) SetWeatherColor red:int green:int blue:int whichColor:int weather:ref whichTime:int`

GetWeatherLightningFrequency - returns the frequency of the lightning
`(frequency:int) GetWeatherLightningFrequency weather:ref`
`(frequency:int) GetLightningFrequency weather:ref`

SetWeatherLightningFrequency - sets the frequency of the lightning
`(nothing) SetWeatherLightningFrequency frequency:int weather:ref`
`(nothing) SetLightningFrequency frequency:int weather:ref`

GetWeatherClassification - returns the precipitation classification of the weather as defined in the editor
`(classification:int) GetWeatherClassification weather:ref`

## General Functions

IsDoor - returns whether the calling reference or passed objectID is a door
`(isDoor:bool) reference.IsDoor objectID:ref`

IsFurniture - returns whether the calling reference or passed objectID is furniture
`(isFurniture:bool) reference.IsFurniture objectID:ref`

IsActivator - returns whether the calling reference or passed objectID is an activator
`(isActivator:bool) reference.IsActivator objectID:ref`

GetGameLoaded - returns 1 if a saved game was loaded or a new game was started since the last time this call was made. This command returns true once per game load/start for each script that uses it.
`(gameLoaded:bool) GetGameLoaded`

GetGameRestarted - returns 1 if Oblivion was exited and restarted since the last time this call was made from the calling script. Use this condition to reset or undo changes made by OBSE functions which are not stored in the savegame.
`(gameRestarted:bool) GetGameRestarted`

GetOBSEVersion - returns the version number of OBSE
`(obseVersion:int) GetOBSEVersion`

GetOBSERevision - returns the minor version number of OBSE. For instance, when running the second released version of v0014, this function returns 2.
`(obseRevision:int) GetOBSERevision`

SetNumericGameSetting - sets the specified game setting to the following variable or direct value
`(nothing) SetNumericGameSetting gameSettingName:string value:float`

GetStringGameSetting - returns the string value of a game setting
`(setting:string_var) GetStringGameSetting settingName:string`

SetStringGameSettingEX - sets the string value of a game setting. The new string value is contained within the format string, following the setting name and separated by a pipe character, i.e. `"nameOfGameSetting|newValueOfGameSetting"`. When calling from the console, use '@' instead of the pipe character.
`(nothing) SetStringGameSettingEX settingNameAndNewValue:formatString`

GetNumericINISetting - returns the specified ini setting
`(setting:float) GetNumericINISetting iniSettingName:string`

SetNumericINISetting - sets the specified ini setting to the following variable or direct value
`(nothing) SetNumericINISetting iniSettingName:string value:float`

GetStringINISetting - returns the value of a string ini setting
`(setting:string_var) GetStringINISetting settingName:formatString`

SetStringINISetting - sets the ini setting to the specified string. Pass both arguments as a single string of the format "settingName|newValue". If called from the console, use the "@" character in place of the pipe character.
`(nothing) SetStringINISetting settingNameAndValue:formatString`

GetFPS - returns the frames per second of the game
`(fps:float) GetFPS`

IsThirdPerson - returns whether the point of view is 3rd person or not
`(isThirdPerson:bool) IsThirdPerson`

IsGlobalCollisionDisabled - returns whether collision is disabled
`(isDisabled:bool) IsGlobalCollisionDisabled`

SetDisableGlobalCollision - sets whether to disable the global collision or not
`(nothing) SetDisableGlobalCollision toDisableOrNot:bool`

RunBatchScript - runs a specified text file under the Oblivion directory as a script. Works the same as the console function `bat.` The optional second parameter causes the script to execute on the calling object, if any. The optional third parameter prevents any output from appearing in the console while the script executes.
`(nothing) reference.RunBatchScript bRunOnRef:bool bSuppressOutput:bool`

IsPluginInstalled - returns whether a given plugin is installed
`(isInstalled:bool) IsPluginInstalled pluginName:string`

GetPluginVersion - returns the version of the specified plugin
`(version:int) GetPluginVersion pluginName:string`

GetDebugSelection - returns the reference to the item last selected in the console
`(selection:ref) GetDebugSelection`

GetSoundPlaying - If no parameters are passed, then it dumps a list of the currently playing sounds and actors making sound to obse.log (this may change). If a string is passed, then it returns the number of times the specified sound is playing. The string may contain wildcards: matches several characters, and ? matches one character. If a reference is passed in, then the search is restricted to that reference, returning the number of times it is playing that sound. Some sounds are not associated with objects, so if you pass in a "fuzzy check radius" parameter, it returns the number of times the sound is playing within the specified radius around the reference.
`(playingCount:int) reference.GetSoundPlaying soundName:string fuzzyCheckRadius:float`

RunScriptLine - runs a line of script as if it were called from the console. If bRunOnRef is 1, the line of script will be executed on the calling object, if any. If bSuppressOutput is true, no output will be generated in the console while the script line is executing.
`(nothing) reference.RunScriptLine formatString:string var1 var2 ... var20 bRunOnRef:bool bSuppressOutput:bool`

GetFormFromMod - attempts to look up and return a form defined in another mod, prepending the two-digit mod index to the formID. The formID is passed in hexadecimal format, i.e. 0001A46B. The first two digits of the formID are ignored and can be omitted. The formID must be passed as a literal value as script variables don't have the precision necessary to store all possible formIDs. The file name must include the file extension. Pass "NONE" as the file name to look up a dynamic form in the saved game (mod index 0xFF, for example cloned forms).
`(form:ref) GetFormFromMod modFileName:string formID:hexString`

ToggleFirstPerson - toggles the player's POV to first or third person. Passing 1 enables first person view, 0 enables third person.
`(nothing) ToggleFirstPerson toFirstPerson:bool`

GetLastCreatedSpell - returns the spell most recently created by the player during the current game session
`(spell:ref) GetLastCreatedSpell`

GetLastEnchantedItem - returns the enchanted item most recently created by the player during the current game session
`(item:ref) GetLastEnchantedItem`

GetLastCreatedPotion - returns the potion most recently created by the player during the current game session
`(potion:ref) GetLastCreatedPotion`

GetLastUniqueCreatedPotion - returns the last unique potion created by the player. The game remembers which potions the player has created in the past. The first time the player creates apotion of a given magnitude and effects, that potion will be returned by GetLastUniqueCreatedPotion. Subsequently, creating a potion of the same effects and magnitude will not create a unique potion and so the potion will not be returned by this command.
`(potion:ref) GetLastUniqueCreatedPotion`

IsConsoleOpen - returns 1 if the console is currently open
`(open:bool) IsConsoleOpen`

LoadGameEx - attempts to load the saved game with the specified name
`(nothing) LoadGameEx formatString:string var1 var2 ... var20`

ActorValueToString - converts an actor value to its localized name
`(actorValueName:string) ActorValueToString toConvert:actorValue`
`(actorValueName:string) AVString toConvert:actorValue`

ActorValueToStringC - converts an actor value code to its localized name
`(actorValueName:string) ActorValueToStringC toConvert:actorValueCode`

StringToActorValue - converts the name of an actor value into the actor value code itself
`(actorValue:int) StringToActorValue toConvert:string`
`(actorValue:int) StringAV toConvert:string`

GetEditorID - attempts to retrieve the editorID for the specified object. EditorIDs for most forms are not loaded at run-time. Currently this function only returns editor IDs for cells and quests - for other types, returns the formID as a string. If the second argument is non-zero, however, returns an empty string instead of the formID.
`(editorID:string) GetEditorID object:ref noFormID:bool`

GetFormIDString - returns the formID of the specified object as a hexadecimal string. If the object cannot be found in memory (for example, a non-persistent reference), returns "00000000"
`(formID:string) reference.GetFormIDString object:ref`

GetRawFormIDString (GetFormIDString2) - returns the formID stored in an array element or ref variable as a hexadecimal string. Unlike GetFormIDString, this command does not care if the formID is valid.
`(formID:string) GetRawFormIDString object:ref`

GetUserTime - returns a StringMap containing information about the time and date on the player's system
`(userTime:StringMap) GetUserTime`

The returned StringMap has the following key/value pairs, all of which are integers:

- Year (1601 - 30827)
- Month (1-12)
- DayOfWeek (1:Sunday - 7:Saturday)
- Day (1-31)
- Hour (0-23)
- Minute (0-59)
- Second (0-59)
- Millisecond (0-999)

ActorValueToCode - given an actor value name, returns the corresponding actor value code
`(code:int) ActorValueToCode toConvert:actorValue`

GetGameDifficulty - returns the current difficulty level of the game as a float from -1.0 to 1.0, with higher values corresponding to greater difficulty.
`(difficulty:float) GetGameDifficulty`

SetGameDifficulty - sets the current difficulty level of the game as a float from -1.0 to 1.0, with higher values corresponding to greater difficulty. Values outside of the valid range are ignored.
`(nothing) SetGameDifficulty difficulty:float`

GetOblivionDirectory - returns the full path to the user's Oblivion install
`(directory:string) GetOblivionDirectory`

GetWaterShader - returns information about the current water shader given a string representing one of the water shader properties. Supports the same property names as the ModWaterShader console command: "direction", "velocity", "frequency", "amplitude", "fresnel", "reflectivity", "opacity", "blend", "scrollx", "scrolly", "rainforce", "rainvelocity", "rainfalloff", "rainsize", "displaceforce", "displacevelocity", "displacefalloff", and "displacedampener".
`(shaderValue:float) GetWaterShader propertyName:string`

GetGridsToLoad - returns the effective value of the uGridsToLoad ini setting. This value is specified in Oblivion.ini but adjusted by the game during play.
`(gridsToLoad:int) GetGridsToLoad`

SetOLMPGrids - specifies the number of grids that a call to OutputLocalMapPicturesOverride should use when generating local map pictures. The value passed in must be smaller than the effective value of the uGridsToLoad ini setting, which can be obtained with GetGridsToLoad. All subsequent calls to OutputLocalMapPicturesOverride will use the new value.
`(valueSet:bool) SetOLMPGrids grids:int`

OutputLocalMapPicturesOverride - this command is identical to the console command OutputLocalMapPictures, except it uses the number of grids specified by the last call to SetOLMPGrids when generating the maps.
`(nothing) OutputLocalMapPicturesOverride`
`(nothing) OLMPOR`

GetWorldSpaceParentWorldSpace - returns a worldspace's parent worldspace
`(worldspace:ref) GetWorldSpaceParentWorldSpace worldspace:ref`
`(worldspace:ref) GetWorldParentWorld worldspace:ref`

GlobalVariableExists - returns 1 if a global variable exists with the specified editorID
`(globalVariableExists:bool) GlobalVariableExists variableEditorID:string`

GetCellChanged -returns 1 if the player has entered a new cell since the last time the command was called from the calling script, including transitioning from one exterior cell to another.
`(cellChanged:bool) GetCellChanged`

ResolveModIndex - Attempts to resolve a mod index which was stored during a previous game session to account for any changes to the user's load order. Given the stored mod index for a mod, returns the mod index currently associated with that same mod, or -1 if the index could not be resolved (for instance, because the mod is no longer loaded).
`(resolvedModIndex:int) ResolveModIndex storedModIndex:int`

## Cloning Functions

The cloning functions are special. They are declared as taking Inventory Objects so any inventory object can be passed as a raw name from the CS. However you can clone any form by first assigning it to a ref and then passing that ref to CloneForm.

CloneForm - creates and returns a new base object that is an exact copy of the passed objectID
`(clonedForm:ref) CloneForm objectID:ref`

Examples:

    	ref clonedInventoryItem
    	ref clonedSpell
    	ref originalSpell
    	set clonedInventoryItem to CloneForm WeapSteelShortsword
    	set originalSpell to StandardCalmTouch1Novice
    	set clonedSpell to CloneForm originalSpell

IsClonedForm - returns whether the passed objectID is a cloned form or not. A cloned form is saved as part of the save game. Instances of cloned forms are player created potions, spells and enchanted items
`(isCloned:bool) IsClonedForm objectID:ref`

## Flow Control Functions

OBSE supports several types of commands for altering the flow of execution within a script. The simplest are `Label` and `Goto`, which allow unconditional jumps from one location in a script to a previous location. `While` loops cause execution to remain within the loop until the specified expression becomes false. `ForEach` loops iterate over the elements of an array or string.

`ForEach` and `While` loops both define structured blocks in the same way that `if` and `endif` or `begin` and `end` do. Every `While` or `ForEach` in a script must be matched by exactly one `Loop` command.

Examples of good and bad loops:

    	while (expr)
    		do stuff
    	loop		; good

    	while (expr)
    	if (something)
    		loop  ; BAD, Loop must be on same level of indentation as While
    	endif

`Break` and `Continue` statements are only valid within a loop body. `Goto` should never be used within a loop body to jump to a label defined outside of the loop's body.

Label - save the location of the command following the `SaveIP` command
`(nothing) SaveIP slot:int`
`(nothing) Label slot:int`

Goto - jump to a previously saved location
`(nothing) RestoreIP slot:int`
`(nothing) Goto slot:int`

While - evaluates an OBSE expression. If the expression is true, the statements following it will be executed until the next `Loop` command, at which point control returns to the top of the loop and the expression is evaluated again.
`(nothing) While expression`

ForEach - `ForEach` is used to iterate over the elements of an array, the characters in a string, or references to objects in a container. The syntax `ForEach item <- collection` is used to indicate the variable ("`item`") which will hold the current element and the string, array, or container reference ("`collection`") from which elements will be drawn. On loop entry, `item` is set to the first element in `collection`. When the next `Loop` command is encountered, `item` is set to the next element in `collection` and execution returns to the top of the loop. The loop terminates when all elements have been returned. The type of `item` varies based on the type of `collection`.

For arrays, `item` is an array_var, specifically a StringMap. The loop will initialize `item` with two elements: "key", which holds the key of the current element, and "value", which holds the value associated with that key. Within a `ForEach` loop you can access both fields via `item["key"]` and `item["value"]`. Once the loop terminates, `item` is reset to an uninitialized array.
`(nothing) ForEach iterator:array_var <- sourceArray:array`

For strings, `item` is a string_var. The loop initializes `item` to the first character in the string; on each successive iteration `item` contains the next character in the string.
`(nothing) ForEach iterator:string_var <- sourceString:string`

For containers, `item` is a ref variable. See the section on Inventory References for details on the usage.
`(nothing) ForEach iterator:ref_var <- sourceContainer:ref`

Loop - Returns execution to the most recent `While` or `ForEach` command. The loop condition is evaluated and if it passes, execution continues inside the body of the loop. Otherwise, execution returns to the instruction immediately following the `Loop` command.
`(nothing) Loop`

Break - Must be called inside of a `ForEach` or `While` loop. `Break` causes the loop to exit immediately, forcing execution to jump to the instruction immediately following the next `Loop` command.
`(nothing) Break`

Continue - Must be called inside of a `ForEach` or `While` loop. `Continue` skips the rest of the body of a loop, returning execution to the top of the loop and evaluating the loop condition. If the condition passes, execution enters the loop body, otherwise the loop terminates and continues from the instruction following the corresponding `Loop` command.
`(nothing) Continue`

## Ref Walking Functions

GetFirstRef - returns the first reference in the current cell. A type can optionally be supplied to return only references matching that type. Additionally, you can pass 69 for actors and 70 for inventory items. This function should be used only within a `Label...Goto` loop and `GetNextRef`. An optional cell depth can be supplied to specify the number of adjacent cells to scan in exteriors: a cell depth of 1 scans the player's current cell plus 8 adjacent cells, a depth of 2 scans the player's cell plus 25 adjacent cells. By default, inactive references to items which were previously picked up by an actor are ignored; passing 1 for the third parameter will force those references to be included.
`(reference:ref) GetFirstRef type:int cellDepth:int includeInactiveRefs:int`

GetNextRef - returns the next reference in the curent cell. `GetFirstRef` must be called first; this function uses the cell depth and type passed to `GetFirstRef` and returns the next reference matching that type, or zero after the last reference has been returned. This function should only be used within a `Label...Goto` loop.
`(reference:ref) GetNextRef`

GetNumRefs - returns the number of references in the current cell which match the optionally supplied type code. Use 69 for actors and 70 for inventory items. An optional cell depth can be specified for exteriors. By default, inactive references to items which were previously picked up by an actor are ignored; passing 1 for the third parameter will force those references to be included.
`(numRefs:int) GetNumRefs type:int cellDepth:int includeInactiveRefs:int`

GetFirstRefInCell - Works the same as `GetFirstRef` but takes an additional parameter specifying the cell to scan. Note that if the specified is not loaded in memory, this function will only return persistent references. Use `GetNextRef` to iterate through the rest of the references in the cell.
`(reference:ref) GetFirstRefInCell cell:ref type:int cellDepth:int includeInactiveRefs:int`

GetNumRefsInCell - Works the same as `GetNumRefs` but takes an additional parameter specifying the cell to scan. Only counts persistent references if the cell is not loaded in memory.
`(numRefs:int) GetNumRefsInCell cell:ref type:int cellDepth:int includeInactiveRefs:int`

GetHighActors - returns an Array containing all actors currently in high AI processing. Generally this is equivalent to all the actors in the currently loaded interior cell or set of exterior cells adjacent to and including the player's current cell. This command is more efficient than using GetFirst/NextRef.
`(actors:Array) GetHighActors`

GetMiddleHighActors - returns an Array containing all actors currently in middle high AI processing. This generally includes all actors in cells that are not currently loaded but which have recently been visited by the player. This command is more efficient than using GetFirst/NextRef.
`(actors:Array) GetMiddleHighActors`

Example of ref looping (transfers all carriable items in the cell to the player's inventory):

    	ref nextItem
    	begin onActivate
    	set nextItem to GetFirstRef 70 ; get first carriable item
    	Label 10
    	if ( nextItem ) ; continue until all refs are processed
    	nextItem.activate player ; give the item to the player
    	set nextItem to getNextRef
    	Goto 10
    	endif
    	end

## Console Functions

Some of the console commands have been exposed as scripting commands. In many cases, their functionality is not completely documented, and as they were not designed to be used via scripts, strange behavior may occur when using them. The primary thing to expect is changes not being saved in the player's savedata file.

- con_CAL
- con_GetINISetting
- con_HairTint
- con_LoadGame
- con_ModWaterShader
- con_QuitGame
- con_RefreshINI
- con_RunMemoryPass
- con_Save
- con_SavINI
- con_SetCameraFOV
- con_SetClipDist
- con_SetFog
- con_SetGameSetting
- con_SetGamma
- con_SetHDRParam
- con_SetImageSpaceGlow
- con_SetINISetting
- con_SetSkyParam
- con_SetTargetRefraction
- con_SetTargetRefractionFire
- con_SexChange
- con_TCL
- con_TFC
- con_TGM
- con_ToggleAI
- con_ToggleCombatAI
- con_ToggleDetection
- con_ToggleMenus
- con_WaterDeepColor
- con_WaterReflectionColor
- con_WaterShallowColor
- con_PlayerSpellBook
- con_ToggleMapMarkers
- con_Show1stPerson
- con_OutputLocalMapPictures

## Input Functions

IsKeyPressed - returns whether the specified key is currently pressed. Uses standard windows key codes.
`(isKeyPressed:bool) IsKeyPressed windowsKeyCode:int`

IsKeyPressed2 - returns whether the specified key is currently pressed. Uses DX scancodes.
`(isKeyPressed:bool) IsKeyPressed2 dxScanCode:int`

GetKeyPress - returns the DX scan code of the key being pressed. If more than one key is pressed use whichIndex to choose which keycode to return.
`(keyPressed:int) GetKeyPress whichIndex:int`

GetNumKeysPressed - returns the number of keys currently pressed
`(count:int) GetNumKeysPressed`

DisableKey - disables the key with the specified dx scancode
`(nothing) DisableKey dxScanCode:int`

EnableKey - enables the key with the specified dx scancode. Turns off DisableKey.
`(nothing) EnableKey dxScanCode:int`

HoldKey - holds down the key with the specified dx scancode
`(nothing) HoldKey dxScanCode:int`

MenuHoldKey - holds down the key with the specified dx scancode when a menu is open
`(nothing) MenuHoldKey dxScanCode:int`

ReleaseKey - releases a held key with the specified dx scancode
`(nothing) ReleaseKey dxScanCode:int`

MenuReleaseKey - releases a held key with the specified dx scancode when a menu is open
`(nothing) ReleaseKey dxScanCode:int`

TapKey - presses the key with the specidied dx scancode once
`(nothing) TapKey dxScanCode:int`

MenuTapKey - presses the key with the specificed dx scancode once when a menu is open
`(nothing) MenuTapKey dxScanCode:int`

HammerKey - fakes keypresses every other frame of the key with the specified dx scancode
`(nothing) HammerKey dxScanCode:int`

AHammerKey - fakes keypresses every other frame on the alternate frames from HammerKey of the key with the specified dx scancode
`(nothing) AHammerKey dxScanCode:int`

UnHammerKey - stops hammering the key with the specified dx scancode
`(nothing) UnHammerKey dxScanCode:int`

GetControl - returns the dx scancode of the key used for the specified control
`(dxScanCode:int) GetControl whichControl:int`

GetAltControl2 - returns the dx scancode of the alternate key used for the specified control. Unlike GetAltControl, the return value of this function is a valid DX scan code which requires no further calculation for use with other input functions.
`(dxScanCode:int) GetAltControl2 whichControl:int`

GetMouseButtonPress - returns the dx scancode of the mouse button being pressed. If more than one mouse button is pressed, use whichIndex to choose which code to return
`(dxScanCode:int) GetMouseButtonPress whichIndex:int`

GetNumMouseButtonsPressed - returns the number of mouse buttons pressed
`(count:int) GetNumMouseButtonsPressed`

DisableMouse - prevents the mouse from moving
`(nothing) DisableMouse`

EnableMouse - turns off `DisableMouse`
`(nothing) EnableMouse`

MoveMouseX - moves the mouse horizontally the specified number of pixels
`(nothing) MoveMouseX pixels:int`

MoveMouseY - moves the mouse veritcally the specified number of pixels
`(nothing) MoveMouseY pixels:int`

SetMouseSpeedX - moves the mouse in the horizontal axis at the specified number of pixels per second
`(nothing) SetMouseSpeedX pixels:float`

SetMouseSpeedY - moves the mouse in the vertical axis at the specified number of pixels per second
`(nothing) SetMouseSpeedY pixels:float`

IsKeyPressed3 - returns 1 if the key or mouse button specified is currently pressed. Just like IsKeyPressed2, but detects disabled keys.
`(isPressed:bool) IsKeyPressed3 dxScanCode:int`

IsControlPressed - returns 1 if either the key or mouse button assigned to the specified control code is currently pressed. Detects disabled keys.
`(isPressed:bool) IsControlPressed whichControl:int`

DisableControl - disables both the key and mouse buton assigned to the specified control
`(nothing) DisableControl whichControl:int`

EnableControl - enables the key and mouse button for a control disabled with `DisableControl`
`(nothing) EnableControl whichControl:int`

OnKeyDown - registers a script as a listener for input events. Returns 1 for one frame when the passed key or mouse button is pressed. If used by multiple scripts, each script will be informed of the key's state. Will not return true again until the key is released and then pressed again.
`(keyPressed:bool) OnKeyDown dxScanCode:int`

OnControlDown - works like `OnKeyDown`, but takes a control code and returns 1 when the key or mouse buttonassigned to that control is pressed
`(controlPressed:bool) OnControlDown whichControl:int`

TapControl - presses the key or mouse button associated with the specified control once
`(nothing) TapControl whichControl:int`

RefreshControlMap - re-parses the Oblivion.ini file to update OBSE's internal map of the player's controls. Call this function after the player exits the Controls menu (menumode 1021) to detect any changes to the control layout. DEPRECATED: Input functions are now in sync with Oblivion control bindings.
`(nothing) RefreshControlMap`

SetControl - assigns a new key to the specified control. If the specified control already has a key assigned, the key mappings are swapped.
`(nothing) SetControl whichControl:int dxScanCode:int`

SetAltControl - assigns a new mouse button to the specified control. If the specified control already has a mouse button assigned, the button mappings are swapped.
`(nothing) SetAltControl whichControl:int dxScanCode:int`

GetCursorPos - returns the current X or Y coordinate of the mouse cursor in menu mode. Minumum coordinate is zero, maximum is determined by the user's screen resolution. Specify 'X' or 'Y' for the axis.
`(cursorPos:int) GetCursorPos axis:char`

SetIsControl - allows mods to register or unregister keys or mouse buttons as custom controls. Other mods can then use `IsControl` to detect conflicts between custom controls.
`(nothing) SetIsControl keyCode:int isControl:bool`

IsControl - returns 1 if the specified key or mouse button is assigned to a game control, 2 if it has been registered as a custom control by a mod via `SetIsControl`, or 0 otherwise.
`(isControl:int) IsControl keyCode:int`

IsKeyDisabled - returns 1 if the key has been disabled using `DisableKey`
`(isDisabled:bool) IsKeyDisabled keycode:int`

IsControlDisabled - returns 1 if thecontrol has been disabled by a call to `DisableControl`. Note that this only keeps track of calls to `DisableControl` and `EnableControl`; it does not check if the disabled state of the key or mouse button has been affected by `DisableKey`
`(isDisabled:bool) IsControlDisabled whichControl:int`

GetMouseButtonsSwapped - returns true if the user has configured his operating system to swap the left and right mouse buttons. Input functions do not change their behavior when the buttons are swapped.
`(swapped:bool) GetMouseButtonsSwapped`

## Math Functions

Abs - returns the absolute value of the argument
`(absoluteValue:float) abs arg:float`

Ceil - returns the nearest whole number above the argument
`(ceil:float) ceil arg:float`

Exp - returns e to the power of the argument
`(exp:float) exp arg:float`

Floor - returns the nearest whole number less than the argument
`(floor:float) floor arg:float`

Log - returns the natural logarithm of the number
`(log:float) log arg:float`

Log10 - returns the base 10 logarithm of the number
`(log10:float) log10 arg:float`

Pow - returns the base raised to the exponents power
`(pow:float) pow base:float exponent:float`

Rand - returns a random number between min and max
`(rand:float) rand min:float max:float`

SquareRoot - returns the square root of the argument
`(sqrt:float) squareroot arg:float`
`(sqrt:float) sqrt arg:float`

Fmod - returns the floating point modulus of dividend in the given base. This differs from `dividend % base` in the scripting language as `%` is a strictly integer function. When base is positive, `0 <= result < base`. The optional offset shifts the range of the result to `offset <= result < base+offset`.

The two most likely uses of this function are `modulus angle 360` to normalize a computed angle, i.e., ensure it is `>= 0` and `< 360.0` and `modulus angle 360 -180` which ensures the computed [change of] angle is `>= -180.0` and `< 180.0`.

`modulus n base` is defined as `n - base Floor n / base`. If the base is negative the direction of the inequality changes. Thus: `0 >= result > base` and `offset >= result > base+offset`.

Syntax:
`(fmod:float) fmod dividend:float base:float offset:float`

## Trigonometry Functions

ACos - returns the arccosine of the argument. `ACos` and `DACos` use degrees. `RACose` uses radians.
`(acos:float) acos arg:float`
`(acos:float) dacos arg:float`
`(acos:float) racos arg:float`

ASin - returns the arcsine of the argument. `ASin` and `DASin` use degrees. `RASin` uses radians.
`(asin:float) asin arg:float`
`(asin:float) dasin arg:float`
`(asin:float) rasin arg:float`

ATan - returns the arctangent of the argument. `ATan` and `DATan` use degrees. `RATan` uses radians.
`(atan:float) atan arg:float`
`(atan:float) datan arg:float`
`(atan:float) ratan arg:float`

ATan2 - returns the arctangent of the arguments. `ATan2` and `DATan2` use degrees. `RATan2` uses radians.
`(atan2:float) atan2 arg1:float arg2:float`
`(atan2:float) datan2 arg1:float arg2:float`
`(atan2:float) ratan2 arg1:float arg2:float`

Cos - returns the cosine of the angle. `Cos` and `DCos` use degrees. `RCos` uses radians.
`(cos:float) cos arg:float`
`(cos:float) dcos arg:float`
`(cos:float) rcos arg:float`

Cosh - returns the hyperbolic cosine of the angle. `Cosh` and `DCosh` use degrees. `RCosh` uses radians.
`(cosh:float) cosh arg:float`
`(cosh:float) dcosh arg:float`
`(cosh:float) rcosh arg:float`

Sin - returns the sine of the angle. `Sin` and `DSin` use degrees. `RSinh` uses radians.
`(sin:float) sin arg:float`
`(sin:float) dsin arg:float`
`(sin:float) rsin arg:float`

Sinh - returns the hyperbolic sine of the angle. `Sinh` and `DSinh` use degrees. `RSinh` uses radians.
`(sinh:float) sin arg:float`
`(sinh:float) dsin arg:float`
`(sinh:float) rsin arg:float`

Tan - returns the tangent of the angle. `Tan` and `DTan` use degrees. `RTan` uses radians.
`(tan:float) tan arg:float`
`(tan:float) dtan arg:float`
`(tan:float) rtan arg:float`

Tanh - returns the hyperbolic tangent of the angle. `Tanh` and `DTanh` use degrees. `RTanh` uses radians.
`(tanh:float) tanh arg:float`
`(tanh:float) dtanh arg:float`
`(tanh:float) rtanh arg:float`

## Bitwise Manipulation Functions

LeftShift - shifts the argument left by the specified number of bits. Returns zero if shiftAmount is >= 32.
`(result:int) LeftShift value:int shiftAmount:int`

RightShift - shifts the argument right by the specified number of bits, inserting zeros on the left. Returns zero if shiftAmount is >= 32.
`(result:int) RightShift value:int shiftAmount:int`

LogicalAnd - returns the bitwise AND of the two arguments
`(result:int)LogicalAnd arg1:int arg2:int`

LogicalOr - returns the bitwise OR of the two arguments
`(result:int)LogicalOr arg1:int arg2:int`

LogicalXor - returns the bitwise XOR of the two arguments
`(result:int)LogicalXor arg1:int arg2:int`

LogicalNot - returns the bitwise NOT of the argument
`(result:int)LogicalNot arg:int`

## Linear Algebra Functions

These functions treat Arrays as vectors and matrices, performing standard linear algebra operations on them.

Internally, matrices are two-dimensional arrays, where the elements of the outer array each arrays holding the rows. Therefore, `A[i][j]` refers to the jth element of the ith row, in keeping with common mathematical convention.

To be a matrix, the array must be one or two dimensional, contain only numerical values, and in the case of two-dimensional arrays, every row in the array must have the same length. These functions will always fail if an input does not meet these criteria.

Some functions require that the matrix be sqaure, which means that its height and width are equal.

Other functions further require that the matrix be a vector, that is, either be a one-dimensional array, or a two-dimensional array where there is either only one sub-array (a row vector), or every sub-array has only one element (a column vector).

One-dimensional arrays may be used as vectors, but these functions will not assume that they are either row or column vectors. In most cases, this is not important, but in some it is. For example, with `MatrixMultiply`, the value changes based on which of the vectors is a column vector and which is a row vector (see the function description for more information). In such ambiguous cases, the functions will not work; use `ForceRowVector` or `ForceColumnVector` to resolve such ambiguities. If a function does not indicate such a situation, one-dimensional arrays will work for a vector just fine.

These functions returns 0 if they fail for whatever reason (incompatible matrix dimensions is the most common reason). In some cases (e.g. `MatrixDeterminant`), 0 is also a valid return value, so it is the scripter's responsibility to ensure that the matrix is acceptable for the function.

GenerateZeroMatrix - Returns an n×m matrix with each element filled with a 0.
`(zeroMat:array) GenerateZeroMatrix height:int width:int`
`(zeroMat:array) ZeroMat height:int width:int`

GenerateIdentityMatrix - Returns a square (n×n) matrix with each element along the diagonal (from top-left to bottom-right) filled with a 1, and every other element with 0.
`(idenMat:array) GenerateIdentityMatrix height:int`
`(idenMat:array) IdentityMat height:int`

GenerateRotationMatrix - Returns a 3×3 square matrix that can serve as a rotation matrix about the specified axis. Rotation matrices are always invertible, and their inverse is equal to their transpose.
`(rotationMat:array) GenerateRotationMatrix axis:axis angle:float`
`(rotationMat:array) RotMat axis:axis angle:float`

VectorMagnitude - Returns the magnitude of a vector (square-root of the sum of the squares of its elements).
`(magnitude:float) VectorMagnitude vector:array`
`(magnitude:float) VecMag vector:array`

VectorNormalize - Returns the normalized version of a vector (each entry of the vector divided by its magnitude). A normalized vector has a magnitude of 1.
`(norm:array) VectorNormalize vector:array`
`(norm:array) VecNorm vector:array`

VectorDot - Returns the dot (scalar) product of two vectors. The vectors must have the same length.
Warning: If this function fails (generally because the vectors do not have the same length), it will return zero. However, zero is also a valid value for a dot product, so it is the scripter's responsibility to ensure that the vectors have the same length.
`(dotProduct:float) VectorDot vector:array vector:array`
`(dotProduct:float) dot vector:array vector:array`

VectorCross - Returns the cross (vector) product of two vectors. The vectors must have the same length.
`(crossProduct:array) VectorCross vector:array vector:array`
`(crossProduct:array) cross vector:array vector:array`

ForceRowVector - Takes a one-dimensional array, and returns an equivalent two-dimensional array, where the outer array's only element is the 1d array; i.e. `A[0][j] == v[j]`. This forces various linear algebra functions to treat the vector as a row vector, and can be necessary when using `MatrixMultiply`.
Note that row vectors require only 2 array variables, as opposed to the n+1 (where n is the number of elements) array variables needed for column vectors; for this reason, row vectors are generally preferred.
`(rowVector:array) ForceRowVector vector1d:array`
`(rowVector:array) RowVec vector1d:array`

ForceColumnVector - Takes a one-dimensional array, and returns an equivalent two-dimensional array, where the outer array's elements are each arrays with only one element - each element in the 1d array. I.e., `A[i][0] == v[i]`. This forces various linear algebra functions to treat the vector as a column vector, and can be necessary when using `MatrixMultiply`.
Note that row vectors require only 2 array variables, as opposed to the n+1 (where n is the number of elements) array variables needed for column vectors; for this reason, row vectors are generally preferred.
`(colVector:array) ForceColumnVector vector1d:array`
`(colVector:array) ColVec vector1d:array`

MatrixTrace - Returns the trace of a square matrix, that is the sum of the elements along the diagonal (from top-left to bottom-right).
Warning: If the matrix is not square, the return value will be zero, but zero is also a possible value for an actual trace; it is the scripter's responsibility to ensure that the matrix is square.
`(trace:float) MatrixTrace squareMatrix:array`
`(trace:float) tr squareMatrix:array`

MatrixDeterminant - Returns the determinant of a square matrix.
Warning: If the matrix is not square, the return value will be zero, but zero is also a possible value for an actual determinant; it is the scripter's responsibility to ensure that the matrix is square.
`(determinant:float) MatrixDeterminant squareMatrix:array`
`(determinant:float) det squareMatrix:array`

MatrixRREF - Returns the reduced row echelon form (RREF) of a matrix.
`(rref:array) MatrixRREF matrix:array`
`(rref:array) RREF matrix:array`

MatrixInvert - Returns the inverse matrix of a given matrix. Returns 0 if the matrix is not invertible.
`(inverse:array) MatrixInvert matrix:array`
`(inverse:array) MatInv matrix:array`

MatrixTranspose - Returns the transpose of a matrix. The rows of a matrix become the columns of its transpose.
`(transpose:array) MatrixTranspose matrix:array`
`(transpose:array) Transpose matrix:array`

MatrixScale - Returns a matrix scaled by a number, that is, with every element multiplied by that number.
`(scaledMatrix:array) MatrixScale scalar:float matrix:array`
`(scaledMatrix:array) MatScale scalar:float matrix:array`

MatrixAdd - Returns the sum of two matrices, that is, a matrix where each element is the sum of the elements in the corresponding position in each of the addends. The two matrices must have the same dimensions.
`(sum:array) MatrixAdd addend:array addend:array`
`(sum:array) MatAdd addend:array addend:array`

MatrixSubtract - Returns the difference of two matrices, that is, a matrix where each element is the difference between the elements in the corresponding position in the terms. The two matrices must have the same dimensions.
`(difference:array) MatrixSubtract minuend:array subtrahend:array`
`(difference:array) MatSubtract minuend:array subtrahend:array`

MatrixMultiply - Returns the product of two matrices using matrix multiplication. Matrix multiplication is not commutative, that is, order matters and `AB != BA`. In order to multiply two matrices, the width of the first factor must equal the height of the second.
Two one-dimensional arrays (as opposed to two-dimensional vectors) cannot be multiplied because a column vector multiplied by a row vector has a different result than if a row vector is multiplied by a column vector, even if all the values are the same. Therefore, at least one of the vectors must be represented as a two-dimensional array (usually using `ForceRowVector`) to remove this ambiguity (they do not both need to be two-dimensional as a column vector cannot be multiplied with another column vector, nor a row vector with another row vector, so there is no ambiguity).
`(product:array) MatrixMultiply factor:array factor:array`
`(product:array) MatMult factor:array factor:array`

## Output Functions

Output functions are used to display messages. Some take a string containing format specifiers and an optional list of up to 20 variables which may include reference variables. Format specifiers include all of those used by the `Message` and `MessageBox` functions, as well as additional specifiers.

PrintToConsole - prints a formatted message to the console using the extended format specifiers
`(nothing) PrintToConsole formatString:string var1 var2 ... var20`
`(nothing) PrintC formatString:string var1 var2 ... var20`

Example script using MessageBoxEX:

    	ref refVar1
    	ref refVar2
    	short keyCode
    	short goldCost
    	set refVar1 to AdrianDecanusREF
    	set refVar2 to ShadySamREF
    	set keyCode to GetControl 15 ; menu key, assuming 'Tab' (15)
    	set goldCost to 500
    	MessageBoxEX "Press %k to summon a companion %rCost: %g gold|%n|%n|Cancel" keyCode goldCost refVar1 refVar2

The script displays a messageBox in the following format:

    	Press TAB to summon a companion	                  Cost: 500 gold	               [Adrian Decanus]	                   [Shady Sam]	                     [Cancel]

SetMessageSound - sets the sound which is to be played by the next call to `MessageEX`. The sound must be defined in the Sounds branch of the Object Window. Once `MessageEX` has been called the sound is cleared.
`(nothing) SetMessageSound soundID:string`

SetMessageIcon - sets the icon which is to be displayed to the left of the text for the next call to `MessageEX`. The icon is a .dds file located in the folder "Data\Textures\Menus\" or a subfolder thereof. Once `MessageEX` has been called the icon will be cleared.
`(nothing) SetMessageIcon iconPath:string`

DebugPrint - prints a message to the console only if debug mode has been enabled for the mod from which the calling script originates. Use `SetDebugMode` to toggle debug messages on or off.
`(nothing) DebugPrint formatString:string var1 var2 ... var20`

SetDebugMode - toggles all debug messages on or off for the mod from which the calling script originates. Pass 1 as the argument to turn debug messages on, or 0 to turn them off. Optionally pass the modIndex of the mod for which you wish to toggle messages.
`(nothing) SetDebugMode EnableDebugMessages:bool modIndex:int`

Print - prints a string expression to the console. This is mainly a convenience function to eliminate the need for temporary string variables when printing complex strings using `PrintToConsole`, as it supports string concatenation, the `ToString` function, etc.
`(nothing) Print string:expr`

PrintD - as `DebugPrint`, but accepts any OBSE expression evaluating to a string
`(nothing) PrintD string:expr`

## Spam-Blocking Functions

Some existing script functions generate UI messages in the top-left corner of the screen when called on the player. The following functions duplicate the behavior of those functions while suppressing those messages. Syntax is identical to the original functions.

- AddItemNS
- RemoveItemNS
- EquipItemNS
- UnequipItemNS
- AddSpellNS
- RemoveSpellNS

The following commands, in addition to suppressing UI messages, also suppress the "item up/down" sounds generated by their original versions:

- EquipItemSilent
- UnequipItemSilent

## Mod Functions

These functions return information about currently loaded Oblivion plugins and manipulate mod-specific data

GetModIndex - returns the mod index of the specified plugin. This is equivalent to the first two digits of the object's formID.
`(index:int) GetModIndex modName:string`

GetSourceModIndex - returns the mod index of the plugin from which the specified object originates
`(index:int) reference.GetSourceModIndex object:ref`

GetNumLoadedMods - returns the number of plugins currently loaded. Used in conjunction with GetModIndex, this can be used to verify load order at run-time.
`(loadedPluginCount:int) GetNumLoadedMods`

IsModLoaded - returns 1 if the specified .esp or .esm is currently loaded. String is case-insensitive but must include the file extension.
`(isLoaded:bool) IsModLoaded modName:string`

GetNthModName - returns the filename of the nth loaded mod
`(name:string_var) GetNthModName modIndex:int`

## Mod Local Data Functions

In some circumstances it is useful for a mod to record information about its state independent of the savegame. For instance, a mod which uses OBSE commands to modify objects or settings may want to reset those changes when a different savegame is loaded. OBSE provides each loaded mod with the ability to define data which persists for the duration of the game session. Data is defined as key-value pairs, where the key is a string and the value is a number, object, or string. A script has access only to the data defined for the mod to which it belongs. In the example below, a quest script is used to make sure that modifications to the player's movement speed are recorded in the savegame and reset when a new savegame is loaded

    	scriptName pcSpeedQuestScript
    	short moddedAmt		; the amount by which player's movement speed has been modified (stored in the savegame as a script variable)
    	short prevModAmt
    	begin gamemode
    	if getGameLoaded				; a game has been loaded
    		if getGameRestarted == 0					; reset the player's movement speed
    			let prevModAmt := GetModLocalData "speedMod"
    			ModPCMovementSpeed -prevModAmt
    		endif

    		; record the value from the savegame
    		SetModLocalData "speedMod" moddedAmt
    	endif
    	end

A script attached to an activator in the gameworld modifies the player's movement speed by 10 each time it is activated and updates the local data

    	scriptName pcSpeedActivatorScript
    	begin OnActivate player
    		let pcSpeedQuest.moddedAmt += 10
    		SetModLocalData "speedMod" pcSpeedQuest.moddedAmt
    		ModPCMovementSpeed 10
    	end

SetModLocalData - sets the data value associated with the specified key for the mod to which the calling script belongs. The key must be a string; the data can be a string, number, or object. Keys are case-insensitive and unique - only one data value can be associated with a particular key.
`(success:bool) SetModLocalData key:string data:multi`

GetModLocalData - gets the data value associated with the specified key for the mod to which the calling script belongs. If no data exists for the key, returns 0.
`(data:multi) GetModLocalData key:string`

ModLocalDataExists - returns true if local data exists with the specified key for the mod to which the calling script belongs.
`(exists:bool) ModLocalDataExists key:string`

RemoveModLocalData - removes the data value associated with the specified key for the mod to which the calling script belongs. If no data exists for the key, returns false, otherwise returns true.
`(removed:bool) RemoveModLocalData key:string`

GetAllModLocalData - returns a StringMap consisting of all of the name-value entries for the mod local data associated with the mod to which the calling script belongs. This is a copy of the local data so modifying the array contents will not modify the stored data.
`(data:StringMap) GetAllModLocalData`

## Hotkey Functions

GetHotkeyItem - returns the item or spell bound to the specified hotkey (1-8)
`(itemOrSpell:ref) GetHotkeyItem whichHotkey:int`

SetHotkeyItem - sets a hotkey to the specified spell or item
`(nothing) SetHotkeyItem whichHotkey:int spellOrItem:ref`

ClearHotkey - removes any spell or item bound to the specified hotkey
`(nothing) ClearHotkey whichHotkey:int`

## File Functions

FileExists - returns 1 if the specified file exists in the user's installation folder or within one of the BSA archives. Path is relative to the user's install folder, which is "Bethesda Softworks\Oblivion" by default.
`(fileExists:bool) FileExists filePath:string`

## UI Functions

Return information about the user interface. When the term "active menu" is used, it refers to the menu over which the mouse cursor is positioned when the command is called. Some functions accept an optional parameter specifying the specific menu you are interested in, assuming that menu is currently open.

GetActiveMenuMode - returns the menu code of the active menu. These are the same codes used by the `MenuMode` function.
`(menuCode:int) GetActiveMenuMode`

GetActiveMenuSelection - returns the item in the active menu over which the mouse is currently positioned
`(activeItem:ref) GetActiveMenuSelection`

The return type varies depending on the active menu:

Magic: Highlighted spell
Container: Highlighted item
Inventory: Highlighted item
SpellPurchase: Highlighted spell

GetActiveMenuFilter - returns the code which indicates the current filteroptions for the active menu
`(filterCode:int) GetActiveMenuFilter menuType:int`

GetActiveMenuRef - returns the reference from which the active menu is derived
`(menuRef:ref) GetActiveMenuRef menuType:int`

The return type varies depending on the active menu:

SpellPurchase: Spell merchant
Container: Container, corpse, or merchant
Dialog: Speaking NPC
Book: Book reference in the gameworld
Recharge: Recharging NPC, if any

GetActiveMenuObject - returns the base object from which the active menu is derived
`(menuObject:ref) GetActiveMenuObject menuType:int`

The return type varies based on the active menu type:

Book: Book base object
Alchemy: Potion being brewed
Message: The formID of the reference whose attached script generated the message, or the quest script which generated it. Returns 0 for game-generated messages such as confirmation boxes

GetEnchMenuSoulgem - returns the soulgem selected for enchantment in the enchantment menu. Only works if the enchantment menu is the active menu.
`(soulgem:ref) GetEnchMenuSoulgem`

GetEnchMenuEnchItem - returns the enchantment which is to be applied to the item to be enchanted. Only works if the enchantment menu is the active menu.
`(enchantment:ref) GetEnchMenuEnchItem`

IsBarterMenuActive - returns 1 if the player is bartering with a merchant, providing a way to distinguish between an ordinary container menu and a barter menu, which both return the same MenuMode code
`(isBarterMode:bool) IsBarterMenuActive`

GetAlchMenuIngredient - returns one of the four ingredients, from 0 to 3, selected for inclusion in the potion currently being brewed
`(ingredient:ref) GetAlchMenuIngredient whichIngred:int`

GetAlchMenuIngredientCount - returns the number of the specified ingredient selected for inclusion in the potion being brewed. Pass 0 for the first ingredient, 3 for the last.
`(count:int) GetAlchMenuIngredientCount whichIngred:int`

GetAlchMenuApparatus - returns the apparatus object being used in the brewing process
`(apparatus:ref) GetAlchMenuApparatus apparatusType:int`

CloseAllMenus - closes all currently open menus. Note: if the console is open at the time this function is called, it will be closed but the displayed console text will remain visible until the console is opened and closed again.
`(nothing) CloseAllMenus`

GetContainerMenuView - when the container/barter menu is open, returns 1 if the player is viewing his own inventory, or 0 if viewing the container or merchant's inventory
`(menuView:int) GetContainerMenuView`

SetButtonPressed - When any Message menu is displayed (game prompts such as the inventory quantity prompt as well as those created by the `MessageBox` function), forces the menu to behave as if the specified button was pressed. Button IDs range from 0 to 9.
`(nothing) SetButtonPressed buttonID:int`

IsGameMessageBox - returns 1 if a messagebox is currently displayed which was generated by game code (e.g., confirm item purchase) rather than a script
`(isGameMessage:bool) IsGameMessageBox`

GetMessageBoxType - returns a code indicating the origin of the currently-displayed messagebox

Return values:

- 0: No messagebox displayed or unknown origin
- 1: Generated from script
- 2: Confirm Buy Item
- 3: Confirm Sell Item
- 4: Confirm Give Item
- 5: Confirm Buy Spell
- 6: Confirm Poison Weapon
- 7: Confirm Overwrite Savegame
- 8: Confirm Load Savegame
- 9: Confirm Load Savegame with Missing Content
- 10: (RepairMenu) Attempting to repair a magic item without sufficient skill

`(type:int) GetMessageBoxType`

OBSE v0016 adds the ability to retrieve or modify the value of any trait defined in a menu's XML file. In order to use these commands you must specify the location of the desired trait within the XML hierarchy. For instance, given the following excerpt from MessageMenu.xml:

    	<menu name="MessageMenu">
    		<rect name="background">
    			<image name="button_1">
    				<visible> &true </visible>

To access the "visible" attribute of the first button, you would use "background\button_1\visible". Traits can have values of three types: float, boolean, or string. Boolean values are treated as floats, with 1 representing "false" and 2 representing "true." You must also specify the menu code of the menu you are interested in.

Examples:

    	float  floatVar
    	string_var strVar
    	; MessageMenu - is button 3 visible?
    	set floatVar to GetMenuFloatValue "background\button_3\visible" 1001
    	; MessageMenu - retrieve message text
    	set strVar to GetMenuStringValue "background\message_text\string" 1001
    	; hides the "Take All" button in the Container menu
    	SetMenuFloatValue "cont_background\page_layout\cont_contents\cont_button_take_all\visible" 1008 1
    	; sets the text of button 1 to the contents of strVar
    	SetMenuStringValue "background\button_1\button_1_text\string|%z" strVar 1001
    	; clicks the icon for the player's active spell, switching from item view to spell view if inventory is open
    	ClickMenuButton "hudmain_background\hudmain_magic_cover" 1009

GetMenuFloatValue - returns the value of a float or boolean trait of the specified menu
`(value:float) GetMenuFloatValue trait:formatString menuType:int`

GetMenuStringValue - returns the value of a string trait of the specified menu
`(value:string_var) GetMenuStringValue trait:formatString menuType:int`

SetMenuFloatValue - sets the value of a float or boolean trait of the specified menu
`(nothing) SetMenuFloatValue trait:formatString menuType:intnewValue:float`

SetMenuStringValue - sets the value of a string trait of the specified menu. The new value follows the trait name, separated from it by a pipe character. i.e. "elementName\traitName|newValue". (If calling from the console, replace the pipe character with the '@' character).
`(nothing) SetMenuStringValue traitAndNewValue:formatString menuType:int`

GetActiveUIComponentID - returns the integer ID of the menu elemented currently highlighted by the mouse cursor as defined by that element's <id> trait in the menu XML file.
`(id:int) GetActiveMenuComponentID`

GetActiveUIComponentName - returns the name of the menu element currently highlighted by the mouse cursor as defined in the menu XML file.
`(name:string_var) GetActiveUIComponentName`

GetActiveUIComponentFullName - like GetActiveUIComponentName, returns the name of the menu element currently highlighted by the mouse cursor, if any. However the returned name is fully qualified with the names of the element's parents in a form suitable to pass to commands like GetMenuFloatValue. i.e., if button_1 is highlighted in the MessageMenu, this command returns "background\button_1".
`(name:string_var) GetActiveUIComponentFullName`

ClickMenuButton - simulates the user clicking on the specified UI component. Pass the fully qualified component name as described above, or pass the <id> trait of the desired component as specified in the XML, preceded by a '#'; i.e. "`#32`" to click the button with ID 32. Note that specifying the name results in much better performance than specifying an ID.
`(nothing) ClickMenuButton componentName:formatString menuType:int`

GetMenuHasTrait - returns 1 if the menu has the trait specified. The trait name may be qualified with component names to access traits of subcomponents.
`(hasTrait:bool) GetMenuHasTrait traitName:formatString menuType:int`

GetTileChildren - given a UI component (referred to by the game as a "Tile"), returns an Array containing the names of all of the direct subcomponents of that component. Using this command is more efficient than accessing children individually if you need to inspect more than one subcomponent.
`(children:Array) GetTileChildren parentTile:string menuType:int`

GetTileTraits - given a UI component, returns a StringMap representing all of that component's traits and their values. The keys of the returned StringMap's elements are the names of the traits; their values are the string or numeric values of the traits. This command is more efficient for accessing multiple traits of the same component than the commands which access traits individually.
`(traits:StringMap) GetTileTraits componentName:string menuType:int`

PrintTileInfo - a debugging command which outputs all of the children of a UI component as well as the names and values of all of its traits. Output is sent to the console and to obse.log. Avoid using this function in released mods; it is intended for testing and debugging only.
`(nothing) PrintTileInfo componentName:string menuType:int`

PrintActiveTileInfo - a debugging command which outputs all of the children of the UI component currently under the mouse cursor as well as the names and values of all of its traits. Output is sent to the console and to obse.log. Avoid using this function in released mods; it is intended for testing and debugging only.
`(nothing) PrintActiveTileInfo`

GetMapMenuMarkerName - when the world map menu is visible and a location icon is highlighted by the mouse, this command returns the name of the highlighted icon. At all other times it returns an empty string.
`(markerName:string) GetMapMenuMarkerName`

GetMapMenuMarkerRef - when the world map menu is visible and a location icon is highlighted by the mouse, this command returns a reference to the MapMarker reference associated with the highlighted icon. This is a slow function, so avoid calling it repeatedly. If you want to detect changes in the currently highlighted map icon, it is best to check GetMapMenuMarkerName over the course of several frames, and only call GetMapMenuMarkerRef if the name changes and is not an empty string.
`(markerRef:ref) GetMapMenuMarkerRef`

GetBarterItem - returns the active item in a container menu
`(item:ref) GetBarterItem`

GetBarterItemQuantity - returns the selected quantity of the active item in a container menu
`() GetBarterItemQuantity`

GetLastTransactionItem - returns the item most recently confirmed for buying or selling by the player. Note that this transaction may not have been completed due to the purchaser having insufficient gold or attempting to sell a quest item. Use GetTransactionInfo for more accurate information.
`(item:ref) GetLastTransactionItem`

GetLastTransactionQuantity - returns the quantity of the most recent buy/sell transaction confirmed by the player. Note that the transaction may not have been completed due to the purchaser having insufficient gold or attempting to sell a quest item. Use GetTransactionInfo for more accurate information.
`(quantity:short) GetLastTransactionQuantity`

GetTransactionInfo - returns information about the most recent barter transaction completed by the player as a Stringmap. Specify "buy" for information about the player's most recent purchase, or "sell" for his most recent sale to a merchant. Once a transaction has been returned to a particular script, subsequent calls to this function requesting the same type of transaction ("buy" or "sell") will return zero until a new transaction of that type takes place. The returned Stringmap contains the following information:

    	"seller" (ref): The actor who sold the item
    	"buyer" (ref): The actor who purchased the item
    	"item" (base object): The item purchased or sold
    	"quantity" (short): The number of items purchased or sold
    	"price" (short): The total cost of the transaction

`(transactionInfo:Stringmap) GetTransactionInfo transactionType:string`

GetQMCurrent (GetQuantityMenuCurrentQuantity) - returns the current quantity in the quantity menu
`(quantity:int) GetQMCurrent`

GetQMMaximum (GetQuantityMenuMaximumQuantity) - returns the maximum quantity in the quantity menu
`(maxQuantity:int) GetQMMaximum`

GetQMItem (GetQuantityMenuItem) - returns the active item in the quantity menu
`(item:ref) GetQMItem`

GetClassMenuSelectedClass - while the class selection menu is visible, returns the class which would be selected by the player if he were to click 'Done'.
`(class:ref) GetClassMenuSelectedClass`

GetClassMenuHighlightedClass - while the class selection menu is visible, returns the class over which the cursor is currently positioned, if any.
`(class:ref) GetClassMenuHighlightedClass`

GetEnchMenuBaseItem - while the enchantment menu is visible, returns the unenchanted item selected by the player as the target of the enchantment.
`(item:ref) GetEnchMenuBaseItem`

UpdateContainerMenu - if called while a container or barter menu is displayed, updates the contents of the menu. In barter mode this recalculates prices and quantities of available items.
`(nothing) UpdateContainerMenu`

UpdateSpellPurchaseMenu - when called while the spell purchase menu is visible, updates the contents of the menu to reflect changes in prices
`(nothing) UpdateSpellPurchaseMenu`

## Text Input Functions

Allow the user to enter and edit text, with limited support for HTML formatting.

Controls while entering text:

- - Left/Right arrows: move cursor left or right. Pressing in conjunction with the CTRL key moves the cursor to the beginning of the closest word.
- - Home/End: move cursor to the beginning or end of the text.
- - Backspace/Delete: delete text. Use with CTRL to delete an entire word.
- - TAB: Inserts 4 spaces.
- - Up/Down: When editing books or scrolls, move cursor to the end of the previous line or the beginning of the next line.

Additional formatting can be inserted when editing books and scrolls by pressing CTRL in combination with one of the following:

- - L, R, or C: align the current line left, right, or center respectively. Alignment affects the current line and any subsequent lines until the next alignment tag.
- - 1, 2, 3, 4, 5: change the font of the text.

`<IMG>` tags are not directly supported, but can be added using `InsertInInputText`. The <, >, and ~ characters are not considered valid input characters.

Note that it is possible for the user to close the menu by clicking one of the buttons in a messagebox or the "Exit" button in a book. Calls to `UpdateTextInput` will re-display a messagebox with the user's text intact, but will not re-open a book once closed. Further, it is still necessary to call `CloseTextInput` to release the text input menu for use by other scripts.

OpenTextInput - opens a text input menu if one is not currently in use. MenuType is 0 for a messagebox, 1 for a book, or 2 for a scroll. The MaxLength parameter specifies how many characters to allow the user to enter. For messageboxes, the prompt string will be displayed before the cursor and cannot be erased. It may also contain buttons, with the button text separated from the prompt text with pipe '|' characters as in `MessageBoxEX`. For books and scrolls, the prompt string serves as the default text visible as soon as the menu is opened and may be edited by the user.
`(nothing) OpenTextInput promptString:string var1 var2 ... var20 menuType:int maxLength:int`

IsTextInputInUse - returns 1 if a script is currently using a text input menu, regardless of whether or not the menu is visible. Only one script may request text input at a time.
`(isInUse:bool) IsTextInputInUse`

GetInputText - returns the text entered by the user. You may call this function at any point before calling `CloseTextInput`. Note that the returned string includes any html formatting inserted by the user. It also includes an html prefix along the lines of `<FONT face="#"><div align="align">`.
`(inputText:string_var) GetInputText`

UpdateTextInput - tells the text input menu to check for user input and refresh the displayed text if necessary. In general, unless you want to temporarily disallow input, this command should be called every frame while the text input menu is open.
`(nothing) UpdateTextInput`

CloseTextInput - closes the text input menu, releasing it for use by other scripts. Be sure to call this command when you are done getting input.
`(nothing) CloseTextInput`

InsertInInputText - inserts formatted text at the current cursor position in the text input menu, as long as doing so would not increase the length of the text beyond its maximum length.
`(nothing) InsertInInputText formatString:string var1 var2 ... var20`

GetTextInputControlPressed - allows scripters to define custom controls for text input. Returns the scan code of the last key pressed in conjunction with the CTRL key, excluding those keys reserved for use by the text input menu. Once the code has been retrieved, subsequent calls to this command will return -1; it will also return -1 if no control has been pressed (similar to `GetButtonPressed`).
`(scanCode:int) GetTextInputControlPressed`

DeleteFromInputText - deletes a number of characters or words from the input text in the direction specified, beginning from the current cursor position. Note that an html tag is treated as both a word and a character (it is not possible to delete only part of a tag). Both optional parameters are false by default.
`(nothing) DeleteFromInputText numToDelete:int bBackwards:bool bDeleteWholeWords:bool`

GetTextInputCursorPos - returns the current position of the cursor as an index into the input string
`(cursorPos:int) GetTextInputCursorPos`

MoveTextInputCursor - moves the cursor a specified number of characters in the specified direction from its current position. Note that each html tag is treated as a single character.
`(nothing) MoveTextInputCursor numChars:int moveBackwards:bool`

SetInputText - replaces any text which has been input by the user with the specified text and repositions the cursor to the specified position. If the specified position is invalid (e.g. greater than the length of the text, or inside an html tag), returns false without modifying the input text; otherwise returns true. For books, the text must be in an appropriate format - no invalid html tags should be present and the text must be prefixed with html of the format `<FONT face="#"><div align="align">`
`(textSet:bool) SetInputText text:string newCursorPos:int`

SetTextInputHandler - registers a function script to handle control-key combos pressed while the current text input menu is active. The function script should accept a single integer argument; when a key is pressed in conjunction with the Control key, that key's scan code will be passed to the function script. The script will not be informed of control-key combos which are handled by OBSE (for instance, ctrl+5 to change to font #5) unless the default controls have been disabled with SetTextInputDefaultControlsDisabled. The function script is unregistered when the text input menu is closed.
`(nothing) SetTextInputHandler functionScript:ref`

SetTextInputDefaultControlsDisabled - sets whether or not OBSE responds to control-key combos it recognizes, such as ctrl+(number) for changing the font. While default controls are disabled, they will be passed to the function script registered with SetTextInputHandler or stored for retrieval using GetTextInputControlPressed. This setting is reset when the text input menu is closed.
`(nothing) SetTextInputDefaultControlsDisabled disableDefaultControls:bool`

Example script:

    scriptName GetUserInputSCR
    int button
    int state
    string_var userText
    begin OnEquip
    	if (IsTextInputInUse == 0)
    		OpenTextInput "Type stuff (max 20 chars) | Finished" 0 20
    		set state to 1
    	endif
    end

    begin menuMode
    	if (state)
    		set button to GetButtonPressed
    		if (button == 0) ; user has finished
    			set userText to GetInputText
    			CloseTextInput
    			set state to 0
    		else
    			UpdateTextInput
    		endif
    	endif
    end

## String Variables

OBSE v0016 introduces the string_var datatype for representing strings of characters. String variables can be declared and used like normal variables and can hold the return values from OBSE commands defined as returning a string_var. Their contents are preserved with the savegame. String-related commands include commands to modify a string variable and commands to retrieve a game string and store it in a string variable. Additionally, many existing commands like `SetName` now have EX counterparts (i.e. `SetNameEX`) which can accept a format string and a variable number of arguments, including string variables.

A string variable should not be used until it has been initialized with a value, by using it on the left hand side of a call to `sv_Construct` or a command that returns a string. An uninitialized string variable has a value of zero, which can be tested for in scripts. The value of an initialized string, on the other hand, is undefined and should never be modified directly by statements such as `set someStringVar to 6` or using arithmetic operators. Similarly, string variables should only be used to store strings, and the result of a string-returning variable should only (and always) be assigned to a string variable. Note that direct assignment of one string variable to another causes both variables to refer to the same string. For instance, in the following code:

    	string_var string1
    	string_var string2
    	set string1 to sv_Construct "First string"
    	set string2 to string1	set string1 to sv_Construct "Second string" ; modifies both string1 and string2

both string1 and string2 end up containing "Second string." If this is not desired behavior, use `sv_Construct` to copy the contents of one string to another, i.e.:

    	set string2 to sv_Construct "%z" string1 ; copies string1's contents to string2
    	set string2 to player.GetName ; modifies only string2

String variables persist in the savegame until they are explicitly destroyed or until the mod from which they originate is removed from the user's mod list. In general, string variables should be destroyed after use unless it is necessary to save their values permanently. In the following example, the string variable is used each time the scripted object is activated:

    	string_var refName
    	ref activatingRef
    	begin onActivate
    		set activatingRef to GetActionRef
    		set refName to activatingRef.GetName
    		if (sv_Count "e" refName > 0)
    			Message "Your name contains the letter e"
    		endif
    		set refName to sv_Destruct
    	end

Because the value of the string variable is only needed temporarily, `sv_Destruct` is used to prevent it from being saved.

As of OBSE v0017, string variables can be passed to any command expecting a string literal as an argument by prefacing the name of the variable with a dollar sign. This deprecates many of the Set...EX commands. The variable can be a quest variable, specified as $quest.varname, or local to the calling script specified as $varname. Example:

    	string_var msg
    	let msg := "Greetings from Stonekeep, " + player.GetName + "!!!"
    	MessageBox $msg

Additionally in v0017, support for string operations has been integrated into the language via OBSE expressions, which leaves functions such as `sv_Construct`, `sv_Substring`, etc. mostly deprecated.

sv_Construct - [text has been deleted]
`(nothing) sv_Construct formatString:string var1 var2 ... var20 variableToSet:string_var`

sv_Destruct - destroys a string variable, setting its value to zero and preventing its contents from being saved in the savegame. Two different syntaxes are supported: the first should be used in an assignment with no parameters, using the `Set` keyword: `set stringVar to sv_Destruct`. The second is used without assignment and accepts up to ten string variables as arguments, destroying them all: `sv_Destruct var1 var2 ... var10`.
`(string_var) sv_Destruct`
`(nothing) sv_Destruct var1:string_var var2:string_var ... var10:string_var`

sv_Length - returns the number of characters in a string variable
`(length:int) sv_Length variable:string_var`

sv_Compare - compares a string to a formatted string. Performs a case-insensitive comparison by default. Returns 0 if the strings are equal, 1 if the string variable occurs alphabetically before the formatted string, -1 if the string variable occurs alphabetically after the formatted string, or -2 if the comparison fails.
`(comparison:int) sv_Compare formatString:string var1 var2 ... var20 variable:string_var caseSensitive:bool`

sv_Erase - erases the specified number of characters from a string starting at the specified position. If omitted, startPos = 0. Omitting numToErase erases all characters from `startPos` to the end of the string.
`(nothing) sv_Erase variable:string_var startPos:int numToErase:int`

sv_ToNumeric - attempts to convert the contents of a string variable to a number. Valid characters include digits, a leading sign, and an e to indicate scientific notation. Conversion halts at the first invalid character.
`(float) sv_ToNumeric sourceString:string_var`

sv_Find - returns the index of the first occurrence of a substring within a string variable, starting at the specified position and only including occurrences contained completely within the range [startPos, startPos + searchLen]. Omit the arguments to search the entire string without regard to case.
`(index:int) sv_Find subString:formatString formatVars source:string_var startPos:int searchLen:int caseSensitive:bool`

sv_Count - returns the number of occurrences of a substring within a string variable, using the same arguments as `sv_Find`.
`(count:int) sv_Count subString:formatString formatVars source:string_var startPos:int searchLen:int`

sv_Replace - replaces occurrences of a string1 with string2 within a string variable. Both the text to replace and that with which to replace it are passed in a single format string separated by a pipe character as in "toReplace|replaceWith" (when calling from the console, use '@' in place of the pipe character). You can specify a range to search and case-sensitivity as in `sv_Find`, plus an additional final argument specify how many occurrences to replace. By default, the command replaces all occurrences.
`(numReplaced:int) sv_Replace subString:formatString formatVars source:string_var startPos:int searchLen:int caseSensitive:bool numToReplace:int`

sv_Insert - inserts a substring into a string at the specified position, provided the position is less than the length of the string, or prepends it if no position is specified.
`(nothing) sv_Insert subString:formatString formatVars targetString:string_var insertPos:int`

sv_Split - given a string and a set of delimiters, returns an Array containing all the substrings separated by one or more of the delimiting characters. For example, `sv_Split "#This is.a##. string." ".# "` returns `{ "This", "is", "a", "string" }`. The '.', '#', and space characters are removed.
`(substrings:Array) sv_Split toSplit:string delimiters:string`

GetKeyName - returns the name of a key given its DirectInput scan code
`(keyName:string) GetKeyName keycode:int`

AsciiToChar - returns the character associated with an ASCII code as a string
`(character:string) AsciiToChar asciiCode:int`

NumToHex - returns a string representation of an integer in hexadecimal format. An optional width parameter ranging from 0 to 8 specifies the minimum number of digits toinclude; unused digits are padded with zeroes. By default, 8 digits are included.
`(hex:string) NumToHex num:int width:int`

sv_Percentify - Takes an input string and returns it with each '%' character replaced by two '%' characters. For instance, "100% gold" becomes "100%% gold" and "99.99%%" becomes "99.99%%%%". The argument can be any expression evaluating to a string value.
`(percentified:string) sv_Percentify source:string`

sv_ToLower - returns the passed string with all characters converted to lowercase.
`(lower:string) sv_ToLower source:string`

sv_ToUpper - returns the passed string with all characters converted to uppercase.
`(upper:string) sv_ToUpper source:string`

#### Character Functions

A single character is represented by an integer with a value from 0 to 127 corresponding to its ASCII code. `sv_GetChar` returnscharacters.

IsDigit - returns 1 if the character is a digit
`(isDigit:bool) IsDigit character:int`

IsPunctuation - returns 1 if the character is punctuation
`(isPunctuation:bool) IsPunctuation character:int`

IsUppercase - returns 1 if the character is an uppercase letter
`(isUpper:bool) IsUppercase character:int`

IsPrintable - returns 1 if the character is printable (not a non-printable control character)
`(isPrint:bool) IsPrintable character:int`

IsLetter - returns 1 if the character is alphabetic
`(isLetter:bool) IsLetter character:int`

CharToASCII - returns the ASCII code of a character passed as a string. Additional characters in the string are ignored.
`(character:int) CharToASCII character:string`

ToUpper - returns the ASCII code of a character converted to uppercase
`(upperCharacter:int) ToUpper character:int`

ToLower - returns the ASCII code of a character converted to lowercase
`(lowerCharacter:int) ToLower character:int`

ToNumber - takes a string expression and attempts to convert it to a numeric value. By default the string is assumed to be in decimal notation containing digits, at most one decimal point, and an optional leading sign. If the string is prefixed with "0x" or the optional argument is non-zero, the string is interpreted in hexadecimal notation instead, with valid characters consisting of digits and the letters 'A' through 'F'. Returns 0 if the conversion fails.
`(number:float) ToNumber expression:string bIsHex:bool`

#### Examples:

Copying a string:
`set string2 to sv_construct "%z" string1`

Concatenating two strings:
`set string2 to sv_construct "%z%z" string1 string2`

## Format Specifiers

Some OBSE commands take a format string as a parameter. Format strings are actually a collection of arguments consisting of a string followed by zero to twenty variables and/or numbers. The string specifies how the command should use the rest of the arguments to construct a new string. Within the format string, percent signs are used to indicate special characters.

The format specifiers recognized by OBSE commands include all of those recognized by vanilla Oblivion script commands like `MessageBox` as well as several extended specifiers:

- %a - replaced by the character matching the ASCII code passed as an integer
- %c - replaced with the name of a component within another object. Takes two arguments - an object (ref) and the index of the component you want to access (short). Supported object types:
  - Magic Item - prints the name of the nth effect item.
  - Faction - prints the male rank title of the nth rank.
- %e - replaced by nothing. Useful for passing an empty string as an argument, as the script compiler will not accept an empty string. Can be used outside of format strings.
- %i - is replaced by the formID of a reference or object passed in a ref variable
- %k - replaced by a string representing the key associated with a DirectInput scan code
- %n - replaced with the name of a reference or object passed in a ref variable
- %p - replaced with a pronoun based on the gender of the object parameter passed in a ref variable:
  - %ps - subjective (he, she, it)
  - %pp - possessive (his, her, its)
  - %po - objective (him, her, it)
- %q - replaced with a double quote character (takes no arguments). Can be used outside of format strings.
- %r - replaced by a new-line character (takes no arguments). Can be used outside of format strings.
- %v - replaced by the name of an actor value passed as an integer actor value code
- %x - replaced with an integer in hexadecimal format. An optional digit from 0-9 immediately following this specifier indicates the minimum width of the displayed value. For example, `MessageEx "%x4" 255` will display "00FF".
- %z - replaced by the contents of a string variable
- %{ .. %} - Conditionally omits a portion of the format string based on a boolean value. The left bracket accepts a variable; if the value of the variable is zero, all text up to the right bracket will be ignored, and any parameters supplied to format specifiers within the omitted substring will be skipped.
- %B - toggles blue text on for console output
- %b - toggles blue text off for console output. e.g. "%BBlue%b suede shoes": when printed to the console, the word "Blue" will be printed in blue text.

Note that the %e, %q, and %r specifiers can be used within any string literal and will be replaced by an empty string, a double quote, or a carriage return respectively.

## Array Variables

OBSE v0017 introduces the array_var datatype for storing a collection of values within a single variable. An array_var is a set of data elements each identified by a unique key. A key can be a number or a string, and the value associated with the key can be a string, number, game object, or another array. An element's value can be accessed using bracket notation, e.g. `array[key]`. In this documentation, "key" refers to the element's key, and "value" refers to the data associated with that key.

All elements within an array must have the same type of key - all strings or all numeric. However, an array can contain any mix of types for its values. Elements are sorted by key, in ascending order either alphabetically or numerically depending on the key type.

OBSE's array_var type actually represents three different kinds of associative containers:

1. Array:
  An Array behaves like arrays in most programming languages: the key is an unsigned integer starting at zero, and there are no gaps between elements. (In other words, if an element exists at indexes 1 and 3 then an element necessarily exists at 0 and 2). Attempting to access an element using a key which is greater than the highest key in the array results in an error. The only exception to this rule is during assignment: it is okay to assign a value to the key which is one greater than the highest key in the array.
2. Map:
  A Map associates numeric keys with values. Unlike an Array, a Map allows negative and floating point numbers to be used as keys and allows gaps to exist between elements.
3. StringMap:
  Like a Map, except the keys are strings. Keys are case-insensitive, so `array[INDEX]` and `array[index]` both refer to the same value. There is no practical limit on the length of the strings used as keys. StringMaps can be used to simulate C-style structs by associating named properties with data values.

An array_var must be initialized before it can be used in expressions, either by explicitly initializing it using `ar_Construct`, assigning the value of another array_var to it, or assigning it the return value of a command returning an array such as `GetItems`. Most array operations should be performed within OBSE expressions such as `Let` or `Eval` statements. Array elements cannot be passed directly to most commands as arguments. Assigning one array to another as in `Let array_1 := array_2` causes both array_1 and array_2 to refer to the same array, as illustrated below:

    	array_var a
    	array_var b
    	let a := ar_Construct Array
    	let a[0] := "First elem"
    	let b := a                  ; b now refers to the same array as a
    	let b[1] := "Second elem"   ; array now contains two elements

OBSE keeps track of the number of references to each array and destroys the array when no references to it remain. This makes it unnecessary for scripts to worry about destroying arrays explicitly. For example, continuing from the code above:

    	; our array currently has 2 references: the variables a and b
    	let a := ar_Construct StringMap ; now a refers to a new array, and only b refers to ours
    	let b := ar_Null                ; b now refers to no array. No references to our array remain
    	; OBSE will delete the unreferenced array

### Array Operations

OBSE supports a variety of operations on arrays within the context of `Let`, `Eval`, and similar statements.

#### Examples:

    	array_var arr_1
    	array_var arr_2
    	let arr_1 := ar_Construct Array
    	let arr_1[0] := "a string"
    	let arr_1[1] := 1.234
    	let arr_1[2] := Player.GetEquippedObject 16
    	; let arr_1[10] := 0 <- this is an error, index out of bounds
    	let arr_1[3] := Player.GetEquippedItems	; <- arr_1[3] is another array
    	let arr_1[4] := arr_1[3][0]		; <- access first item returned by GetEquippedItems
    	let arr_2 := arr_1[1:3]			; <- arr_2 contains elements 1, 2, and 3 from arr_1
    	let arr_2 := arr_1[1:-2]  ; <- arr_2 contains elements 1 through (size of arr_1 minus 2) of arr_1

### Array Functions

Note: Unless otherwise indicated, an `array_var` parameter may be either a variable declared as array_var or an array element containing an array. Commands accepting this type of parameter must be called within the context of an OBSE expression such as `Let` or `Eval`.

ar_Construct - creates a new array_var and assigns it to an array variable. Must be called within the context of an OBSE expression such as `Let`. The parameter specifies the type of array to create: StringMap, Map, or Array. See the above section for more information on the different types of array variables.
`(array_var) ar_Construct arrayType:string`

ar_Size - returns the number of elements in an array, or -1 if the array is not initialized. For Array-type variables the highest key in the array is equal to one less than the array's size. Must be called within the context of an OBSE expression. The array can be an array variable or an array element which contains an array.
`(size:int) ar_Size array:array_var`

ar_Dump - for debugging purposes, prints the key and value of every element in an array to the console. Must be called within an OBSE expression.
`(nothing) ar_Dump array:array_var`

ar_DumpID - does the same as ar_Dump but accepts an array ID instead of an array_var. Provided as a convenience for debugging in the console.
`(nothing) ar_DumpID arrayID:int`

ar_Erase - erases elements from an array. You may provide a single element, in which case only that element will be erased and only if it is present. Or, you may provide a range in slice notation. Any elements greater than or equal to the lower bound and less than or equal to the upper bound of the range will be erased. If the array is of type `Array`, elements above the erased elements will be shifted down. Returns the number of elements removed. Users of OBSE 0020 or later may omit the second argument; doing so will erase all elements of the array.
`(numRemoved:int) ar_Erase target:array index:arrayIndex`
`(numRemoved:int) ar_Erase target:array range:slice` (numRemoved:int) ar_Erase target:array

Examples:

    	array_var arr
    	let arr := ar_Construct StringMap
    	let arr["another array"] := ar_Construct Array
    	ar_Erase arr["another array"] 0  ; erase element 0 if it exists, higher elements will be shifted down by 1
    	ar_Erase arr "begin":"end"  ; erase any elements having keys >= "begin" and <= "end"

ar_Find - locates the first occurrence of the specified value within an array and returns the key associated with it. A range may optionally be specified using range notation, i.e. `let key := ar_Find "tofind" arrayVar lowerBound:upperBound`. If the value is not found, the function returns an empty string (for string-indexed arrays) or the value -99999.0 (for numeric-index arrays).
`(key:stringOrNumber) ar_Find value:stringOrNumberOrForm arrayToSearch:array inRange:range`

ar_Sort - attempts to sort the elements of an array in ascending or descending order and returns a new Array containing the elements in sorted order (keys associated with the elements are lost). In order to be sorted all elements of an array must be of the same type (strings, numbers, or objects). If this condition is not met an empty Array is returned. Strings are sorted alphabetically and case-insensitively, numbers are sorted numerically, and objects are sorted by formID. By default the elements are sorted in ascending order.
`(sortedArray:Array) ar_Sort toSort:array sortDescending:bool`

ar_SortAlpha - sorts the elements of an array alphabetically in ascending or descending order and returns a new Array containing the elements in sorted order. Ordering is case-insensitive. Unlike `ar_Sort`, does not require elements to be of the same type - numeric elements are converted to a string representation, and forms are sorted by their names (if named) or the string representation of their formIDs. Omitting the optional parameter causes elements to be sorted in ascending order.
`(sortedArray:Array) ar_SortAlpha toSort:array sortDescending:bool`

ar_Copy - creates a copy of the keys and elements of the specified array. The resulting array is identical to the source array. If the source array contains other arrays, the copy will contain references to those same arrays.
`(copy:array) ar_Copy src:array`

ar_DeepCopy - performs the same function as `ar_Copy`, except any arrays contained within the source array are also copied (and any arrays within those arrays are copied as well, and so on).
`(copy:array) ar_DeepCopy src:array`

ar_First - returns the key of the first element in an array
`(key:arrayKey) ar_First src:array`

ar_Last - returns the key of the last element in an array
`(key:arrayKey) ar_Last src:array`

ar_Next - returns the key of the element immediately following the passed key, or `BadIndex` if no key follows it
`(key:arrayKey) ar_Next src:array precedingKey:arrayKey`

ar_Prev - returns the key of the element immediately preceding the passed key, or `BadIndex` if no key precedes it
`(key:arrayKey) ar_Prev src:array prevKey:arrayKey`

ar_BadNumericIndex - returns a constant representing an invalid numeric array index. Compare to the return value of commands returning an array key to determine if a valid key was returned.
`(badKey:int) ar_BadNumericIndex`

ar_BadStringIndex - as above, but for string array keys
`(badKey:string) ar_BadStringIndex`

ar_Keys - returns an Array containing all of the keys of the source array
`(keys:Array) ar_Keys src:array`

ar_HasKey - returns true if the array has an element with the specified key
`(hasKey:bool) ar_HasKey src:array key:arrayKey`

ar_Null - returns an invalid array. This is useful if you wish to specify that a variable which previously referred to an array should no longer refer to any array.
`(nullArray:array) ar_Null`

ar_List - Takes up to twenty arguments of any type and returns an Array containing those elements in the order in which they were passed. We recommend separating the values with commas (starting after the first argument).
`(list:Array) ar_List element0:multi element1:multi ... element19:multi`

The following commands are usable only with Array-type arrays:

ar_Resize - resizes an Array-type array to be of the specified size. If the new size is smaller than the current size, elements at the end of the array are discarded. If the new size is larger, additional elements are appended to the array. By default these elements have the numeric value zero, but an optional argument can be used to specify the value with which to pad the array. Returns 1 if successful, 0 otherwise.
`(bResized:bool) ar_Resize array:Array newSize:int paddingValue:multi`

ar_Insert - inserts a single element into an Array-type array at the specified index provided the index is not greater than the current size of the array. Elements above the index are shifted up by one index.
`(bInserted:bool) ar_Insert array:Array index:int valueToInsert:multi`

ar_InsertRange - inserts a range of elements into an Array-type array at the specified index provided the index is not greater than the current size of the array. The range is passed as an Array. Each element of the range is inserted into the target Array in order. Elements above the insertion index are shifted up by the number of elements inserted.
`(bInserted:bool) ar_Insert target:Array index:int rangeToInsert:Array`

ar_Range - returns an Array of zero or more numbers ranging from start up to and including end spaced in intervals of step. For example, `ar_Range (5,10,2)` returns `(5,7,9)` and `ar_Range (5,3,-1)` returns `(5,4,3)`. This is useful for performing a traditional `for` loop within a `foreach` expression. The optional step argument defaults to 1.
`(range:Array) ar_Range start:int end:int step:int`

ar_Map - creates a Map or Stringmap given a list of 0-20 key-value pairs. Pairs are specified as 'key::value', where 'key' is a string or numeric value and 'value' is a string, number, array, or form.
`(Map/StringMap) ar_Map key-value pair: key-value pair: key-value pair: entry_1:pair entry_2:pair ... entry_20:pair`

ar_Append - appends an element to an Array
`(nothing) ar_Append array: toInsert:`

ar_CustomSort - returns an Array sorted by calling the provided function script to perform comparison of elements. The function should be defined to take two array_var arguments. When it is called, the arguments will contain exactly one element each - the elements to be compared. It should return true if the first argument is less than the second argument, and true if it is greater than or equal to the second argument. You can define 'less', 'greater', and 'equal' in whatever way makes sense for you provided your definitions provide a definitive ordering of any set of values; otherwise the sort may never terminate. The optional third argument sorts the elements in reverse order.
`(sorted:Array) ar_CustomSort toSort:Array comparisonFunction:ref reverse:bool`

## OBSE Expressions

OBSE v0017 introduces support for evaluation of complex expressions involving a larger set of operators than that provided by Oblivions `set` and `if` statements, type-checking and type inference, and operations on strings and arrays. These expressions are supported within the context of new commands such as `let` (for assignment, analogous to `set`) and `eval` (to be used within `if` statements to test the value of a boolean expression).

Operators
Symbol | Precedence | Function | Number of Operands | Description
--- | --- | --- | --- | ---
`:=` | 0 | Assignment | 2 | Assigns the value of an expression on the right to the variable or array element on the left. Right-associative. The value of the assignment is the right-most operand. Supports multiple assignment i.e. `a := b := c := 0` sets all 3 variables to zero. Assignment of strings creates a copy of the string, whereas assignment of arrays creates a reference to the array.
`||` | 1 | Logical Or | 2 | True if either expression is true.
`&&` | 2 | Logical And | 2 | True if both expressions are true.
`+=` | 2 | Add and Assign | 2 | Adds the expression on the right to the variable or array element on the left.
`-=` | 2 | Subtract and Assign | 2 | Subtracts the expression on the right from the variable or array element on the left.
`*=` | 2 | Multiply and Assign | 2 | Multiplies the variable or array element on the left by the expression on the right.
`/=` | 2 | Divide and Assign | 2 | Divides the variable or array element on the left by the expression on the right.
`^=` | 2 | Exponent and Assign | 2 | Raises the variable or array element on the left to the power of the expression on the right.
`:` | 3 | Slice/Range | 2 | Specifies a range of elements in a string or array. For strings, creates a substring. For arrays, creates a copy of the elements within the range. Range includes the upper element. For strings, negative indices start at the last element and count backwards.
`::` | 3 | Make Pair | 2 | Specifies a key-value pair. The lefthand operand defines the key as a numeric or string value, and the righthand operand defines the value (of any type).
`==` | 4 | Equality | 2 | True if the operands are equal. Operands must be comparable to each other.
`!=` | 4 | Inequality | 2 | True if the operands are not equal.
`>` | 5 | Greater Than | 2 | Operands must be comparable and ordered. For strings, comparison is case-insensitive.
`<` | 5 | Less Than | 2 | For strings, case-insensitive.
`>=` | 5 | Greater or Equal | 2 | For strings, case-insensitive.
`<=` | 5 | Less than or Equal | 2 | For strings, case-insensitive.
`|` | 6 | Bitwise Or | 2 | Performs a bitwise or, demoting the operands to integers.
`&` | 7 | Bitwise And | 2 | Performs a bitwise and, demoting the operands to integers.
`<<` | 8 | Binary Left Shift | 2 | Shifts left operand left by specified number of bits, demoting both operands to integers.
`>>` | 8 | Binary Right Shift | 2 | Shifts left operand right by specified number of bits, demoting both operands to integers.
`+` | 9 | Addition/Concatentation | 2 | Adds two numbers or joins two strings.
`-` | 9 | Subtraction | 2 | Self-explanatory.
`*` | 10 | Multiplication | 2 | Self-explanatory.
`/` | 10 | Division | 2 | Self-explanatory.
`%` | 10 | Modulo | 2 | Returns the remainder of integer division.
`^` | 11 | Exponentiation | 2 | Raises left operand to the power of the right operand.
`-` | 12 | Negation | 1 | Returns the opposite of an expression.
`$` | 12 | Stringize | 1 | Returns a string representation of an expression. (Shorthand for ToString).
`#` | 12 | Numericize | 1 | Returns the numeric value of a string. (Shorthand for ToNumber).
`*` | 12 | Dereference/Unbox | 1 | Dereferences an array. If the array is a StringMap with a "value" key, returns the value associated with that key. Otherwise returns the value of the first element.
`&` | 12 | Box | 1 | "Boxes" a value of any type, returning an Array containing that value as its only element. The value can be retrieved with the unary * (unbox) operator.
`!` | 13 | Logical Not | 1 | Returns the opposite of a boolean expression. i.e. `!(true)` evaluates to false.
`( )` | 14 | Parentheses | 0 | Enclose expressions within parentheses to override default precedence rules.
`[ ]` | 15 | Subscript | 2 | For arrays, accesses the element having the specified key. For strings, returns a string containing the single character at the specified position. The expression within the brackets is treated as if it were parenthesized (overrides precedence rules).
`->` | 15 | Member Access | 2 | The lefthand operand is a StringMap having a key specified by the righthand operand. Returns the value associated with that key. Example: 'dict->key' is equivalent to 'dict["key"]'

### Using OBSE expressions in scripts

By default, only a handful of OBSE commands like Let, Eval, and ar_List accept OBSE expressions as arguments. However, as of v0020 OBSE allows individual script blocks to optionally be compiled in a way that lets any command accept OBSE expressions - including arrays, strings, and user-defined function calls - as arguments. To turn this feature on for a script block, prepend an underscore to the block name. All commands within that block will then be allowed to accept OBSE expressions. For example:

    	; compiled normally
    	begin gamemode
    	  let axis := someArray[index]
    	  let pos := (call SomeFunction) + someRef.getPos z
    	  if eval axis == "Z"
    		setpos z pos
    	  elseif eval axis == "Y"
    		setpos y pos
    	  else
    		setpos x pos
    	  endif
    	end

    	; the same behavior, compiled with OBSE expression support enabled
    	begin _gamemode
    	  setPos someArray[index], (call SomeFunction)  + someRef.getPos z
    	end

This gives you increased flexibility when using certain argument types:

- Actor value: Accepts a string such as "strength" or an integer actor value code
- Effect setting: Accepts a string such as "FIDG", an integer effect code, or a ref

Note that commands originating from an OBSE plugin will be compiled without support for OBSE expressions unless the plugin has been built with OBSE v0020 or later. Check with the plugin author for updates and be sure to test the plugin version at run-time if you use this feature to ensure that your users have an appropriate version installed.

### Considerations

Unlike most programming languages, Oblivion's scripting language doesn't require function arguments to be delineated (e.g., enclosed in parentheses). In most cases this is not a problem, but when an expression contains a call to a function which itself accepts an expression as an argument, followed by another argument or expression, OBSE cannot determine where the inner expression ends. In these cases the entire function call, including the function name, can be enclosed in parentheses to clarify the statement.

Example:
`let a := ar_size array1 + ar_size array2`

The above expression will not compile because OBSE tries to interpret the entire expression following the first call to `ar_size` as an array. Instead the expression must be written as:
`let a := (ar_size array1) + ar_size array2`

For the majority of commands, including all vanilla commands, OBSE commands prior to v0017, and most v0017 commands, the parentheses are not required.

Scripts compiled with OBSE v0018 or greater are made dependent on their respective versions even if their commands are not being used, as the script bytecode representation was changed in the former.

### Run-time Error Reporting

Because it performs type-checking and type-inference, OBSE can detect and report most syntax errors when compiling a script in the Construction Set. However in some cases errors may be impossible to detect until the script is executed. In ambiguous cases, OBSE gives the scripter the benefit of the doubt by assuming the expression is valid. Run-time errors are logged to the console and obse.log, along with the formID of the script which caused the error. Errors may be tested for (and the output of error messages suppressed) using the `TestExpr` command.

Common causes of run-time errors include:

- Expressions involving array elements: Because an array element can hold a value of several types, its type is ambiguous at compile-time. For instance, an expression multiplying two array elements will compile, but will cause an error at run-time if the elements contain non-numeric values. It is the scripter's responsibility to either know that the elements are of the correct type or check their types at run-time.
- Uninitialized arrays: It is an error to use bracket notation to attempt to retrieve an element from an uninitialized array. Arrays are initialized by assignment, for instance by calling `ar_Construct` or by assigning the return value of a command like `GetItems` to an array variable. An uninitialized array stores an arrayID of 0 so testing if an array is initialized is as simple as `if (array)`.
- Non-existent or out-of-bounds array index: Attempting to retrieve a value from an array using a key which does not exist in that array is an error. Assigning to an element with a key which doesn't exist is fine - doing so creates an element with that key - unless the array is of the Array type, in which case using a key which is greater than the number of elements in the array will cause an error.
- Function calls: OBSE knows the return type of commands which return strings or array. However, all vanilla commands and the majority of OBSE commands do not return strings or arrays; they return either numbers or objects. At compile-time OBSE can't know which will be returned, so attempting to use the result of a command like `GetInventoryObject` in an arithmetic expression will result in an error at run-time.

### Expression Statements

Let - The Let statement is OBSE's version of Oblivion's `Set` statement. It takes the form `let expr1 := expr2` where expr1 evaluates to something which can hold a value, such as a variable or array element, and expr2 is an expression of a type which can be stored in expr1. Values within expressions can include arithmetic expressions, function calls, etc. The assignment operator checks the types of its operands, so it will allow assigning a number to a `short` variable but not to a `string_var`.
`(nothing) Let expr := expr`

There is no practical limit to the complexity of the expressions on either side of the assignment as long as their types match.

Examples:

    string_var str
    array_var arr
    short num
    let str := "a string"
    let str := str[0:num] + player.GetName + " some more text"
    let arr := ar_Construct Map
    let arr[(num + player.GetPos Z) / player.GetPos X] := player.GetDistance someRef ^ 2

Eval - `Eval` is used within `if` statements to test the value of an expression. This allows OBSE expressions to be used as conditions. The expression must evaluate to a boolean value.
`(bool) Eval expr`

Example:

    if eval (array[0] > 1)
    	; code executes if array[0] > 1
    endif

TestExpr - attempts to evaluate an expression, returning false if an error occurs during evaluation and true otherwise. This can be useful when checking if an array index is out of bounds or if an element exists with a given key, among other things. `TestExpr` suppresses the output of error messages to the console and log file.
`(bool) TestExpr expr`

Example:

    array_var array
    let array := ar_Construct Array
    if testexpr (array[5] := 2)
    	PrintC "5 is a valid index, assignment succeeded."
    else
    	PrintC "Index 5 is out of bounds, no assignment."
    endif
    let array := ar_Construct StringMap
    if testexpr (array["INDEX"])
    	PrintC "An element exists in array with key 'INDEX'"
    else
    	PrintC "No element with the specified key exists."
    endif

ToString - attempts to convert an expression to a string. For numeric expressions, the result is a string representation of the numeric value. For objects, it is the name of the object if available; otherwise it is the formID expressed in hexadecimal notation. For string expressions no conversion is necessary.
`(string) ToString expr`

Note that the `$` operator can be used in place of `ToString`. The following two lines are equivalent:

    let aStringVar := ToString (aNumber + 1)
    let aStringVar := $(aNumber + 1)

TypeOf - returns a string representing the type of an expression. This is mainly useful for determining the type of an array element at run-time. Possible return values: "String", "Number", "Form", "Array", "StringMap", "Map".
`(type:string) TypeOf expr`

## User-Defined Functions

OBSE allows scripters to define their own functions, which can be called from other scripts. When a function is called, script execution passes to the function and resumes after the function call when a return statement is encountered or execution reaches the end of the function script. Factoring commonly-used code out into a function prevents repetitious code and shortens scripts. Encapsulating complicated routines into stand-alone functions results in simplified, more readable code.

Functions are defined as Object scripts but are treated as a distinct type with special limitations. A function script can contain only one block. The name of the script is the name of the function. Function scripts should never be attached to any object. All variables in a function script must be declared before the function body.

A simple function script might look like:

    ScriptName Multiply	; the name of this function
    float arg1	; holds an argument passed to the function
    float arg2	; second arg
    float localVar	; a local variable
    Begin Function {arg1, arg2}		; function body, with parameter list in {braces}
    	Let localVar := arg1 * arg2
    	SetFunctionValue localVar	; this is the value that will be returned
    	Return				; optional, causes the function to return immediately
    End

Parameters are stored in local variables and must be indicated within `{`braces`}` in the function definition; a set of empty braces indicates the function takes no arguments. Local variables and argument variables retain their values only until the function returns.

To call this function you would use:
`Call Multiply 10 5`

To store the result (50, in this case):
`Let someVar := Call Multiply 10 5`

When parsing a function call, the compiler will verify that the number and type of the arguments match those expected by the function's parameter list. If the called function is specified as a ref variable this validation cannot be performed; it is the scripter's responsibility to ensure the argument list is valid to avoid errors at run-time.

Functions have some useful properties. Because they are object scripts, you can call them on references using `someRef.Call someFunc`; any commands used inside the function will then operate implicitly on the calling reference. Because they are scripts, they can be stored in and called using ref variables, and even passed as arguments to other functions. Functions can call other functions, including themselves (i.e. recursively); for instance:

    ScriptName Pow ; calculates base to the exp power
    float base
    short exp
    short val
    begin Function {base, exp}
    	if exp == 0
    		let val := 1
    	else
    		let val := base * Call Pow base, exp - 1
    	endif
    	SetFunctionValue val
    end

OBSE allows a maximum of 30 nested function calls. This means the above function will only work with exponents less than 30.

A note about local variables within functions: when the function terminates, all local variables are reset to zero. Local array variables are automatically cleaned up so there is no need to use `ar_Null` to reset them. String variables used to hold function arguments are also automatically destroyed. Local string variables, however, are not automatically cleaned up because they may refer to strings in use by other scripts. It is the scripter's responsibility to use `sv_Destruct` to destroy any local variables when appropriate. The following example code illustrates this idea:

    scn SomeFunction
    string_var arg
    string_var local0
    string_var local1
    string_var local2
    Begin Function { arg }
    	let local0 := "some string"
    	set local1 to someQuest.someStringVar
    	let local2 := someQuest.someStringVar
    	sv_Destruct local0 local2
    End

In the above script, the string variable `arg` will be automatically cleaned up by OBSE when the function terminates. `local1` will not be, and should not be destroyed explicitly because doing so would invalidate the `someStringVar` variable in an external script. `local0`, however, must be explicitly destroyed as it is not referenced by any other script. `local2` must also be destroyed as `let`, unlike `set`, creates a copy of the string with a new string ID.

Function - a blocktype which precedes the body of a function. This blocktype is only valid within function scripts. A parameter list consisting of up to ten local variables used to hold arguments passed to the function must follow this keyword enclosed in curly braces; if the function takes no arguments the braces should be empty.

    Begin Function {arg1, arg2, ... arg10}
    	; function body
    End

SetFunctionValue - specifies the value to be returned from a function. Valid only within a `Function` block. If a function does not specify a return value, the return value is assumed to be numeric zero. If multiple calls to `SetFunctionValue` are processed within a single Function block, the most recent value specified will be returned.
`(nothing) SetFunctionValue returnValue:expr`

Call - calls a user-defined function. Should be followed by a list of arguments matching the types expected by the function. If a calling reference is specified, commands within the function body will operate on that reference. Call returns whatever value is returned by the function.
`(returnValue:multi) ref.Call function:ref arg1:multi arg2:multi ... arg10:multi`

GetCallingScript - returns the script that called the currently executing function script. Returns nothing if the function script was not invoked by a Call statement from another script (e.g., will return nothing if the function was invoked as an event handler by OBSE).
`(callingScript:ref) GetCallingScript`

## Event Handler Functions

An event handler is a user-defined function designed to respond to game events. Rather than calling the function directly, the scripter uses SetEventHandler to register it as a handler for a specific event. When the associated event occurs during gameplay, OBSE will invoke any handlers for that event, passing information about the event to the function through its arguments.

Events include block types such as "OnHit", "OnDeath", and so on, as well as other events involving loading, saving, and exiting the game. Each event expects its handlers to accept a specific set of arguments. The supported events, including any required arguments (listed in the order in which they should appear in the function definition) are listed below:

Events
Name | Parameters | Notes
--- | --- | ---
OnHit | target:ref attacker:ref
OnHitWith | target:ref weapon:form
OnMagicEffectHit | target:ref effectCode:int
OnMagicEffectHit2 | target:ref effect:ref | Only useful for effects which have valid formIDs at compile-time, e.g. effects from the Oblivion Magic Extender plugin
OnActorEquip | target:ref item:form
OnDeath | target:ref killer:form
OnMurder | target:ref killer:form
OnKnockout | target:ref
OnActorUnequip | target:ref item:form
OnAlarm Trespass | alarmedActor:ref criminal:ref
OnAlarm Steal | alarmedActor:ref criminal:ref
OnAlarm Attack | alarmedActor:ref criminal:ref
OnAlarm Pickpocket | alarmedActor:ref criminal:ref
OnAlarm Murder | alarmedActor:ref criminal:ref
OnPackageChange | target:ref package:form
OnPackageStart | target:ref package:form
OnPackageDone | target:ref package:form
OnStartCombat | target:ref opponent:ref
OnActivate | activatedRef:ref activatingRef:ref
OnVampireFeed | NONE | invoked after player finishes feeding as a vampire
OnSkillUp | skillActorValueCode:int | invoked after skill increases through use
OnScriptedSkillUp | skillActorValueCode:int amount:int | when ModPCSkill/AdvanceSkill are used to increase skill, invoked before the skill is modified
OnDrinkPotion | drinker:ref potion:form
OnEatIngredient | eater:ref ingredient:form | also triggers OnActorEquip event
OnActorDrop | dropper:ref droppedItem:ref | droppedItem is the new reference in the game world to the dropped item
OnSpellCast | caster:ref spell:form | only invoked when the caster is an actor
OnScrollCast | caster:ref scrollEnchantment:form | only invoked when the caster is an actor
OnFallImpact | faller:ref | invoked when a falling actor hits the ground with sufficient velocity to be potentially damaging, before damage is applied
OnMapMarkerAdd | mapMarker:ref
OnHealthDamage | damage:float attacker:ref | Invoked on the actor taking damage (i.e. GetSelf will return the damaged actor) whenever damage is taken. "Attacker" may be zero e.g. when taking damage from falling. The handler is invoked just before the damage is applied, so it can be nullified by commands like ModActorValue. Use the object filter to specify the damaged actor to which your event handler should be attached, if any. The ref filter can be used to specify the attacking actor, if any.
OnCreateSpell | spell:ref | when player creates a new spell
OnCreatePotion | potion:ref isUnique:int | when player creates a new potion. The second argument is 1 if the resulting potion is a new base object, 0 if a previously-created potion has the same effects as the newly-created one (in which case the existing base object is used).
OnEnchant | enchantedItem:ref | when player enchants an item.
OnAttack | actor:ref | Slightly misnamed. Invoked whenever actor begins the animation sequence for a melee or staff attack or a spell cast. Use commands like IsCasting to determine the current action.
OnBowAttack | actor:ref | actor begins the animation of drawing his bowstring
OnRelease | actor:ref | animation begun by OnAttack or OnBowAttack completes - e.g., actor releases an arrow shot, swings his weapon, or releases a spell projectile.
OnBlock | actor:ref | actor begins block animation
OnRecoil | actor:ref | actor begins recoil animation
OnStagger | actor:ref | actor begins stagger animation
OnDodge | actor:ref | actor begins dodge animation
OnSoulTrap | capturedActor:ref soulgem:ref | Second parameter is an InventoryReference for the soulgem used to capture the soul, valid only for the duration of the event handler
OnQuestComplete | quest:ref | when a quest is marked as completed
OnMagicCast | magicItem:ref target:ref | Invoked on the casting reference whenever it attempts to cast a spell/scroll. The target ref is valid only for self-range spells (the exception is when the spell is cast using the Cast command). Works on both actors and non-actor magic casters (activators, furniture, doors, etc.).
OnMagicApply | magicItem:ref caster:ref | Invoked on the target reference whenever a magic item's (spells, enchantments, potions, ingredients) effects are applied to it.
LoadGame | filename:string
SaveGame | filename:string
PostLoadGame | gameLoadedSuccessfully:bool | 0 if error occurred during load (corrupt savegame?), 1 otherwise
ExitGame | NONE | exiting from main menu or in-game menu
ExitToMainMenu | NONE | exiting from in-game menu to main menu
QQQ | NONE | exiting via QQQ/QuitGame console command
OnNewGame | NONE | user starts a new game from the main menu
OnSaveIni | postSave:bool | Invoked before (postSave=false) and after (postSave=true) the game's ini settings are saved to the ini file. Not invoked when saving ini settings when quitting the game - use an ExitGame handler if settings must be reset before the ini is saved at game exit

For events associated with block types, you may provide a specific value for any, all, or none of the arguments when registering an event handler. The first argument is referred to by the name "first" or "ref" and the second as "second" or "object", regardless of the names of the argument variables in your function script (exception: for OnHealthDamage, "second" or "object" refers to the damaged actor). Doing so allows you to filter out events you're not interested in. For instance, to handle events involving the player being hit by another actor, use `SetEventHandler OnHit yourScript first::playerRef`. To handle events in which the player, and only the player, hits anyone else, use `SetEventHandler OnHit yourScript second::playerRef`. To handle the player being affected by a Restore Health magic effect, use `SetEventHandler OnMagicEffectHit yourScript first::playerRef second::"REHE"`.

It is recommended that you prefer to filter events as strictly as possible to allow OBSE to avoid calling your handler for events you're not interested in. Further, once an event handler becomes unneeded (for instance, if the target of the handler dies), use RemoveEventHandler to remove it; this prevents OBSE from having to check against the defunct handler when processing events. Be aware that event handler scripts are invoked at the moment the event is registered by the game. For example, an OnEquip handler is invoked when an actor decides to equip an item, but before the item is actually equipped, which means that trying to unequip the item from within the handler will fail. IMPORTANT: avoid using AddSpell to add an ability or disease to an actor from within an OnMagicEffectHit handler, as doing so may cause the game to become unstable.

SetEventHandler - registers a user-defined function as a handler for the specified event. If the function script returns a value, it will be ignored. Two optional arguments can be supplied as key::value pairs to filter events according to the target and/or object.
`(success:bool) SetEventHandler eventID:string functionScript:ref filter1:pair filter2:pair`

Example usage: `

    	scn FnOnHitByPlayer
    	ref target
    	ref attacker

    	begin Function { target, attacker }
    		; we know the attacker must be the player, but the argument is still required
    		print $target + " was hit by the player"
    	end
    	-------------
    	scn FnOnPlayerRestoreHealth
    	ref target
    	long effectCode

    	begin Function { target, effectCode }
    		print "The player has been hit by a restore health effect"
    	end
    	--------------
    	scn FnOnLoadGame
    	string_var filename

    	begin Function { filename }
    		print "Loading game from " + $filename
    	end
    	---------------
    	scn SomeQuestScript
    	begin gamemode
    		if getGameRestarted
    			SetEventHandler "OnHit" FnOnHitByPlayer second::PlayerRef
    			SetEventHandler "OnMagicEffectHit" FnOnPlayerRestoreHealth first::PlayerRef second::"REHE"
    			SetEventHandler "LoadGame" FnOnLoadGame
    		endif
    	end

`

RemoveEventHandler - removes the specified script as an event handler for the specified event. Two optional arguments can be supplied as key::value pairs to filter events according to the target and/or object. If both filters are omitted, all event handlers matching the script and event will be removed. If only one filter is omitted, all handlers matching the script, event, and the other filter will be removed. Returns true if at least one matching event handler was found and removed, false otherwise.
`(removed:bool) RemoveEventHandler eventID:string functionScript:ref filter1:pair filter2:pair`

GetCurrentEventName - When called from within an event handler, returns the name of the event currently being handled, as defined above.
`(eventName:string) GetCurrentEventName`

### User-Defined Events

In addition to the events supplied by OBSE, mods can also register event handlers for events dispatched by other mods. These types of events are referred to as "user-defined events". The event handler for a user-defined event always takes one argument: a Stringmap. The stringmap argument always includes the following two key-value pairs:

    	"eventName": a string indicating the event which occurred
    	"eventSender": a string indicating the origin of the event. By default this is the filename of the mod which dispatched the event, unless that mod supplied an alternate sender name.

The stringmap argument will also contain any additional data supplied by the sender of the event.

To register an event handler for a user-defined event, use SetEventHandler. To dispatch an event to any registered listeners, use DispatchEvent
Example:

    scriptname EventHandler
    array_var args
    begin Function {args}
    	print "Event " + args->eventName + " received from " + args->eventSender
    	print $arg->activator + " was activated by " + $arg->activatedBy
    end

    scriptname EventSender
    begin onActivate
    	DispatchEvent "Activated" (ar_Map "activator"::GetSelf "activatedBy"::GetActionRef)
    end

DispatchEvent - dispatches a user-defined event to any registered listeners. The eventName parameter specifies the event that occurred; this should be fairly unique to prevent event name clashes between different mods, but the event handler can also disambiguate name clashes by checking the name of the event sender if necessary. The optional second parameter is a StringMap containing any additional information about the event. When the event is dispatched, the array will also include the event name and the name of the sender. If omitted, the name of the sender is the filename from which the event originated; otherwise it matches the supplied third argument.
`(dispatched:bool) DispatchEvent eventName:string args:StringMap senderName:string`

## Inventory References

In Oblivion, objects stored inside of the inventories of actors or containers are not references. However, it can be useful to treat them as references in order to modify them. OBSE provides this functionality through the use of "inventory references", which are specialized, temporary references representing a stack of one or more items inside of a container. Scripts can obtain an inventory reference in three ways: by iterating over the contents of a container, by requesting references to items in a container matching a particular base item using GetInvRefsForItem, or by creating one directly using CreateTempRef.

Iteration is performed using a ForEach loop. On each pass through the loop, the iterator variable is set to a temporary reference to a stack of identical items within the source container. Items are considered identical if they share the same health, soul level, ownership, and/or other values; if any one of these differ then the items are not considered identical and will be returned in different stacks. The order in which stacks are returned is arbitrary, but stacks of the same base object type are guaranteed to be returned consecutively. Note that the number and contents of the stacks returned may not correspond directly to those displayed in the inventory/container menu.

Within the loop, the temporary reference stored in the iterator variable can be treated almost exactly like a normal reference, allowing you to call functions like SetCurrentHealth, SetCurrentSoulLevel, etc on it. However, as soon as execution returns to the top of the loop the previous value of the iterator becomes invalid - the reference it held no longer exists, and has been replaced by a reference to the next stack of items in the container. When the loop ends, the final reference becomes invalid and the iterator variable is set to `null`. Therefore, you should never store a temporary reference and try to use it later on.

The temporary nature of inventory references require some extra care in their use. The contents of the source container should not be modified within the loop. In general:

- If you move or remove the reference from within a loop using RemoveMeIR, the reference becomes immediately invalid.
- Never use Remove/Add/Equip/UnequipItem/RemoveAllItems on the source container from within the loop. Using EquipMe and UnequipMe to equip or unequip the current reference is fine.
- Don't use SetRefCount to modify the quantity of an inventory reference

The following code illustrates inventory reference usage:

    		scriptName ExampleInvRefSCR	; attached to a container/actor reference
    		ref iter
    		ref container
    		short count
    		begin onActivate
    			let container := getSelf
    			foreach iter <- container
    				let count := iter.GetRefCount
    				print "Found " + $count + " " + iter.GetName + "(s)"
    				if iter.GetOwner && iter.GetOwner != playerRef
    					if iter.IsEquipped == 0		; can't remove equipped items
    						; move stolen items to another container
    						iter.RemoveMeIR someOtherContainerRef
    					endif
    				else
    					; remove completely
    					iter.RemoveMeIR
    				endif
    				; iter is now invalid because RemoveMeIR was used - so we won't attempt to continue using it
    			loop	; now that loop has terminated, iter has been set to null (0)

    			; create a temp ref to a weapon with a specific health value and quantity
    			let iter := CreateTempRef weapSteelDagger
    			iter.SetRefCount 5		; okay to use SetRefCount on a temp ref that is NOT in a container
    			iter.SetCurrentHealth 10 	; damage the 5 daggers
    			iter.CopyIR container		; container now contains 5 damaged daggers
    			let iter := 0				; temp ref will be invalid next frame, set to null to be sure we don't try to re-use it
    		end

RemoveMeIR - removes an inventory reference from its container, optionally transferring it to a different container, in much the same way as the vanilla RemoveMe command. The inventory reference becomes invalid once this command is called and should no longer be used. This command will not remove equipped items until the end of the loop.
`(success:bool) reference.RemoveMeIR containerRef:ref`

CopyIR - copies an inventory reference to the specified container. The calling object needn't be in a container and remains valid after the command is called. If the calling object is equipped, the copy will not be equipped.
`(success:bool) reference.CopyIR container:ref`

CreateTempRef - creates a temporary reference to the specified form. This reference does not exist in the gameworld or in a container, and remains valid for only one frame. It is mostly useful for creating a stack of one or more items to be added to a container with CopyIR
`(tempRef:ref) CreateTempRef baseObject:ref`

GetInvRefsForItem - given a base inventory item, returns an Array of temporary references to stacks of that item inside the calling container.
`(refs:Array) ref.GetInvRefsForItem baseObject:ref`

IsEquipped - returns true if the calling object is currently being worn
`(bool) reference.IsEquipped`

## Temporary Functions

These functions duplicate existing commands, but they attempt to prevent the changes made by those commands from being stored in the savegame. The arguments and behavior are otherwise identical to the original functions. By default, a command like SetOwnership or SetPos sets a flag telling the game that an attribute of the object (ownership, position, etc) has been changed. When the game is saved, the current value of the flagged attribute will be recorded in the savegame. The game remembers only the fact that the attribute was changed - not the value to which it was changed. The upshot is that if, for example, any script uses SetPos to change the position of an object, the object's position as saved in the savegame will be its position at the time the save is made - not necessarily the position set by any particular script command.

SetOwnership_T

ClearOwnership_T

SetPos_T - note that some persistent references, such as load doors in exterior worldspaces, are flagged as having been moved at the beginning of the game. SetPos_T will not prevent changes to the positions of such objects from being saved.

SetGoldValue_T

## Physics Functions

These functions allow scripts to modify the physical properties of the world and objects in it. Velocity is measured in game units per second, and acceleration in game units per second squared. Currently, commands that modify velocity are only effective on living actors. Because actors move under their own control, they are not strictly subject to forces other than gravity, so making noticeable changes to their movement using these commands requires using a velocity of large magnitude or repeated calls to SetVelocity over the course of several frames.

GetLocalGravity - returns the acceleration due to gravity in the specified axis for the current cell. Unless SetLocalGravityVector has been used, the x and y components will always be zero.
`(gravity:float) GetLocalGravity axis:axis`

SetLocalGravity - sets the vertical acceleration due to gravity for the current cell. Negative values are the norm, causing objects to accelerate downward, but positive values are also acceptable. Changing the gravity for an exterior cell changes it for all exterior cells until it is reset by another call to this function. Changes to gravity in an interior cell affect only that cell, and the change will be reset once the cell is reloaded.
`(nothing) SetLocalGravity gravity:float`

SetLocalGravityVector - sets the x, y, and z components of local acceleration due to gravity. This can be used to cause gravity to act in a non-vertical direction, which might be useful for simulating water currents.
`(nothing) SetLocalGravityVector xAccel:float yAccel:float zAccel:float`

GetVelocity - returns the actor's current velocity in the specified axis.
`(velocity:float) reference.GetVelocity axis:axis`

GetVerticalVelocity - returns the z component of the actor's current velocity.
`(velocity:float) reference.GetVerticalVelocity`

SetVelocity - sets the x, y, and z components of the actor's velocity. The change applies only to the current frame.
`(nothing) reference.SetVelocity xVelocity:float yVelocity:float zVelocity:float`

SetVerticalVelocity - Sets the vertical velocity for an actor. This is primarily useful for actors who are jumping or falling. Positive values will cause the actor to move upwards, negative values will cause him to move downwards, and zero will prevent him from moving vertically for the current frame. On the subsequent frame, acceleration due to gravity will be applied to the new velocity. This means that if you set a falling actor's velocity to zero, on the next frame he will appear to accelerate as if he had just begun falling.
`(nothing) reference.SetVerticalVelocity velocity:float`

## Type Codes

### Form Type IDs

- 0: None
- 1: TES4
- 2: Group
- 3: GMST
- 4: Global
- 5: Class
- 6: Faction
- 7: Hair
- 8: Eyes
- 9: Race
- 10: Sound
- 11: Skill
- 12: Effect
- 13: Script
- 14: LandTexture
- 15: Enchantment
- 16: Spell
- 17: BirthSign
- 18: Activator
- 19: Apparatus
- 20: Armor
- 21: Book
- 22: Clothing
- 23: Container
- 24: Door
- 25: Ingredient
- 26: Light
- 27: Misc
- 28: Stat
- 29: Grass
- 30: Tree
- 31: Flora
- 32: Furniture
- 33: Weapon
- 34: Ammo
- 35: NPC
- 36: Creature
- 37: LeveledCreature
- 38: SoulGem
- 39: Key
- 40: AlchemyItem
- 41: SubSpace
- 42: SigilStone
- 43: LeveledItem
- 44: SNDG
- 45: Weather
- 46: Climate
- 47: Region
- 48: Cell
- 49: REFR
- 50: ACHR
- 51: ACRE
- 52: PathGrid
- 53: WorldSpace
- 54: Land
- 55: TLOD
- 56: Road
- 57: Dialog
- 58: DialogInfo
- 59: Quest
- 60: Idle
- 61: Package
- 62: CombatStyle
- 63: LoadScreen
- 64: LeveledSpell
- 65: ANIO
- 66: WaterForm
- 67: EffectShader
- 68: TOFT
- 69: Actors
- 70: Inventory items
- 72: MapMarker references

### Equipment Slot IDs*

- 0: head
- 1: hair
- 2: upper body
- 3: lower body
- 4: hand
- 5: foot
- 6: right ring
- 7: left ring
- 8: amulet
- 9: weapon
- 10: back weapon
- 11: side weapon
- 12: quiver
- 13: shield
- 14: torch
- 15: tail
- 16: weapon
- 17: ammo
- 18: lower and upper body
- 19: lower and upper and foot
- 20: lower, upper, hand and foot
- 21: lower, upper, and hand
- 22: upper and hand

*Return values only

#### Equipment slot bit assignments:

- 0x00000001 1 Head
- 0x00000002 2 Hair
- 0x00000004 4 UpperBody
- 0x00000008 8 LowerBody
- 0x00000010 16 Hand
- 0x00000020 32 Foot
- 0x00000040 64 RightRing
- 0x00000080 128 LeftRing
- 0x00000100 256 Amulet
- 0x00000200 512 Weapon
- 0x00000400 1024 BackWeapon
- 0x00000800 2048 SideWeapon
- 0x00001000 4096 Quiver
- 0x00002000 8192 Shield
- 0x00004000 16384 Torch
- 0x00008000 32768 Tail
- 0x00010000 65536 Weapon
- 0x00020000 131072 Ammo
- 0x00040000 262144 Ranged Weapon

### Weapon Type

- 0: Blade1H
- 1: Blade2H
- 2: Blunt1H
- 3: Blunt2H
- 4: Staff
- 5: Bow

### Apparatus Type

- 0: Mortar & Pestle
- 1: Alembic
- 2: Calcinator
- 3: Retort

### Apparatus Quality Levels

- .10: Novice
- .25: Apprentice
- .50: Journeyman
- .75: Expert
- 1.0: Master

### Armor Type

- 0: Light Armor
- 1: Heavy Armor

### Soul Level

- 0: None
- 1: Petty
- 2: Lesser
- 3: Common
- 4: Greater
- 5: Grand

### Magic Item Type

- 0: Not a Magic Item
- 1: Spell
- 2: Enchantment
- 3: Alchemy Item
- 4: Ingredient

### Magic Effect Range

- 0: Self
- 1: Touch
- 2: Target

### Spell Type

- 0: Spell
- 1: Disease
- 2: Power
- 3: Lesser Power
- 4: Ability

### Spell Mastery Level

- 0: Novice
- 1: Apprentice
- 2: Journeymand
- 3: Expert
- 4: Master

### Enchantment Type

- 0: Scroll
- 1: Staff
- 2: Weapon
- 3: Apparel

### Magic Schools

- 0: Alteration
- 1: Conjuration
- 2: Destruction
- 3: Illusion
- 4: Mysticism
- 5: Restoration

### Actor Value Codes

- 0: Strength
- 1: Intelligence
- 2: Willpower
- 3: Agility
- 4: Speed
- 5: Endurance
- 6: Personality
- 7: Luck
- 8: Health
- 9: Magicka
- 10: Fatigue
- 11: Encumbrance
- 12: Armorer
- 13: Athletics
- 14: Blade
- 15: Block
- 16: Blunt
- 17: HandToHand
- 18: HeavyArmor
- 19: Alchemy
- 20: Alteration
- 21: Conjuration
- 22: Destruction
- 23: Illusion
- 24: Mysticism
- 25: Restoration
- 26: Acrobatics
- 27: LightArmor
- 28: Marksman
- 29: Mercantile
- 30: Security
- 31: Sneak
- 32: Speechcraft
- 33: Aggression
- 34: Confidence
- 35: Energy
- 36: Responsibility
- 37: Bounty
- 38: Fame
- 39: Infamy
- 40: MagickaMultiplier
- 41: NightEyeBonus
- 42: AttackBonus
- 43: DefendBonus
- 44: CastingPenalty
- 45: Blindness
- 46: Chameleon
- 47: Invisibility
- 48: Paralysis
- 49: Silence
- 50: Confusion
- 51: DetectItemRange
- 52: SpellAbsorbChance
- 53: SpellReflectChance
- 54: SwimSpeedMultiplier
- 55: WaterBreathing
- 56: WaterWalking
- 57: StuntedMagicka
- 58: DetectLifeRange
- 59: ReflectDamage
- 60: Telekinesis
- 61: ResistFire
- 62: ResistFrost
- 63: ResistDisease
- 64: ResistMagic
- 65: ResistNormalWeapons
- 68: ResistParalysis
- 67: ResistPoison
- 68: ResistShock
- 69: Vampirism
- 70: Darkness
- 71: ResistWaterDamage
- 256: No Actor Value

### Class Specialization Codes

- 0: Combat
- 1: Magic
- 2: Stealth

### Input Control IDs

- 0: Forward
- 1: Back
- 2: Slide Left
- 3: Slide Right
- 4: Use
- 5: Activate
- 6: Block
- 7: Cast
- 8: Ready Item
- 9: Crouch/Sneak
- 10: Run
- 11: Always Run
- 12: Auto Move
- 13: Jump
- 14: Toggle POV
- 15: Menu Mode
- 16: Rest
- 17: Quick Menu
- 18: Quick1
- 19: Quick2
- 20: Quick3
- 21: Quick4
- 22: Quick5
- 23: Quick6
- 24: Quick7
- 25: Quick8
- 26: QuickSave
- 27: QuickLoad
- 28: Grab

### Creature Type

- 0: Creature
- 1: Daedra
- 2: Undead
- 3: Humanoid
- 4: Horse
- 5: Giant

### HDR Value

- 0: Eye Adapt
- 1: Blur Radius
- 2: Blur Passes
- 3: Emissive Mult
- 4: Target LUM
- 5: Upper LUM Clamp
- 6: Bright Scale
- 7: Bright Clamp
- 8: LUM Ramp No Tex
- 9: LUM Ramp Min
- 10: LUM Ramp Max
- 11: Sunlight Dimmer
- 12: Grass Dimmer
- 13: Tree Dimmer

### Weather Color

- 0: Sky Upper
- 1: Fog
- 2: Clouds Lower
- 3: Ambient
- 4: Sunlight
- 5: Sun
- 6: Stars
- 7: Sky Lower
- 8: Horizon
- 9: Clouds Upper
- 10: Lightning

### Weather Time

- 0: Sunrise
- 1: Day
- 2: Sunset
- 3: Night

### RGB Value

- 0: Red
- 1: Green
- 2: Blue

### Music Type

- 0: Default
- 1: Public
- 2: Dungeon

### Projectile Type

- 0: Arrow
- 1: Magic Ball
- 2: Magic Fog
- 3: Magic Bolt

### Actor Sound

- 0: LeftFoot
- 1: RightFoot
- 2: LeftBack
- 3: RightBack
- 4: Idle
- 5: Aware
- 6: Attack
- 7: Hit
- 8: Death
- 9: Weapon

### Detection State

- 0: Lost
- 1: Unseen
- 2: Noticed
- 3: Seen

### Animation Group

Note: Functions expecting an Animation Group parameter will accept the string associated with that group.

- 0: Idle
- 1: DynamicIdle
- 2: SpecialIdle
- 3: Forward
- 4: Backward
- 5: Left
- 6: Right
- 7: FastForward
- 8: FastBackward
- 9: FastLeft
- 10: FastRight
- 11: DodgeForward
- 12: DodgeBack
- 13: DodgeLeft
- 14: DodgeRight
- 15: TurnLeft
- 16: TurnRight
- 17: Equip
- 18: Unequip
- 19: AttackBow
- 20: AttackLeft
- 21: AttackRight
- 22: AttackPower
- 23: AttackForwardPower
- 24: AttackBackPower
- 25: AttackLeftPower
- 26: AttackRightPower
- 27: BlockIdle
- 28: BlockHit
- 29: BlockAttack
- 30: Recoil
- 31: Stagger
- 32: Death
- 33: TorchIdle
- 34: CastSelf
- 35: CastTouch
- 36: CastTarget
- 37: CastSelfAlt
- 38: CastTouchAlt
- 39: CastTargetAlt
- 40: JumpStart
- 41: JumpLoop
- 42: JumpLand

### Service Flags

Note: Add two or more flags together to specify a group of services offered by an NPC.

- 1: Weapons
- 2: Armor
- 4: Clothing
- 8: Books
- 16: Ingredients
- 128: Lights
- 256: Apparatus
- 1024: Misc
- 2048: Spells
- 4096: MagicItems
- 8192: Potions
- 16384: Training
- 65536: Recharge
- 131072: Repair

### Biped Path Codes

Specifies icon/model paths associated with biped objects, i.e. clothing and armor

- 0: Male Biped Path
- 1: Female Biped Path
- 2: Male Ground Path
- 3: Female Ground Path

### Process Level

For actors, the level at which the game processes their AI.

- 0: High
- 1: Middle-high
- 2: Middle-low
- 3: Low

### Menu Code

- 1001: Message
- 1002: Inventory
- 1003: Stats
- 1004: HUDMain
- 1005: HUDInfo
- 1006: HUDReticle
- 1007: Loading
- 1008: Container, Barter
- 1009: Dialog
- 1010: HUDSubtitle
- 1011: Generic
- 1012: SleepWait
- 1013: Pause
- 1014: LockPick
- 1015: Options
- 1016: Quantity
- 1017: Audio
- 1018: Video
- 1019: VideoDisplay
- 1020: Gameplay
- 1021: Controls
- 1022: Magic
- 1023: Map
- 1024: MagicPopup
- 1025: Negotiate
- 1026: Book
- 1027: LevelUp
- 1028: Training
- 1029: BirthSign
- 1030: Class
- 1031: Attributes
- 1032: Skills
- 1033: Specilization
- 1034: Persuasion
- 1035: Repair
- 1036: RaceSex
- 1037: SpellPurchase
- 1038: Load
- 1039: Save
- 1040: Alchemy
- 1041: SpellMaking
- 1042: Enchantment
- 1043: EffectSetting
- 1044: Main
- 1045: Breath
- 1046: QuickKeys
- 1047: Credits
- 1048: SigilStone
- 1049: Recharge
- 1051: TextEdit

### Menu Filter Code

#### Magic Menu:

- 1: Target
- 2: Touch
- 3: Self
- 7: All
- 8: Active Effects

#### Container/Barter/Inventory Menu:

- 1: Weapons
- 2: Armor/Clothing
- 3: Alchemy
- 4: Miscellaneous
- 31: All

### Alchemy Apparatus

- 0: Mortar and Pestle
- 1: Retort
- 2: Alembic
- 3: Calcinator

### Map Marker Types

- 1: Camp
- 2: Cave
- 3: City
- 4: Elven Ruin
- 5: Fort Ruin
- 6: Mine
- 7: Landmark
- 8: Tavern
- 9: Settlement
- 10: Daedric Shrine
- 11: Oblivion Gate

### Weather Classifications

- 0: None
- 1: Pleasant
- 2: Cloudy
- 3: Rainy
- 4: Snow

### Package Object Codes

- 1: Activator
- 2: Apparatus
- 3: Armor
- 4: Book
- 5: Clothing
- 6: Container
- 7: Door
- 8: Ingredient
- 9: Light
- 10: Misc
- 11: Flora
- 12: Furniture
- 13: Weapon (Any)
- 14: Ammo
- 15: NPC
- 16: Creature
- 17: Soulgem
- 18: Key
- 19: Alchemy
- 20: Food
- 21: Combat Wearable
- 22: Wearable
- 23: Weapon None
- 24: Weapon Melee
- 25: Weapon Ranged
- 26: Spells (Any)

### Package Procedure Names

- TRAVEL
- WANDER
- ACTIVATE
- ACQUIRE
- SLEEP
- EAT
- FOLLOW
- ESCORT
- ALARM
- COMBAT
- FLEE
- YIELD
- DIALOGUE
- WAIT
- TRAVEL_TARGET
- PURSUE
- GREET
- CREATE_FOLLOW
- OBSERVE_COMBAT
- OBSERVE_DIALOGUE
- GREET_DEAD
- WARN
- GET_UP
- MOUNT_HORSE
- DISMOUNT_HORSE
- DO_NOTHING
- CAST_SPELL
- AIM
- NOTIFY
- ACCOMPANY
- USE_ITEM_AT
- FEED
- AMBUSH_WAIT
- SURFACE
- WAIT_FOR_SPELL
- CHOOSE_CAST
- FLEE_NON_COMBAT
- REMOVE_WORN_ITEMS
- SEARCH
- CLEAR_MOUNT_POSITION
- SUMMON_CREATURE_DEFEND
- MOVEMENT_BLOCKED
- UNEQUIP_ARMOR
- DONE

### Surface Type Codes

- 0: Stone
- 1: Cloth
- 2: Dirt
- 3: Glass
- 4: Grass
- 5: Metal
- 6: Organic
- 7: Skin
- 8: Water
- 9: Wood
- 10: HeavyStone
- 11: HeavyMetal
- 12: HeavyWood
- 13: Chain
- 14: Snow
- 15: StoneStairs
- 16: ClothStairs
- 17: DirtStairs
- 18: GlassStairs
- 19: GrassStairs
- 20: MetalStairs
- 21: OrganicStairs
- 22: SkinStairs
- 23: WaterStairs
- 24: WoodStairs
- 25: HeavyStoneStairs
- 26: HeavyMetalStairs
- 27: HeavyWoodStairs
- 28: ChainStairs
- 29: SnowStairs
- 30: Elevator
- 31: Default/Unknown

## Deprecated Functions

These functions should no longer be used.

- GetEquippedCurrentValue - replaced by GetEquippedCurrentHealth,GetEquippedCurrentCharge and GetEquippedWeaponPoison
- GetEquippedObjectValue - replaced by GetEquippedObject and the appropriate individual value functions
- GetInventoryItemType - renamed GetBaseObject
- GetMagicEffectCodeValue - replaced by the individual GetMagicEffectXXXXC functions.
- GetMagicEffectValue - replaced by the individual GetMagicEffect functions
- GetMagicItemValue - replaced by the individual MagicItem functions
- GetObjectValue - replaced by the individual value functions
- SetActiveSpell - duplicate of standard `SelectPlayerSpell` function
- RefreshControlMap - input functions are now in sync with Oblivion control bindings
- GetAltControl - use GetAltControl2 instead
- sv_Substring - use slice notation i.e. `let substr := str[a:b]`
- sv_Set - use assignment operator
- sv_GetChar - use bracket notation i.e. `let char := str[pos]`
- SetIconPathEX - use SetTexturePath
- GetIconPath - use GetTexturePath
- SetModelPathEX - pass a string_var to `SetModelPath`
- MessageBoxEx - pass a string_var to `MessageBox`