This API allows mod authors to add custom under-buildings to this system for use by the AI by way of templates. Each template is made up of at least 1 under-building. When a new under-city is detected, this system finds all templates that are valid for the given region and then randomly selects one of them. Mod authors are able to provide their own custom 'condition()' function for each template. This condition function is called to determine if a template is a good fit for the current region. For more detailed information, see the function descriptions below.

- aiut_add_building(buildingKey, properties)
- aiut_update_building(buildingKey, properties)
- aiut_remove_building(buildingKey)
- aiut_add_template(templateName, templateBuildings, useSpecialWeight, factionKey)
- aiut_get_template(templateName, factionKey)
- aiut_remove_template(templateName, factionKey)

The aiut_add_building function adds a new building and its associated properties to the system. This allows templates to make use of this building.

Parameters

• buildingKey (string): A unique identifier for the new building. This key must not already exist in the system.
  
• properties (table): A table containing various properties of the building. Some properties are mandatory, while others are optional.
  
  • Mandatory Property
    
    • delay (integer): The number of turns before the building is constructed. This simulates the construction time. It must be a non-negative integer.
      
  • Optional Properties
    
    • upgrade (string): The building key this building may upgrade into.
      
    • gdp (integer): The income produced or cost of the building per turn. Costs should be negative numbers.
      
    • food (integer): The amount of food produced or cost of the building per turn. Costs should be negative numbers.
      
    • discoverability (integer): The discoverability increase or decrease provided by the building. Decreases should be negative numbers.
      
    • isDestructive (boolean): Indicates whether the building causes obvious harm to the host settlement (e.g., Doomsphere, Plague Cauldron, Vermintide).
      
    • warRequired (boolean): If true, the building can only be constructed when the under-city faction is at war with the settlement faction.
      

Returns

• boolean: Returns true if the building is successfully added to the system. Returns false if there was a problem adding the building, such as a non-unique buildingKey, invalid property types, or cyclic upgrade links.

Error Handling
The function performs several checks to ensure data integrity:

• Verifies the uniqueness of buildingKey.
  
• Ensures all mandatory properties are present and valid.
  
• Validates the data types of both mandatory and optional properties.
  
• Checks for cyclic upgrade links to prevent buildings from upgrading in a loop.

Examples

The aiut_update_building function is used to replace the properties of an existing building in the system.

Parameters

• buildingKey (string): The unique identifier of the building to be updated. This key must already exist within the system.
  
• properties (table): A table containing the new properties of the building. The function ensures that the mandatory property is present and that all provided properties have valid data types.
  
  • Mandatory Property
    
    • delay (integer): The number of turns before the building is constructed. It must be a non-negative integer.
      
  • Optional Properties
    
    • upgrade (string): The building key this building may upgrade into.
      
    • gdp (integer): The income produced or cost of the building per turn. Costs should be negative numbers.
      
    • food (integer): The amount of food produced or cost of the building per turn. Costs should be negative numbers.
      
    • discoverability (integer): The discoverability increase or decrease provided by the building. Decreases should be negative numbers.
      
    • isDestructive (boolean): Indicates whether the building causes obvious harm to the host settlement (e.g., Doomsphere, Plague Cauldron, Vermintide).
      
    • warRequired (boolean): If true, the building can only be constructed when the under-city faction is at war with the settlement faction.
      

Returns

• boolean: Returns true if the building is successfully updated within the system. Returns false if there was a problem updating the building, such as a non-existent buildingKey, invalid property types, or cyclic upgrade links.

Error Handling
The function performs several checks to ensure data integrity:

• Verifies the existence of buildingKey in the system.
  
• Ensures the mandatory 'delay' property is present and valid.
  
• Validates the data types of both mandatory and optional properties.
  
• Checks for cyclic upgrade links to prevent buildings from upgrading in a loop.

Examples

The aiut_remove_building function is designed to remove a specified building from the system. It also removes any upgrade references to this building from other buildings in the system.

Parameters

• buildingKey (string): The unique identifier of the building to be removed. This key must exist within the system for the function to proceed.

Returns

• boolean: Returns true if the building is successfully removed from the system. Returns false if the building was not found within the system.

Behavior

• The function first checks if the specified building exists within the system.
  
• If the building exists, it iterates over all buildings in the system.
  
• For each building, it checks if it has an 'upgrade' property pointing to the building being removed. If found, this reference is removed.
  
• Finally, the specified building is removed from the system.

Error Handling

• The function does not perform extensive error checking beyond verifying the existence of the buildingKey in the system.
  
• If the building is not found, the function returns false, indicating failure to remove.

Examples

The aiut_add_template function is used to create a new template and add it to the template pool. The factionKey and useSpecialWeight parameters are optional. This system will not upgrade buildings past the point defined here. The AI may do so however and, if detected, this system will downgrade buildings to match the template.

Parameters

• templateName (string): The unique name of the new template. This name must not already exist in the template pool.
  
• templateBuildings (table): A table of building keys included in the template. Each key must correspond to a building added using aiut_add_building.
  
• useSpecialWeight (boolean, optional): Determines if the template should be weighted within the template pool using the specialWeight MCT setting. Defaults to false if not provided.
  
• factionKey (string, optional): Identifies the faction associated with this template. If not provided, the template is added to the general pool making it available to all Skaven factions.

Returns

• Table: Returns the newly created template object if successful; nil if the template could not be created due to errors.

Error Handling

• Checks for valid input, unique templateName, and existing building keys in templateBuildings.
  
• Validates the number of buildings against the maximum allowed build slots MCT setting.
  
• Ensures useSpecialWeight is a boolean, when provided.
  
• Errors are logged.

Template Condition Function

• Users should redefine the default condition() method that the template object comes with. The condition() method should return either true or false, and will return false by default if not redefined.
  
• The condition() function will have a 'context' variable passed to it with properties: context.region, context.underFaction, and context.foreignSlotManager.

Example

The aiut_get_template function retrieves a specified template table, allowing access to the entire template object the system uses, and providing some extra properties and methods. It is recommended that this be treated as read-only data, as there is no way to modify the template this way and then reintroduce it to the system.

Parameters

• templateName (string): The unique name of the template to be retrieved. This name should correspond to a template added using aiut_add_template.
  
• factionKey (string, optional): The faction identifier associated with the template. If not provided, the function searches in the general template pool, rather than the faction-specific template pool.

Returns

• Table: Returns the template table if found. If the template does not exist, the function returns nil.

Error Handling

• Ensures that templateName is a valid string. If not, it logs an error and returns nil.
  
• Validates the existence of the specified faction's template pool if a factionKey is provided. If the pool does not exist, it logs an error and returns nil.

Examples

The aiut_remove_template function is designed to remove a specific template from the system. It can target either the general template pool or a faction-specific template pool, depending on the parameters provided.

Parameters

• templateName (string): The unique name of the template to be removed. This name should correspond to a template previously added using aiut_add_template.
  
• factionKey (string, optional): The faction identifier associated with the template. If provided, the function attempts to remove the template from the faction-specific template pool. If not provided, it targets the general template pool.

Returns

• Boolean: Returns true if the template is successfully removed from the system. Returns false if the template was not found.

Error Handling

• The function logs an error if the template with the specified templateName is not found in the relevant template pool.
  
• If the template is successfully removed, a confirmation message is logged.

Examples

- I recommend enabling logging for this mod, if it's not already enabled, as it will contain any API call errors.
- Steam isn't the best place for documentation like this, so let me know if you have questions.
- This mod has additional examples of how aiut_add_template is used in one of the script files.