Foundation - Modding Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
[[api/building_function|BUILDING_FUNCTION]] classes are registerable types in Foundation that define what purpose  a certain [[api/building_part|BUILDING_PART]] will serve in the game.

For reference all available [[api/building_function|BUILDING_FUNCTION]] classes can be found in [[api/building_function|this]] section of the API.

===== Creating & Using a Custom BUILDING_FUNCTION =====
==== Step 1: Defining a BUILDING_FUNCTION Class using a Lua Table ====
To create a custom [[api/building_function|BUILDING_FUNCTION]] class we will need to make use of the ''mod:registerClass(AssetTable)'' function providing it with an associated Lua Table.

Here you decide what properties your custom [[api/building_function|BUILDING_FUNCTION]] object will contain. Furthermore you can override default [[api/building_function|BUILDING_FUNCTION]] methods as well as define custom ones.
<code lua>
local MY_BUILDING_FUNCTION = {
    TypeName = "MY_BUILDING_FUNCTION",
    ParentType = "BUILDING_FUNCTION",
    Properties = {
        { Name = "Property1", Type = "string", Default = "SomeString" },
        { Name = "Property2", Type = "list<RESOURCE_QUANTITY_PAIR>" },
        { Name = "Property3", Type = "integer", Default = 1 }
    }
}
</code>
Now that the base [[api/building_function|BUILDING_FUNCTION]] Lua Table is ready we can define functions for it before registering it.

All [[api/building_function|BUILDING_FUNCTION]]s have three base functions that can be overriden, ''activateBuilding'', ''reloadBuildingFunction'', and ''removeBuildingFunction''.

''activateBuilding'' is called the first time a [[api/building_function|BUILDING_FUNCTION]] is instantiated in game be it because the [[api/building_part|BUILDING_PART]] it was defined on was built or because it was assigned by the player. This function can be used to set up any necessities for the [[api/building_function|BUILDING_FUNCTION]] to work, for example in the case of [[api/building_function_workplace|BUILDING_FUNCTION_WORKPLACE]] this function creates the [[api/comp_workplace|COMP_WORKPLACE]] necessary for assigning workers to the [[api/building_part|BUILDING_PART]].

''reloadBuildingFunction'' is called upon save game loading. This function usually serves as a back-call to the ''activateBuilding'' function to ensure any necessities are present and initialised after a reload.

''removeBuildingFunction'' is called when a [[api/building_function|BUILDING_FUNCTION]] is manually unassigned by the player. This function is used to remove components or other elements that should no longer be present once the function is removed from the [[api/building_part|BUILDING_PART]].

For example below we set up a function that upon activation logs its properties and upon reload executes a back-call to its activation function.
<code lua>
function MY_BUILDING_FUNCTION:activateBuilding(gameObject)
    mod:log("Property1: " .. tostring(self.Property1))
    mod:log("Property2: " .. tostring(self.Property2))
    mod:log("Property3: " .. tostring(self.Property3))
    
    return true
end

function MY_BUILDING_FUNCTION:reloadBuildingFunction(gameObject)
    self:activateBuilding(gameObject)
end
</code>
And finally we register our custom [[api/building_function|BUILDING_FUNCTION]] class.
<code lua>
mod:registerClass(MY_BUILDING_FUNCTION)
</code>
Note that [[api/building_function|BUILDING_FUNCTION]]s do not need the ''SAVE_GAME'' flag as their properties are read from their registration on load. As such it is not possible to save runtime data in them directly!

Also remember that you can define properties based on the basic [[data-types|data types]] (i.e. string, integer, float, etc.) or based on any of the existing [[api#data_classes|DATA]] or [[assets|ASSET]] objects, as well as ''list''s therof!

==== Step 2: Registering an Instance of a BUILDING_FUNCTION Class ====
Note: This also aplies to using vanilla BUILDING_FUNCTION classes!

In your mod's lua code you when you want to register an instance of your new [[api/building_function|BUILDING_FUNCTION]] class you will have to use the ''mod:registerAsset(AssetTable)'' method as follows.
<code lua>
mod:registerAsset({
    DataType = "MY_BUILDING_FUNCTION",
    Id = "MY_BUILDING_FUNCTION_INSTANCE",
    Property1 = "SomeOtherString",
    Property3 = 5
})
</code>
Remember, each unique [[api/building_function|BUILDING_FUNCTION]] instance requires an Id that identifies it from other [[api/building_function|BUILDING_FUNCTION]]s of the same class.

In case you omit any properties you don't yet need to explicitly set they will use their default values. As we have done with ''Property2'' above.

==== Step 3: Using an Instance of a BUILDING_FUNCTION Class ====
When you want to use your new [[api/building_function|BUILDING_FUNCTION]] instance in a [[api/building_part|BUILDING_PART]] registration you can use the string Id to reference it by name.
<code lua>
mod:registerAsset({
    DataType = "BUILDING_PART",
    Id = "MY_BUILDING_PART",
    .
    .
    .
    AssetBuildingFunction = "MY_BUILDING_FUNCTION_INSTANCE"
})
</code>