User Tools

Site Tools


custom-building-function

BUILDING_FUNCTION classes are registerable types in Foundation that define what purpose a certain BUILDING_PART will serve in the game.

For reference all available BUILDING_FUNCTION classes can be found in 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 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 BUILDING_FUNCTION object will contain. Furthermore you can override default BUILDING_FUNCTION methods as well as define custom ones.

local MY_BUILDING_FUNCTION = {
    TypeName = "MY_BUILDING_FUNCTION",
    DataType = "BUILDING_FUNCTION",
    Properties = {
        { Name = "Property1", Type = "string", Default = "SomeString" },
        { Name = "Property2", Type = "list<RESOURCE_QUANTITY_PAIR>" },
        { Name = "Property3", Type = "integer", Default = 1 }
    }
}

Now that the base BUILDING_FUNCTION Lua Table is ready we can define functions for it before registering it.

All BUILDING_FUNCTIONs have three base functions that can be overriden, activateBuilding, reloadBuildingFunction, and removeBuildingFunction.

activateBuilding is called the first time a BUILDING_FUNCTION is instantiated in game be it because the 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 BUILDING_FUNCTION to work, for example in the case of BUILDING_FUNCTION_WORKPLACE this function creates the COMP_WORKPLACE necessary for assigning workers to the 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 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 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.

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

And finally we register our custom BUILDING_FUNCTION class.

mod:registerClass(MY_BUILDING_FUNCTION)

Note that BUILDING_FUNCTIONs 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 (i.e. string, integer, float, etc.) or based on any of the existing DATA or ASSET objects, as well as lists 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 BUILDING_FUNCTION class you will have to use the mod:registerAsset(AssetTable) method as follows.

mod:registerAsset({
    DataType = "MY_BUILDING_FUNCTION",
    Id = "MY_BUILDING_FUNCTION_INSTANCE",
    Property1 = "SomeOtherString",
    Property3 = 5
})

Remember, each unique BUILDING_FUNCTION instance requires an Id that identifies it from other BUILDING_FUNCTIONs 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 BUILDING_FUNCTION instance in a BUILDING_PART registration you can use the string Id to reference it by name.

mod:registerAsset({
    DataType = "BUILDING_PART",
    Id = "MY_BUILDING_PART",
    .
    .
    .
    AssetBuildingFunction = "MY_BUILDING_FUNCTION_INSTANCE"
})
custom-building-function.txt · Last modified: 2022/04/30 19:23 by minotorious