Sign in to Mod The Sims- Site Map >
- Modding and Creation >
- Sims 3 Creation >
- Modding Discussion >
- Sims 3 Script Extender Overview
- Site Map >
- Modding and Creation >
- Sims 3 Creation >
- Modding Discussion >
- Sims 3 Script Extender Overview
Replies: 6 (Who?), Viewed: 1633 times.
#1
23rd Apr 2021 at 10:18 PM
Last edited by Battery : 9th Oct 2021 at 2:43 PM.
23rd Apr 2021 at 10:18 PM
Last edited by Battery : 9th Oct 2021 at 2:43 PM.
Posts: 433
Thanks: 792 in 6 Posts
Sims 3 Script Extender Overview
What Is the Sims 3 Script Extender (S3SE) ?
"S3SE is the modding tool that allows your game to communicate from inside the game, with the outside world, which can be useful to load files, make manipulations to the disk, etc. See examples in Lyralei's tutorial ."
History
- Nov 2016 Release of Pregnancy Variations mod with methods that became commonly used by me
- May 2018 Start migrating common functionality from older mods into a shared Library
- Jul 2018 initial public release of the shared Library now called C# Utility Mod
- Feb 2020 first concepts and attempts of expanding script capabilities beyond usual Sims 3 Script modding
- Jan 2021 First proof of concept and Protoype of the Sims 3 Script Extender (S3SE)
- Feb 2021 limited testing of S3SE
- 17 Feb 2021 Release of the working Prototype to the public
- 16. April 2021 leaving the Prototype phase for Full Release version (Update 1)
When do I need S3SE ?
- If you want to Save or Load Files from a drive
- If you want a simple Global Sound Player
How modders use S3SE
Lyralei(for Prototyping):
„I did actually make an additional interaction with S3SE: the “Give Clothing as a Gift” feature“
Whenever I start with the bare functionality of a mod or a function, I like to test it with Battery's mod! This goes for added interactions on objects, simple print statements, adding a social interaction, pretty much anything that doesn't require (yet) any file reading. (that being, loading in an XML file for example, like traits)
Table of Content
Link: Tutorial and Shwocase by Lyralei Tutorial - Using Battery's S3SE tool as a script modder
Post 2: S3SE Installation
Sharp Develop
Visual Studio
Post 3: General Methods
FastQuitApplication
IsInitialized
Post 4 Audio / Sound:
GetMusicStatus
Music_NextPlaylistSong
Music_SetPlaylist
PauseMP3Music
PlayMP3Music
PlayWav
ResumeMP3Music
SetVolumeMP3Music
StopMP3Music
Post 5: File Input / Output
LoadAssembly
Post 5: File Input / Output Directory
UserModDirectory
Create
Exists
GetFiles
GetFilesOfType
GetFilesOfTypeContaining
GetFolders
GetUserModFolderPath
Post 6: File Input / Output File
Exists
GetFilename
GetFilenameWithoutExtension
ReadAllBytes
ReadAllText
WriteAllBytes
WriteAllText
Advertisement
#2
23rd Apr 2021 at 10:19 PM
Last edited by Battery : 9th Oct 2021 at 2:44 PM.
23rd Apr 2021 at 10:19 PM
Last edited by Battery : 9th Oct 2021 at 2:44 PM.
Posts: 433
Thanks: 792 in 6 Posts
S3SE Installation:
Step 1
Put the C# Script Utility package somewhere in the packages folder
Step 2
S3SE zip has to be extracted to the game/bin folder
Step 3
Extract the dll from the utility package and add it as a reference to your Code project
3A Steps for Sharp Develop:
(1) Add the extracted utility dll to your Project by right clicking References
(2) select Add Reference
(3) in the new window go to the .Net Assembly Browser tab
(4) Click Browse...
(5) select the extracted Battery.Utility.dll on your drive, then finish by clicking OK
3B Steps for Visual Studio:
Step 4
You should now be able to access the Utility by start typing batt and the autocomplete should suggest the “Battery” Namespace
Step 5
Create your Basic Startup code
The first thing you always should do is check if the user has Launched S3SE by using the “Battery.S3SE.IsInitialized()” method which returns true if the System is running. Otherwise the game will freeze when trying to use other S3SE Methods ( Infinite loop ) so either remind the user to run S3SE or disable the access to those methods.
Step 1
Put the C# Script Utility package somewhere in the packages folder
Step 2
S3SE zip has to be extracted to the game/bin folder
Step 3
Extract the dll from the utility package and add it as a reference to your Code project
3A Steps for Sharp Develop:
(1) Add the extracted utility dll to your Project by right clicking References
(2) select Add Reference
(3) in the new window go to the .Net Assembly Browser tab
(4) Click Browse...
(5) select the extracted Battery.Utility.dll on your drive, then finish by clicking OK
3B Steps for Visual Studio:
Step 4
You should now be able to access the Utility by start typing batt and the autocomplete should suggest the “Battery” Namespace
Step 5
Create your Basic Startup code
The first thing you always should do is check if the user has Launched S3SE by using the “Battery.S3SE.IsInitialized()” method which returns true if the System is running. Otherwise the game will freeze when trying to use other S3SE Methods ( Infinite loop ) so either remind the user to run S3SE or disable the access to those methods.
#3
23rd Apr 2021 at 10:19 PM
Last edited by Battery : 9th Oct 2021 at 2:19 PM.
23rd Apr 2021 at 10:19 PM
Last edited by Battery : 9th Oct 2021 at 2:19 PM.
Posts: 433
Thanks: 792 in 6 Posts
General Methods:
Battery.S3SE
void FastQuitApplication()
Usage: Quit to desktop
Example:
bool IsInitialized()
Usage: Method used to check if S3SE was initialized ALWAYS check if this is true once when starting before doing anything else with S3SE !!!
void Free() and void Startup()
Usage:
Do NOT use !!! (internal Management method)
Battery.S3SE
void FastQuitApplication()
Usage: Quit to desktop
Example:
Code:
public static void Quit()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.FastQuitApplication();
}
}
bool IsInitialized()
Usage: Method used to check if S3SE was initialized ALWAYS check if this is true once when starting before doing anything else with S3SE !!!
Code:
static bool S3SE_Initialized = false;
static Main()
{
World.sOnStartupAppEventHandler += OnStartup;
}
static void OnStartup(object sender, EventArgs e)
{
S3SE_Initialized = Battery.S3SE.IsInitialized();
}
void Free() and void Startup()
Usage:
Do NOT use !!! (internal Management method)
#4
23rd Apr 2021 at 10:20 PM
Last edited by Battery : 9th Oct 2021 at 2:20 PM.
23rd Apr 2021 at 10:20 PM
Last edited by Battery : 9th Oct 2021 at 2:20 PM.
Posts: 433
Thanks: 792 in 6 Posts
Audio / Sound:
Battery.S3SE.Audio
MusicStatus GetMusicStatus()
Usage: Returns the enum MusicStatus to determine the status of S3SE Music
Example:
void Music_NextPlaylistSong()
Usage: This method skips the currently playing song in the S3SE playlist
Example:
void Music_SetPlaylist(string[] PlaylistPaths)
Usage: Set the Music playlist by providing an array of all the mp3 audio file paths
Example:
void PauseMP3Music()
Usage: Pauses the currently playing mp3
Example:
void PlayMP3Music(string path)
Usage: Starts to play the mp3 file in the given path
Example:
void PlayWav(string path)
Usage: Starts to play the Wav file in the given path
Example:
void PlayWav(string path, bool loop)
Usage: Starts to play the Wav file in the given path with the option to loop until either the sound is stopped or another soundfile is played
Example:
void ResumeMP3Music()
Usage: Resumes paused S3SE music
Example:
void SetVolumeMP3Music(ushort Volume = 100)
Usage: Sets the volume of the mp3 music min = 0 max = 1000
Example:
void SetVolumeMP3Music(ushort Volume = 100)
Usage: Sets the volume of the mp3 music min = 0 max = 1000
Example:
void SetVolumeMP3Music(stringVolume = "100")
Usage: Sets the volume of the mp3 music min = "0" max = "1000"
Example:
void StopMP3Music()
Usage: Stops the currently playing music
Example:
Battery.S3SE.Audio
MusicStatus GetMusicStatus()
Usage: Returns the enum MusicStatus to determine the status of S3SE Music
Example:
Code:
public static MusicStatus GetMusicStatus()
{
if(Battery.S3SE.IsInitialized())
{
return Battery.S3SE.Audio.GetMusicStatus();
}
return MusicStatus.Stopped
}
void Music_NextPlaylistSong()
Usage: This method skips the currently playing song in the S3SE playlist
Example:
Code:
public static void SkipSong()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.Music_NextPlaylistSong();
}
}
void Music_SetPlaylist(string[] PlaylistPaths)
Usage: Set the Music playlist by providing an array of all the mp3 audio file paths
Example:
Code:
public static void SetPlaylist()
{
if(Battery.S3SE.IsInitialized())
{
string[] playlistpaths = new string[]
{
@"C:\MyMusic\Song1.mp3",
@"C:\MyMusic\Song2.mp3",
@"C:\MyMusic\Song3.mp3",
@"C:\MyMusic\Song4.mp3"
};
Battery.S3SE.Audio.Music_SetPlaylist(playlistpaths);
}
}
void PauseMP3Music()
Usage: Pauses the currently playing mp3
Example:
Code:
public static void PauseMusicAndPlaylist()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.PauseMP3Music();
}
}
void PlayMP3Music(string path)
Usage: Starts to play the mp3 file in the given path
Example:
Code:
public static void PlayFavoriteSong()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.PlayMP3Music(@"C:/BestSongsEVER/Never Gonna Give You Up.mp3");
}
}
void PlayWav(string path)
Usage: Starts to play the Wav file in the given path
Example:
Code:
public static void PlayFavoriteSong()
public static void PlayFavoriteWav()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.PlayWav(@"C:/SoundEffects/RRoll.wav");
}
}
void PlayWav(string path, bool loop)
Usage: Starts to play the Wav file in the given path with the option to loop until either the sound is stopped or another soundfile is played
Example:
Code:
public static void PlayFavoriteSong()
public static void PlayFavoriteWavEndlessly()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.PlayWav(@"C:/SoundEffects/RRoll.wav", true);
}
}
void ResumeMP3Music()
Usage: Resumes paused S3SE music
Example:
Code:
public static void ResumeMusicAndPlaylist()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.ResumeMP3Music();
}
}
void SetVolumeMP3Music(ushort Volume = 100)
Usage: Sets the volume of the mp3 music min = 0 max = 1000
Example:
Code:
public static void SetVolumeTo50Percent()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.SetVolumeMP3Music(500);
}
}
void SetVolumeMP3Music(ushort Volume = 100)
Usage: Sets the volume of the mp3 music min = 0 max = 1000
Example:
Code:
public static void SetVolumeTo50Percent()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.SetVolumeMP3Music(500);
}
}
void SetVolumeMP3Music(stringVolume = "100")
Usage: Sets the volume of the mp3 music min = "0" max = "1000"
Example:
Code:
public static void SetVolumeTo50Percent()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.SetVolumeMP3Music("500");
}
}
void StopMP3Music()
Usage: Stops the currently playing music
Example:
Code:
public static void StopMusic()
{
if(Battery.S3SE.IsInitialized())
{
Battery.S3SE.Audio.StopMP3Music();
}
}
#5
23rd Apr 2021 at 10:20 PM
Last edited by Battery : 9th Oct 2021 at 2:21 PM.
23rd Apr 2021 at 10:20 PM
Last edited by Battery : 9th Oct 2021 at 2:21 PM.
Posts: 433
Thanks: 792 in 6 Posts
Directory
Battery.S3SE.IO
Assembly LoadAssembly(string path)
Usage: Loads in the raw managed dll from the given path
Example:
Assembly LoadAssembly(string path, bool RunInitializer)
Usage: Loads in the raw managed dll from the given path, if you have a class called Main that has a static method called Initialize ( signature void Initialize() ) and the RunInitializer is set to true it will try to run that method right away.
Example:
Battery.S3SE.IO.Directory
string UserModDirectory
Usage: A property that returns the users mod directory as a string
Example:
bool Create(string path)
Usage: Creates a new Directory(folder) with the given path.
Note: the game needs permission to write to that location
Example:
bool DeleteDirectory(string path)
Usage: Deletes a Directory(folder) and its contents under the given path.
Note: the game needs permission to write to that location
Example:
bool Exists(string path)
Usage: Checks if the Directory(folder) exists under the given path and returns true if so
Example:
List<string> GetFiles(string path)
Usage: Returns all the files in a given directory path as a string list
Example:
List<string> GetFilesOfType(string path, string extension)
Usage: Returns all the files in a given directory path as a string list with the given extension (include the . like “.package” not just “package”)
Example:
List<string> GetFilesOfTypeContaining(string path, string extension, string MustContain)
Usage: Returns all the files in a given directory path as a string list with the given extension that also have to contain the string provided in “MustContain” (include the . like “.package” not just “package” for the extension)
Example:
List<string> GetFolders(string path)
Usage: Returns all the sub directories (folders) in a given directory path as a string list
Example:
string GetUserModFolderPath()
Usage:
Example:
Battery.S3SE.IO
Assembly LoadAssembly(string path)
Usage: Loads in the raw managed dll from the given path
Example:
Code:
string path = Sims3.UI.StringInputDialog.Show("Load Assembly File",@"Enter a path like A:/TestLib.dll","");
if(string.IsNullOrEmpty(path))
{
return true;
}
Assembly assembl = Battery.S3SE.IO.LoadAssembly(path);
if(assembl != null)
{
Battery.UI.MessageUtil.WriteNotification(assembl.FullName +"\nLoaded");
}
Assembly LoadAssembly(string path, bool RunInitializer)
Usage: Loads in the raw managed dll from the given path, if you have a class called Main that has a static method called Initialize ( signature void Initialize() ) and the RunInitializer is set to true it will try to run that method right away.
Example:
Code:
string path = Sims3.UI.StringInputDialog.Show("Load Assembly File",@"Enter a path like A:/TestLib.dll","");
if(string.IsNullOrEmpty(path))
{
return true;
}
bool InitOnLoad = Sims3.UI.AcceptCancelDialog.Show("Run Main->Initialize() for Assembly after load ?");
Assembly assembl = Battery.S3SE.IO.LoadAssembly(path, InitOnLoad);
if(assembl != null)
{
if(!InitOnLoad)
{
Battery.UI.MessageUtil.WriteNotification(assembl.FullName +"\nLoaded");
}
}
Battery.S3SE.IO.Directory
string UserModDirectory
Usage: A property that returns the users mod directory as a string
Example:
Code:
public override bool PrintUserPath()
{
Battery.UI.MessageUtil.WriteNotification(Battery.S3SE.IO.Directory.UserModDirectory);
return true;
}
bool Create(string path)
Usage: Creates a new Directory(folder) with the given path.
Note: the game needs permission to write to that location
Example:
Code:
Battery.S3SE.IO.Directory.Create( @"A:/NewFolder");
bool DeleteDirectory(string path)
Usage: Deletes a Directory(folder) and its contents under the given path.
Note: the game needs permission to write to that location
Example:
Code:
Battery.S3SE.IO.Directory.DeleteDirectory( @"A:/NewFolder");
bool Exists(string path)
Usage: Checks if the Directory(folder) exists under the given path and returns true if so
Example:
Code:
bool exists = Battery.S3SE.IO.Directory.Exists(@"A:/NewFolder");
List<string> GetFiles(string path)
Usage: Returns all the files in a given directory path as a string list
Example:
Code:
List<string> Files = Battery.S3SE.IO.Directory.GetFiles("C:/MyMusic");
List<string> GetFilesOfType(string path, string extension)
Usage: Returns all the files in a given directory path as a string list with the given extension (include the . like “.package” not just “package”)
Example:
Code:
List<string> files = Battery.S3SE.IO.Directory.GetFilesOfType("C:/Files/Content",".xml");
List<string> GetFilesOfTypeContaining(string path, string extension, string MustContain)
Usage: Returns all the files in a given directory path as a string list with the given extension that also have to contain the string provided in “MustContain” (include the . like “.package” not just “package” for the extension)
Example:
Code:
List<string> files = Battery.S3SE.IO.Directory.GetFilesOfTypeContaining("C:/", ".mp3", "Never Give");
List<string> GetFolders(string path)
Usage: Returns all the sub directories (folders) in a given directory path as a string list
Example:
Code:
List<string> folders = Battery.S3SE.IO.Directory.GetFolders("C:/Games");
string GetUserModFolderPath()
Usage:
Like the property “UserModDirectory” returns the users mod directory as a string. use the property instead for better performance !!!
Example:
Code:
Use "Battery.S3SE.IO.Directory.UserModDirectory" instead !
#6
23rd Apr 2021 at 10:23 PM
Last edited by Battery : 9th Oct 2021 at 2:21 PM.
23rd Apr 2021 at 10:23 PM
Last edited by Battery : 9th Oct 2021 at 2:21 PM.
Posts: 433
Thanks: 792 in 6 Posts
File
Battery.S3SE.IO.File
bool Exists(string path)
Usage: Checks if the File exists under the given path and returns true if so
Example:
bool DeleteFile(string path)
Usage: Deletes a File under the given path.
Note: the game needs permission to write to that location
Example:
string GetFilename(string path)
Usage: Returns the filename with the extension in the given path ( C:/Testfolder/myfile.txt becomes myfile.txt)
Example:
string GetFilenameWithoutExtension(string path)
Usage: Returns the filename without the extension in the given path ( C:/Testfolder/myfile.txt becomes myfile)
Example:
byte[] ReadAllBytes(string path)
Usage: Reads the file under the given path and returns its bytes as an byte array
Example:
string ReadAllText(string path)
Usage: Reads the file under the given path and returns its content converted into an utf8 string
Example:
void WriteAllBytes(string path, byte[] message)
Usage: Writes a byte array to a file in the given path (creates new files as well)
Example:
bool WriteAllText(string path, string Text)
Usage: Writes utf8 text to a file in the given path (creates new files as well)
Example:
Battery.S3SE.IO.File
bool Exists(string path)
Usage: Checks if the File exists under the given path and returns true if so
Example:
Code:
bool exists = Battery.S3SE.IO.Directory.Exists(@"A:/NewFolder/test.xml");
bool DeleteFile(string path)
Usage: Deletes a File under the given path.
Note: the game needs permission to write to that location
Example:
Code:
Battery.S3SE.IO.File.DeleteFile( @"A:/Pleasedeleteme.txt");
string GetFilename(string path)
Usage: Returns the filename with the extension in the given path ( C:/Testfolder/myfile.txt becomes myfile.txt)
Example:
Code:
string filename = Battery.S3SE.IO.File.GetFilename("C:/Testfolder/myfile.txt");
string GetFilenameWithoutExtension(string path)
Usage: Returns the filename without the extension in the given path ( C:/Testfolder/myfile.txt becomes myfile)
Example:
Code:
string filename = Battery.S3SE.IO.File.GetFilenameWithoutExtension("C:/Testfolder/myfile.txt");
byte[] ReadAllBytes(string path)
Usage: Reads the file under the given path and returns its bytes as an byte array
Example:
Code:
byte[] bytes = Battery.S3SE.IO.File.ReadAllBytes("C:/NewFolder/Settings.bin");
string ReadAllText(string path)
Usage: Reads the file under the given path and returns its content converted into an utf8 string
Example:
Code:
string text= Battery.S3SE.IO.File.ReadAllText("C:/NewFolder/Settings.xml");
void WriteAllBytes(string path, byte[] message)
Usage: Writes a byte array to a file in the given path (creates new files as well)
Example:
Code:
byte[] bytestowrite = { 0,1,2,3,4,5,6,7,8,9,10,255};
string path = Battery.S3SE.IO.Directory.UserModDirectory;
Battery.S3SE.IO.File.WriteAllBytes(path, bytestowrite);
bool WriteAllText(string path, string Text)
Usage: Writes utf8 text to a file in the given path (creates new files as well)
Example:
Code:
string message = "Hello Outside World"; string path = Battery.S3SE.IO.Directory.UserModDirectory; Battery.S3SE.IO.File.WriteAllText(path,message);
#7
24th Apr 2021 at 3:05 PM
24th Apr 2021 at 3:05 PM
Posts: 3,860
Thanks: 8546 in 67 Posts
Thank you so much for the documentation! (Not sure if you're done, if not, sorry for making this reply break the chain!) That was something I struggled with a little with what's there that could be useful in my future mods or whatever I was working on at the time. So I'll check this out with my new upcoming mod and see what i can use! 
Thank you for this again!
Thank you for this again!
Who Posted
|
|