Modular Constructions

Modular constructions are built like every other construction with parameters but can be edited afterwards by adding and removing some parts like pieces of a puzzle. These parts are called modules. The locations where they can be placed are indicated by slots.

To provide different start configurations, it is possible to define construction templates.

Whenever a construction shall be previewed or actually built, a meta function is executed that orchestrates the execution of update functions for the whole construction as well as the individual modules.

It first calls the updateFn function of the construction and stores its result. If the parameters contain modules - both via template calls or during construction reconfiguration - a second part is executed. For each module, sorted in ascending order of the slotIds, the following steps are executed:

1. Search for the slotId in the list of existing slots in the current result set from the construction and previous modules.
2. If the slotId is not in the list and invalid slots are not accepted (result.callInvalidModules unset or false) skip the current module.
3. Fetch the slot location and tag name.
4. Prepare the addModel function.
5. Call the updateFn function of the module and provide the addModel function.

Finally if the construction added a terminateConstructionHook, that will be executed.

The updateFn function of the construction is used to assemble the core elements of the construction add put them in the result data struct. This may cover basic models, ground faces and terrain alignments as well as additional functions that can be called from modules later:

...
updateFn = function(captureParams, params)
  ...
  return result
end
...

Beside the usual parameters of a construction updateFn, it receives a list of all modules that should be built for the construction in modules:

  modules = {
    [10001000] = {
      metadata = {},
      name = "airfield_main_building.module",
      updateScript = {
        fileName = "",
        params = {}
      },
      variant = 0
    },
    ...
  },

The index is the slotID where the module should be placed. The properties are:

• metadata is a struct containing all the metadata that was set in the metadata struct of the module.
• name is the reference to the module relative to the construction.
• updateScript is the reference to the module updateFn function.
• variant is an integer that is increased and decreased by pressing M and N while placing a module. It can be used to provide rotated variants of models in a module or cycle through different assets. The value can be positive and negative, default is 0.

The result data struct is based on the one from normal constructions. On top there are additional structs specifically for modular constructions:

• result.slotConfig for slot type restrictions.
• result.slots for a list of slots currently available in the construction.

It is possible that construction extend the result by custom structs, e.g. helper functions that can then be used by modules at a later point.

In the result.slotConfig list, there can be restrictions for some slot types. The list uses the slot type as a key and contains two properties for each entry:

• maxModules is the maximum amount of modules with this slot type that can be built in the whole construction. If maxModules is set to -2, it depends on the value of message if the module button is enabled or disabled. No messages results in the button being enabled, a set message disables the button.
• message is a message that is displayed on modules of this type in the menu, when they can't be build due to the slot configuration restrictions.
• skipCollisionCheck is an optional boolean value that is used to disable the ui collision checks. With skipped checks, the slot markers are not painted red when they are obstructed by something else, e.g. free tracks. The potential collider collisions of the module models still apply.

The result.slots struct is a list of all currently existing slots in the construction. Each entry in the list has the following properties:

• id is the unique slot id that is used as reference for the placed modules. It is a non-negative number.
• type is the key that is used to restrict the compatible modules on this position.
• transf is the position relative to the construction origin as a transformation matrix.
• spacing is a four value vector that is used to set the size of the slot around the transf position. It is {-x, x, -y, y }.
• shape is a value that is used to select the style of the slot marker symbol. It is either 0 for a square, 1 for a triangle, 2 for a transverse rectangle or 3 for a longitudinal rectangle.
• height is the height of the slot counted from the position of transf. Together with the spacing this is used for selection and bulldozing purposes.
• autofill is a boolean value used for industry fields/satellites. If set to true, these slots are considered to be filled on initial construction of the industry.
• alignToTerrain is a boolean value used for constructions that should adapt to the terrain. If set to true, the slot is considered to be aligned to the terrain height at its position.
• replaceable is a boolean value used to mark slots where modules may be overridden by modules of the same type.

With result.callInvalidModules set to true it is possible to allow modules in slots that were not predefined, e.g. because they have an ID that is lower than the slot that defines them.

The upgradeScript function for modular buildings is only slightly different than the one for non-modular constructions. The slotId parameter contains the slotId where the cursor pointed on when applying the tool.

A module is a construct of one or more models that can be placed in certain positions in modular constructions. They are defined in .module.lua files. The basic structure of a module is:

function data()
return {
  availability = { ... },
  menuCategory = { ... },
  description = { ... },
 
  buildMode = "SINGLE",
  autoRemovable = false,
 
  type = "shed",
  metadata = {
    price = 12000,
    maintenanceCost = 2000,
  }
 
  getModelsScript = {
    fileName = "roundhouse_modules.script@shed.getModelsFn",
    params = {
      ...
    },
  },
 
  updateScript = {
    fileName = "roundhouse_modules.script@shed.updateFn",
    params = {
      ...
    },
  },
}
end

Beside the usual availability, description, menuCategory and buildMode known from constructions, each modules has additional properties:

• autoRemovable is an optional property to flag this module for automatic removal when something else is built over it. This is used for fields of industries. If unset, it is considered as false
• type is a key that is used to restrict modules to a certain slot type

To provide additional static metadata, the modules can provide more information in a metadata struct. It might be used by the construction and other modules to identify this module properly. It also may contain info about the build and maintenance cost of the module.

Before a module is actually placed, the getModelsScript is used to provide the models for a floating module preview attached to the cursor. The updateScript references the update function that is executed on update of the construction. It may receive additional parameters as captureParams. See below for more details.

The getModelsFn is a function without any parameters other than captureParams. It returns a list of models that should be used for the floating preview that follows the mouse cursor while not pointing on a slot. The function looks like:

...
getModelsFn = function()
  local result = {
    { 
      id = "hangar_preview.mdl",
      transf = transf.identity(),
    }
  }
  return result
end,
...

The updateFn function of modules is called after the construction updateFn to add the models of the module to the construction as well as do all the stuff that is needed for the module, e.g. adding terminals. It receives several parameters:

1. the captureParams provided by the script reference in the .module.lua
2. the result of the updateFn from the construction or the module that was called before containing all previously added models, data etc.
3. the transformation of the slot relative to the construction origin as a transformation matrix. This should be applied to all models of the module if they are located relative to the slot. Be aware that the transformation is nil if the construction makes use of the callInvalidModules property.
4. a tag that should be added to the models in the result to assign them to the current module at that slot. This is used to identify models that are removed when a module is demolished.
5. the slotId that is a unique numeric identifier of this slot.
6. the addModuleFn function is a function that adds models to the construction and ensures that the correct tag is set. It is provided in the construction.script.tl in constructWithModules.
7. the constrParams struct containing all params that the construction got for its updateFn function too.

Note that not all modules need every parameter. It is possible to omit parameters from the end of the function header. A function that uses only some of the parameters could look like:

...
updateFn = function(captureParams, result, transform, tag)
  result.subconstructions[1].models[#result.subconstructions[1].models + 1] = { 
    id = "hangar.mdl",
    transf = transform,
    tag = tag
  }
 
  local faces = { {-25.0, -25.0, 0.0, 1.0}, {25.0, -25.0, 0.0, 1.0}, ... }
  modulesutil.TransformFaces(transform, faces)
  result.subconstructions[1].groundFaces[#result.subconstructions[1].groundFaces + 1] = {  
    face =  faces,
    modes = {
      {
        type = "FILL",
        key = "airfield_hangar.gtex.lua",
	texCoords = { {.0, .0}, {1.0, .0}, {1.0, 1.0}, {.0, 1.0} }
      },
    }
  }
 
  -- add further stuff		
end,
...

The updateFn should return the result that was received where the content of the module was inserted.

...
local modelConfig = {
  stands = resolve("roof_hall_stands.mdl"),
}
... 
  updateScript = {
  fileName = "station_hall_modules.script@platformPassengerHallRoof.updateFn",
  params = {
    modelConfig = modelConfig,
  },
},
getModelsScript = {
  fileName = "station_hall_modules.script@platformPassengerHallRoof.getModelsFn",
  params = {
    modelConfig = modelConfig,
  },
},
...

...
type = "passenger_platform_roof",
metadata = {
  platform_roof = true,
  platform_roof_curved = true,
  platform_roof_hall_style = "test",
  maintenanceCost = 0,
},
...

local updateFnPlatformPassengerHallRoof = function(captureParams, result, transform, tag, slotId, addModel, constrParams, params)
  local modelConfig = captureParams.modelConfig
  result = result.cargoStation
  local addModelFn = function(a, b, c) addModel(a, b, c, result.models) end
 
  addModelFn(modelConfig.stands, transf.rotZTransl(math.rad(90), vec3.new(0, 0, -2)))
 
  local coords = result.GetCoord(slotId)
  local i = coords[1]
  local j = coords[2]
 
  for i2 = i+1, i+9 do
    local roofAti2 = result.GetRoofAt(i2, j)
    if roofAti2 and roofAti2.metadata.platform_roof_hall_style == result.GetRoofAt(i, j).metadata.platform_roof_hall_style then
      local roofModel = hallRoofStyle2Size2ModelsConfig[roofAti2.metadata.platform_roof_hall_style][(i2-i)*5]
      addModelFn(roofModel, transf.rotZTransl(math.rad(-90), vec3.new(0, 0, -2)))
      break
    end
  end
end

...
mainSubconstruction.models[#mainSubconstruction.models + 1] = {
  id = "turntable.mdl",
  transf = transf.identity()
}
...

...
result.slots = { }
 
for i = 1, 30 do
  result.slots[i] = {
    id = i,
    type = "shed",
    transf = transf.mul(transf.rotZ(math.rad(-12 + i * 12)), transf.transl(vec3.new(30, 0, 0))),
    spacing = {4, 4, 1, 1},
    shape = 1,
    height = 1,
    replaceable = true,
  }
end
...

function data()
  return {
    shed = {
      updateFn = updateFnShed,
      getModelsFn = getModelsFnShed,
    },
    empty = {
      updateFn = updateFnEmpty,
      getModelsFn = getModelsFnEmpty,
    },
  }
end

...
local getModelsFnShed = function(captureParams)
  return {
    { 
      id = "shed_wall_left.mdl", 
      transf = transf.transl(vec3.new(-30,0,0)) 
    },
    { 
      id = "shed_segment.mdl", 
      transf = transf.transl(vec3.new(-30,0,0)) 
    },
    { 
      id = "shed_wall_right.mdl", 
      transf = transf.transl(vec3.new(-30,0,0)) 
    }
  }
end
...

...
local leftIndex  = (slotId % maxSegments) + 1
local rightIndex = ((slotId - 2) % maxSegments) + 1
 
local moduleLeft = constrParams.modules[leftIndex]
local moduleRight = constrParams.modules[rightIndex]
...

...
if not (moduleLeft ~= nil and moduleLeft.metadata ~= nil and moduleLeft.metadata.type == "shed") then
  addModel("shed_wall_left.mdl", transf.transl(vec3.new(-30, 0, 0)), tag, result.subconstructions[1].models)
end
if not (moduleRight ~= nil and moduleRight.metadata ~= nil and moduleRight.metadata.type == "shed") then
  addModel("shed_wall_right.mdl", transf.transl(vec3.new(-30, 0, 0)), tag, result.subconstructions[1].models)
end
...