Last Update: 2023-08-01

Builder Component

API Version: 624447

The Builder component allows entities to craft and construct items and structures. It manages recipes, ingredients, technology levels, and crafting buffs.

Basic Usage

-- Add a builder component to an entity
local entity = CreateEntity()
entity:AddComponent("builder")

-- Configure the builder component
local builder = entity.components.builder
builder:GiveAllRecipes() -- For testing, gives all recipes
builder:UnlockRecipe("campfire") -- Unlock specific recipe

Properties

Property	Type	Description
recipes	Table	List of known recipe names
freebuildmode	Boolean	Whether building requires ingredients
ingredientmod	Number	Modifier for ingredient requirements
techlevels	Table	Current tech levels the builder has access to
bonus_tech_level	Table	Extra tech levels from buffs or equipment
buffered_builds	Table	Builds queued for crafting
current_prototyper	Entity	Current workstation being used
builder_skills	Table	Skills from character's skill tree that enable recipes (added in API 624447)

Key Methods

Recipe Management

-- Learn recipes
builder:UnlockRecipe("spear") -- Learn a specific recipe
builder:GiveAllRecipes() -- Learn all recipes
builder:AddRecipe("firepit") -- Add a single recipe

-- Check recipes
local knows_recipe = builder:KnowsRecipe("axe")
local can_build = builder:CanBuild("hammer")
local tech_level = builder:GetTechLevel(TECH.SCIENCE_ONE)

Building

-- Build an item
builder:MakeRecipe("backpack", nil, nil, nil, nil, nil, 1)

-- Get ingredient requirements
local ingredients = builder:GetIngredients("tent")

-- Count available ingredients
local can_build, missing = builder:CanBuild("birdcage")
if not can_build then
    for i, v in ipairs(missing) do
        print("Missing: " .. v.type .. " x" .. v.amount)
    end
end

Tech Levels

-- Set tech levels
builder:SetTechLevel(TECH.SCIENCE_ONE, 1)
builder:SetTechLevel(TECH.MAGIC_TWO, 1)

-- Add temporary tech boost from equipment
builder:AddBonus(TECH.SCIENCE_ONE, 1, "sciencemachine")

-- Remove tech boost
builder:RemoveBonus("sciencemachine")

Skill Tree Integration

As of API version 624447, builder tags for skill trees have been replaced with builder skills:

-- Add a builder skill from a character's skill tree
builder:AddBuilderSkill("woodcutter_harvester")

-- Remove a builder skill
builder:RemoveBuilderSkill("woodcutter_harvester")

-- Check if builder has a specific skill
local has_skill = builder:HasBuilderSkill("woodcutter_harvester")

Tech Trees

The builder component organizes recipes by tech trees:

• TECH.NONE - Basic recipes available to everyone
• TECH.SCIENCE_ONE - Science Machine level
• TECH.SCIENCE_TWO - Alchemy Engine level
• TECH.MAGIC_TWO - Prestihatitator level
• TECH.MAGIC_THREE - Shadow Manipulator level
• TECH.ANCIENT_TWO - Ancient Pseudoscience Station level
• TECH.CELESTIAL_ONE - Celestial Altar level

Integration with Other Components

The Builder component often works with:

• Inventory - For managing ingredients
• Sanity - Some crafting can affect sanity
• ActionHandler - For triggering building actions
• Prototyper - For workstations that enhance crafting abilities
• Skilltreeupdater - For skills that unlock recipes (added in API 624447)

See also

• Inventory Component - For storing crafting ingredients
• Prototyper Component - For workstations that provide tech levels
• Recipes - For crafting recipe definitions
• Sanity Component - For sanity effects from crafting
• Container Component - For storing crafted items

Example: Setting Up a Builder with Tech Levels

local function SetupBuilder(inst)
    inst:AddComponent("builder")
    
    local builder = inst.components.builder
    
    -- Give basic tech level
    builder:SetTechLevel(TECH.SCIENCE_ONE, 1)
    
    -- Unlock basic survival recipes
    builder:UnlockRecipe("axe")
    builder:UnlockRecipe("pickaxe")
    builder:UnlockRecipe("campfire")
    builder:UnlockRecipe("firepit")
    builder:UnlockRecipe("spear")
    
    -- Add callback when near prototypers
    inst:ListenForEvent("techtreechange", function(inst, data)
        -- Do something when tech level changes
        print("Tech tree changed: " .. data.level)
    end)
    
    return builder
end

-- Example of using a prototyper (Science Machine)
local function OnActivatePrototyper(inst, doer)
    if doer.components.builder ~= nil then
        doer.components.builder:AddBonus(TECH.SCIENCE_ONE, 1, inst)
    end
end

local function OnDeactivatePrototyper(inst, doer)
    if doer.components.builder ~= nil then
        doer.components.builder:RemoveBonus(inst)
    end
end

Builder Skills vs Builder Tags

Prior to API version 624447, character skill trees used builder tags to unlock recipes. As of 624447, these have been replaced with builder skills, which integrate directly with the skill tree system. If you were using builder tags related to skill trees in your mods, you'll need to update to the new builder skills system.