Skip to content

Timber Commons

Jump to bottom
Igor Zavoychinskiy edited this page Jun 20, 2026 · 13 revisions

Overview

TimberCommons provides reusable irrigation tower components for building blueprints. A mod can use these components to create custom buildings that irrigate nearby terrain and optionally apply effects to growables or contamination in the active range.

Most blueprint authors only need the sections below. The lower-level C# extension points are described at the end of the page.

Building an irrigation tower

There are two ready-to-use tower components:

Both tower types irrigate tiles around the building while the building is active. The configured consumption or recipe duration should describe full coverage; TimberCommons scales runtime consumption by the actual covered area.

Common tower fields

Both tower specs use these fields:

  • IrrigationRange - maximum irrigation distance from the building foundation.
  • IrrigateFromGroundTilesOnly - optional, defaults to true. When enabled, the tower starts its range search only from foundation blocks marked as ground-only.

Useful range details for blueprint authors:

  • Range is measured from the building foundation, not from a single center tile.
  • Affected tiles must be connected to the tower and on the tower's ground level.
  • Terrain obstacles and full-moisture barriers can block the range.
  • Building efficiency can reduce the active range.

Simple good-consuming tower

Use GoodConsumingIrrigationTower when the building should consume exactly one good.

Required components:

  • GoodConsumingBuilding
  • GoodConsumingBuildingSpec with exactly one ConsumedGoodSpec
  • GoodConsumingIrrigationTowerSpec

GoodConsumingIrrigationTowerSpec fields:

  • IrrigationRange
  • IrrigateFromGroundTilesOnly

The tower consumes goods only while it has reachable tiles. If the building also has range-effect components, all of them are active whenever the tower irrigates.

Blueprint example (Timberborn 1.1)

For a complete blueprint-shaped JSON document, see ExampleIrrigationTower.Folktails.blueprint.json.

The full example targets Timberborn 1.1 and is valid for TimberCommons 1.16.0 and 1.16.1 (TBD). Replace the template name, localization keys, icon, model path, costs, tool group, and numbers with your own values, then validate the blueprint in the target game version.

The TimberCommons-specific part is small:

{
  "GoodConsumingBuildingSpec": {
    "FullInventoryWorkHours": 24,
    "ConsumedGoods": [
      {
        "GoodId": "Water",
        "GoodPerHour": 1.0
      }
    ]
  },
  "GoodConsumingIrrigationTowerSpec": {
    "IrrigationRange": 8,
    "IrrigateFromGroundTilesOnly": true
  }
}
  • GoodConsumingBuildingSpec tells the game which good the building consumes.
  • GoodConsumingIrrigationTowerSpec turns the building into an irrigation tower and defines its range.

The rest of the full blueprint is ordinary Timberborn building structure: placement, block shape, label, driveway, access point, visual model, and colliders.

For Timberborn 1.1, DrivewayModelsSpec is the root blueprint spec for driveway models, and individual driveway entries go into its Driveways array. Do not use DrivewayModelSpec as a root spec in Timberborn 1.1 blueprints.

For Timberborn 1.0, validate the same idea against Timberborn 1.0 game assets before publishing. Blueprint root specs can differ between game versions, and a key that is valid in one version may fail in another.

Recipe-based tower

Use ManufactoryIrrigationTower when the building should consume different ingredient sets through recipes.

Required components:

  • Manufactory
  • ManufactorySpec
  • ManufactoryIrrigationTowerSpec

Do not configure another production executor, such as a workplace or production increaser. The tower itself drives the manufactory production.

ManufactoryIrrigationTowerSpec fields:

  • IrrigationRange
  • IrrigateFromGroundTilesOnly
  • Effects - optional recipe-to-effect mappings in the <recipe id>=<effect group> format.

Example:

Water=NormalIrrigation
Fertilizer=GrowthBoost

The tower irrigates while the manufactory is unblocked and ready to produce. If Effects are configured, only range effects matching the current recipe's effect group are active.

Built-in range effects

Range effects are optional components that can be added to irrigation tower prefabs.

Modify growable growth

ModifyGrowableGrowthRangeEffect changes the growth rate of growables in the active range.

ModifyGrowableGrowthRangeEffectSpec fields:

  • EffectGroup - group name used by ManufactoryIrrigationTower. It is ignored by GoodConsumingIrrigationTower.
  • GrowthRateModifier - relative percent modifier. For example, 15.5 means +15.5%, and -8.5 means -8.5%.
  • ComponentsFilter - optional full component type names. If set, a growable matches when it has any listed component.
  • TemplateNamesFilter - optional exact template names from the growable's TemplateSpec.TemplateName.

PrefabNamesFilter is deprecated in TimberCommons 1.16.1 (TBD). It is still present only for temporary compatibility with older blueprints and should not be used in new specs.

When multiple growth effects overlap, modifiers do not stack by simple addition. The effective result uses the best positive booster and the worst negative moderator.

Block contamination

BlockContaminationRangeEffect blocks contamination on the active range.

BlockContaminationRangeEffectSpec fields:

  • EffectGroup - group name used by ManufactoryIrrigationTower. It is ignored by GoodConsumingIrrigationTower.

Overlapping contamination-blocking ranges are tracked independently, so removing one effect does not remove protection provided by another active effect.

Checklist

For a new tower blueprint:

  • Choose GoodConsumingIrrigationTower for one consumed good, or ManufactoryIrrigationTower for recipes.
  • Add the matching Timberborn building component and spec.
  • Set IrrigationRange.
  • Configure consumption or recipes for full coverage.
  • Add built-in range effects if the tower should do more than irrigate.
  • For recipe-based towers, map recipe ids to effect groups with Effects.

C# extension points

Mods that need custom range behavior can implement IRangeEffect.

public interface IRangeEffect {
  public string EffectGroup { get; }
  public void ApplyEffect(HashSet<Vector3Int> tiles);
  public void ResetEffect();
}

ApplyEffect receives the currently reachable tiles. ResetEffect must undo everything the last ApplyEffect call did. Tower components may call these methods again when coverage, recipe, terrain, barriers, or building state changes.

For deeper integrations, inherit from IrrigationTower only if the ready-to-use tower components do not fit the building model.

en-US ru-RU

Clone this wiki locally