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.
¶ Intro (How It Works)
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.
¶ Preparing Holiday Decorations
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.
- In the Cell View window, make sure the World Space drop down is set to Interiors, then find SS2BuildingStage in the left-hand list and double-click it.
- In the Layers window, click New Layer, and provide a unique name for your layer to work from.
- Right-click your layer, and choose Make Active Layer.
- In the Object Window, filter for SS2_HolidayControlled_, then drag the one you'd like to work with onto the title bar of the Render window so that it ends up at coordinates 0/0/0.
- Drag the Static record for the model you want to use and line it up within the holiday marker box so that it's positioned correctly for that type.
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).
- Once you're satisfied with the positioning, in the Object Window, filter for StaticCollectionPivotDummy under WorldObjects > Static, then drag that to the title bar so it ends up at coordinates 0/0/0.
- In the Layers window, right-click your layer and choose Select All Loaded References in Layer.
- Click on the title bar of the Render Window so it is active, and use the keyboard shortcut Alt+O. You will receive a warning, to which you can answer "Create Collection without these references.".
- A small pop-up titled Input Collection Name will come up. **Enter a unique ID **for your decoration, then click OK. A second, similar, popup titled Input Object Window Filter will come up which you can answer OK to as well.
¶ Injecting New Holiday Decorations
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.
- In the Object Window, filter for SS2_HolidayAddonTemplate_ under Miscellaneous > FormList. Right-click and duplicate the one that matches the holiday and decoration size you are working on, then double-click your copy.
- Change the ID field to something like yourPrefix_HolidayDecorations_HOLIDAYNAME_TYPE_SIZE. For example, kinggath_HolidayDecorations_Christmas_Hanging_Large.
- Leave the first entry in place, that keyword always needs to be the first entry, and then drag the title bar of the formlist window off to the side.
- In the Object Window, filter for your decoration(s) for this holiday and size and drag them onto the formlist. Then press OK to close the formlist, answering No to creating new, and Yes to rename.
- Repeat for each holiday, type, and size combination that you have decorations for.
If this is your first time working on an addon, or you haven't created addon configuration data yet, check out this tutorial).
- In the Object Window, filter for your addon config under Items > MiscItem and double-click it to open it, then double-click the script on it to bring up the Script Properties screen.
- Double-click the property MyItems, then click Add on the far right and find the formlist you created in step 1, repeat for each formlist.
¶ Creating Custom Holidays
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.
- In the object window, filter for SS2_ThemeDefinition_Holidays_AddonTemplate under Items > Armor (don't worry about the fact that it's armor, this is a little hack we use for UI purposes), right-click it and choose Duplicate, then double-click your copy to open it.
- Change the ID to something like yourPrefix_ThemeDefinition_Holidays_HOLIDAYNAME.
- Change the Name field to the holiday name you'd like displayed in game. (It's currently not used anywhere yet, but in a future patch it will be used for things like allowing players to force certain holidays to trigger on demand)
- Double-click the script entry SimSettlementsV2:... to open the script properties.
- Set the properties for iStartDay, iStartMonth, iEndDay, and iEndMonth to establish the in-game dates your holiday should be used. So for example, if you want your holiday to go from June 1st to June 10th, you would enter the following: iStartMonth = 6, iStartDay = 1, iEndMonth = 6, iEndDay = 10.
- Drag the Object Window to a place where you can see it around these script properties (or drag the script properties window somewhere you can see the Object Window).
- Click on FormList under Miscellaneous.
- Right-click on the right half of the Object Window and click New.
- Enter a unique ID for the formlist, something like yourPrefix_HolidayDecorationPool_HOLIDAYNAME_TYPE_SIZE. For example, kinggath_HolidayDecorationPool_MayThe4th_Hanging_Small.
- If you have any decorations of this type ready for your holiday, drag them in to the formlist now (you can come back and do so later if you don't have them ready yet).
- Click OK to save the formlist.
- Repeat for each of the different properties in your Holiday record under DecorationForms (and optionally under FlagsAndBanners if you would like to support those as well).
- Once you're finished setting up formlists, setup the corresponding properties on your holiday to point to those formlists.
- Click OK on the script properties, and then OK on the holiday armor record - answering No to create new, and Yes to rename.
¶ Register Your Custom Holidays
Last thing is to register your custom holidays.
- In the object window, filter for SS2_Holidays_AddonTemplate, right-click it and choose Duplicate, then open your copy.
- Change the ID to something like yourPrefix_Holidays.
- Be sure to leave the first entry as the first entry, and drag your holidays into the list.
- Click OK to save the formlist, answering No to create new, and Yes to rename.
- In the Object Window, filter for your addon config under Items > MiscItem and double-click it to open it, then double-click the script on it to bring up the Script Properties screen.
- Double-click the property MyItems, then click Add on the far right and find the formlist you created in step 1.
You do NOT have to register each of your custom holiday formlists with SS2. Your holiday will manage those on its own.
¶ Testing Holiday Decorations
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.
¶ You're Done!
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!