OBSE Wishes Fulfilled

Wishes Fulfilled

The following functions had been requested and have now been implemented in OBSE. Please consult the OBSE documentation to avoid requesting a feature which is already available. Some of the newer functions are not yet documented on the wiki.

Other

• Not so much an actual OBSE function, but a way to use the OBSE with the Oblivion Launcher, instead of having to create two shortcuts.
  • Use OCOL
  • Use OBMM - if obse_loader.exe is found in the Oblivion folder, the Launch Oblivion button in OBMM will use it instead of Oblivion.exe
  • Use Wrye Bash launch buttons.
    • Check green box to activate OBSE.
    • Click either Oblivion or TESCS launch buttons. If the OBSE box is checked, they'll launch with OBSE running.

Plug-ins

OBSE now offers the ability to use plug-ins to add even more functions.

Tibixe's String Function Collection

• GetObject/RefFullName - Use StrGetName

Pluggy

• Arrays

Universal Silent Voice

• Non-Spoken Dialog Teaks:

Automatically uses an 8-second silent .mp3 for voiceless actors, and will display the subtitles even if they have been turned off.

OBSE v0008

• GetArmorType [slot] - the weight of the armor in the slot alone would be a very useful function (one we had in Tribunal), but of course, actually getting the armor there would be even better - DONE!
• Math functions - low priority, because there are ways around this. Still, can be annoying to use workarounds in some situations - DONE!
• Message to Console - it would be so useful for debugging, using messages is annoying and sqv doesn't display all of the information - DONE!
• Console only commands - Allow scripters to use console only commands in the editor. - DONE!
• MoveMouse, a command for simulating mouse-movements. Useful for cinematics and combat moves. - DONE! (and done and done and done)
• GetObjectValue [value] - ability to determine the stats of objects, such as finding out how damaged an armor is or the soul value in a soul gem. - DONE!
• GetIsMajor [skill] - returns 1 if specified skill is a major skill of the calling actor - DONE! (undocumented as of yet)
• Simple, binary operations - Dejaside recommends adding simple, binary operations for determining exactly what the script is running on (IsWeapon, IsContainer, etc etc). - Partially Done! See discussion.
• GetSpell [Spell ID] - Returns 1 if actor has declared spell in their spell book. I know this will not be possible till the spell list is found, but it would be quite useful to have. - DONE! (undocumented as of yet)
• Increased (or removed) script size limit - Partially Done! - The 32k text limit has been removed from the editor. The number of opcodes permitted in a script has not increased.
• GetKeyPress - returns the scancode of currently pressed key. - DONE!

OBSE v0009

• set/modObjectValue - Individual functions for each.
• set/modCurrentValue - Individual functions for each.
• GetActorLightAmount - Returns the level of light shining on an actor.
• SetRefEssential - SetEssential works on base objects. This works on references.
• GetGameLoaded - Returns true when a saved game is loaded.
• Basic looping structures - GoTo and Label allow for looping within a script.
• removeMagicEffect/setMagicEffect - Several functions for manipulating spell effects are now available.
• SetName - sets the base object name on a passed base object or calling reference.
• Looping Functions - DONE!

OBSE v0010

• con_SaveGame
• CopyModelPath, CopyIconPath - Copies the model or icon path from one object to another.
• TCL - disables collision either globally or on a specific reference.
• Bitwise logic functions: AND, OR, NOT, XOR.
• get/setPointOfView - Sets or gets the current point of view (first or third person) and allows the scripter to adjust the position and angle of the third person camera. (IsThirdPerson returns the current perspective, which can be changed by forcing a keypress with TapKey).
• getCreatureType - Returns the type of a creature - Humanoid, Daedra, Undead, etc.
• SendKeyToDialog - simulates pressing keys for the dialog e.g. ESC or any other key. (The new menu input functions allow for this).
• GetSpellMagicSchool spellID - finds what magic school a spell belongs in by finding the highest costing effect in the spell and finding what school that effect belongs to.
• IsScripted - a simple boolean function that returns true if the object has a script attached to it.
• getIsInName/getIsInID string - like GetInCell, allows a partial comparison of names or objectIDs. So if there are two NPCs named "OscarWilde" and "OscarTheGrouch", getIsInName "Oscar" would return true for both.
  • Use CompareName

OBSE v0011

• ModName - Works like ModModelPath but on items' names. It would be great to make some naming rules in scripts.
  • Also, use ModName to add a prefix and AppendToName to add a suffix.
• modPCSkillProgress skill amount - modifies the player's progress toward advancing the given skill.

OBSE v0012

• SetUnplayable/GetUnplayable [ObjectID] - Sets or gets the unplayable attribute of apparel.
  • The function is called Get/SetIsPlayable
• SetNthEffectItemScriptName - Sets the nth effect's name.
• GetMerchantContainer - Returns a reference to the calling actor's merchant container.
• GetScript [ObjectID] - Returns the script of the given object.
• GetName - Returns full name of object or reference

OBSE v0013

• con_LoadGame
• IsUnderWater - Returns true if calling object is underwater
• AddToLeveledList/RemoveFromLeveledList - Adds or removes items to/from a leveled item, spell, or creature list
• GetParentCellWaterHeight - Returns height of water in the calling object's cell, if any
• Moon phase functions
• CopyFace/CopyHair
• Get/SetTravelHorse
• Version of PlaceAtMe that accepts a leveled item - pass an object returned from CalcLeveledItem to PlaceAtMe
• CompareNames ObjectID1 ObjectID2 - Compares the first name to the second name. Returns 0 if they're the same, 1 if the first is later in the alphabet, -1 if the second is later in the alphabet.
• GetRunningScriptEffectXXX - returns information about the active effect of the scripted spell including Caster, magnitude, duration, time elapsed and magic item
• GetTotalActiveEffectMagnitude - returns the total magnitude of all active effects on a target for a given magic effect. Includes variations which filter based on spell type
• Get/SetOpenKey - returns or sets the key needed to open a lockable reference
• GetOwner - Returns the owner of the calling reference.
• CellScan - Use GetFirstRef/GetNextRef to iterate through all references (or just those of a given type) within the current cell.

OBSE v0014

• %N in messageBox - the %N character would compile as a new line. Fulfilled by new output functions, using %r instead of %n.
• Message & MessageBox - Could take references as parameters and show the names of the references at the corresponding %f in the format string. It would be great for modders to provide more information to players. Fulfilled by new output functions using %n.
• MagicItemHasScriptedEffectScript - Returns whether the magic item has a scripted effect with the specified script. (Also helpful for sorting scripts --Haama 17:15, 13 November 2007 (EST))
• isOffLimits actorID - returns true if it would be illegal for the actor to activate the calling object.
• getHUDTarget - Returns a reference to the object currently targeted by the HUD reticle. GetCrosshairRef
• Has/SetLowLevelProcessing - Returns true if the "No Low Level Processing" flag is unchecked for the actor. Possibly sets the flag.
• CanFly, isBiped, canSwim, usesWeapon - For creatures, these boolean functions would report on the check boxes used in the Creature properties window. Useful for discriminating between flying creatures, swimming creatures, weapon-wielders, etc.
• GetSoulLevel - Returns the calling actor's soul level. For NPCs, it always returns Grand Level.
• IsPersistent - returns true if the reference is persistent; possibly allows persistence to be toggled via script.
• SetRespawns/GetRespawns [ObjectID] - Sets or gets the respawns attribute of containers. Also implemented for actors.
• getHorse - Returns a reference to the horse currently ridden by the calling actor.
• GetPlayerLastRiddenHorse it does essentially the same thing as GetHorse but has more uses and may be easier to do since there's already an IsPlayersLastRiddenHorse function.
• GetCreatureSoundBase - Most creatures inherit their sounds from other creatures - i.e. all goblins inherit from CreatureGoblin01. This would be useful for figuring out which sounds a creature should use via script. It would also be an indirect but generally reliable way of determining the basic type of creature (goblin, zombie, horse, etc).
• SetCurrentSoulLevel - Sets the soul level of the calling reference (counterpart to the existing function GetCurrentSoulLevel).

OBSE v0015

• addItem/removeItem/equipItem/addSpell/etc without the sound effects and message spam. EquipItemNS, UnequipItemNS, AddItemNS, RemoveItemNS, AddSpellNS, RemoveSpellNS, SetStageNS
• ToggleCreatureModel - Toggles a .nif object within a creature's model list on or off.
• isPluginRunning - if the plugin is active, returns its load order. Use GetModIndex
• IsValidReference - returns true if the supplied reference is valid. This would return false, for instance, if a reference to an item is put into an inventory, or if the reference is non-persistent and not in the loaded cell. Avoids issues with calling functions on such references crashing the game. Use IsFormValid
• PlayCreatureSound [soundGroup] - an alternative to the above. Plays the sound associated with the specified group for the calling object (creature). Creatures have sounds like "Idle", "Hit", "Attack", etc. Pass the return value of GetCreatureSound to PlaySound or PlaySound3D
• RemoveFromDetectionList - Oblivion stores a list of actors who currently detect the player. However, unconscious/paralyzed/knocked-down actors are not properly removed from the list if they detect the player at the moment their AI is turned off, and will continue to detect him regardless of how well-hidden he is. This function forcibly removes them from the detection list.
• GetHotkey [N] and SetHotkey [N] [ref] - get and set the object or spell for hotkey slot N (0-7). This would primarily be of use to write hotkey extenders in a very natural way (the player can assign/re-assign hotkeys in the usualy fashion, the refs of which can then be copied away into script space).
• IsFalling - Returns true if the calling actor is currently falling. Use GetFallTimer; if > 0, actor is falling.
• IsMoving - Returns true if the actor is moving across space (e.g. Player coordinates are changing. For example, flying, jumping, swimming, falling, being pushed or carried, etc).
• myRef.GetScriptVariable VarName, [value] - access the variable on the script that is associated with the myRef object instance. Even if VarName were replaced by VarNumber in the script, this would be very useful.
• onJump - returns true when the actor jumps. Use IsJumping.
• getCurrentAnimGroup - Returns the general AnimGroup of the current animation, e.g. Idle or Attack. Use IsAnimGroupPlaying
• GetTotalGoldValue - Similar to GetGoldValue but will return total value of an object, rather than only the base value. GetFullGoldValue
• IsSpellHostile Spell:ref - returns true if the spell will be considered an attack - not the same as checking the hostility of every effect. In most cases a spell is hostile if any of its effects are hostile, but if a non-hostile spell has a hostile effect added (or a hostile spell has its hostile effects removed), the "hostility" status does not update.
• ForceSpellHostilityUpdate Spell:ref - fixes the above problem. SetSpellHostile
• GetProcessState - Returns the current level of processing for the actor based on its distance from the player. The console functions like ToggleHighProcess and ToggleLowProcess might provide a starting point. GetProcessLevel
• getSoundPlaying - returns true if the specified sound is playing on the calling reference, including things like weapon swishes, shield block sounds, etc.
• GetSelection - Returns the index of the selected item in the current menu. GetActiveMenuSelection

OBSE v0016

• CompareName2 - Returns true only if the reference's name is exactly the given name. (case insensitive) Use sv_Compare
• String variables. New string_var variable type
• GetBookText/SetBookText [ObjectID] - Sets or gets the "Book Text" field of book/scroll objects. GetActiveMenuText/UpdateActiveMenuText
• ShowNameSetting [ObjectID] - Show a menu to make the player type the name for the given ObjectID. It might use the spell-making or enchanting menu as the interface. ShowLineInputBox or ShowTextInputHandler coupled with SetNameEx
• Get/SetCastEfficiency - Get and set the calling actor's casting efficiency as modified by armor. Get/ModPCSpellEffectiveness. Similar functionality will not be implemented for NPCs and creatures because the game does not support spell effectiveness for those actor types (but support could be added via an OBSE plugin).
• Get/SetHideAmulet - Returns or sets the hide amulet attribute of the calling reference.
• Get/SetHideRings - Returns or sets the hide rings attribute of the calling reference.

OBSE v0017

• Array variables
• 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)
• Any function expecting a string argument will accept a string variable in its place.
• ModNthEffectItemScriptName - Modifies the nth effect's name. (It is possible to set the name with SetNthEffectItemScriptName, but not to mod it). Modify the string returned by GetNthEffectItemScriptName and pass the modified string to SetNthEffectItemScriptName
• AppendToNthEffectItemScriptName - Works like AppendToName but for scripted effects. as above
• Combat Style functions - functions to get and set the parameters of a Combat Style

OBSE 0018

Some of the requested functionality is already present in the current stable release.

• setPackageTarget - like addScriptPackage, except it takes a reference as a parameter which then serves as the target of the package.
• 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>.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.

Can be implemented as an user function. Use ConScribe for text logs.

• messageNoDelay - causes the to be displayed immediately, even if another message is currently being displayed.

Use printToConsole instead.

• 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.

• GetDisease - Return if the calling actor gets diseased.

Can be ascertained by using Active Effect functions.

• 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)
• CastByPlayer/Cast2 - 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.

Use getProjectile.

• 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.

Use getFormFromMod to pick an object that stores version info.

• 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.

Use While .. Loop control structures instead.

• GetMouseX/GetMouseY - Returns current mouse position.

Use getCursorPos.

• 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.

Can be ascertained by using Magic Item functions.

• 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.

Use getMagicEffectName.

• Console functions

Use runScriptLine.

• PlayMusic - StreamMusic is horribly buggy. A cleaner version which overrides combat music would be ideal.

StopMusic - stops a mp3 file played with the above or with StreamMusic.

GetMusicPlaying - returns the filename of the currently playing track?

Use the Enhanced Music and Control/SoundCommands OBSE plugin.

• 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.

Use playSound with getMagicEffectHitSound.

• getCaster - in a scripted spell, returns a reference to the object or actor which cast the spell.

Use getNthActiveEffectCaster.

• getCurrentAnim - Returns the currently playing animation.

Use animPathIncludes.

• 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.

Use toggleSpecialAnims.

• setCameraDistance - In third person view, adjusts the camera's distance from the player.

Use setNumericGameSetting to modify the appropriate GMST.

• fadeIn/fadeOut duration - Fades the screen to or from black over the given duration.

Use the Oblivion Graphics Extender OBSE plugin.

• closeMenu - Closes all open menus.

Use closeAllMenus.

• TriggerShader: Adds a shader to the PC camera, the shader could be defined in an INI or via another function (see talk: Custom Shaders).

Use the Oblivion Graphics Extender OBSE plugin.

• PlayAnimationSourceFile: Plays animations directly from a source file on the specified actor.

Set up idles and use pickIdle.

• GetFirstRefInContainer - Like GetFirstRef, but returns a reference to first item in a container.

Use getInventoryObject.

• 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.

Use getFirstRef/getNextRef with getDistance.

• getTelekinesisRef - Returns reference of the object player is currently targeting with telekinesis.
• GetTeleportMarker - Return teleport marker associated with the door that called the function

Use getTeleportCell instead.

• 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).

Use isAnimGroupPlaying.

• 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.

Use the isSummon user function.

• GetActorMagicEffectMagnitude [Effect] - Returns the total magnitude of a particular magic effect from all spells/abilities/etc affecting an actor.

Use getTotalActiveEffectMagnitude.

• 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...

Use getMenuStringValue.

• Get/Set/ModWaterHeight - change the height of water in an Interior cell

Use setCellWaterHeight.

• IsPCUnderArrest - return a boolean indicating whether the player is chased by any guard.

Use getFollowers.

• GetGameDifficulty - Returns current game difficulty.
• GetPoison - Returns the poison applied to the calling weapon reference.

Use getEquippedWeaponPoison.

• 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)
• EquipItem2 - equips an item and causes the OnEquip block to run if applicable.
• EquipMe - Makes the actor holding the calling reference equip it and runs the item's OnEquip block.
• RunScript- Forces a run of the specified script, even if the begin/end block is not Gamemode. Makes quest stage reactions faster and allows variables to be defined in a stage result script.

Use Call to execute a function script

• 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.

Use a string variable and ToUpper or ToLower; this is a more general solution that needn't be used only with MessageBoxEx.

OBSE 0019 (forthcoming)

• [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

Use SetEventHandler to register a function script as a callback to be invoked when an event associated with a block type occurs.

• DuplicateAllItems2 - Same as DuplicateAllItems, but doesn't create a new ID/cloneformed item for each scripted item that's duplicated

Use CopyIR to copy the item(s) to the target container

• getEquipmentSlot - Many clothes occupy foot + lower body. according to the wiki, there is no return value for this configuration.

New slot IDs added

• OnActorHits (Id Optional) - This block will be run once when the scripted actor hits the specified Object or actor.

Use SetEventHandler "OnHit" SomeScript where SomeScript is a function script; the attacker and/or target can optionally be specified.

• getLastAttacked - Returns a reference to the actor last attacked by the calling actor.

SetEventHandler again.

• (reference).GetLastKilled - Returns the reference of the last actor killed by the player/an actor.

SetEventHandler yet again.

• 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)

Use GetBoundingBox