About This File
Welcome to The Sims 4 Community Library!
This is more of an API than a mod itself. It does nothing on its own and is meant as a framework for other Sims 4 developers to utilize in their own code bases. Only install the library if you have installed a mod that requires it!
To see the documentation for S4CL check out the docs!
To start creating mods using S4CL check out the template project!
Looking to install S4CL?
Follow the installation instructions below for details.
For a changelog of the most recent updates and additions, take a look at the releases page.
For a complete list of features and utilities, check out the documentation
- Vanilla Tuning identifiers for:
- Relationship Bits
- Relationship Tracks
- Short-Term Relationship Bits
- Many Others!
- Log messages to a file
- Log custom exceptions
- Log the current stack trace, find out who or what is calling your functions!
- Useful when debugging code!
- Enable/Disable logs via a command in-game. `s4clib.enable_log�<log_name>`
- Exception Handling
- Log to a file exceptions that are thrown
- Catch exceptions within your functions via a decorator
- Custom Dialogs
- Ok/Cancel Dialog
- Choose Object Dialog
- Choose Sim Dialog
- Custom Icons:
- Right Arrow
- Navigate Into Arrow
- Question Mark
- Six Sided Dice
- Checked Box
- Unchecked Box
- Sim Icons
- Story Dialogs (Add custom buttons, add sim icons)
- Sim Picker
- Prompt the player to choose a sim or a number of sims from a dialog.
- Custom Notifications
- Basic Notification - Display a notification with a title and description of varying urgency.
- Register Interactions to:
- Objects (Sims, Furniture, etc.)
- Custom Interactions
- Create interactions the run Python code in their backends
- Interaction Types:
- CommonInteraction - Inherit from this to hook into an interaction and add python functionality to its functions
- Immediate Super Interaction - An interaction that doesn't require a target to perform. It is started immediately and without an animation.
- Super Interaction - Like the Immediate Super interaction but these require a target to perform. (sim_chat is one example of a Super Interaction)
- Mixer Interaction - Use this for custom Mixer interactions.
- Social Mixer Interaction - Use this for custom Social Mixer interactions.
- Terrain Interaction - Use for interactions that appear when clicking on the ground.
- Perform logical checks to determine whether or not to show an interaction
- Or display an interaction as disabled, with a displayed tooltip that shows when the player hovers the interaction.
- Run Python code when an interaction is started, cancelled, or has finished.
- Custom Interaction Tooltips
- Display tooltips on interactions that display on hover.
- Locate CommonInteraction for an example of how to utilize custom tooltips in your own interactions.
- Event Handling
- Create, Dispatch, and Handle Dynamic Events
- Handle events without needing a reference to the code that sends the event.
- Decouple that code!
- Interval Events
- Run functions on millisecond intervals.
- Run functions once, after an amount of time has passed.
- Interaction events (Queued, Started, Ended, Interaction Outcomes)
- Spawn - Occurs when a Sim spawns or is born into the world.
- Initialization - Occurs when a Sim is initialized (before being spawned).
- Occult Swapping - Occurs when a Sim changes to a different Occult (i.e. Human to Mermaid or Human to Vampire or vice verse)
- Zone Events
- Zone Update - Occurs every time the zone updates. (Basically every time the game ticks)
- Zone Teardown - Occurs every time the zone is torn down. Occurs before a loading screen, but only after a Zone had been previously loaded. (See Zone Early/Late Load)
- Zone Save - Occurs every time a zone is saved. This occurs before the game saves for the player. Be careful with this one!
- Zone Early Load - Occurs when a zone is loaded, but before the players household has loaded.
- Zone Late Load - Occurs when a zone is loaded, but after the players household has loaded.
- Sim utilities
- Get the Active Sim
- Get Sim Info, Sim Instance, and Sim Ids
- Get All Sims nearby and�filter which types of sims to get�(Age, Species, Occult, Traits, Buffs, etc.)
- Occults - Check Occult Types of sims.
- Ages - Get/Set/Check Ages of sims.
- Genders - Get/Set/Check Genders of sims.
- Species - Get/Set/Check Species of sims.
- Buffs - Add/Remove/Check Buffs of sims.
- Traits - Add/Remove/Check Traits of sims.
- Sim State - Check various states of sims. (Wearing towel, Dying, etc.)
- Sim Spawn/Despawn - Spawn, Despawn, and Delete Sims.
- Outfit - Set/Get/Update/Check the current outfit of sims.
- CAS Utils - Attach/Detach/Check cas parts of a sims outfit. You can put any cas part in any BodyType via these.
- Components - Get various components of objects (Statistics, Traits, Buffs, etc.)
- Resources - Load Resources or Tuning files by their identifiers. (Buffs, Traits, Statistics, Snippets, etc.)
- Icons - Load Icons provided by S4CL or your own Icons.
- Types - Determine the type of objects without needing to use isinstance or having a reference to the type itself in your own code.
- Time - Manage time. Pause the game, get/change the current game speed, get/set the time of day, etc.
- Collections - Determine if an object is a collection, combine collections, flatten collections, etc.
- Injection - Inject custom functionality into functions
- IO (Input/Output) - Write string data to a file or load string data from a file.
- Stack Trace - Retrieve the complete and full stack trace.
- Localization utilities
- Retrieve LocalizedStrings from StringTables of .package files.
- Format tokens into LocalizedStrings
- Display text in specific colors (Colors can be added by request)
- Create Localized Tooltips - Use to display tooltips on interactions (while also displaying the interaction)
- These can be useful to give more information to the player about why something cannot be performed, instead of simply hiding that something.
- Many more!
- Testing Framework
- Write tests to test your python code and run the tests via a command within the game.
- The results will be logged to the 'Documents/The Sims 4/'�folder
- A single function can handle multiple tests utilizing the same code with different arguments.
- Run tests via the command: `s4clib.run_tests <class_names_separated_by_a_space>`
- Class Names are the names of the classes decorated with 'test_class'
- If no class names are provided, all of the tests will run.
- Download the latest zip archive from the releases page (It is the one with the version number in it Example: sims4communitylib.v0.0.0.zip) (Ignore the ones that contain Source Code in their name)
- Unpack the archive using your favorite archiving tool.
- Drag the files/folders to your Mods directory.
- Keep in mind the ts4script file MUST be either top level (Directly in the Mods/<ts4script file>�folder) or one folder deep (Mods/Blah/<ts4script file>). Any deeper and it will not work.
- Sims 4 Patch Version 188.8.131.520 (Island Living) or above
- DLCs are NOT required, you only need to have an up to date game (Check the bottom of the main menu for your current version).
- For a list of planned features, take a look at the repository.
Note for Modders:
- If you have ideas for additions to add or want one of the planned features sooner rather than later, I'm all ears! Let's work together to create a library that we all can use!
- To see the documentation for S4CL check out the docs!
What is the workflow for working with S4CL?
- Create a project based off of the Template Project
- Use the green button in the top right The Main Page to download this project as a zip file.
- In your project, create another directory called `S4CL`.
- Open the downloaded project and copy the `Scripts/sims4communitylib` folder into the `S4CL` folder we created in the previous step. The folder structure should then be: `<Your Project>/S4CL/sims4communitylib`
- Right click the `S4CL` folder -> Mark Directory as -> Sources Root
- The `S4CL` folder should turn a blue color and the `sims4communitylib` folder should look like a folder with a dot (In other words, it should NOT be blue).
- Your folder structure should look like this: `<Your Project>/S4CL/sims4communitylib` at this point.
- Ensure you list in the description of your mod a link to the github releases (You may even link a specific release to ensure compatibility.)
- Ensure you properly attribute S4CL and its author according to the license located at the bottom of this readme.
- YOU DO NOT HAVE MY PERMISSION TO BUNDLE S4CL INTO YOUR OWN MOD. So don't do it. Redirect the users of your mod to the github repository or releases pages instead.
The Sims 4 Community Library is licensed under the Creative Commons Attribution 4.0 International public license (CC BY 4.0).
Copyright (c) COLONOLNUTTY
If you make a post containing or referencing adult content in the support thread, your post WILL be reported and removed. (This does not include profile pictures or signatures)
If you or another mod author spots something that you consider to be "plagiarism" please ask me about it, it is highly likely that it is merely a coincidence. I will be more than happy to discuss it with you and we can together come to a compromise, whether that be deleting the offending file or recreating it entirely.
DO NOT just report this mod for plagiarism, it is both rude and immature. Use your words, Lovers Lab is NOT a place for immature children to be running around, there is an age required to create accounts after all. False accusations will be reported.
If you decide to report any part of the code as plagiarized, expect to be asked for proof and a list of files/code spots where you believe code has been plagiarized. If no proof is provided, or if the response "all of it" is provided. Your claim will be invalid and subject to report abuse.
A note to moderators: If you are planning on taking this mod down, please warn me, or send me a message, or do ANYTHING to get my attention before hand. I'm sick of my mods being taken down without so much as a word, it is extremely disrespectful! I would love to have a chance to rectify my mistakes before deletion.
If it is deleted in the future without a warning or any indication of why, I will promptly re-upload it within 24 hours of the incident, under the assumption that it was mistakenly deleted, I hope you can understand. Thank you in advance!
What's New in Version 1.23 See changelog
A changelog, older versions, and modder files (examples, etc.) can be found here: https://github.com/ColonolNutty/Sims4CommunityLibrary/releases