Modding: Buildings

Building model

Prefab

Contains the 3D-model and effects that make the building. The root of the hierarchy should be properly named Empty object and should include a Box Collider in the rough shape of the building, an Animator running all the effects and motions that building may contain and Workplace State Config (Script), which controls various states for the building such as working and pause. These will be addressed in the [Work States] section.

Construction prefab

Contains the 3D-model used to visualise the building process of the building. No effects, no animations, just the base model without LODs (Level-Of-Detail versions).

Building mesh

The 3D-model of the modded building should have around 2000-5000 triangles at the base detail level. Modded buildings will work without additional LODs, but it is good practise to include LOD0 to LOD2 in order to prevent unnecessary performance issues. Buildings use a standard shader and require PBR textures ranging from 512px to 2048px. Size of the texture should be considered relative to the size of the building. All objects in the modded building should use the same textures and one shader to avoid bloating the mod. Multiple models can be used to bring life to the building, including fans and signs that can be animated.

Prefab Hierarchy

DamageFX

All the effects for building damage such as fires and explosions are handled with Damage Visualizer (Script). Building can have multiple effects based on its remaining health with model and particle support. Destroyed Effect should link to the effect that is shown when the building is completely destroyed. Because of this, explosion effects need to be outside the DamageFX, as it will be turned off once the building health reaches 0. Same goes for the Destroyed model, which is turned on and switched to replace the partially damaged building. Destroyed model needs to contain a Destruction Zone Visual (Script) to work with the Damage Visualizer (Script). Critical Damage Health value is the threshold where the building starts to slowly burn down on its own.

Note: Critically Damaged Effects are not used at the moment.

Damage Visualizer

WorkingFX

Effects which showcase the activity of the building, such as smoke from the chimney and various lights. Great textures and careful adjustments can make a huge difference, so it is preferable to use a few well-made particle effects rather than blocking the sky with thousands of default particles. As a rough guideline, the basic chimney smoke should have around 50 particles visible at one time, while a single massive explosion can go up to a couple of hundred. This also includes the DamageFX, if the building uses particles for fire effects. Quality over quantity is key.

Door

Doors or gates which need to open as colonists walk through them need an animator to open. Most doors can share the same animator with each other, but if a modded building includes doors that open differently, they need to have their own animator. Each door needs a Door Visual (Script) linked to the correct animator. Each door also needs their own Door Id, or otherwise multiple doors open at the same time when a that Door Id is called. Open Trigger Name and Close Trigger Name are names which reference the animation trigger in a door animator.

Door Visualization

Work States

Building that produces something and is not meant to be a home for colonists needs multiple Workplace State Config (Script)s to manage the different states of the building.

States include: Off: When a building is off completely, this means that building is destroyed.

Idle: When a building is ready to work but it is not currently working, like missing resources or a worker.

Working: When a building is working and producing goods.

Paused: When a player has paused the building, this usually goes to buildings that use electricity to allow the player to manage energy usage.

Out of energy: When a building doesn’t have enough energy to power it.

Transitioning: Old system no longer in use.

Active Sound Events are currently not supported. If Initial State box should be checked on either Out of energy or Idle depending on the building. This checks a default state that is required for building to work correctly.

Activation time and Deactivation time manage the delay between states. This can be used to allow small adjustments for transitioning. Start Animation Name is the Trigger name in the building animator. Names of these triggers don’t matter as long as they match the ones in the animator, but for clarity it is recommended they are named after states of their functions. Loop Animation Name and End Animation Name are not necessary as animation closes regardless as a new state is called. Toggled objects are effects and models that toggle when state is called, same effect can be managed through timeline.

Building animator

Each building has their own building specific animator that controls the animations needed in the building. Parameters need to have the same names as the Start Animation Names that were set up with the states. Idle, Working and Off Triggers for example are usually enough to control the animation flow. Connect animation clips to Any State and set Conditions equivalent trigger. Entry should be connected to either Idle or Off animation clip in order to avoid small animation starting before building state can update.

As an example, in Fishfactory mod, Fishfactory_Working animation clip starts playing when a State containing Start Animation Name: Working is called and the building starts to produce goods. If you need animation to loop, you need to apply the checkbox for looping in the animation clip itself.

Workstate Controller

Animation Clips

Building animations can be done inside Unity by opening the timeline window and adding keyframes to create movement. Create multiple clips, one for each Trigger you are planning to call. It is recommended that each state should look visually different. Players should be able to visually recognisable what state the building is in from the animation, but if that is not possible you can always try adding Work Paths in the Building setup to colonists who spend time there.

Building setup

Modded building needs an asset file to handle the necessary functions during gameplay. Our example Fishfactory asset file can be located in the Building folder.

Fishfactory path

Fishfactory Configuration 1

Basic Building: not in use

Unlock Condition: adjusts whether building needs specific conditions to unlock such as owning another game.

Building Tech Description: description for tech tree unlocks.

Name: localization key for building's name.

Category: determines in which Build Menu category this building belongs to.

Menu Type: needs to be set to building

Included In Statistics: checks if the building should appear in the statistics window.

Show Details In Tech Info: Tech window details

Priority: The smaller the number, the greater the priority this building gets when several are being built (example: Water Well has Priority: 1, so it's built first).

Construction

Build Resource: this value determines how long building takes to build and how much damage it can take.

Resources: materials and their quantity needed to start building.

Repair Resource: materials and their quantity needed to repair the building.

Destruction Resource: materials and their quantity that player receives back when the building is demolished.

Work Slot Count: how many colonists can work in the building.

Can Be Repaired: checks whether the building can be repaired at all.

Road ID: Only used if mod is a road.

Level: Used with road upgrades.

Visual

Fishfactory Configuration 2

Icons: UI icons used for the building.

Models: multiple versions of the same building can be added to bring variation.

Visual: main prefab of the building.

Brush visual: model that shows when a player is looking for a place to set the building.

Destruction model: not in use. Handled with DamageFX in building prefab.

Constructions: model that shows when a player has placed the building and building is waiting to be constructed.

Visualization Data

Show Deposit:

Paths: contains both Building Path and Entry Path. This allows colonists to do specific animated tasks within the building when the working state is called. This section will be elaborated further at a later date.

Function

Properties: set the amount of functions needed and link to proper assets. These decide for example if the building requires power to operate and what it produces. Fishfactory example files can be found in the Building folder.

Building properties

ResourceStorage

DestroyBuildingProperty

CorpseStorageProperty

TradeProperty

SchoolProperty

ScavengerProperty

ResourceTransformProperty

Housing

Global Resource Storage Property

Global Resource Production Property

Global Resource Consumption Property

Global Disaster Forecast Property

GateProperty

FieldProperty

Entertainment

HealInjury

UI Settings

Check which elements you would like to be shown.

Placement

Tiles: set how many tiles does the building take in both X and Y axis.

Tile Editor: Basic building works by setting all tiles to B and selecting an entry side for the building. Many of the states are legacy features and not used anymore.

B: Blocked, building uses this tile

N: Normal

Reverse C: Doorway, not in use.

N: Water

S: Shore, this must be on the water in between B and N (for example Fishing Hut)

R: Reserved

Placement Type

No Dry Soil: building isn’t allowed on dry soil.

Only Dry Soil: building must be built on dry soil.

Show Radius: show working area radius during gameplay.

Show Radius Tile Grid: show working area radius on grid.

Cell Efficiency Mode: set building efficiency to be dependent on surrounding tiles.

Use Work Area Efficiency: Effectiveness of the building depends on the work area contents (for example Trapper and trees)

Highlight Deposits: show usable deposits.

Can Resize Workarea: allow players to change the work area size of the building.

Can Edit Storage: allow players to manage storage items.

Target Efficiency: How "full" of materials must the work area be to reach 100% efficiency.

Is Unique: only one instance of a building can be built.

Indestructible: building can’t be destroyed.

Damage Modifier: adjust the amount of damage taken by the building.

Restrict Placement:

Only Deep Deposits: can only be placed if one of the tiles touches a fully scavenged deposit.

Restricted Placement Position:

Decal Override: Set custom Decal for the building, otherwise default decal will be used.

Decal Enabled: Check if building uses decal under the building.

Work Area Radius: Set the size of the Work Area.

Sounds

Building Destroyed Sound Event

Building Running Sound Event

Disaster

Damage Target Types: Set building type to allow compatible Catastrophes and Disasters to target it (for example "Energy Producer" is targeted with Overcharge and Magnetic Storm events)

Workpaths

Fishfactory Workpaths

Workpaths refer to the Building Paths and Entry Paths that can be set for each work building. In Building Path, Size sets the amount of paths that a worker can randomly choose from during the working state. This creates an equivalent amount of elements that each need their own node size count which determines how many points there are in each specific path.

Building Path

Building Path is the route that workers patrol during their work hours. Ideally there should be multiple routes to create variation for the movement in the building.

Every Building Path should start and end from the same position, preferably from the point where the Entry Path ends and if possible from inside the house to to make transition between Workpaths smoother.

World Position X, Y and Z refer to the space that was set earlier in Placement Tiles. Here X refers to width, Y refers to height and Z refers to depth starting from 0.

For example in building Tiled "5x5", if you wish to have a worker walk to the lower left corner of the building on ground level, you set X=0, Y=0 and Z=0. If you wish to have a worker walk upstairs to the top right corner of the building, you need to set X=4, Y=height of the floor and Z=4.

Currently it is not possible to have different movement animations on workpaths, so ladders are not supported.

To open doors, Use Door needs to be checked on the node that is behind the door. Optimally previous node should be close to the front of the door, in order for the door to open right when the worker goes through it. Door ID needs to match the correct door set in the Building prefab.

Is Inside checkbox makes the worker vanish and is most often used when a worker goes inside a building. Is Action Node checkbox is used when a node is supposed to have an animation. Wait Time is used when a worker needs to stay still for a while for example when animation is playing. Should rotate checkbox allow workers to rotate when standing still with wait time and Look Direction Y axis determines which way workers should face during the animation. Animation ID determines what animation should play.

List of current animation is:

0 = Default animation for chosen Tool ID.

1 = Generic work with hands.

2 = Work kneeling.

3 = Kneel down.

4 = Have a break.

5 = Pick something up from the ground.

6 = Wave hands as if giving instructions.

7 = Slightly altered version of waving hands as if giving instruction.

8 = Wave and shout.

9 = Pick something up and clean it.

10 = Do some measurements

Tool ID determines the tool that workers will be carrying and using during animations. Sound Event not available yet

Entry Path

Entry Path is the route that workers take when they go to work. Entry Path should always start from outside the building, otherwise workers may run through the 3D-model of the building. Usually a good starting point is to set the first node to X=0, Y=0 and Z=-1. Currently there is support for only one main Entry Path. Node system itself works the same way as the Building Path nodes. Once the working state ends or the worker stops working, they leave through the reversed Entry Path.

Loop Working Path should be checked on to have colonists loop between different Building Paths.

Exporting Mod

Once the mod is done, be sure to save. To export the mod, simply look for the the Mod and Build Mod options on the top bar.

Building the Mod