===========================
OBSE Elys Pluggy v124

Pluggy v1-122 Elys
Pluggy v123 Leandro
Pluggy v124 haama
===========================

1. Description
2. Requirements
3. Installing
4. Using Pluggy
5. Uninstalling
6. Backup
7. Pluggy Commands List
8. Contact and Information
9. Disclaimer
10. Open Source
11. Credit

===========================
1. DESCRIPTION
===========================

Pluggy is a multifunction OBSE plugin that adds new functions to Oblivion, and is a further extension to Oblivion Script Extender. The functions allow modders to create and manipulate arrays, strings, .ini files, text files, both text and surface/image HUDs, and change object names.

It uses OBSE to add the functions to the game, and like OBSE it doesn't make any modifications to oblivion.exe, TESConstructionSet.exe, or any other files in your oblivion install, so don't worry about permanent side effects.

===========================
2. REQUIREMENTS
===========================

Oblivion Version 1.2.0416
Oblivion Script Extender Version 15.3 or above.
( http://obse.silverlock.org/ )

===========================
3. INSTALLING
===========================

Extract "OBSE_Elys_Pluggy.dlx" and "OBSE_Elys_Pluggy.dll" to "Oblivion Install Directory\Data\OBSE\Plugins". If you don't have an "..\OBSE\Plugins" directory, create one.

===========================
4. USING PLUGGY
===========================

As a player, installing will probably be your last step.

If you have a Pluggy mod that uses HUD functionality, see the warning below. If you decide to enable the HUD functionality, change the Pluggy dll file name from "OBSE_Elys_Pluggy.dll" to "OBSE_Elys_Pluggy_HUD.dll". (Only change the .dll file name, leave the .dlx name the way it is!)

If you use a save game manager, or manually move around your save files, be aware that there are 2 extra files to move. These co-save files keep the data that correspond to your save game. One contains the Pluggy data (---.pluggy) and the other the OBSE data (---.OBSE). Make sure to keep these files when you move the .ess save file, or delete them if you delete the .ess file. As far as Savegame Managers are concerned, I know Wrye Bash is aware of both .OBSE and .pluggy and will correctly move them around, but I don't know about any other Savegame managers.

=============
Known Issues
=============

HUD crashes - The HUD functionality has been found to cause crashes when entering buildings. Which users are affected by the crash seems to be hit and miss, but seems to solely affect nVidia users. Note that just because nVidia users are the only ones with the crash, that doesn't mean it affects all nVidia users (my 8800 GTS has yet to crash with the HUD functionality).

Bad mouse buttons - If you have a mouse that double-clicks instead of single-clicks (like mine), then use the Keyboard to select and load a save game. If the mouse double-clicks, the Pluggy data may be skipped.

=============
Modder Info
=============

Modders: The documentation inside the Pluggy Docs folder is far from being up to date.
You'll find HUD function information and some more up to date information at the CS wiki: "http://cs.elderscrolls.com/constwiki/index.php/Category:Pluggy".

Like OBSE, you'll want to make sure the player has a good version Pluggy installed. You can check it with
if ((GetPluginVersion "OBSE_Elys_Pluggy") >= 124) ;or any other version number
;then initialize your mod
If you need HUD functionality, make sure the player has enabled it with
if IsHUDEnabled

Note that even though the player has to change the name of the .dll, Pluggy will always be refered to as "OBSE_Elys_Pluggy" with GetPluginVersion and IsPluginInstalled (and any other OBSE Plugin function)

Also note that the Pluggy data will only be available if the Pluggy co-save is still around. If the player deletes it, or mixes up Pluggy co-saves, the data won't be available. You can check this by using IsPluggyDataReset. Best suggestion is to use it in a quest script that always runs
begin GameMode
if GetGameLoaded
if IsPluggyDataReset
;warn the player, prevent them from proceeding, re-initialize the data, etc.

===========================
5. UNINSTALLING
===========================

Delete "OBSE_Elys_Pluggy.dlx" and "OBSE_Elys_Pluggy(_HUD).dll". Delete your Pluggy co-saves in the Oblivion save directory "...\My Documents\My Games\Oblivion\Saves\".

===========================
6. BACKUP
===========================

As a surviving gold rule, always backup all your save games before trying a new mod. Better safe than sorry. It applies to this mod as well.


===========================
5. PLUGGY COMMANDS LIST
===========================

Name HelpText Opcode(h) Opcode
----------------------------------------------------------------------------------------------------
GetEsp Get EspID. 2330h 9008
CreateArray Create a new array. 2331h 9009
DestroyArray Destroy array. 2332h 9010
ArraySize Set the Array size. 2333h 9011
ArrayCount Get the Array count. 2334h 9012
SetInArray Store value in Array. 2335h 9013
SetFloatInArray Store float in Array. 2336h 9014
GetInArray Retrieve value from array. 2337h 9015
GetTypeInArray Retrieve type from array. 2338h 9016
RemInArray Remove value from array. 2339h 9017
FindInArray Find occurence in array. 233Ah 9018
FindFloatInArray Find float occurence in array. 233Bh 9019
SetRefInArray Store reference ID in Array. 233Ch 9020
FindRefInArray Find reference occurence in array. 233Dh 9021
CopyArray Duplicate an array. 233Eh 9022
DupArray Duplicate an array. 233Eh 9022
ArrayEsp Set the EspID 233Fh 9023
ArrayProtect Set the Array Protected Flag 2340h 9024
FirstInArray Get the first empty or used Index in the array. 2341h 9025
FirstFreeInArray Get the first empty or used Index in the array. 2341h 9025
DestroyAllArrays Destroy all Esp's array. 2342h 9026
PackArray Pack array. 2343h 9027
CreateString Create a new string. 2344h 9028
DestroyString Destroy string. 2345h 9029
SetString Set string. 2346h 9030
StringEsp Set the EspID 2347h 9031
StringProtect Set the String Protected Flag 2348h 9032
StringLen Get the String Length. 2349h 9033
DestroyAllStrings Destroy all Esp's String. 234Ah 9034
StringSetName Set the name. 234Bh 9035
StringGetName Get the name. 234Ch 9036
StringMsg Display the string as Message. 234Dh 9037
StringCat Concatenates strings. 234Eh 9038
UserFileExists Does a Pluggy text file exist? 234Fh 9039
TxtFileExists Does a Pluggy text file exist? 234Fh 9039
RenFile Renames a Pluggy user file. 2378h 9080
RenTxtFile Renames a Pluggy user file. 2378h 9080
DelFile Delete a Pluggy user file 2379h 9081
DelTxtFile Delete a Pluggy user file 2379h 9081
StringToTxtFile Write a string in a text file 237Ah 9082
CopyString Copy a String. 237Bh 9083
IntToString Convert an integer into a string. 237Ch 9084
FloatToString Convert a float into a string. 237Dh 9085
RefToString Convert a reference into a string. 237Eh 9086
IniReadInt Read integer from ini file. 237Fh 9087
IniReadFloat Read float from ini file. 2380h 9088
IniReadRef Read a reference from ini file. 2381h 9089
IniWriteInt Write integer to ini file. 2382h 9090
IniWriteFloat Write float to ini file. 2383h 9091
IniWriteRef Read a reference from ini file. 2384h 9092
IniKeyExists Checks if a key exists in ini file. 2385h 9093
IniDelKey Deletes a key in ini file. 2386h 9094
EspToString Convert an esp filename into a string. 2387h 9095
IniReadString Reads a string from ini file. 2388h 9096
IniWriteString Writes a string from ini file. 2389h 9097
ModRefEsp Returns a reindexed reference 238Ah 9098
GetRefEsp return the reference's EspID. 238Bh 9099
StringToRef Converts a string into ref. 238Ch 9100
StringCmp Compares two strings and return the position of the first difference 238Dh 9101
FileToString Copy a file into a string 238Eh 9102
StringPos Returns the position of a substring in a string 238Fh 9103
StringToInt Converts a string into an integer. 2390h 9104
StringToFloat Converts a string into a float. 2391h 9105
ArrayCmp Compares two arrays 2392h 9106
StringMsgBox Display the string in a Message Box. 2393h 9107
StringIns Inserts a substring into a string 2394h 9108
StringRep Replace a substring in a string 2395h 9109
IntToHex Convert an integer into a hex string. 2396h 9110
LC Long based calculation 2397h 9111
FromTSFC Copy a TSFC String. 23B0h 9136
ToTSFC Copy a string to a TSFC String. 23B1h 9137
StrLC Long based calculation. 23B2h 9138
CreateEspBook Create a book in a new plugin. 23B3h 9139
FmtString Set a string using OBSE formating. 23B4h 9140
FixName Fix the name. 23B5h 9141
ResetName Reset the name. 23B6h 9142
HasFixedName Has a fixed name? 23B7h 9143
csc Converts a ScanCode. 23B8h 9144
StringSetNameEx Set the name. 23B9h 9145
StringGetNameEx Get the name. 23BAh 9146
FixNameEx Fix the name. 23BBh 9147
IniGetNthSection Get a section name from ini file. 23BCh 9148
IniSectionsCount Return the sections count. 23BDh 9149
RunBatString Run a string as batch. 23BEh 9150
Halt Halt Oblivion immediatly! 23BFh 9151
RefToLong Convert Long to Ref. 23C0h 9152
LongToRef Convert Ref to Long. 23C1h 9153
FindFirstFile Find first file. 23C2h 9154
FindNextFile Find next file. 23C3h 9155
GetFileSize Return the file size 23C4h 9156
NewHudS Create a new Hud Surface. 23C5h 9157
DelHudS Destroy a HudS. 23C6h 9158
ScreenInfo Return info about the screen. 23C7h 9159
HudS_X HudS X 23C8h 9160
HudS_SclX HudS Scale X. 23C9h 9161
HudS_Show HudS Show State. 23CAh 9162
HudS_Opac HudS Opacity. 23CBh 9163
Huds_Opacity HudS Opacity. 23CBh 9163
HudS_Align HudS_Alignment. 23CCh 9164
AutoSclHudS HudS AutoScale State. 23CDh 9165
HudS_Y HudS Y 23CEh 9166
HudSEsp Set the EspID 23CFh 9167
HudSProtect Set the HudS Protected Flag 23D0h 9168
HudsInfo Return info about the HudS. 23D1h 9169
DelAllHudSs Destroy all Esp's HudS. 23D2h 9170
HudS_L HudS L 23D3h 9171
rcsc Converts a char to scancode. 23D4h 9172
HudS_SclY HudS Scale Y. 23D5h 9173
NewHudT Create a new Text Hud. 23D6h 9174
DelHudT Destroy a HudT. 23D7h 9175
HudT_X HudT X 23D8h 9176
HudT_SclX HudT Scale X. 23D9h 9177
HudT_Show HudT Show State. 23DAh 9178
HudT_Opac HudT Opacity. 23DBh 9179
HudT_Opacity HudT Opacity. 23DBh 9179
HudT_Align HudT_Alignment. 23DCh 9180
AutoSclHudT HudT AutoScale State. 23DDh 9181
HudT_Y HudT Y 23DEh 9182
HudTEsp Set the EspID 23DFh 9183
HudTProtect Set the HudT Protected Flag 23E0h 9184
HudTInfo Return info about the HudT. 23E1h 9185
DelAllHudTs Destroy all Esp's HudT. 23E2h 9186
HudT_L HudT L 23E3h 9187
HudT_SclY HudT Scale Y. 23E4h 9188
PauseBox Display the string in a Pause Box. 23E5h 9189
KillMenu Kill the menu 23E6h 9190
SetHudT Set a HudT text 23E7h 9191
HudT_Text HudT Text. 23E8h 9192
HudS_Tex HudS Texture. 23E9h 9193
SanString Sanitize String. 23EAh 9194
IsHUDEnabled Returns if HUD functions are available. 23EBh 9195
IsPluggyDataReset Returns if Pluggy data has been reset or not loaded. 23ECh 9196
PlgySpcl Pluggy Special Reserved Command. Do not use! 23FFh 9215

----------------------------------------------------------------------------------------------------

===========================
8. CONTACT AND INFORMATION
===========================

Contact "haama" at the BethSoft forums "http://www.bethsoft.com/bgsforums/"
"Pluggy" Discussion thread at "http://www.bethsoft.com/bgsforums/index.php?showtopic=978991"

===========================
9. DISCLAIMER
===========================

This software is provided 'as-is', without any express or implied
warranty. In no event shall the authors be held liable for any damages
arising from the use of this software.

===========================
10. OPEN SOURCE
===========================
This software is open source and the source code should be available at the download site.
Copy, derive, etc. at will. Please, though, no Unofficial releases - if you have a some code in mind or a file ready to go, please bring it up in the discussion thread or TESNexus or PM me.

===========================
11. CREDIT
===========================
Elys for the original Pluggy versions
Leandro for Delphi and Pluggy help
Scruggsy and Dragoonwraith for explaining the OBSE side of things
Everyone who tested out the various fixes, attempts, and crashes going from v122-124
The OBSE crew (I probably wouldn't be able to make heads or tails of anything without their groundwork)