Reminder - in all my tutorials, green text can be skipped by modding vets, and red text can be skipped by beginners. These are side notes meant to clarify something I imagine certain readers will have questions on, and if they are not targeted at your skill level, you can skip them or ignore them if they are over your head or seem obvious.
Before we get into the steps for making holiday related content, we need to talk about how this works in Sim Settlements 2 so you can plan out how to tackle your new content.
The holidays themselves are triggered based on in-game dates. When the player arrives at a settlement, the in-game date is checked, and the narrowest date holiday is chosen.
For example, by default, all of October is flagged as Halloween in Sim Settlements 2, but if an add-on adds a new holiday for just the first 3 days of October, that holiday will be used instead during those 3 days.
This design ensures we can have as many as 365 holidays defined, or a mix of larger scope holidays and smaller more easter-egg type holidays that only appear at more specific dates. (In the future, we will likely give players tools to force specific holiday decorations as I always enjoy giving players near total control of how the mod operates).
The individual holiday items are placed based on a marker object system I've dubbed Theme Controlled Objects. (This naming is because this same system is used for more than just Holidays. It also controls our Flag system and will eventually be used for the Faction Theming when we release Conqueror 2).
There are Activator records prefixed with SS2_HolidayControlled_, each of these can be placed on plots (or eventually in City Plans, or even placed by the player themselves directly in workshop mode). Then when a new holiday is triggered, each of those Activator records will look to the corresponding formlists for any registered decorations for that holiday and place one at random.
Similar to how the alignment helpers for building creation represent the maximum area of a plot building, the models for these activators represent the maximum space a particular holiday decoration should fill. The naming of them is also used to help explain how the item should be used. The idea is to ensure players and designers can predict how those spaces will be filled to avoid unimmersive floating or clipping.
The following named categories exist in a variety of sizes:
SS2_HolidayControlled_Hanging_ types are expected to be dangling from something with the top center point representing the spot they should be attached.
SS2_HolidayControlled_Surface_ objects are expected to lay on top of a surface so the objects should be aligned to the bottom of the marker, this could be the ground, a roof, a table, a shelf, etc.
SS2_HolidayControlled_Wall_ objects are expected to be up against a surface. Presumably a vertical surface, but there's room to get clever here I'm sure.
It's up to you as a decoration designer to get creative within the restraints of the space and connection point expectations.
We're definitely open to expanding the activator collection, but we always want to ensure that SS2 itself has decorations for every size and type combination for our 4 major holidays, which means rolling out additional activators will be a slow process and also needs to be a very convincing argument that we missed something substantial.
This portion will not cover how to create new models or material swaps, those topics have been covered in many other places. Though I will point you to my kit bashing video tutorial, and my custom textures and material swaps tutorial if you are looking for somewhere to get started.
Instead, this will cover how to take models you have already, or that you've found in the base game, and ensure they work well with the holiday system.
Note that these steps will only work for non-animated Statics, if you'd like to use other types, such as animated statics, furniture, or activators - you will need to edit the nif itself to align it accordingly. Explaining how to do that is beyond the scope of this tutorial.
Hanging should be aligned to the top of the marker.
Surface should be aligned to the bottom of the model.
Wall should be aligned to the back of the marker (to determine the back, select the marker, then press Y on your keyboard until the title of the Render Window becomes SS2BuildingStage [Front view, perspective], which means your camera is now looking at the front of the model, so you should align your model away from your viewpoint).
Now that you have your models prepared, you can set them up for injection into the holiday system! It's incredibly easy to do, and is a familiar pattern if you've already created other addon content for Sim Settlements 2.
If you are working on a custom holiday, you can skip this section.
If this is your first time working on an addon, or you haven't created addon configuration data yet, check out this tutorial).
Custom holidays can be a very involved process if you want to support all of the markers. So let's first talk about a few things to take off some of that pressure!
A. You don't have to support every marker - if no eligible decoration is found for a marker, it will simply not spawn anything.
B. Addons can cross-inject to each other's holidays, so you can get some help from the community! (There is not currently a script for managing this injection, but as soon as it comes up where someone is looking to do so, I'll gladly help create a script for it!)
Presumably, you have a date range and name in mind for your holiday. So let's start with the configuration and registration of the holiday itself.
Last thing is to register your custom holidays.
You do NOT have to register each of your custom holiday formlists with SS2. Your holiday will manage those on its own.
We have a console command built in for testing holidays, it works with the default holidays as well as custom. The trick is to make sure you actually have some of the markers set up to display them.
As of the writing of this document, only the level 3 versions of the Residential, Commercial, and Municipal buildings have these set up. We'll be releasing an addon mod that makes those markers buildable in workshop mode in the near future, which will make these much easier to test.
In the meantime, you'll want to do something like build a City Plan, and cheat the plots to level 3 with the command: cf forceplotlevel 3 -1
Once you're in-game, head to the settlement you want to test the holiday on, and run the console command:
cqf ss2_optionsManager TestThemeChange X
Replacing X with the form ID of holiday you want to set.
The form ID is 8 hexidecimal digits. The first 2, are the load order of the mod the item is coming from, and the last 6 are the 6 you see in the Creation Kit under the Form ID column when looking in the Object Window.
If that's intimidating - don't worry - there's an easy way to find this ID right inside the game!
Open the console, and type: help "HOLIDAYNAME" 4 armo (replace HOLIDAYNAME with the holiday you're searching for)
The game should return a list of matching forms, including their IDs.
Within a minute or so, holiday decorations should start appearing on any of the plot buildings that support them (and the workshop built decoration markers if you have any).
Once you're done testing, you can clear the holiday by running:
cqf ss2_optionsManager ClearThemeTestingFlag and then leaving the settlement and returning.
As you can see it's very straight-forward to add new holidays and decorations to this system!
If you'd like to step up your game and get even more clever with the holiday system, check out the activator form SS2_Prop_HalloweenSurfaceXXL_ACT_01 under WorldObjects > Activator - which uses a subspawning system to create multiple objects - almost like a miniature self-contained plot!