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 FromOBSE (STILL IN DEV PHASE !!!) (alt: FromOBSEString)
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>
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>
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>