Difference between revisions of "OBSE Wish List"

From the Oblivion ConstructionSet Wiki
Jump to navigation Jump to search
imported>Thalassicus
imported>8asrun6aer
m (removing my request for now)
 
(49 intermediate revisions by 18 users not shown)
Line 1: Line 1:
:''Note : Function requests are better made in the current OBSE discussion thread. Search for '''Oblivion Script Extender (OBSE)''' at the [http://www.bethsoft.com/bgsforums/index.php?showforum=25 BGS forums] to find the latest one.''
This wish list is a place to put ideas for inclusion in OBSE. It will be kept organized, consistent, and clean as possible. That means your contribution may be edited or deleted in order to keep this list manageable. Contributions will ''only'' be deleted if they are redundant - either because Oblivion came with a function for this, or because the function has already been requested. Contributions may be edited for a large variety of reasons, from consistency to aesthetics. Please do not take this personally.
This wish list is a place to put ideas for inclusion in OBSE. It will be kept organized, consistent, and clean as possible. That means your contribution may be edited or deleted in order to keep this list manageable. Contributions will ''only'' be deleted if they are redundant - either because Oblivion came with a function for this, or because the function has already been requested. Contributions may be edited for a large variety of reasons, from consistency to aesthetics. Please do not take this personally.


Line 13: Line 17:
Tweaks to functions already present in the scripting language:
Tweaks to functions already present in the scripting language:


*'''SetDebugMode''' - This function currently accepts the mod index to enable debugging on, and a boolean value as to whether debugging should be enabled or disabled.  Changing the boolean value to an integer would provide greater functionality, such that 0 = turn off debugging, 1 = debug to console only, 2 = debug to log file only (see below), and 3 = debug to console and log file.  In short, it would provide the ability to write mod-generated debug text to a log file.  Perhaps the log file could be called "OBSE<ModIndex><Date><Time>.log", and would be created in the OBSE subdirectory of the Oblivion\Data\ folder, but these are just suggestions, this format can and should be altered to meet with OBSE standards and conventions.  Also, each entry in the log file should have a timestamp written before each line.
*'''PlayMagicShaderWeapon''' - Similar to the standard "PlayMagicShaderVisuals", but plays a magic shader only on an actor's equipped weapon; Not the body, not the scabbard, just the weapon.  Like an enchantment shader.  Could be abbreviated to "pmsw", much like how the template can be shortened to "pms".  May require a contingency for when the equipped weapon are unarmed/fists (IE: nothing happens).
*'''PlayMagicShaderWeapon''' - Similar to the standard "PlayMagicShaderVisuals", but plays a magic shader only on an actor's equipped weapon; Not the body, not the scabbard, just the weapon.  Like an enchantment shader.  Could be abbreviated to "pmsw", much like how the template can be shortened to "pms".  May require a contingency for when the equipped weapon are unarmed/fists (IE: nothing happens).
*'''StopMagicShaderWeapon''' - The counterpart to the above command, it acts like "StopMagicShaderVisuals".  Like its template, and like the counterpart requested function, it could be shortened to "smsw" for convenience.
*'''StopMagicShaderWeapon''' - The counterpart to the above command, it acts like "StopMagicShaderVisuals".  Like its template, and like the counterpart requested function, it could be shortened to "smsw" for convenience.
*'''PlayMagicShaderArmor''' - As above, but with specific pieces of armor. Perhaps could have a flag for scabbard. Could be abbreviated pmsa. would be used instead of above for unarmed fists.
*'''StopMagicShaderArmor''' - The counterpart to the above command. it would act like "StopMagicShaderVisuals". Could also be shorted to "smsa" as well.


*'''castNoAnim''' - When called on an actor, the actor casts the spell without playing the casting animation.
*'''castNoAnim''' - When called on an actor, the actor casts the spell without playing the casting animation.


*'''messageNoDelay''' - causes the message to be displayed immediately, even if another message is currently being displayed.
*'''castut''' - when called, the actor casts a spell in the direction he/she is facing without needing a target.
*'''castut''' - when called, the actor casts a spell in the direction he/she is facing without needing a target.
*'''[ref].On[blocktype] [ObjectID]''' Would be used as a block type in quest scripts which would run as if the block type is used in the reference or object's script.
*'''GetPlayerCameraAngle''' - Like GetAngle Z except detects the angle the player is looking instead of the angle the horse is heading when the player is on horseback.
** player.getHeadingAngle horseRef could be useful here.
*'''DeleteClonedForm''' - Delete the reference and base object of a cloned form like DeleteFullActorCopy
*'''DeleteClonedForm''' - Delete the reference and base object of a cloned form like DeleteFullActorCopy
*'''SetObjectAlpha''' - Just like SetActorAlpha except works on any object, not just actors.
*'''SetObjectAlpha''' - Just like SetActorAlpha except works on any object, not just actors.
*'''EquipItem2''' - Just like EquipItem except runs the item's OnEquip block.
**If it's your own item, you can use an onUnEquip block for this one. Unequipping an item, and then requipping it in the next line, will still run the item's onUnEquip block. Since the onUnEquip block will run after the calling script (the one that did the UnEquipItem and EquipItem), you can use a [[GetEquipped]] check, in the onUnEquip block, to make sure the item is equipped.
**Using OnUnequip blocks is a good idea. However, if it's not allowed to modify the script on the item I want to equip, I cannot use OnUnequip blocks. I think it'd be a great help for some mods like scruggs' "Expanded Hotkeys and Spell Delete".--Isatin 16:30, 12 November 2007 (EST)
*'''DuplicateAllItems2''' - Same as DuplicateAllItems, but doesn't create a new ID/cloneformed item for each scripted item that's duplicated
*'''EnablePlayerControls2/DisablePlayerControls2''' - Acts like the original functions but without hiding UI.
*'''EnablePlayerControls2/DisablePlayerControls2''' - Acts like the original functions but without hiding UI.
*'''Resurrect2''' - Like Resurrect but doesn't remove all of your abilities when called on the player.
*'''Resurrect2''' - Like Resurrect but doesn't remove all of your abilities when called on the player, nor causes camera issues.
*'''GetDisease''' - Return if the calling actor gets diseased.
*'''Activate2''' - Exactly like Activate but with an unlimited nesting limit (currently only 4-5 scripts started with '''Ref.Activate player, 1''' will run at once while there is no limit on result scripts). Would be great if it was also bug free - [[Crashes#Activating_a_Container_.28including_NPC.29|safely use the ''RunOnActivate'' flag with containers]] and [[Activate#Buggy Bug Bug of a Weird Weird Bug|using the ''RunOnActivate'' flag on any object without an onActivate block won't stop it from being normally activated]].
* (projectile:ref) '''Cast2''' - a [[Cast]] function which simultaneously returns the projectile of the spell just launched.
* '''CastByPlayer''' - combine a [[Cast]] call with [[SetPlayerProjectile]] call on the projectile fired by the Cast, to avoid having to loop through references to find the projectile cast.
* '''PushActorAway2''' - just like [[PushActorAway]] except that the calling ref don't have to be an [[Actor]]
* '''PushActorAway2''' - just like [[PushActorAway]] except that the calling ref don't have to be an [[Actor]]
*'''ResurrectActorHealthPercent'''- Resurrects the target actor with the given health remaining.
*'''SetLocalGravity/SetLocalGravityVector''' - These functions seem to have no effect at all while an actor is swimming or under water. It would be very helpful if they ''had'' an effect actually, because this would allow to simulate burden and buoyancy under water.


==Modifications/Extensions of OBSE Functions==
==Modifications/Extensions of OBSE Functions==
*Add the ''Simple'' Quality to Spells and enchantments.  The ''SetIconPath'' function could be used to make custom script effects less monotonous.
 
*'''GetModVersion/fModVersion''' - fModVersion is a variable that is available uniquely to any mod, and can be set from any script in that mod (thinking along the lines of fQuestDelayTime for quest scripts).  Then, any mod (including the original) can call GetModVersion, passing the esp ID or the mod's filename, to return the version of that plugin (though it's artificial; the modder explicitly sets the version by defining the fModVersion variable).  This would greatly aid in creating mods that are meant to be compatible with multiple versions of another mod.  If fModVersion is too difficult to implement, SetModVersion could be a function that has the same effect as setting fModVersion manually.
*'''GetUnusedLabel''' - Return an unused label number. If we run out of label numbers, return -1. Looping is absolutely great, but when using ''label'' & ''goto'' in stage functions, I found it would be a problem that I had to specify the label number. I couldn't assure that label numbers I used were unused. So I think it'd be helpful to this kind of situation.
**NOTE: It is rare that two scripts will be running at the same time: result/stage scripts, and scripts started with '''Ref.Activate player, 1''' are the only known scripts that can run while another script is running. There was a brief discussion in an OBSE thread, starting from [http://www.bethsoft.com/bgsforums/index.php?s=&showtopic=670186&view=findpost&p=9667117 this post].
*'''GetMouseX/GetMouseY''' - Returns current mouse position.
*'''MagicItemHasEffectAndActorValue(/Code/Count/CodeCount)''' - Returns whether the magic item has the specific effect and actor value (i.e., the magic item has "Fortify Intelligence", rather than the magic effect "Fortify Attribute"). Also accepts 256/No Actor Value. (This would really help for effect sorting scripts --[[User:Haama|Haama]] 17:15, 13 November 2007 (EST))
*'''CopyName for Magic Effects''' - Copies the name of the magic effect unto an item. Might also be able to get around this by making a function that returns the reference of the magic effect, and feeding that reference to the standard CopyName.
*'''IsKeyPressed2+3''' - IsKeyPressed2 can pick up tapped keys, IsKeyPressed3/IsControlPressed can pick up disabled keys. Combining them into one IsKeyPressed4 function would be nice, but more to the point being able to do both with an IsControlPressed2 would make coding much easier.
*'''IsKeyPressed2+3''' - IsKeyPressed2 can pick up tapped keys, IsKeyPressed3/IsControlPressed can pick up disabled keys. Combining them into one IsKeyPressed4 function would be nice, but more to the point being able to do both with an IsControlPressed2 would make coding much easier.
*'''MessageBoxEx Force Upper/Lower case''' - Add two new commands - %u and %l - to force the first character of a variable to be either upper or lower case. For example, using %u %pp at the start of a sentence would print as His, Her ot Its, instead of his, her or its.
*'''MessageBoxEx Centre Message''' - add a new command to force the text in a message box to be centred, in the same way that the buttons are.
*'''MessageBoxEx Centre Message''' - add a new command to force the text in a message box to be centred, in the same way that the buttons are.
*'''SetRaceNthSpell''' - Sets the race's Nth spell. Useful for adding spells to races without conflicting with other mods, when used in combination with GetRaceSpellCount.
*'''SetRaceNthSpell''' - Sets the race's Nth spell. Useful for adding spells to races without conflicting with other mods, when used in combination with GetRaceSpellCount.
*'''MessageBoxEx Silent Menu''' - Add a way to set the box to silent, so no sound plays when the menu pops up and no sound plays when you click a button. Useful for mods where you want to play your own custom sound for just one menu, or want to play a sound while the menu is there, without being cut off by the sound the MessageBox makes.
*'''MessageBoxEx Silent Menu''' - Add a way to set the box to silent, so no sound plays when the menu pops up and no sound plays when you click a button. Useful for mods where you want to play your own custom sound for just one menu, or want to play a sound while the menu is there, without being cut off by the sound the MessageBox makes.
*'''SetNthActiveEffectCaster''' - If we can set the caster, we could use activator to cast spells then set the caster to which ever actor we wish and achieve a total silent spell with out any casting animation.
*'''Ar_Sum''' - Sums the numeric values ranging from ''start'' to ''end''. Syntax would be
 
  ar_Sum src:array start, end
==Console Functions==
Existing console functions made available in scripts, or useful new console functions:
*'''AutosaveSlot [Slot Number]''' - An alternative to SaveGame, saves the game to the name "autosave #" where # is the integer given by Slot Number. This way someone can make a mod where you can press a button to autosave, cycling through 5/10/15 slots. It's safer than SaveGame and more convenient.
*'''PRID [referenceID]''' - This function would be hugely useful in scripts, allowing you to specify the reference on which subsequent functions would be run.
*'''TM''' - toggles the HUD/Interface. Can be useful in cut scenes.
*'''GetFormID/GetObjectID [formID|objectID]''' - In the console, converts a formID to an objectID and vice-versa. Mainly useful for debugging.
*'''EnableConsoleMessage/DisableConsoleMessage''' - While disabling console messages, no incoming messages will be shown. Useful for debug to filter the console messages. And can be used to avoid the spam sent by some functions like ''RemoveSpell'' and ''GetNumItems''. I hope it can be also used in scripts.


==Language Enhancements==
==Language Enhancements==
Line 67: Line 49:
*Global reference variables, to avoid issues where calling '''quest.refVar.someFunction''' is not allowed.
*Global reference variables, to avoid issues where calling '''quest.refVar.someFunction''' is not allowed.
*'''Return2''' - Unlike ''Return'' stopping the scripts in this frame, ''Return2'' only breaks the current block and other blocks in the same script can be still run. Useful for the script writers who want to use multiple ''Return'' to reduce the use of nested if/endif blocks without missing the calling of other blocks.
*'''Return2''' - Unlike ''Return'' stopping the scripts in this frame, ''Return2'' only breaks the current block and other blocks in the same script can be still run. Useful for the script writers who want to use multiple ''Return'' to reduce the use of nested if/endif blocks without missing the calling of other blocks.
*'''OnActorHits (''Id Optional'')''' - This block will be run once when the scripted actor hits the specified Object or actor.
*'''OnDetect'''- runs when the actor detects the target actor.


==Audio Functions==
==Audio Functions==
Functions dealing with music and sound:
Functions dealing with music and sound:
*'''PlaySound2/PlaySound3D2''' - This function allows more than one copy of the same sound to be played before the first one finishes. Example: Normally if one sound lasts 3 seconds and is played twice within that time, the second one will never play. Using PlaySound2/PlaySound3D2 any subsequent instances of the first sound will play no matter how many times they were called before the oldest playing one finished.
*'''stopSound''' - stops a looping sound from playing.
*'''stopSound''' - stops a looping sound from playing.
*<s>'''PlayMusic''' - [[StreamMusic]] is horribly buggy. A cleaner version which overrides combat music would be ideal.</s> - Fixed with the plugin SoundCommands
*'''StopMusic''' - stops a mp3 file played with the above or with [[StreamMusic]].
*'''GetMusicPlaying''' - returns the filename of the currently playing track?
*'''PlayEffectSound Effect SoundType''' - Plays the sound effect of a spell effect. SoundType is an integer that determines if it plays the cast, bolt, hit, or area sound.
*'''EnableTrivialSound/DisableTrivialSound''' - While disabling trivial sounds, the sounds played by the functions in scripts like ''AddItem, RemoveItem, EquipItem, Activate'' (while picking up items), and even for the actions done by the player like while equiping or picking up items. Mainly for script writers to avoid these interface sounds with a simple way when they want something to be done in the background.
*'''EnableTrivialSound/DisableTrivialSound''' - While disabling trivial sounds, the sounds played by the functions in scripts like ''AddItem, RemoveItem, EquipItem, Activate'' (while picking up items), and even for the actions done by the player like while equiping or picking up items. Mainly for script writers to avoid these interface sounds with a simple way when they want something to be done in the background.


Line 81: Line 60:
Functions dealing with combat, crime, detection, and AI:
Functions dealing with combat, crime, detection, and AI:
*'''setHitBy''' ''actorID, damage'' - damages the actor and updates AI as if the calling actor had attacked them. The [[Kill]] function might provide a shortcut to implementing this function, as it allows an actorID parameter to be specified as the attacker.
*'''setHitBy''' ''actorID, damage'' - damages the actor and updates AI as if the calling actor had attacked them. The [[Kill]] function might provide a shortcut to implementing this function, as it allows an actorID parameter to be specified as the attacker.
*'''getCaster''' - in a scripted spell, returns a reference to the object or actor which cast the spell.
*'''getBodyPartHit''' - returns the body part hit by an attack - hands, torso, head, etc. The game engine apparently randomly picks one, then checks the armor rating of that body part to calculate damage.
*'''SetHostile''' - would force the calling actor to behave as if they perceived a hostile threat, assuming such states can be imposed in the absence of real combat.
*'''SetHostile''' - would force the calling actor to behave as if they perceived a hostile threat, assuming such states can be imposed in the absence of real combat.
*'''actor1.VirtualAttack actor2''' - Makes actor2 react like he's attacked by actor1 without suffering from any damage.
 


==Animation and Graphics Functions==
==Animation and Graphics Functions==
Functions dealing with animations or game rendering:
Functions dealing with animations or game rendering:
*'''getCurrentAnim''' - Returns the currently playing animation.
 
*'''changeAnimFilepath''' - Changes the filepaths used for the player anims by script effect, so he/she e.g. floats like a lich always when a "Lichdom"-effect effects him/her.
*'''forceDismount''' - Forces a mounted actor to dismount.
*'''forceDismount''' - Forces a mounted actor to dismount.
*'''setCameraDistance''' - In third person view, adjusts the camera's distance from the player.
*'''fadeIn/fadeOut''' ''duration'' - Fades the screen to or from black over the given duration.
*'''closeMenu''' - Closes all open menus.
*'''ReloadCell''' or '''UpdateLighting''' - Reloads the cell as if the player had just entered or as if he were moved out of and then back into the cell; or updates the illumination of lights on static objects. Kind of a specific request to eliminate issues with disabled and re-enabled lights not illuminating properly.
*'''ReloadCell''' or '''UpdateLighting''' - Reloads the cell as if the player had just entered or as if he were moved out of and then back into the cell; or updates the illumination of lights on static objects. Kind of a specific request to eliminate issues with disabled and re-enabled lights not illuminating properly.
*'''Get/SetFacialData''' - Returns/sets facial data of the calling actor.
*'''Get/SetFacialData''' - Returns/sets facial data of the calling actor.
*'''GetShader''': Returns shader(s) active on PC camera (e.g. nighteye, hitshader/blur, etc).
*'''GetShader''': Returns shader(s) active on PC camera (e.g. nighteye, hitshader/blur, etc).
*'''TriggerShader''':  Adds a shader to the PC camera, the shader could be defined in an INI or via another function (see talk: Custom Shaders).
*'''ForcePickIdle''' - force an Idle to be played even if the player is not on the ground or under any other circumstance that would usually block pickidle.
*'''ForcePickIdle''' - force an Idle to be played even if the player is not on the ground or under any other circumstance that would usually block pickidle.
*'''PlaceCinematicCamera''': Enter tfc mode & Place the camera at any xyz location or xmarker, set elevation & rotation angle, or track a reference object.
*'''FlyingCinematicCamera''': enter tfc and script the camera motion between reference points while tracking another reference.  Also able to set speed of movement.
*'''SetCellAmbientLight''': Accepts 3 integer values that set the red, green, and blue ambient light values in an interior cell. A GetCellAmbientLight function would also be nice.
*'''SetCellAmbientLight''': Accepts 3 integer values that set the red, green, and blue ambient light values in an interior cell. A GetCellAmbientLight function would also be nice.
*'''PlayAnimationSourceFile''': Plays animations directly from a source file on the specified actor.
*'''PlayAnimationSourceFileFP''': Plays first person animations directly from a source file on the specified actor.


==Functions Returning a Reference==
==Functions Returning a Reference==
Functions that return a reference:
Functions that return a reference:
*'''GetFirstRefInContainer''' - Like GetFirstRef, but returns a reference to first item in a container.
 
*'''getLastAttacked''' - Returns a reference to the actor last attacked by the calling actor.
*'''getLastActivated''' - Returns a reference to the last object activated by the player or calling actor.
*'''getLastActivated''' - Returns a reference to the last object activated by the player or calling actor.
*'''getNearest ''integer'' ''type'''''  - Returns a reference to the nearest object to the calling reference.  ''Type'' specifies which type of reference - Actor, Activator, etc.  So, for example, ''player.getNearest 6 NPC'' will return the sixth closest NPC to the player.
*'''getTelekinesisItem''' - Returns reference of the object player is currently targeting with telekinesis.
*'''GetTeleportMarker''' - Return teleport marker associated with the door that called the function


==Actor Functions==
==Actor Functions==
Functions which read or alter the state of an actor:
Functions which read or alter the state of an actor:
*'''SetRace''' - Allows you to change the race of an actor
*'''SetRace''' - Allows you to change the race of an actor
*'''IsStill''' - Returns true if the actor is not moving any of its body parts - providing that it has body parts - by itself at all (e.g. standing still, flying still, jumping still, swimming still, falling still, being crashed or limbs moved by only other actors - not the actor himself, etc).
*'''GetIsSummon''' - Returns true if the calling actor is a summoned creature (a normal summon associated with one of the "Summon" spell effects). This would allow scripters to avoid issues where the reference is destroyed when the spell effect ends or creature is killed.
*'''Open [Reference]''' - Makes the calling actor open the given door or container with his or her keys. Even suitable for a calling container.
*'''GetActorMagicEffectMagnitude [Effect]''' - Returns the total magnitude of a particular magic effect from all spells/abilities/etc affecting an actor.
*'''DropEquipped [slot]''' - Drops the equipped item according to the given equipment slot. This function keeps the item's statuses like RemoveMe or disarmament.
*'''DropEquipped [slot]''' - Drops the equipped item according to the given equipment slot. This function keeps the item's statuses like RemoveMe or disarmament.
*'''CancelInvisibility''' - If the player is invisible through a spell, cancel the spell and make the player visible.
*'''GetKilledBy''' - Get the reference by whom the actor was killed. Should be available in blocks like ''actorId.GetDead == 1''.
*'''GetKilledBy''' - Get the reference by whom the actor was killed. Should be available in blocks like ''actorId.GetDead == 1''.
*'''GetHitBy''' - Returns the reference whom just hit the actor.
*'''GetHitBy''' - Returns the reference whom just hit the actor.
*'''GetAge''' - Returns the age of the actor if it is an NPC
*'''GetAge''' - Returns the age of the actor if it is an NPC
*'''SetAge''' - Allows you to change the age of an NPC
*'''SetAge''' - Allows you to change the age of an NPC
*'''MatchRace'''- Changes the target reference's race to match another Actor. Similar to SetRace above, but allows for custom races and races not defined in the CS.
*'''MatchFaceData'''- Changes the target's face data to match another Actor.
*'''IsInWater''' ''WaterTypeID'' - returns 1 if actor is currently being underwater or even touching the water, even with Water Walking. Specifying the optional ''WaterTypeID'' allows us to check whether the actor is currently touching the specific type of water.
*'''ForceLeaveWater''' ''SwimmingFlag'' ''NoReenteringFlag'' - forces actor to leave the water. If ''SwimmingFlag'' is not specified or set to 0, actor will attempt to completely leave the water, even if he's only touching it, not swimming. With ''SwimmingFlag'' set to 1, this function will only force him to get high enough to be no longer swimming. With ''NoReenteringFlag'' set to 1, using this function will force actor to avoid touching water/swimming (and thus if he's pushed back into water, he will again attempt to leave it). If function below was previously used with ''NoLeavingFlag'', using '''ForceLeaveWater''' will nuke the effects of this flag.
*'''ForceEnterWater''' ''SwimmingFlag'' ''NoLeavingFlag'' - forces actor to find the closest area where he can touch the water and attempt to enter it. With ''SwimmingFlag'' set to 1, called actor will not only try to touch the water, but start swimming. Could have no effect in interiors and worldspaces with no water. With ''NoLeavingFlag'' set to 1, using this function will prevent actor from leaving the water (and thus if he's pushed away from the water, he will again attempt to enter it). If function above was previously used with ''NoReenteringFlag'', using '''ForceEnterWater''' will nuke the effects of this flag.
*'''ClearWaterBehaviour''' - clears the ''NoReenteringFlag'' and ''NoLeavingFlag'' from functions above.
*'''IsEquipmentSlotFree [slot]''' - returns 1 if the specified slot is free, and 0 when not.


==UI Functions==
==UI Functions==
*'''GetDialogID''' - retrieve the ID of the dialog currently shown.
*'''GetTextFromDialog''' - retrieve dialog text, manually entered text, or the answer options that the user can choose /this would make only sense if we had string manipulation routines, too, such get Trim(), Substr(), Compare(), Catenate()/. Would be great for some puzzles...
*'''SelectDialogResponse''' - Choose a particular answer in a dialog (e.g. Yes, No, Cancel, Optionx, etc.)
*'''SelectDialogResponse''' - Choose a particular answer in a dialog (e.g. Yes, No, Cancel, Optionx, etc.)
*'''ShowMap2 (FastTravelFlag)''' - Unlike ShowMap, this function just bring the map menu on the screen and the player can fast-travel or close the menu. If the ''FastTravel'' flag is true, the player can fast-travel whether the cell is set as unable to travel from here.
*'''SetEffectItemScriptEffectIcon (Effect ID) (Path/Filename.dds)''' - Causes the "Script Effect" of a magic item (Spell, enchantment, etc.) to display a custom icon instead of the default Script Effect icon.  Affects every "Script Effect" on the item without changing non-script effect's icons.
*'''ShowInventory (PageNumber)''' - Bring the player inventory menu on the screen. If ''PageNumber'' is given, show the corresponding page. Otherwise, show the last page the player opened.
*'''ShowMagic (PageNumber)''' - Bring the player magic menu on the screen. If ''PageNumber'' is given, show the corresponding page. Otherwise, show the last page the player opened.


==Other Functions==
==Other Functions==
Functions which don't fit into other categories:
Functions which don't fit into other categories:
*'''GetCollisionTrace''' - Generalized version of [[GetLOS]] to return where collision occurs, rather than a boolean expression of success or failure. Traces a line from a start point to a destination and returns an array of 3 elements corresponding to the XYZ coordinates one iteration-step before collision with a surface occurs. If collision is never detected, returns the destination point. Actors are ignored for the collision check if optional parameter ignoreActors is true, defaults to false. If necessary for efficiency, implementation can include a distance between collision checks specified by optional parameter distanceSkip, defaulting to 16 (or some other efficient value).  
*'''GetCollisionTrace''' - Generalized version of [[GetLOS]] to return where collision occurs, rather than a boolean expression of success or failure. Traces a line from a start point to a destination point and returns a two-dimensional array. Each row corresponds to a point where collision with a new object is detected from the start to destination, with four columns: the reference ID of the colliding object, and X,Y,Z coordinates of the collision. If collision is never detected, returns an empty array. Actors are ignored for the collision check if optional parameter ignoreActors is true, defaults to false. If necessary for efficiency, implementation can include a distance between collision checks specified by optional parameter distanceSkip, defaulting to 16 (or some other efficient value).
(If the game engine has the power to do so, an even better return value would be a two-dimensional array, each row containing a 3-column XYZ sub-array, for each point where collision with a new surface is detected from the start to destination.) Usage:
:Usage:
:array<float> startRef:reference.'''GetCollisionTrace''' destRef:reference, ''ignoreActors:bool, distanceSkip:float''
:array<float> startRef:reference.'''GetCollisionTrace''' destRef:reference, ''ignoreActors:bool, distanceSkip:float''
:array<float> '''GetCollisionTrace''' startX:float, startY:float, startZ:float, destX:float, destY:float, destZ:float, ''ignoreActors:bool, distanceSkip:float''
:array<float> '''GetCollisionTrace''' startX:float, startY:float, startZ:float, destX:float, destY:float, destZ:float, ''ignoreActors:bool, distanceSkip:float''
*'''GetCollisionTraceSpherical''' - Same as GetCollisionTrace, but uses [http://en.wikipedia.org/wiki/Spherical_coordinate_system spherical coordinates] to calculate the destination point. Usage:
*'''GetCollisionTraceSpherical''' - Same as GetCollisionTrace, but uses [http://en.wikipedia.org/wiki/Spherical_coordinate_system spherical coordinates] to calculate the destination point.
:Usage:
:array<float> startRef:reference.'''GetCollisionTraceSpherical''' distance:float, elevation:float, heading:float, ''ignoreActors:bool, distanceSkip:float''
:array<float> startRef:reference.'''GetCollisionTraceSpherical''' distance:float, elevation:float, heading:float, ''ignoreActors:bool, distanceSkip:float''
:array<float> '''GetCollisionTrace''' startX:float, startY:float, startZ:float, distance:float, elevation:float, heading:float, ''ignoreActors:bool, distanceSkip:float''
:array<float> '''GetCollisionTraceSpherical''' startX:float, startY:float, startZ:float, distance:float, elevation:float, heading:float, ''ignoreActors:bool, distanceSkip:float''
*'''RevertName''' - Called on a reference or base object with the 'Named' property to revert its name to its original definition in the construction set.  Examples: if setname or setnameex is used on Shadowmere to name her "Darkness", calling RevertName on 'ShadowmereRef' or 'Dark10Horse' would reset her name to "Shadowmere".  Likewise, if a mod is loaded that explicitly sets the name property of Shadowmere to "Black Beauty" using the CS (and assuming her name is then set (in game) to "Darkness" using setname or setnameex), calling RevertName on her should set her name to "Black Beauty".  I.E. The name should be set to whatever is defined in the construction set, with regard to installed mods.   
*'''RevertName''' - Called on a reference or base object with the 'Named' property to revert its name to its original definition in the construction set.  Examples: if setname or setnameex is used on Shadowmere to name her "Darkness", calling RevertName on 'ShadowmereRef' or 'Dark10Horse' would reset her name to "Shadowmere".  Likewise, if a mod is loaded that explicitly sets the name property of Shadowmere to "Black Beauty" using the CS (and assuming her name is then set (in game) to "Darkness" using setname or setnameex), calling RevertName on her should set her name to "Black Beauty".  I.E. The name should be set to whatever is defined in the construction set, with regard to installed mods.   
*'''GetModRecords''' - With the advent of arrays in OBSE v17, this request seems possible.  The function returns an array of the records introduced by a particular mod.  For example, the first level of the array would store an array for each of Actors, Items, Magic, Miscellaneous, and WorldObjects.  The contents of each subarray would be the records that each CS category contains that are new/introduced by the mod.  For example, If there is a mod loaded that adds 5 books to the game, and the mod is 8th in this imaginary load order, calling GetModRecords, passing 08 as the mod index, should return an array, and let's call it arItems.  arItems[Actors], arItems[Magic], etc. would be empty, but arItems[Items] would contain 5 records (numeric keys are used as opposed to labels, this is just for illustration).  These 5 records should be the FormID's of the five books.  In this way, one could search a mod for records, and make use of them in-game using placeatme or additem.   
*'''GetModRecords''' - With the advent of arrays in OBSE v17, this request seems possible.  The function returns an array of the records introduced by a particular mod.  For example, the first level of the array would store an array for each of Actors, Items, Magic, Miscellaneous, and WorldObjects.  The contents of each subarray would be the records that each CS category contains that are new/introduced by the mod.  For example, If there is a mod loaded that adds 5 books to the game, and the mod is 8th in this imaginary load order, calling GetModRecords, passing 08 as the mod index, should return an array, and let's call it arItems.  arItems[Actors], arItems[Magic], etc. would be empty, but arItems[Items] would contain 5 records (numeric keys are used as opposed to labels, this is just for illustration).  These 5 records should be the FormID's of the five books.  In this way, one could search a mod for records, and make use of them in-game using placeatme or additem.   
*'''Get/Set/ModWaterHeight''' - change the height of water in an Interior cell
*'''SetIsPersistent''' -  allows persistence to be toggled via script.*
*'''SetIsPersistent''' -  allows persistence to be toggled via script.*
*'''(reference.)SetNthVariable''' ''integer'' ''type'' ''quest(optional)'' - Sets the value of the Nth variable in the given script. This would let everyone use arrays without using an array type into the Oblivion scripting language. See [[Talk:OBSE_Wish_List#Arrays | Discussion]].
*'''[optional reference].AutocalSpellMagickaCost spellID''' - autocalculates spell cost including area factor, duration factor, and range factor based on the formula in [[FMagicCasterSkillCostMult]]. If optional reference is included, also calculates in the skill factor for that actor (including luck).  
*'''[optional reference].AutocalSpellMagickaCost spellID''' - autocalculates spell cost including area factor, duration factor, and range factor based on the formula in [[FMagicCasterSkillCostMult]]. If optional reference is included, also calculates in the skill factor for that actor (including luck).  
*'''IsPCUnderArrest''' - return a boolean indicating whether the player is chased by any guard.
*'''GetScriptStage''' - Returns the stage index of the calling result script. If the calling script is not a stage result script, then return -1. Very handy for those using stage functions to create arrays.
*'''LoadObject''' - Forcibly cache/load an object, or '''LoadCellBuffer''' which would load/cache an entire cell, sort of opposite to [[PurgeCellBuffers]]
*'''LoadObject''' - Forcibly cache/load an object, or '''LoadCellBuffer''' which would load/cache an entire cell, sort of opposite to [[PurgeCellBuffers]]
*'''GetDifficulty''' - Returns current game difficulty.
*'''EquipMe''' - Makes the actor holding the calling reference equips it. Even better if it can trigger OnEquip blocks.
*'''GetPoison''' - Returns the poison applied to the calling weapon reference.
*'''WallCollision''' - Returns true if the player is colliding with a wall. If that is not feasible, then returning true if the player is colliding with any solid object that isn't a floor would be more helpful than what we've got.
*'''Get/SetCellFogNear''' & '''Get/SetCellFogFar''' - Get and set interior cell fog distance.
*'''Get/SetCellFogNear''' & '''Get/SetCellFogFar''' - Get and set interior cell fog distance.
*'''GetStartingCell''' ''CellID'' - Returns true if editor cellID is the same a the parameter specified.
*'''GetStartingCell''' ''CellID'' - Returns true if editor cellID is the same a the parameter specified.
*'''GetGroundPos''' - Returns the groundlevel co-ordinate of the current cell.
*'''GetGroundPos''' - Returns the groundlevel co-ordinate of the current cell.
*'''IsOnGround''' - Returns true of the calling object of at ground level.
*'''Add/RemoveMajorSkill''' - Adds or removes major skill on calling actor.
*'''Add/RemoveMajorSkill''' - Adds or removes major skill on calling actor.
*'''Add/RemoveClassSkill''' - Adds or removes class skill for indicated class (If above request is prohibitive)
*'''Add/RemoveClassSkill''' - Adds or removes class skill for indicated class (If above request is prohibitive)
*'''SetCurrentCharge''' - Sets the charge of the calling reference (getcurrentcharge already exists)
*'''SetCurrentHealth''' - Sets the health of the calling reference - for objects,not actors (getcurrenthealth already exists)
*'''GetDimension [x|-x|y|-y|z|-z] ''' - returns the distance from the object 'origin' to its outer limit in the requested axis and direction - very useful when moving/placing/aligning/spacing references by script. (a typical NPC with the origin at the feet would return 125 to Z (origin to top) and 0 to -Z (origin to bottom)
*'''IsColliding  reference:ref''' - returns true if any part of the calling object occupies the same space as the provided reference:ref.
*'''GetCollidingRefs''' - returns an array of the references colliding with the calling reference.  <OR>  '''GetFirst/NextCollidingRef''' - returns one at a time.
*'''GetCollidingRefs''' - returns an array of the references colliding with the calling reference.  <OR>  '''GetFirst/NextCollidingRef''' - returns one at a time.
 
*'''TrainSkill'''- similar to advskill, only trains the skill as if you are training it in-game.
==Non-Functions (Game Tweaks)==
*'''IsRemoved'''- to check if a ''persistent'' reference is removed from the game - for instance put in chest scripted with RemoveAllItems, dropped in an oblivion world which got purged or put in the inventory of a dead actor which got deleted. IsFormValid returns true for a persistent reference in all these cases, and there seems to be no way to know if such a reference is still around.
*'''Non-Spoken Dialog Teaks:'''
*'''ForceFunctionValue'''- Forces a function to always return a value with the number specified. For instance
:When mods add dialog for which there is there is no voice file, it would be very useful if: 1) subtititles were automatically displayed, whether the dialog display setting is on or not, and 2) the subtitle would stay up until the user clicked to dismiss it. (Or at least stayed up for longer than than 1-2 seconds it currently displays.) Lacking these functions, 1) the player has to turn subtitles on all the time, which is annoying; and 2) the modder has to create empty voice files just to get the dialog to display for a long enough period of time, which is both annoying and immensely wasteful of resources and disk space.  
ForceFunctionValue GetIsPlayableRace 0
 
would force the function GetIsPlayableRace to return 0, no matter what the calling reference is. Adding an optional reference parameter would set the function to return a specific value whenever the function is called on that reference. So,
:If OBSE included a tweak to fix this behavior, it would make it much more practical for mods to add dialog, and IMO would be enough reason in itself to install OBSE. --[[User:Wrye|Wrye]] 23:25, 14 January 2008 (EST)
ForceFunctionValue GetIsPlayableRace 0 player
 
would force GetIsPlayableRace to return 0 every time it is called on the player, but normal values any time it's called on someone else. For debug, limitation, and certain Gameplay Effect purposes.
==Documentation==
*'''ReleaseFunctionOverride'''- Releases the effect of ForceFunctionValue and allows the function to continue acting normally.
*'''A small tutorial to the source code''' - A Tutorial for these who want to create new OBSE functions. I now understand it mostly, but it takes some time to figure it all out (for example you could explain what CommandInfo does, how you can create ParamInfo structures, etc, and also maybe some build instructions).
*'''getReference''' - Returns a string containing the reference given to the calling reference in the editor. This string can be used like
set stringVar to anyRef.getReference
set stringVar.anyVariable to x


==Questionable Requests==
==Questionable Requests==

Latest revision as of 11:13, 17 January 2012

Note : Function requests are better made in the current OBSE discussion thread. Search for Oblivion Script Extender (OBSE) at the BGS forums to find the latest one.


This wish list is a place to put ideas for inclusion in OBSE. It will be kept organized, consistent, and clean as possible. That means your contribution may be edited or deleted in order to keep this list manageable. Contributions will only be deleted if they are redundant - either because Oblivion came with a function for this, or because the function has already been requested. Contributions may be edited for a large variety of reasons, from consistency to aesthetics. Please do not take this personally.

Care will be taken to include a name with any requested function if that request is signed. If you don't care about having your name attached, please do not sign your request, since it will keep the list neater.

If, for any reason, you disagree with a change or deletion from this list, please discuss this in the Talk page - we are not infallible, it is entirely possible that we misunderstood the need or use of a given function, and we need that explained so that the contribution can be reverted into its original form and/or be changed into something more appropriate.

To keep the list more manageable, requests have been broken down into categories according to the type of function and, in some cases, the probable ease of implementation. Requested functions which can be accomplished with existing functions appear in a separate section at the bottom of the list.

To avoid requesting a feature which is already available, first consult the OBSE documentation and the list of OBSE Wishes Fulfilled.

Modifications of Existing Functions[edit | edit source]

Tweaks to functions already present in the scripting language:

  • PlayMagicShaderWeapon - Similar to the standard "PlayMagicShaderVisuals", but plays a magic shader only on an actor's equipped weapon; Not the body, not the scabbard, just the weapon. Like an enchantment shader. Could be abbreviated to "pmsw", much like how the template can be shortened to "pms". May require a contingency for when the equipped weapon are unarmed/fists (IE: nothing happens).
  • StopMagicShaderWeapon - The counterpart to the above command, it acts like "StopMagicShaderVisuals". Like its template, and like the counterpart requested function, it could be shortened to "smsw" for convenience.
  • PlayMagicShaderArmor - As above, but with specific pieces of armor. Perhaps could have a flag for scabbard. Could be abbreviated pmsa. would be used instead of above for unarmed fists.
  • StopMagicShaderArmor - The counterpart to the above command. it would act like "StopMagicShaderVisuals". Could also be shorted to "smsa" as well.
  • castNoAnim - When called on an actor, the actor casts the spell without playing the casting animation.
  • castut - when called, the actor casts a spell in the direction he/she is facing without needing a target.
  • DeleteClonedForm - Delete the reference and base object of a cloned form like DeleteFullActorCopy
  • SetObjectAlpha - Just like SetActorAlpha except works on any object, not just actors.
  • EnablePlayerControls2/DisablePlayerControls2 - Acts like the original functions but without hiding UI.
  • Resurrect2 - Like Resurrect but doesn't remove all of your abilities when called on the player, nor causes camera issues.
  • PushActorAway2 - just like PushActorAway except that the calling ref don't have to be an Actor
  • ResurrectActorHealthPercent- Resurrects the target actor with the given health remaining.
  • SetLocalGravity/SetLocalGravityVector - These functions seem to have no effect at all while an actor is swimming or under water. It would be very helpful if they had an effect actually, because this would allow to simulate burden and buoyancy under water.

Modifications/Extensions of OBSE Functions[edit | edit source]

  • IsKeyPressed2+3 - IsKeyPressed2 can pick up tapped keys, IsKeyPressed3/IsControlPressed can pick up disabled keys. Combining them into one IsKeyPressed4 function would be nice, but more to the point being able to do both with an IsControlPressed2 would make coding much easier.
  • MessageBoxEx Centre Message - add a new command to force the text in a message box to be centred, in the same way that the buttons are.
  • SetRaceNthSpell - Sets the race's Nth spell. Useful for adding spells to races without conflicting with other mods, when used in combination with GetRaceSpellCount.
  • MessageBoxEx Silent Menu - Add a way to set the box to silent, so no sound plays when the menu pops up and no sound plays when you click a button. Useful for mods where you want to play your own custom sound for just one menu, or want to play a sound while the menu is there, without being cut off by the sound the MessageBox makes.
  • Ar_Sum - Sums the numeric values ranging from start to end. Syntax would be
ar_Sum src:array start, end

Language Enhancements[edit | edit source]

New control structures and data types:

  • onBreak - This block runs when a scripted spell hits an inanimate object.
  • anyMode - Runs in gameMode and menuMode.
  • Global reference variables, to avoid issues where calling quest.refVar.someFunction is not allowed.
  • Return2 - Unlike Return stopping the scripts in this frame, Return2 only breaks the current block and other blocks in the same script can be still run. Useful for the script writers who want to use multiple Return to reduce the use of nested if/endif blocks without missing the calling of other blocks.
  • OnDetect- runs when the actor detects the target actor.

Audio Functions[edit | edit source]

Functions dealing with music and sound:

  • PlaySound2/PlaySound3D2 - This function allows more than one copy of the same sound to be played before the first one finishes. Example: Normally if one sound lasts 3 seconds and is played twice within that time, the second one will never play. Using PlaySound2/PlaySound3D2 any subsequent instances of the first sound will play no matter how many times they were called before the oldest playing one finished.
  • stopSound - stops a looping sound from playing.
  • EnableTrivialSound/DisableTrivialSound - While disabling trivial sounds, the sounds played by the functions in scripts like AddItem, RemoveItem, EquipItem, Activate (while picking up items), and even for the actions done by the player like while equiping or picking up items. Mainly for script writers to avoid these interface sounds with a simple way when they want something to be done in the background.

AI Functions[edit | edit source]

Functions dealing with combat, crime, detection, and AI:

  • setHitBy actorID, damage - damages the actor and updates AI as if the calling actor had attacked them. The Kill function might provide a shortcut to implementing this function, as it allows an actorID parameter to be specified as the attacker.
  • SetHostile - would force the calling actor to behave as if they perceived a hostile threat, assuming such states can be imposed in the absence of real combat.


Animation and Graphics Functions[edit | edit source]

Functions dealing with animations or game rendering:

  • forceDismount - Forces a mounted actor to dismount.
  • ReloadCell or UpdateLighting - Reloads the cell as if the player had just entered or as if he were moved out of and then back into the cell; or updates the illumination of lights on static objects. Kind of a specific request to eliminate issues with disabled and re-enabled lights not illuminating properly.
  • Get/SetFacialData - Returns/sets facial data of the calling actor.
  • GetShader: Returns shader(s) active on PC camera (e.g. nighteye, hitshader/blur, etc).
  • ForcePickIdle - force an Idle to be played even if the player is not on the ground or under any other circumstance that would usually block pickidle.
  • SetCellAmbientLight: Accepts 3 integer values that set the red, green, and blue ambient light values in an interior cell. A GetCellAmbientLight function would also be nice.

Functions Returning a Reference[edit | edit source]

Functions that return a reference:

  • getLastActivated - Returns a reference to the last object activated by the player or calling actor.

Actor Functions[edit | edit source]

Functions which read or alter the state of an actor:

  • SetRace - Allows you to change the race of an actor
  • DropEquipped [slot] - Drops the equipped item according to the given equipment slot. This function keeps the item's statuses like RemoveMe or disarmament.
  • GetKilledBy - Get the reference by whom the actor was killed. Should be available in blocks like actorId.GetDead == 1.
  • GetHitBy - Returns the reference whom just hit the actor.
  • GetAge - Returns the age of the actor if it is an NPC
  • SetAge - Allows you to change the age of an NPC
  • MatchRace- Changes the target reference's race to match another Actor. Similar to SetRace above, but allows for custom races and races not defined in the CS.
  • MatchFaceData- Changes the target's face data to match another Actor.
  • IsInWater WaterTypeID - returns 1 if actor is currently being underwater or even touching the water, even with Water Walking. Specifying the optional WaterTypeID allows us to check whether the actor is currently touching the specific type of water.
  • ForceLeaveWater SwimmingFlag NoReenteringFlag - forces actor to leave the water. If SwimmingFlag is not specified or set to 0, actor will attempt to completely leave the water, even if he's only touching it, not swimming. With SwimmingFlag set to 1, this function will only force him to get high enough to be no longer swimming. With NoReenteringFlag set to 1, using this function will force actor to avoid touching water/swimming (and thus if he's pushed back into water, he will again attempt to leave it). If function below was previously used with NoLeavingFlag, using ForceLeaveWater will nuke the effects of this flag.
  • ForceEnterWater SwimmingFlag NoLeavingFlag - forces actor to find the closest area where he can touch the water and attempt to enter it. With SwimmingFlag set to 1, called actor will not only try to touch the water, but start swimming. Could have no effect in interiors and worldspaces with no water. With NoLeavingFlag set to 1, using this function will prevent actor from leaving the water (and thus if he's pushed away from the water, he will again attempt to enter it). If function above was previously used with NoReenteringFlag, using ForceEnterWater will nuke the effects of this flag.
  • ClearWaterBehaviour - clears the NoReenteringFlag and NoLeavingFlag from functions above.
  • IsEquipmentSlotFree [slot] - returns 1 if the specified slot is free, and 0 when not.

UI Functions[edit | edit source]

  • SelectDialogResponse - Choose a particular answer in a dialog (e.g. Yes, No, Cancel, Optionx, etc.)
  • SetEffectItemScriptEffectIcon (Effect ID) (Path/Filename.dds) - Causes the "Script Effect" of a magic item (Spell, enchantment, etc.) to display a custom icon instead of the default Script Effect icon. Affects every "Script Effect" on the item without changing non-script effect's icons.

Other Functions[edit | edit source]

Functions which don't fit into other categories:

  • GetCollisionTrace - Generalized version of GetLOS to return where collision occurs, rather than a boolean expression of success or failure. Traces a line from a start point to a destination point and returns a two-dimensional array. Each row corresponds to a point where collision with a new object is detected from the start to destination, with four columns: the reference ID of the colliding object, and X,Y,Z coordinates of the collision. If collision is never detected, returns an empty array. Actors are ignored for the collision check if optional parameter ignoreActors is true, defaults to false. If necessary for efficiency, implementation can include a distance between collision checks specified by optional parameter distanceSkip, defaulting to 16 (or some other efficient value).
Usage:
array<float> startRef:reference.GetCollisionTrace destRef:reference, ignoreActors:bool, distanceSkip:float
array<float> GetCollisionTrace startX:float, startY:float, startZ:float, destX:float, destY:float, destZ:float, ignoreActors:bool, distanceSkip:float
  • GetCollisionTraceSpherical - Same as GetCollisionTrace, but uses spherical coordinates to calculate the destination point.
Usage:
array<float> startRef:reference.GetCollisionTraceSpherical distance:float, elevation:float, heading:float, ignoreActors:bool, distanceSkip:float
array<float> GetCollisionTraceSpherical startX:float, startY:float, startZ:float, distance:float, elevation:float, heading:float, ignoreActors:bool, distanceSkip:float
  • RevertName - Called on a reference or base object with the 'Named' property to revert its name to its original definition in the construction set. Examples: if setname or setnameex is used on Shadowmere to name her "Darkness", calling RevertName on 'ShadowmereRef' or 'Dark10Horse' would reset her name to "Shadowmere". Likewise, if a mod is loaded that explicitly sets the name property of Shadowmere to "Black Beauty" using the CS (and assuming her name is then set (in game) to "Darkness" using setname or setnameex), calling RevertName on her should set her name to "Black Beauty". I.E. The name should be set to whatever is defined in the construction set, with regard to installed mods.
  • GetModRecords - With the advent of arrays in OBSE v17, this request seems possible. The function returns an array of the records introduced by a particular mod. For example, the first level of the array would store an array for each of Actors, Items, Magic, Miscellaneous, and WorldObjects. The contents of each subarray would be the records that each CS category contains that are new/introduced by the mod. For example, If there is a mod loaded that adds 5 books to the game, and the mod is 8th in this imaginary load order, calling GetModRecords, passing 08 as the mod index, should return an array, and let's call it arItems. arItems[Actors], arItems[Magic], etc. would be empty, but arItems[Items] would contain 5 records (numeric keys are used as opposed to labels, this is just for illustration). These 5 records should be the FormID's of the five books. In this way, one could search a mod for records, and make use of them in-game using placeatme or additem.
  • SetIsPersistent - allows persistence to be toggled via script.*
  • [optional reference].AutocalSpellMagickaCost spellID - autocalculates spell cost including area factor, duration factor, and range factor based on the formula in FMagicCasterSkillCostMult. If optional reference is included, also calculates in the skill factor for that actor (including luck).
  • LoadObject - Forcibly cache/load an object, or LoadCellBuffer which would load/cache an entire cell, sort of opposite to PurgeCellBuffers
  • Get/SetCellFogNear & Get/SetCellFogFar - Get and set interior cell fog distance.
  • GetStartingCell CellID - Returns true if editor cellID is the same a the parameter specified.
  • GetGroundPos - Returns the groundlevel co-ordinate of the current cell.
  • Add/RemoveMajorSkill - Adds or removes major skill on calling actor.
  • Add/RemoveClassSkill - Adds or removes class skill for indicated class (If above request is prohibitive)
  • GetCollidingRefs - returns an array of the references colliding with the calling reference. <OR> GetFirst/NextCollidingRef - returns one at a time.
  • TrainSkill- similar to advskill, only trains the skill as if you are training it in-game.
  • IsRemoved- to check if a persistent reference is removed from the game - for instance put in chest scripted with RemoveAllItems, dropped in an oblivion world which got purged or put in the inventory of a dead actor which got deleted. IsFormValid returns true for a persistent reference in all these cases, and there seems to be no way to know if such a reference is still around.
  • ForceFunctionValue- Forces a function to always return a value with the number specified. For instance
ForceFunctionValue GetIsPlayableRace 0

would force the function GetIsPlayableRace to return 0, no matter what the calling reference is. Adding an optional reference parameter would set the function to return a specific value whenever the function is called on that reference. So,

ForceFunctionValue GetIsPlayableRace 0 player

would force GetIsPlayableRace to return 0 every time it is called on the player, but normal values any time it's called on someone else. For debug, limitation, and certain Gameplay Effect purposes.

  • ReleaseFunctionOverride- Releases the effect of ForceFunctionValue and allows the function to continue acting normally.
  • getReference - Returns a string containing the reference given to the calling reference in the editor. This string can be used like
set stringVar to anyRef.getReference
set stringVar.anyVariable to x

Questionable Requests[edit | edit source]

"Questionable" is not meant to be demeaning. These requests may be unclear, or it may be possible to implement them using existing functions, thus they receive lower priority. If you disagree with a function's classification here, discuss it on the TALK page:

Requests that can be implemented with current functions[edit | edit source]

  • getStandingActor - use onTrigger.
  • isBowDrawn - use IsKeyPressed2 in conjunction with getControl to find out when the attack button is pressed and how long it is held down.
  • cellChanged - use getParentCell.
  • getActorID - use getActionRef.
  • PCActivateActorInventory - This can be done using DuplicateAllItems to copy the actor's inventory to a container, then calling Container.Activate player. OBSE's inventory functions provide other ways of doing this as well.
  • "Function scripts" - use an OnActivate block in a persistent reference's script, and call Activate to run the code inside it.
  • DropAllItems - Similar to RemoveAllItems, but causes all items in inventory to appear at the actor's feet as in Drop.

This can be done using existing OBSE functions: [[1]]

  • SetScript [ScriptID] [ObjectID] - Replaces the attached script of the give object and returns the previous script if applicable.

This can be done by cloning an object with the desired script, and using various functions (i.e., CopyName, SetWeight) to make the clone look like the desired item. Any other use of this particular function might be unstable, as other mods will expect the original script to be on the original object.
This function is included in OBSEv12, however, it should be considered a beta function and not released in public mods, as the effects of replacing a script have not been tested yet (and doesn't follow, for the most part, good modding etiquette)

  • Activate the Magnitude option for script effect spells, then send it to a float variable (fMagnitude) in the related script. (Would allow the script to behave differently based on the magnitude of the spell).

The magnitude won't show up in game, but it will be the number you set it to (with SetNthEffectItemMagnitude, and you can use GetNthEffectItemMagnitude to return that number. By the way, it will be an integar, as with any other spell effect.

  • RemoveAllItems2 - Like RemoveAllItems, but removes quest items too.

This can be done by scanning through the player's inventory, listing all quest items in a separate inventory, changing the quest status to non-quest items, using RemoveAllItems, and then going through the quest item list to return their quest item status.

  • GetCrosshairDistance - How far away is the item or surface under the crosshair?

This can already be done with GetDistance using the reference returned by GetCrosshairRef and player.

The above only works if the object is within the activate distance. You can, however, change that distance with the GMST setting functions: [[iActivatePickLength].
  • GetEquipmentSlot - Extend this function to detect more inventory slot groups. currently, lower body with foot combination is not documented as available.

This can be done with GetEquipmentSlotMask

  • EnableMessage/DisableMessage - While disabling messages, the messages (on top-left corner) sent meanwhile won't be queued and never be shown. EnableMessage can reset this flag.

Spam-blocking versions of functions like AddItem and RemoveSpell will be available in OBSE v0015. Completely blocking UI messages is possible, but would cause conflicts with other mods which need to display messages and therefore is unlikely to be implemented.

    • GetClothingGoldValue - Returns the actual value of worn equipment in gold, where armor and weapons count as 0 gold.
    • GetEquipmentGoldValue - Returns the actual value of worn equipment in gold.
    • GetBackpackGoldValue - Returns the actual value of all items on an actor in gold.
Although it would be nice to have OBSE do the work for you, all three of these can be done using a loop and GetInventoryObject or GetEquippedObject. v0017 will include commands which return equipped items or all inventory items as an array variable which will allow these calculations to be done much more quickly in scripts than currently possible.
  • Drop2 - Same as basic drop, but returns a reference that actually works, instead of a null one. Use GetPCLastDroppedItemRef
  • Min|Max Var1 var2 . . . Var n - The usual: returns the smaller|larger value from the list (just a convenience to do [If A > B] [Set A to B] [Endif] in a single line: [Set A to Min A B] )
Put the values in an array, sort the array, extract the first or last element.

Unclear requests[edit | edit source]

  • spread - Explain what this function is supposed to do...
  • evaluateEquippedItems - Use a dummy AI package to force the actor to evaluate his equipped items.
  • All 4 functions below have the same issue - The requester seems to want references rather than the object record. It is currently unclear whether items with different stats are actually stored separately in the inventory, and as of now, there are no ways to specify any one of these items or grab the reference of an item in a container.
    • RemoveItem2 [ObjectID] (TargetContainer) - Removes the items of the same type to the target container and keep the item statuses (like stolen, health, charge, and poison).
    • DuplicateItem [ObjectID] [TargetContainer] - Copies the items of given type in the calling container to the target with the same quantity. It keeps the same ObjectID for scripted items. I'm not sure if it's possible to give the count in the parameter list. It seems there's no way to distinguish among the item with the same type even if they have different item statuses. Hope I'm wrong.
    • Drop2 [Reference] - Drops the given reference from the calling container. DropMe only works for ObjectID and is not suitable for a reference. Unlike DropMe, you have to first add the item to drop. You don't need (and probably cannot) add the reference to a container.
    • AddItem2 [Reference] - Adds the given item reference to the calling container. The reference is still valid while it's in the container, and it can keep its item statuses even after being dropped on the ground. I guess it might be impossible to do these due to the item maintenance mechanism used by the engine. But I wish we could.