PLUGGY STRING-COMMANDS

 

The text and INI file functions wait only for the FileName (including the extension).
All the Pluggy created text files are stored in « My Documents\My Games\Oblivion\Pluggy\User Files\ ».
Any full path included in the filename will be ignored.
However you can use relative subfolders in the file name in parameter such as "MyCustomFolder\MyFile.txt", which will result of a file in « My Documents\My Games\Oblivion\Pluggy\User Files\MyCustomFolder\MyFile.txt »
All read file function type accepts an optional RootID parameter, which defines the base path for filename:
            0: « My Documents\My Games\Oblivion\Pluggy\User Files\ ».
            1: Oblivion Data folder.
            2: Oblivion main folder.

String functions accept StringToken as a StringID. But you cannot use a StringToken as a StringID that is going to be modified by the function, to the exception of StringTokens between -2099 and -2000.

StringTokens are premade strings existing in Pluggy that can be used directly in string functions. A StringToken is always a negative value.
StringTokens between -2099 and -2000 can be modified with script functions. You have to use them within the same script frame since they can be modified any time by any script outside the script frame, and so are only reliable during the frame life.
Currently the following StringTokens are defined in Pluggy (more can be added on request to next Pluggy version if they make sens) :
            -1 : empty stringd
           
-2 down to -255 : Each Correspond respectively to the ASCII character code from 2 to 255 ( for example -32 is equivalent to a space ).
           
-256 :Null character (/0).
           
-257 :SOH (/1).
           
-1310 : EOL (End Of Line, you do not normally need to use it but it can be usefull is some particular cases).
           
-2000 down to -2099 : Temporary StringTokens who can be modified.
            -
9000 : Current date, format MM/DD/YYY.
           
-9001 : Current time, format HH:MM:SS
           
-9010 : Current millisecond, format ZZZ
            -9011 : Current second, format SS
            -9012 : Current minute, format MM
            -9013 : Current hour, format HH
            -9014 : Current day, format DD
            -9015 : Current month, format MM
            -9016 : Current year, format YYYY
           
-9017 :Current hour, format HH (am/pm.
           
-9018 : Current day phase : AM or PM
            -10000: abcdefghijklmnopqrstuvwxyz
            -10001: ABCDEFGHIJKLMNOPQRSTUVWXYZ
            -10002: 0123456789
            -10003: ().!?,; ':"
            -100000: Clutter\Books\folio03.nif

            -100001: Clutter\iconbook2.dds
            -100002:  [Done]
            -100003: Select a map marker:
            -100004: Cancel
            -100005:  [x]

            -100006: Map Markers Be Done.ini
            -100007: Tags
            -100008 .. -100017: Choice0 to Choice9
            -100018: Choose a tag:
            -100019: Settings
            -100020: DetectRange
            -100021: RevealHidden
           
-2000000000 : An ASCII bunny.

The theorical max global string count is 8388607.

 

CopyString
CopyString copies the Number of characters from the Source string starting at Position into the Target string. (Position of the first character in a string is 1)
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

            CopyString <(Target)StringID:long> <(Source)StringID:long> <Position:short=1> <Number:short=-1> <Global:short=0>


CreateEspBook (STILL IN DEV PHASE !!!)
CreateEspBook create new Filename plugin that contain a book named Name and with Text as description. The book is a quest item with weight 0 and value 0. When activated the plugin automatically adds the book once to the player inventory.
The book model is set to Model, or to “Clutter\Books\folio03.nif” by default.
The book icon is set to Icon or to “Clutter\iconbook2.dds” by default.
If Filename is already an existing file, the filename will be set to “PluggyCreatedBookXXXXXXXXXXXXXXXX” where “XXXXXXXXXXXXXXXX” is a random 64 bit hex number.

            CreateEspBook <(Filename)StringID:long> <(Name)StringID:long=-1> <(Text)StringID:long=-1> <(Model)StringID:long=-100000> <(Icon)StringID:long=-100001>


csc (STILL IN DEV PHASE !!!)
(not documented yet)

           (CodeASCII:short) csc <ScanCode:short> <CaseUP:short=0> <StringID:long=-1> <Append:short=1> <Global:short=0>


CreateString
CreateString creates a new string containing Text tagged with the EspID, and returns the StringID.
If EspID is not specified then the EspID is automatically associated to the calling esp
If Protected is not 0, then the string will be write-protected from other esp, and only the associated ESP will ever be able to modify the string. Setting Protected to 1 is recommended if you don’t want that your string can be modified by other esp.
If RefuseZero is not 0, then the returned ArrayID will never be zero.
If the ESP file is not active upon reloading a savegame, all the associated strings are destroyed.
Attention: It is strongly recommended to set Protected to 1 if you do not specifically need the string to be modified by another esp.

            (StringID:long) CreateString <EspID:short=-1> <Text:string=””> <Protected:Short=0> <RefuseZero:Short=0>


DelFile (alt: DelTxtFile)
DelFile attempts to delete a file and returns 1 if success, else 0

           (Success:short) DelFile <(Filename)StringID:long>


DestroyAllStrings
DestroyAllStrings destroys all the strings associated to the EspID.
If EspID is not specified then the EspID is automatically associated to the calling esp

            DestroyAllStrings <EspID:short=-1>


DestroyString
DestroyString destroys the string.
If Global = 0 then the function fails if you try to destroy a string not associated to the calling esp. Setting Global to 1 is required if you need to modify a string of another esp.

            DestroyString <StringID:long> <Global:short=0>


EspToString
EspToString converts an esp filename into a string
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.
If LowerCase = 0, the result will not be converted to lower cases.

           EspToString <StringID:long> <EspID:long=-1> <Global:short=0> <LowerCase:short=1>


FileToString
FileToString copy a file into a string.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           FileToString <(Filename)StringID:long> <StringID:long> <Global:short=0> <RootID:short=0>


FindFirstFile
(not documented yet).

           (Bool:short) FindFirstFile <(FileFound)StringID:long> <(FileMask)StringID:long=-42> <RootID:short=0> <Directories:short=0> <Global:short=0>


FindNextFile
(not documented yet).

           (Bool:short) FindNextFile <(FileFound)StringID:long> <Global:short=0>


FixName (STILL IN DEV PHASE !!!)
(not documented yet)

           FixName <Object:ref> <StringID:long=-1>


FixNameEx (STILL IN DEV PHASE !!!)
(not documented yet)

           <Object:ref>.FixNameEx <StringID:long=-1> <Object:ref>


FloatToString
FloatToString converts Value into a string, formatted with the number of Digits (from 0 to 7)
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           FloatToString <StringID:long> <Value:long> <Digits:short=7> <Global:short=0>


FmtString
FmtString sets the string to an OBSE formatted string..
If Global = 0 then the function fails if you try to change the EspID of a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           FmtString <StringID:long> <Global:short=0> <FormattedString:string> <Var1> <Var2> <Var21>

FromOBSE (STILL IN DEV PHASE !!!) (alt: FromOBSEString)
Imports an OBSE string to a Pluggy string.
Note that this is preferable to "SetString PluggyStringID $OBSEStringVar", as that method has a 256 character limit.
           FromOBSE <PluggyStringID:long> <OBSEString:long> <Global:long>


GetFileSize
GetFileSize returns the file size of Filename.
If the file cannot be found, it returns -1.
If the file size is bigger than 2GB, it returns -2.

           (Size:long) GetFileSize <(Filename)StringID:long> <RootID:short=0>


HasFixedName (STILL IN DEV PHASE !!!)
(not documented yet)

           (Bool:short) <Object:ref>.HasFixedName <Object:ref>


IniDelKey
IniDelKey deletes Key from Section in IniFile.
If Key is not specified then IniDelKey delete the whole Section in IniFile.

           (Success:short) IniDelKey <(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long=-1>


IniGetNthSection
IniGetNthSection sets Target as the Nth Section name in IniFile.
If no match is found in the file, Target is set to an empty string.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           IniGetNthSection <(Target)StringID:long> <(IniFile)StringID:long> <Nth:long> <RootID:short=0> <Global:short=0>


IniKeyExists
IniKeyExists returns 1 if Key exists in the Section of IniFile, else 0
If Key is not specified then IniKeyeExists returns 1 if Section exists in IniFile, else 0

           (Success:short) IniKeyExists <(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long=-1> <RootID:short=0>


IniReadFloat
IniReadFloat returns Result as an float matching the Key’s value from the Section of IniFile.
If no match is found in the file, Result is set to DefaultValue.

            (Result:float) IniReadFloat <(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <DefaultValue:float> <RootID:short=0>


IniReadInt
IniReadInt returns Result as an integer matching the Key’s value from the Section of IniFile.
If no match is found in the file, Result is set to DefaultValue.

            (Result:long) IniReadInt <(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <DefaultValue:long> <RootID:short=0>


IniReadRef
IniReadRef returns Result as a reference matching the Key’s value from the Section of IniFile.
If no match is found in the file, Result is set to DefaultValue.
( Then you may use ModRefEsp function to set the plugin index of the reference to a correct value.)
Attention: IniReadRef only works with local DefaultValue variable. If you need to use an external ref variable, assign the value to a local DefaultValue used with IniReadRef.

            (Result:ref) IniReadRef <(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <DefaultValue:ref> <RootID:short=0>


IniReadString
IniReadString sets Target as the string matching the Key’s value from the Section of IniFile.
If no match is found in the file, Target is set to DefaultValue.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           IniReadString <(Target)StringID:long> <(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <(DefaultValue)StringID:long> <Global:short=0> <RootID:short=0>


IniSectionsCount
IniSectionsCount returns the total number of sections in IniFile.

            (Count:long) IniSectionsCount <(IniFile)StringID:long> <RootID:short=0>


IniWriteFloat
IniWriteFloat writes Value as associated with the Key in the Section of IniFile..

           IniWriteFloat<(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <Value:float>


IniWriteInt
IniWriteInt writes Value as associated with the Key in the Section of IniFile..

           IniWriteInt<(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <Value:long>


IniWriteRef
IniWriteRef writes Value as associated with the Key in the Section of IniFile..
Attention: IniWriteRef only works with local ref variable. If you need to use an external ref variable, assign the value to a local ref used with IniWriteRef.

           IniWriteRef<(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <Value:ref>


IniWriteString
IniWriteString writes Value as associated with the Key in the Section of IniFile..

           IniWriteString<(IniFile)StringID:long> <(Section)StringID:long> <(Key)StringID:long> <(Value)StringID:long>


IntToHex
IntToHex converts Value into a hexadecimal string. If the resulting string has less digits than Digits, "0"s are added to the left to fill the missing digits.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.
If Format0x is different than 0, then “0x” will be added as prefix to the resulting string.

           IntToHex <StringID:long> <Value:long> <Digits:short=8> <Global:short=0> <Format0x:short=0>


IntToString
IntToString converts Value into a string
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp..

           IntToString <StringID:long> <Value:long> <Global:short=0>


RefToString
RefToString converts Value into a string
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.
Attention: RefToString only works with local ref variable. If you need to use an external ref variable, assign the value to a local ref used with RefToString.

           RefToString <StringID:long> <Value:ref> <Global:short=0>


RenFile (alt: RenTxtFile)
RenFile attempts to rename a file and returns 1 if success, else 0

           (Sucess:short) RenFile <(Current Filename)StringID:long> <(New Filename)StringID:long>


ResetName (STILL IN DEV PHASE !!!)
(not documented yet)

           <Object:ref>.ResetName <Object:ref>


RunBatString
RunBatString executes the string as a console batch script.

           RunBatString <StringID:long>


SanString
SanString removes unwanted characters not present in CharSet from the string, and truncate it to MaxLen.
If IgnoreCase is different than zero, the function will ignore the case of character when validating the string characters.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

            SanString <(Target)StringID:long> <(CharSet)StringID:long=-1> <MaxLen:Long=-1> <IgnoreCase:short=0> <Global:short=0>


SetString
SetString set the string to Text.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

            SetString <StringID:long> <Text:string> <Global:short=0>


StringCat
StringCat Appends strings to Target.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

            StringCat <(Target)StringID0:long> <StringID:long> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <StringID:long=-1> <Global:short=0>


StringCmp
StringCmp compares two strings and returns the position of the first different character
StringCmp returns 0 if no difference is found.
If CaseSensitive = 0 then the character case differences are ignored.

           (Position:long) StringCmp <StringID:long> <StringID:long> <CaseSensitive:short=0>


StringEsp
StringEsp sets the string EspID to the specified EspID, and returns the EspID.
If EspID is not specified or invalid, it returns the current EspID.
If the string does not exist, it returns -1.
If Global = 0 then the function fails if you try to change the EspID of a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

            (EspID:short) StringEsp <StringID:long> <EspID:short=-1> <Global:short=0>


StringGetName
StringGetName gets the name of the object.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.
Attention: StringGetName only works with local ref variable. If you need to use an external ref variable, assign the value to a local ref used with the function.

           StringGetName <Object:ref> <StringID:long> <Global:short=0>


StringGetNameEx
StringGetNameEx gets the name of the object.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.
Attention: StringGetNameEx only works with local ref variable. If you need to use an external ref variable, assign the value to a local ref used with the function.

           <Object:ref>.StringGetNameEx <StringID:long> <Global:short=0> <Object:ref>


StringIns
StringIns inserts a SubString into Source string, replacing Length characters at position Start.
If Global = 0 then the function fails if you try to modify a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           StringIns <(Substring)StringID:long> <(Source)StringID:long> <Start:long=1> <Length:long=0> < Global:short=0>


StringLen
StringLen sets the string length to Length, and returns the new length.
If Length is not specified, it returns the current length.
If Length is superior to the current length, the new added characters are set to the zero character (/0)
If the string does not exists, it returns -1.
If Global = 0 then the function fails if you try to modify the length of a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.
Attention: StringLen does not recognize StringTokens

            (Length:long) StringLen <StringID:long> <Length:long=-1> <Global:short=0>


StringMsg
StringMsg displays the string as an Oblivion message.
If ToConsole is not 0 then the string is sent to the console instead of being displayed as message.

           StringMsg <StringID:long> <ToConsole:short=0>


StringMsgBox
StringMsgBox displays the string as an Oblivion messagebox, using the provided strings for the buttons.

           StringMsgBox <StringID:long> <(Btn1)StringID:long=-1> <(Btn2)StringID:long=-1> <(Btn3)StringID:long=-1> <(Btn4)StringID:long=-1> <(Btn5)StringID:long=-1> <(Btn6)StringID:long=-1> <(Btn7)StringID:long=-1> <(Btn8)StringID:long=-1> <(Btn9)StringID:long=-1>


StringPos
StringPos returns the position of the first occurrence of Substring in Source, between positions Start end End (inclusive). The search is case sensitive.
If no match is found StringPos returns 0.
If IgnoreCase is not 0 then the character case differences are ignored.
If Last is not 0 then StringPos returns the last occurrence.

           (Length:long) StringPos <(Substring)StringID:long> <(Source)StringID:long> <Start:long=1> <End:long=-1> <IgnoreCase:short=0> <Last:short=0>


StringProtect
StringProtect sets the Protected flag of the string.
If Protected is not specified, it returns the current Protected flag state.
If the string does not exist, it returns -1.
Only the esp associated with the string can modify the Protected flag.

            (State:short) StringProtect <StringID:long> <Protected:short=-1>


StringRep
StringRep replaces the first occurrence of OrgSubString by NewSubString in Source, between positions Start end End (inclusive). The search is case sensitive.
If IgnoreCase is not 0 then the character case differences are ignored.
If ReplaceAll is not 0 then StringPos replaces all the occurences.
If Global = 0 then the function fails if you try to modify the length of a string not associated to the calling esp. Global to 1 is required if you need to modify a string of another esp.

           StringRep <(OrgSubstring)StringID:long> <(NewSubstring)StringID:long> <(Source)StringID:long> <Start:long=1> <End:long=-1> <IgnoreCase:short=0> <ReplaceAll:short=0> <Global:short=0>


StringSetName
StringSetName sets the name of the object.
Attention: SetStringName only works with local ref variable. If you need to use an external ref variable, assign the value to a local ref used with the function.

            StringSetName <Object:ref> <StringID:long=-1>


StringSetNameEx
StringSetNameEx sets the name of the object.
Attention: SetStringNameEx only works with local ref variable. If you need to use an external ref variable, assign the value to a local ref used with the function.

           <Object:ref>.StringSetNameEx <StringID:long=-1> <Object:ref>


StringToFloat
StringToFloat converts a string to a float
If the string does not contain a correctly formatted float, then StringToFloat return 0.


            (Result:float) StringToFloat <StringID:long>


StringToInt
StringToInt converts a string to an integer.
StrintToInt understands hexadecimal number, but they must be preceded by “0x”.
If the string does not contain a correctly formatted integer, then StringToInt return 0.


            (Result:long) StringToInt <StringID:long>


StringToRef
StringToRef converts a string to a ref.
If the string does not contain a correctly formatted ref, then StringToRef return an invalid ref (0).


            (Result:ref) StringToRef <StringID:long>


StringToTxtFile
StringToTxtFile writes a string as a line to the end of a text file. The file is created if necessary
If EOL = 0 then no end of line will added at the end of the string,

           StringToTxtFile <(Filename)StringID:long> <StringID:long> <EOL:short=1>


StrLC (STILL IN DEV PHASE !!!)
StrLC is used to perform precise calculation on Oblivion long variable as the Oblivion Set To commands create calculation errors for long inferior to – 8388608, or superior to 838607.
If Rounded is different than 0, then result is rounded to the closest integer.
StrLC ignores all characters in Formula but 0 1 2 3 4 5 6 7 8 9 . $ + - * / % ( ) p.
StrLC accepts floats as constant in the Formula string.
StrLC accepts a lowcase p as a Power operator.
(not fully documented yet)

            (Result) StrLC <Rounded:short> <(Formula)StringID:long> <$0:long=0> <$1:long=0> <$2:long=0> <$3:long=0> <$4:long=0> <$5:long=0> <$6:long=0> <$7:long=0> <$8:long=0> <$9:long=0>


ToOBSE (STILL IN DEV PHASE !!!) (alt: ToOBSEString)
Exports a Pluggy string to an OBSE string.
Note that you must use Set instead of Let - i.e., "Set sOBSEvar to ToOBSE PluggyStringID".
           (OBSEStringID:short) ToOBSE <StringID:long>


UserFileExists (alt: TxtFileExists)
UserFileExists return 1 if the file exists else 0

           (Success:short) UserFileExists <(Filename)StringID:long> <RootID:short=0>