Modding - Buildings

Map Objects
Map Objects - any static object on the map (including resource nodes, buildings, decorations, and so on) - are probably the most complex element in the game. They can have a wide variety of behaviors, including producing resources, attacking enemies, allowing you to craft special items (Ruins), drop stuff when you destroy them (debris), and so on.

In this page we will focus on Buildings - which are just like any other map objects, but the player can build them. This page describes how to define buildings and their behavior. If you want the player to build them, you will also need to define their Building Blueprints.

Map objects are defined accross several JSON files (the system joins them all together so the separation to different files is only a matter of convenience and useful for our internal tools). The files that define buildings are MapObjects.json and BuildingStats.json.

BuildingStats.json define elements that are common to many buildings - such as production, upkeep, size, weight, etc. MapObjects.json defines elements that are more unique such as blocking behavior, and visual appearance. When you create your mods you can have all the modifications and additions in a single file, regardless of whether the original setting appears in one file or the other.

Base Types
There are lots of base types for map objects. Check out the Reference Configuration Files for all the different options you can use. You can also define your own buildings from scratch if you prefer.

Format
Map Objects are defined using the standard Entity Format.

Map Object Parameters
Map objects have a wide variety of parameters, but most of the behavior is built using Components. More on the different components below.

Boolean Parameters
There are several boolean parameters that have very specific effects:

"size" - the object's size in tiles. Format: "x,y". This should match the displayed prefab's size.

"weight" - weight when built inside the city. Default 0.

"canmove" - when this is true, the building can be moved freely, including when there are incoming raids. Default is false, but most player-built objects have this set to true in the base type that they inherit.

"canmove-noraid" - when true, this building can be moved as long as there is no incoming raid. Used for turrets. Default is false.

"iscity" - Objects that are built within the city and have this value as true will appear to move with the city in the take-off animation. If it is set to false the object will remain on the floor even when it is built inside the city, when the rest of the city takes off.

"demolish" - whether or not the player can demolish this object. Default is false, but player-built objects have this set to true in the base type that they inherit.

"repair-costs" - flux costs to repair this building. When value is negative, the building can't be repaired. Default is -1.

"display-only" - set to true for decorations that don't do anything (including blocking movement), and are there just for visual purposes. It helps with performance. Default false.

"add-collider" - some interactive prefabs don't have a collider, so this value needs to be set true. When you copy a prefab from another object, make sure to copy this value as well. Only interactive objects need colliders, objects that you can open their GUI, move them, demolish them, etc. Default false.

"interact-only" - when true, you can only open this building's window when you're right next to it. Used for interactive buildings out in the world, like ruins. Default false.

"hover-in-management" - when true, the object will become highlighted and its name will appear in the bottom of the screen when hovering it in management mode. Default is true.

"can-deactivate" - whether or not the player can deactivate this building. This is usually set to false to prevent abuse for buildings that are needed only occasionally. For example, floating devices can't be disabled, because then their upkeep would become meaningless (players could disable them all the time and only enable when taking off). Default is true.

"iswall" - set to true if the object is a wall. This will prevent Tiny from moving between two adjacent "wall" objects.

"snap" - whether or not the object will be snapped to grid when placed. Default is true, should only be set to false for decorations that don't need to be placed in the center of the grid.

Components
Components are what makes map objects unique and give them their behavior. See Modding - Instance and Type Components to learn how to define components. Below is a list of the most important component types that are fit for buildings.

MapObjectComponentProduction
instancecomponents: { "production": { class: "MapObjectComponentProduction" "recipes": { "woodwarper": true, "starwood": true, "acidwood": true, "carbonmix": true } 	}, } This instance component means that a building can produce resources, either for free or using raw materials. It needs the "recipes" parameter, which is a Set of Production Recipes that can be produced in this building. Buildings can theoretically have more than one production component, which will allow them to perform multiple production tasks in parallel, but this is not in use in the vanilla version and is not well tested.

MapObjectComponentResourceHarvester
Similar to the production component, but there is a difference in how this behaves in the game. For example, it can send resources to Resource Drop-offs, and it can consume resources in nodes and then run out. Use this for harvesters that are built on top of resource nodes.

MapObjectComponentUpkeep
"upkeep": { "class": "MapObjectComponentUpkeep", "costs": { "funds": 4, "power": 3 }, 	"assigned": { "worker": 3 } } An upkeep component defines which resources this building consumes when active (regardless of whether it is producing or not), and assigned resources.

The "costs" parameter contains a set of items and amounts that are consumed every cycle.

The "assigned" parameter defines resources that are set aside for this building, and which will cause the building to stop functioning if there are not enough that remain unassigned. These resources, unlike "costs", are not consumed and removed from the player's inventory, and can be freed up by removing or disabling the building. Currently this is only used for workers, but there is no problem creating additional resources that are assigned like this.

MapObjectComponentGlobalStorage
instancecomponents: { storage: { class: "MapObjectComponentGlobalStorage" storage: { power: 50 } 	} } This component will cause the building to increase the global storage capacity of the resources defined in it. A good example is batteries that increase the power storage. The resources that can be stored in it are defined in the "storage" parameter.

MapObjectComponentLauncher
instancecomponents: { launcher: { class: "MapObjectComponentLauncher" fuel-costs: 3 carry-weight: 25 } } Used for buildings that increase the city's carrying capacity. The "carry-weight" parameter defines how much this building adds to the maximum carry weight. The "fuel-costs" parameter defines how much additional fuel will be consumed on take-off when this building is active.

MapObjectComponentNeedsPower
Objects with this component will cease to function if they are outside the city's power range (if a tesla tower is destroyed or moved, for example).

MapObjectComponentPowerDist
powerdistributor: { class: "MapObjectComponentPowerDist" range: 15 electric-position: "-0.081, 4.681, -0.236" startpoint: false } Objects with this component will create a power distribution area around them. When "startpoint" is set to true, this building will create a power distribution area without having to be connected to the power network itself. For example, the city core and long-range power hub are set as starting points. Otherwise, the building will be disabled and not create a power distribution area around it if it is not itself within an active power distribution building.

The "range" parameter defines the power distribution area range created by this building, and the "electric-position" parameter is used to define where the electricity line animation originates from, so when copying a displayed prefab, copy this parameter as well.

MapObjectComponentResource
instancecomponents: { resource: { class: "MapObjectComponentResource" resource: "bloodwoodlog" min: 175 max: 300 } } This is used for resource nodes (not exactly buildings, but we don't have a separate page for resources yet). In it you can define the resource item (it will appear in the "costs" section of the resource production recipe), and the min/max amount (a value will be selected at random between the two).

Built-in resources are defined in Resources.json

MapObjectComponentWall
Give wall objects this component so they are displayed correctly (connecting to other adjacent walls)

MapEntityComponentAttacker
instancecomponents: { attacker: { class: "MapEntityComponentAttacker" damage: 30 cooldown: 2 range: 12 tags: { enemy: true } 		projectile-prefab: "AtlasTurretBoltPrefab" shoot-sound: "wood-turret-attack" hit-sound: "heavy-turret-hit" attack-effects: { aoe: { class: "AttackEffectAoe" range: 1.2 dmg-ratio: 1 effect-prefab: "EffectHeavyCrossbowExplosion" } 		} 	} } This component will cause the building to shoot at enemies. Use it for turrets.

See the weapon component of Modding - Items for more information on the different parameters. It works the same (except for the burst, turrets don't support burst). Make sure to use MapEntityComponentDefendAi together with the attacker component, or the building won't attack.

MapEntityComponentDefendAi
Give this component to turret buildings so they will attack enemies.

MapEntityComponentHealth
instancecomponents: { health: { class: "MapEntityComponentHealth" health: 110 cycles-to-heal: 20 color: "player-color" } } Defines the building's health. Make sure to also give it an Attackable componet as described below, or enemies won't be able to attack it. The "health" parameter determines how many hit points it will have. The "cycles-to-heal" parameter defines how many cycles until this building fully repairs itself (regardless of repair costs for immediate manual repair).

MapEntityComponentAttackable
This component makes the building targetable by enemies. Rails, for example, don't have this component so enemies won't attack them.

MapEntityTypeComponentDropLoot
typecomponents: { loot: { class: "MapEntityTypeComponentDropLoot" loot-set: "bloodwoodgather" drop-chance: 0.5 } } Use this component to tell the object to drop loot when it is destroyed. Debris and small destructible resource nodes are examples that use this. The "loot-set" is a reference to a Loot Set entity that defines the different possible items that can be dropped. The "drop-chance" parameter determines how often this object will drop loot.

MapObjTypeComponentBlockAround
typecomponents: { engine-block: { class: "MapObjTypeComponentBlockAround" block-tags: { block-engine: true } 		distance: 5 } } This components determines what and how far is blocked by this building. Blocking can affect Construction Blueprints (in that it will not allow building other stuff on top or near it), and will also affect unit movement.

There are two parameters - the "block-tags" which is a set of tags that determines what will be blocked, and the distance parameter that determines how far, in tiles, these things will be blocked.

This component generates a "blocked area" for each block-tag provided, and then, when you define units or constructions that should be blocked by this tag, they can not be built / can not move into this blocked area.

The example above creates a blocked area tagged "block-engine" in an area of 5 tiles around the building. The construction blueprint for floating devices in turn is configured to no let you build it within a "block-engine" tagged area, and so you can only build other floating devices at least 5 tiles away from this one.