FOSE v0001 Beta Command Documentation

Table of Contents

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
  long     a positve whole number with large values   
  short    a positive whole number with smaller values
  ref      a ref (usually an objectID)
  chars    a 4 character magic effect code (for example: FIDG, Z001)
  string   a set of characters in quotes
  bool     a short with only 2 values: 1 for true and 0 for false
  

Function Calling Conventions:

By Reference or ObjectID
reference.FunctionName someParameters objectID:ref
Examples:
    (health:long) reference.GetObjectHealth objectID:ref

These functions can either be called on a reference or have an objectID passed in as an argument.  If an objectID is passed in, it takes precedence over a calling reference.

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

    (masterLevel:short) GetSpellMasteryLevel spell:ref
    (effectCode:long) GetNthEffectItemCode magicItem:ref whichEffect:long

As Conditionals
Function names in bold may be used as conditionals for dialog topics, quest stages, package conditions, etc.

Qualities
Qualities are a set of related values and functions which apply to multiple Fallout object types.  For documentation purposes I have gathered the related values together.  Any type which has a given quality has all of values listed and all of the quality's functions may be applied to the type. 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
Functions:   
    GetAttackDamage - returns the base attack damage
        (damage:long) reference.GetAttackDamage objectID:ref
    SetAttackDamage - sets the base attack damage
        (nothing) reference.SetAttackDamage nuDamage:long objectID: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:long) reference.GetObjectHealth objectID:ref
    GetEquippedCurrentHealth - gets the current health of the object in the specified equipment slot
        (health:float) reference.GetEquippedCurrentHealth slot:short
    SetEquippedCurrentHealth - sets the current health of the object in the specified equipment slot
        (nothing) reference.SetEquippedCurrentHealth nuHealth:float slot:short

Enchantable
Types with this quality may be enchanted (have object effects applied to them).  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.  
Values:
    Enchantment - ref the specific enchantment on the enchantable item
Functions:
    GetObjectEffect - returns the specific object effect on the object
        (objectEffect:ref) reference.GetObjectEffect objectID:ref

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:
    Weapon Type- short the type of weapon
    Weight - float the weight of one object of this type
    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.
Functions:
    GetType - returns a type code for each type of object
        (type:long) reference.GetType 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
    GetValue - returns the base gold value of the type
        (value:long) reference.GetValue objectID:ref
    GetEquipType - returns the equip type of the object
        (equipType:long) reference.GetEquipType objectID:ref
    GetRepairList - returns a form list containing the items which can repair the specified object
        (repairList:ref)
reference.GetRepairList objectID:ref

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
    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:short) reference.CompareNames compareTo:ref compare: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 Fallout doesn't have a script variable type so you must assign the script to a ref variable for this to work.  This function is currently considered a Beta function which will get official support after it gets some more testing.  For now, please do not use in a shipping mod until further testing is done.
        (script:refID) reference.SetScript scriptID:ref targetObjectID:ref


Fallout Types
Fallout Types are the various forms available to fill out in the GECK.  They correspond to real objects or concepts in Fallout.   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.
Form List
Form Lists are list of Form Types (Object Types) which are used by Fallout for managing lists.  The main uses are for things like lists of items that can be consumed to repair another item.  The Form Lists created in the GECK may only store base forms, and not references, and each base form can only show up in the list once.  The vanilla Fallout functions IsInList and IsWeaponInList may (or may not) depend upon this behavior.
Values:
    Form Count - long the number of forms in the form list
    Index (N) - long a number which represents a slot in the form list. There is one form for every index.  The index is 0 based, so the first item is at index 0 and the last item is at index (Form Count - 1).  The special index number -2 represents the last item in the list.  the special index number -1 represents an invalid form entry.

Functions:
     ListGetCount - returns the number of forms in the list.  This number willl never be negative.
        (count:long) ListGetCount formList:ref
     ListGetNthForm - returns the Form at the specified index N.  If N is -2, then the last form on the list is returned.
        (form:ref) ListGetNthForm formList:ref index:long
     ListGetFormIndex - returns the index of the form in the list, or -1 if the form is not found.
        (index:long) ListGetFormIndex formList:ref formToFind:ref
     ListAddForm - adds a form to the list at a specified index, or to the end of the list if no index is specified, and returns the index where the form was added.
        (index:long)  ListAddForm formList:ref formToAdd:ref index:long
     ListAddReference - adds a reference to the form list at the specified index, or at the end if no index is specified, and returns the index where the form was added.  This function needs some testing .  The reference can be added and retrieved from the form, but I am uncertain about Fallout's behavior when references are in the list.
        (index:long) reference.ListAddReference formList:ref index:long
    ListRemoveNthForm - removes the form at index N from the list and returns it
        (removedForm:ref) ListRemoveNthForm formList:ref index:long
    ListRemoveForm - removes the specified form from the list and returns the index it was at, or -1 if it was not in the list
        (index:long) ListRemoveForm form:ref

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:
    GetBaseObject - returns the base object form of the reference
    (baseObject:ref) reference.GetBaseObject

Weapon
Qualities: Attacking, Breakable, Enchantable, Equippable, Inventory, Named, Simple
Values:
    Weapon Type - short the type of weapon
    Ammo - ref the weapon's ammo type
    ClipRounds - long the number of rounds in a clip for the weapon
    Spread - float the spread of the weapon's shots, expressed as a spread and max spread
    Projectile - ref - the form id of the projectile the weapon fires
    SightFOV - float the field of view of the weapon when zoomed
    Range - float the range of the weapons, expressed as min and max values
    Ammo Use - float the number of rounds fired per shot
    Action Points - float the cost in VATS action points for firing the weapon
    Critical Damage - float the damage done on a critical hit
    Critical Chance - float the chance of scoring a critical hit
    Critical Effect - ref  the objectID of the effect caused by a critical hit
    Fire Rate - float the fire rate of the weapon
    Animation Attack Mult - float the animation attack multiplier (affects timing of shots)
    Rumble  Motor - float  the strength of the rumble motor when the weapon is fired, comes in left and right
    Rumble Duration - float the duration of the rumble when the weapon is fired
    Rumble Wavelength - float the wavelength of the rumble when the weapon is fired
    Animation Shots Per Second - float the number of shots per second in the animation
    Animation Reload Time - float the duration of the reload animation
    Animation Jam Time - float the duration of the jam animation
    Animation Multiplier - float
    Reach - float
   
Automatic - bool specifies whether the weapon is an automatic weapon or not
    Hand Grip - short the hand grip animation of the weapon
    Reload Anim - short the reload animation of the weapon
    Base VATS Chance - short the base to hit chance in VATS mode
    Attack Animation - short the attack animation of the weapon
    Number of Projectiles -
    Skill - short the skill associated with the weapon
    Resist Type - short the actor value of the resistance to the weapon
    Semi-Auto Fire Delay - float the min and max fire delay for semi-automatic use of the weapon
Functions:
    GetWeaponType - returns the weapon type
        (weaponType:short) reference.GetWeaponType objectID:ref
     GetWeaponAmmo - returns the ammo of the weapon
        (ammo:ref) reference.GetWeaponAmmo objectID.ref
     GetWeaponClipRounds - returns the clip size of the weapon
        (clipSize:long) reference.GetWeaponClipRounds objectID.ref
     GetWeaponSpread - returns the spread of the weapon
        (minSpread:float) reference.GetWeaponMinSpread objectID.ref
     GetWeaponMaxSpread - returns the max spread of the weapon
        (maxSpread:float) reference.GetWeaponMaxSpread objectID.ref
     GetWeaponProjectile - returns the objectID of the weapon's projectile
        (projectile:ref) reference.GetWeaponProjectile objectID.ref
     GetWeaponSightFOV - returns the sight field of vision of the weapon
        (sightFOV:float) reference.GetWeaponSightFOV objectID.ref
     GetWeaponMinRange - returns the minimum range of the weapon
        (minRange:float) reference.GetWeaponMinRange objectID.ref
     GetWeaponMaxRange - returns the max range of the weapon
        (maxRange:float) reference.GetWeaponMaxRange objectID.ref
     GetWeaponAmmoUse - returns the number of rounds per shot of the weapon
        (ammoPerShot:float) reference.GetWeaponAmmoUse objectID.ref
     GetWeaponActionPoints - returns the action point cost of firing the weapon
        (ap:float) reference.GetWeaponActionPoints objectID.ref
     GetWeaponCritDamage - returns the critical damage of the weapon
        (critDamage:float) reference.GetWeaponCritDamage objectID.ref
     GetWeaponCritChance - returns the chance to score a critical hit with the weapon
        (critChange:float) reference.GetWeaponCritChance objectID.ref
     GetWeaponCritEffect - returns the effect applied when a critical hit is scored with the weapon
        (criticalEffect:ref) reference.GetWeaponCritEffect objectID.ref
     GetWeaponFireRate
        (fireRate:float) reference.GetWeaponFireRate objectID.ref
     GetWeaponAnimAttackMult
        (animAttackMuli:float) reference.GetWeaponAnimAttackMulthy objectID.ref
     GetWeaponRumbleLeftMotor
        (leftRumbleStrength:float) reference.GetWeaponRumbleLeftMotor objectID.ref
     GetWeaponRumbleRightMotor
        (rightRumbleStrength:float) reference.GetWeaponRumbleRightMotor objectID.ref
     GetWeaponRumbleDuration
        (rumbleDuration:float) reference.GetWeaponRumbleDuration objectID.ref
     GetWeaponRumbleWavelength
        (rumbleWavelength:float) reference.GetWeaponRumbleWavelength objectID.ref
     GetWeaponAnimShotsPerSec
        (animShotsPerSec:float) reference.GetWeaponAnimShotsPerSec objectID.ref
     GetWeaponAnimReloadTime
        (animReloadTime:float) reference.GetWeaponAnimReloadTime objectID.ref
     GetWeaponAnimJamTime
        (animJamTime:float) reference.GetWeaponAnimJamTime objectID.ref
     GetWeaponSkill
        (skill:short) reference.GetWeaponSkill objectID.ref
     GetWeaponResistType
        (av:short) reference.GetWeaponResistType objectID.ref
     GetWeaponFireDelayMin
        (minDelay:float) reference.GetWeaponFireDelayMin objectID.ref
     GetWeaponFireDelayMax
        (maxDelay:float) reference.GetWeaponFireDelayMax objectID.ref
     GetWeaponAnimMult
        (animMult:float) reference.GetWeaponAnimMult objectID.ref
     GetWeaponReach
        (reach:float) reference.GetWeaponReach objectID.ref
     GetWeaponIsAutomatic
        (isAutomatic:bool) reference.GetWeaponIsAutomatic objectID.ref
     GetWeaponHandGrip
        (handGrip:short) reference.GetWeaponHandGrip objectID.ref
     GetWeaponReloadAnim
        (reloadAnim:short) reference.GetWeaponReloadAnim objectID.ref
     GetWeaponBaseVATSChance
        (VATSChance:short) reference.GetWeaponBaseVATSChance objectID.ref
     GetWeaponAttackAnimation
        (attackAnim:short) reference.GetWeaponAttackAnimation objectID.ref
     GetWeaponAimArc
        (aimArc:float) reference.GetWeaponAimArc objectID.ref
     GetWeaponLimbDamageMult
        (limbDamageMult:float) reference.GetWeaponLimbDamageMult objectID.ref
     GetWeaponSightUsage
        (sightUsage:float) reference.GetWeaponSightUsage objectID.ref
     GetWeaponHasScope
        (hasScope:bool) reference.GetWeaponHasScope objectID.ref
     GetWeaponNumProjectiles
        (numProjectiles:short) reference.GetWeaponNumProjectiles objectID.ref
     SetWeaponClipRounds
        (nothing) reference.SetWeaponClipRounds clipSize:long objectID.ref
     SetWeaponMinSpread
        (nothing) reference.SetWeaponClipRounds minSpread:float objectID.ref
     SetWeaponMaxSpread
        (nothing) reference.SetWeaponMaxSpreads maxSpread:float objectID.ref
     SetWeaponSightFOV
        (nothing) reference.SetWeaponSightFOV fov:float objectID.ref
     SetWeaponMinRange
        (nothing) reference.SetWeaponMinRange minRange:float objectID.ref
     SetWeaponMaxRange
        (nothing) reference.SetWeaponMaxRange maxRange:float objectID.ref
     SetWeaponAmmoPerShot    
        (nothing) reference.SetWeaponAmmoPerShot  ammoPerShot:float objectID.ref
     SetWeaponActionPoints
        (nothing) reference.SetWeaponActionPoints actionPoints:float objectID.ref
     SetWeaponCritDamage
        (nothing) reference.SetWeaponCritDamage critDamage:float objectID.ref
     SetWeaponCritChance
        (nothing) reference.SetWeaponCritChance critChance:float objectID.ref
     SetWeaponCritEffect
        (oldEffect:ref) reference.SetWeaponCritEffect critEffect:ref objectID.ref
     SetWeaponAnimMult
        (nothing) reference.SetWeaponAnimMult animMult:float objectID.ref
     SetWeaponReach
        (nothing) reference.SetWeaponReach reach:float objectID.ref
     SetWeaponIsAutomatic
        (nothing) reference.SetWeaponIsAutomatic isAutomatic:bool objectID.ref
     SetWeaponHandGrip
        (nothing)
reference.SetWeaponHandGrip handGrip:short objectID.ref
     SetWeaponReloadAnim
        (nothing)
reference.SetWeaponReloadAnim reloadAnim:short objectID.ref
     SetWeaponBaseVATSChance
        (nothing)
reference.SetWeaponBaseVATSChance vatsChance:short objectID.ref
     SetWeaponAttackAnimation
        (nothing)
reference.SetWeaponAttackAnimation attackAnim:short objectID.ref
     SetWeaponNumProjectiles
        (nothing)
reference.SetWeaponNumProjectiles numProjectiles:short objectID.ref
     SetWeaponAimArc
        (nothing) reference.SetWeaponAimArc aimArc:float objectID.ref
     SetWeaponLimbDamageMult
        (nothing)
reference.SetWeaponLimbDamageMult limbDamageMult:float objectID.ref
     SetWeaponSightUsage
        (nothing) reference.SetWeaponSightUsage sightUsage:float objectID.ref
     SetWeaponAmmo
        (nothing) reference.SetWeaponAmmo ammo:ref objectID.ref
     SetWeaponProjectile
        (nothing) reference.SetWeaponProjectile projectile:ref objectID.ref
   
General Functions
    GetFOSEVersion - returns the version number of FOSE
        (foseVersion:long) GetFOSEVersion
    GetFOSERevision - returns the minor version number of FOSE. For instance, when running the second released version of v0014, this function returns 2.
        (foseRevision:long) GetFOSERevision
    GetDebugSelection - returns the reference to the item last selected in the console
        (selection:ref) GetDebugSelection
    GetNumericIniSetting - returns the value of a numeric ini setting. The setting name is of the format "setting:section" where section is the heading under which the setting appears in the .ini file (i.e. "fGamma:Display").
        (settingValue:float) GetNumericIniSetting settingName:string
    SetNumericIniSetting - sets the value of a numeric ini setting. Setting name is of the same format used by GetNumericIniSetting.
        (nothing) SetNumericIniSetting settingName:string newValue:float
    GetNumericGameSetting - returns the value of a numeric game setting.
        (settingValue:float) GetNumericGameSetting settingName:string
    SetNumericGameSetting - sets the value of a numeric game setting.
        (nothing) SetNumericGameSetting settingName:string newValue:float
    AddSpellNS - Adds a spell to an actor, behaving identically to the vanilla AddSpell command but without generating a message on-screen.
        (nothing) reference.AddSpellNS spell:ref

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_CloseAllMenus
con_GetINISetting
con_LoadGame
con_QuitGame
con_RefreshINI
con_Save
con_SavINI
con_SetCameraFOV
con_SetGameSetting
con_SetINISetting
con_SetVel

User Interface Functions
GetCrosshairRef - returns the formID of the reference currently under the crosshair, if any.
        (crosshairRef:ref) GetCrosshairRef


Input Functions
IsKeyPressed - returns whether the specified key is currently pressed.  Uses DX scancodes.
        (isKeyPressed:bool) IsKeyPressed dxScanCode:long
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:long) GetKeyPress whichIndex:long
GetNumKeysPressed - returns the number of keys currently pressed
        (count:long) GetNumKeysPressed
DisableKey - disables the key with the specified dx scancode
        (nothing) DisableKey dxScanCode:long
EnableKey - enables the key with the specified dx scancode.  Turns off DisableKey.
        (nothing) EnableKey dxScanCode:long
IsKeyDisabled - returns 1 if the key has been disabled by DisableKey
        (isDisabled:short) IsKeyDisabled dxScanCode:short
HoldKey - holds down the key with the specified dx scancode
        (nothing) HoldKey dxScanCode:long
ReleaseKey - releases a held key with the specified dx scancode
        (nothing) ReleaseKey dxScanCode:long
TapKey - presses the key with the specidied dx scancode once
        (nothing) TapKey dxScanCode:long
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:long) GetMouseButtonPress whichIndex:long
GetNumMouseButtonsPressed - returns the number of mouse buttons pressed.
        (count:long) GetNumMouseButtonsPressed
MenuTapKey - taps a key during menu mode.
        (nothing) MenuTapKey dxScanCode:long
MenuHoldKey - holds down the specified key during menu mode.
        (nothing) MenuHoldKey dxScanCode:long
MenuReleaseKey - releases a held key during menu mode.
        (nothing) MenuReleaseKey dxScanCode:long
GetControl - returns the scan code of the key bound to the specified control, or -1 if not bound.
        (keycode:short) GetControl controlCode:short
GetAltControl - returns the scan code of the mouse button bound to the specified control, or -1 if not bound.
        (keycode:short) GetAltControl controlCode:short
SetControl - Binds the specified scan code to the control. If the key is already bound to another control, the two bindings are swapped. Changes are saved to the .ini when Fallout 3 exits.
        (nothing) SetControl controlCode:short dxScanCode:short
SetAltControl - As with SetControl, except it binds a mouse button instead of a key.
        (nothing) SetAltControl controlCode:short dxScanCode:short
DisableControl - disables the key and mouse button assigned to the specified control.
        (nothing) DisableControl controlCode:short
EnableControl - enables the key and mouse button assigned to the specified control.
        (nothing) EnableControl controlCode:short
IsControlDisabled - returns 1 if a control has been disabled with DisableControl.
        (isDisabled:bool) IsControlDisabled controlCode:short
IsControl - returns 1 if the scan code is bound to a game control, 2 if registered as a custom hotkey by SetIsControl, 3 if both, or 0 if not bound to any control.
        (isControl:short) IsControl dxScanCode:short
SetIsControl - allows scripters to register scan codes as custom hotkeys for their mods. Mainly useful for detecting conflicts between mods trying to use the same keys as controls.
        (nothing) SetIsControl dxScanCode:short isControl:bool
TapConmtrol - presses the key associated with the specified control
        (nothing) TapKey controlCode:short
IsControlPressed - returns 1 if the mouse button or key bound to the specified control is pressed.
        (isPressed:bool) IsControlPressed controlCode:short

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
    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:short

Mod Functions
    These functions return information about currently loaded Oblivion plugins.
    GetModIndex - returns the mod index of the specified plugin. This is equivalent to the first two digits of the object's formID.
        (index:short) GetModIndex modName:string
    GetSourceModIndex - returns the mod index of the plugin from which the specified object originates.
        (index:short) reference.GetSourceModIndex object:ref
    GetNumLoadedMods - returns the number of mods currently loaded. Used in conjunction with GetModIndex, this can be used to verify load order at run-time.
        (loadedPluginCount:short) 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


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 GECK.  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 clonedActorEffect
            ref originalActorEffect
            set clonedInventoryItem to CloneForm WeapLaserPistol
            set originalActorEffect to PerkActionBoy
            set clonedActorEffect to CloneForm originalActorEffect

    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

The flow control functions allow you to implement loops in your scripts. Because there is no built-in loop support in the Oblivion script interpreter, the syntax for the functions is somewhat strange. The first function, Label, will record the position of the instruction after itself in an internal list. The second function, Goto, jumps back to the saved position. Here's a simple example of a loop:

begin onActivate
    ; declare a variable to keep track of the number of times we've gone through the loop
    long var
    set var to 0
   
    ; save the current instruction pointer
    ; this records that the beginning of the loop is right before the PrintToConsole command
    Label 
   
    ; print the current loop count
    PrintToConsole "loop %f" var
   
    ; update the loop counter
    set var to var + 1
   
    ; we only want to go through the loop three times, so check the loop counter
    if var < 3
        ; jump back to the saved location
        Goto
    endif
   
    ; if we get here, we're done with the loop
end

When activated, this script will print:

loop 0.0000
loop 1.0000
loop 2.0000

To support nested loops, the Label and Goto commands take an optional integer parameter specifying which 'slot' to save the instruction location in. If you don't specify a number, it defaults to 0. There are 256 slots in the internal list. Here's an example of nested loops:

begin onActivate
    long var
    long var2
   
    set var2 to 0
   
    Label 0
        ; start of outer loop
        set var to 0
       
        Label 1
            ; start of inner loop
            PrintToConsole "loop %f %f" var var2
           
            set var to var + 1
        if var < 3
            ; branch to the start of the inner loop
            Goto 1
        endif
    set var2 to var2 + 1
    if var2 < 3
        ; branch to the start of the outer loop
        Goto 0
    endif
end

The inner loop uses slot 1, and the outer loop uses slot 0.

Important notes:

It is possible to create an infinite loop using these functions, which will hang Fallout. Also note that while the list of saved locations is technically stored globally, the locations only make sense in the context of the script that saved them, and must be treated as if they are invalidated at the end of each script. Finally, do not use Label or Goto in a 'set' or 'if' statement. (for example, "if Goto == 4"). They are of course safe to use inside the body of an if statement as demonstrated in the examples, just not in the if statement itself.

Label - save the location of the command following the Label command
        (nothing) Label slot:long
Goto - jump to a previously saved location
        (nothing) Goto slot:long


Format Specifiers
    Some FOSE 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 FOSE commands include all of those recognized by vanilla Fallout 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.

    %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:
         %po - objective  (he, she, it)
         %pp - possessive (his, her, its)
         %ps - subjective (him, her, it)
    %q - replaced with a double quote character (takes no arguments)
    %r - replaced by a new-line character (takes no arguments)
    %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.

    Additional format specifiers used by the C function printf() may work as well. Due to the fact that integer script variables are stored as floats, specifiers expecting integers may not display the expected output.

Type Codes

Form Type IDs

  0:    None
  1:    TES4
  2:    Group
  3:    GMST
  4:    TextureSet
  5:    MenuIcon
  6:    Global
  7:    Class
  8:    Faction
  9:    HeadPart
 10:    Hair
 11:    Eyes
 12:    Race
 13:    Sound
 14:    AcousticSpace
 15:    Skill
 16:    Effect
 17:    Script
 18:    LandTexture
 19:    Enchantment
 20:    Spell
 21:    Activator
 22:    TalkingActivator
 23:    Terminal
 24:    Armor
 25:    Book
 26:    Clothing
 27:    Container
 28:    Door
 29:    Ingredient
 30:    Light
 31:    Misc
 32:    Static
 33:    StaticCollection
 34:    MoveableStatic
 35:    PlaceableWater
 36:    Grass
 37:    Tree
 38:    Flora
 39:    Furniture
 40:    Weapon
 41:    Ammo
 42:    NPC
 43:    Creature
 44:    LeveledCreature
 45:    LeveledCharacter
 46:    Key
 47:    AlchemyItem
 48:    IdleMarker
 49:    Note
 50:    ConstructibleObject
 51:    Projectile
 52:    LeveledItem
 53:    Weather
 54:    Climate
 55:    Region
 56:    NAVI
 57:    Cell
 58:    Reference
 59:    ACHR
 60:    ACRE
 61:    PMIS
 62:    PGRE
 63:    PBEA
 64:    PFLA
 65:    WorldSpace
 66:    Land
 67:    NavMesh
 68:    TLOD
 69:    DIAL
 70:    INFO
 71:    Quest
 72:    Idle
 73:    Package
 74:    CombatStyle
 75:    LoadScreen
 76:    LeveledSpell
 77:    ANIO
 78:    WaterForm
 79:    EffectShader
 80:    TOFT
 81:    Explosion
 82:    Debris
 83:    ImageSpace
 84:    ImageSpaceModifier
 85:    ListForm
 86:    Perk
 87:    BodyPartData
 88:    AddonNode
 89:    ActorValueInfo
 90:    RadiationStage
 91:    CameraShot
 92:    CameraPath
 93:    VoiceType
 94:    ImpactData
 95:    ImpactDataSet
 96:    ARMA
 97:    EncounterZone
 98:    Message
 99:    Ragdoll
100:    DOBJ
101:    LightingTemplate
102:    SoundFile


Weapon Type
 0:    HandToHandMelee
 1:    OneHandMelee
 2:    TwoHandMelee
 3:    OneHandPistol
 4:    OneHandPistolEnergy
 5:    TwoHandRifle
 6:    TwoHandAutomatic
 7:    TwoHandRifleEnergy
 8:    TwoHandHandle
 9:    TwoHandLauncher
10:    OneHandGrenade
11:    OneHandMine
12:    OneHandLunchboxMine

Equip Type

Equipment Slot IDs
  0:    head
  1:    hair
  2:    upper body
  3:    left hand
  4:    right hand
  5:    weapon
  6:    pip boy
  7:    backpack
  8:    necklace
  9:    headband
 10:    hat
 11:    eyeglasses
 12:    nosering
 13:    earrings
 14:    mask
 15:    choker
 16:    mouth object
 17:    body addon 1
 18:    body addon 2
 19:    body addon 3

Weapon Hand Grips
  0:    default
  1:    hand grip 1
  2:    hand grip 2
  3:    hand grip 3

Attack Animations
  0:    default
  1:    Attack 3
  2:    Attack 4
  3:    Attack 5
  4:    Attack 6
  5:    Attack 7
  6:    Attack 8
  7:    Attack Left
  8:    Attack Loop
  9:    Attack Right
 10:    Attack Spin
 11:    Attack Spin 2
 12:    Attack Throw
 13:    Attack Throw 2
 14:    Attack Throw 3
 15:    Attack Throw 4
 16:    Attack Throw 5
 17:    Place Mine
 18:    Place Mine 2

Reload Animations
  0:    Reload A
  1:    Reload B
  2:    Reload C
  3:    Reload D
  4:    Reload E
  5:    Reload F
  6:    Reload G
  7:    Reload H
  8:    Reload I
  9:    Reload J
 10:    Reload K


Actor Value Codes
 0:    Aggression
 1:    Confidence
 2:    Energy
 3:    Responsibility
 4:    Mood
 5:    Strength
 6:    Perception
 7:    Endurance
 8:    Charisma
 9:    Intelligence
10:    Agility
11:    Luck
12:    ActionPoints
13:    CarryWeight
14:    CritChance
15:    HealRate
16:    Health
17:    MeleeDamage
18:    DamageResistance
19:    PoisonResistance
20:    RadResistance
21:    SpeedMultiplier
22:    Fatigue
23:    Karma
24:    XP
25:    Head
26:    Torso
27:    LeftArm
28:    RightArm
29:    LeftLeg
30:    RightLeg
31:    Brain
32:    Barter
33:    BigGuns
34:    EnergyWeapons
35:    Explosives
36:    Lockpick
37:    Medicine
38:    MeleeWeapons
39:    Repair
40:    Science
41:    SmallGuns
42:    Sneak
43:    Speech
44:    Throwing
45:    Unarmed
46:    InventoryWeight
47:    Paralysis
48:    Invisibility
49:    Chameleon
50:    NightEye
51:    DetectLifeRange
52:    FireResistance
53:    WaterBreathing
54:    RadLevel
55:    BloodyMess
56:    UnarmedDamage
57:    Assistance
60:    EnergyResistance
61:    EMPResistance
62:    Var1Medical
72:    IgnoreCrippledLimbs

Control Codes
0:    Forward
1:    Backward
2:    Left
3:    Right
4:    Attack
5:    Activate
6:    Block
7:    Ready Item
8:    Crouch
9:    Run
10:   Always Run
11:   Auto-Move
12:   Jump
13:   TogglePOV
14:   MenuMode
15:   Rest
16:   VATS
17-24: Hotkeys 1-8
25:   Quicksave
26:   Quickload
27:   Grab

DirectX Scancodes
  1:    Escape
  2:    1
  3:    2
  4:    3
  5:    4
  6:    5
  7:    6
  8:    7
  9:    8
 10:    9
 11:    0
 12:    Minus
 13:    Equals
 14:    Backspace
 15:    Tab
 16:    Q
 17:    W
 18:    E
 19:    R
 20:    T
 21:    Y
 22:    U
 23:    I
 24:    O
 25:    P
 26:    Left Bracket
 27:    Right Bracket
 28:    Enter
 29:    Left Control
 30:    A
 31:    S
 32:    D
 33:    F
 34:    G
 35:    H
 36:    J
 37:    K
 38:    L
 39:    Semicolon
 40:    Apostrophe
 41:    ~ (Console)
 42:    Left Shift
 43:    Back Slash
 44:    Z
 45:    X
 46:    C
 47:    V
 48:    B
 49:    N
 50:    M
 51:    Comma
 52:    Period
 53:    Forward Slash 
 54:    Right Shift
 55:    NUM*
 56:    Left Alt
 57:    Spacebar
 58:    Caps Lock
 59:    F1
 60:    F2
 61:    F3
 62:    F4
 63:    F5
 64:    F6
 65:    F7
 66:    F8
 67:    F9
 68:    F10
 69:    Num Lock
 70:    Scroll Lock
 71:    NUM7
 72:    NUM8
 73:    NUM9
 74:    NUM-
 75:    NUM4
 76:    NUM5
 77:    NUM6
 78:    NUM+
 79:    NUM1
 80:    NUM2
 81:    NUM3
 82:    NUM0
 83:    NUM.
 87:    F11
 88:    F12
156:    NUM Enter
157:    Right Control
181:    NUM/
184:    Right Alt
200:    Up Arrow
203:    Left Arrow
205:    Right Arrow
208:    Down Arrow
256:    Left Mouse Button
257:    Right Mouse Button
258:    Middle/Wheel Mouse Button
259:    Mouse Button 3
260:    Mouse Button 4
261:    Mouse Button 5
262:    Mouse Button 6
263:    Mouse Button 7
264:    Mouse Wheel Up
265:    Mouse Wheel Down

 
Function Index
- functions follwed by a number in subscript were introduced in that release (10:    v0010, 11:    v0011)

AddSpellNS1
con_CloseAllMenus1
con_GetINISetting1
con_LoadGame1
con_QuitGame1
con_RefreshINI1
con_Save1
con_SaveINI1
con_SetINISetting1
con_SetVel1
DebugPrint1
DisableControl1
DisableKey1
EnableControl1
EnableKey1
GetAltControl1
GetAttackDamage1
GetBaseObject1
GetControl1
GetCrosshairRef1
GetDebugSelection1
GetFOSERevision1
GetFOSEVersion1
GetHealth1
GetKeyPress1
GetNumericGameSetting1
GetNumericIniSetting1
GetNumKeysPressed1
GetNumMouseButtonsPressed1
GetObjectType1
GetValue1
GetWeaponActionPoints1
GetWeaponAmmo1
GetWeaponAmmoPerShot1
GetWeaponAnimJamTime1
GetWeaponAnimReloadTime1
GetWeaponAnimShotsPerSec1
GetWeaponClipRounds1
GetWeaponCritChance1
GetWeaponCritDamage1
GetWeaponCritEffect1
GetWeaponFireDelayMax1
GetWeaponFireDelayMin1
GetWeaponFireRate1
GetWeaponMaxRange1
GetWeaponMinRange1
GetWeaponMinSpread1
GetWeaponMaxSpread1
GetWeaponProjectile1
GetWeaponReloadTime1
GetWeaponResistType1
GetWeaponRumbleLeftMotor1
GetWeaponRumbleRightMotor1
GetWeaponRumbleDuration1
GetWeaponRumbleWavelength1
GetWeaponSightFOV1
GetWeaponSkill1
GetWeaponType1

GetWeight1
HoldKey1
IsControl1
IsControlDisabled1
IsControlPressed1
IsKeyDisabled1
IsKeyPressed1
ListAddForm1
ListAddReference1
ListGetCount1
ListGetFormIndex1
ListGetNthForm1
MenuHoldKey1
MenuReleaseKey1
MenuTapKey1
PrintToConsole1
ReleaseKey1
SetAltControl1
SetAttackDamage1
SetControl1
SetDebugMode1
SetIsControl1
SetNumericGameSetting1
SetNumericIniSetting1
SetObjectHealth1
SetWeaponActionPoints1
SetWeaponAmmoUse1
SetWeaponCritChance1
SetWeaponCritDamage1
SetWeaponCritEffect1
SetWeaponClipRounds1
SetWeaponMaxRange1
SetWeaponMinRange1
SetWeaponMaxSpread1
SetWeaponMinSpread1
SetWeaponSightFOV1
SetWeight1
TapKey1

Deprecated Functions