Foundation - Modding Documentation

annotations

Anonymous (anonymous@undisclosed.example.com) — 2022-08-16T14:56:34+00:00

Annotations Type annotations Single-property type A type with this annotation contains only a single serialized property. Thus, to make the syntax lighter, instantiation for this type can be done by simply providing the value of the single property. foundation.createData({ DataType = "BUILDING_PART_COST", ResourceNeededList = { -- list of RESOURCE_COLLECTION_VALUE -- Can be serialized in full, like any other type { Collection = { { Resource = "WOOD", Quantity = 20 }, { Re…

api

Anonymous (anonymous@undisclosed.example.com) — 2026-04-15T14:39:17+00:00

API Engine Core * COMPONENT * COMPONENT_MANAGER * GAME * GAME_OBJECT * LEVEL Assets Classes * ABSTRACT_QUEST * AGENT_NEED_TYPE * AGENT_NEED_TYPE_HOUSING * AGENT_NEED_TYPE_LODGING * AGENT_NEED_TYPE_RESOURCE * AGENT_NEED_TYPE_SOLDIER_EQUIPMENT * AGENT_NEED_TYPE_SOLDIER_HEALING * AGENT_NEED_TYPE_SOLDIER_TRAINING * AGENT_NEED_TYPE_VISIT_BUILDING * AGENT_PORTRAIT * AGENT_PROFILE * ASSET * ASSIGNABLE_BUILDING_FUNCTION_LIST * ATLAS_CELL * AUDIO_EVENT * BALA…

asset-override

Anonymous (anonymous@undisclosed.example.com) — 2019-09-26T21:09:49+00:00

Asset Override All game assets (and other mods assets) can be override by mods, partially or totally. The mod:override function should be used for that purpose. Overriding specific values myMod:override({ Id = "DEFAULT_BALANCING", InitialFamilyCount = 1, MinimumHappinessForLeaving = 30 })

assets

Anonymous (anonymous@undisclosed.example.com) — 2026-04-15T14:39:17+00:00

Assets * AGENT_NEED_TYPE_HOUSING * AGENT_NEED_TYPE_LODGING * AGENT_NEED_TYPE_RESOURCE * AGENT_NEED_TYPE_SOLDIER_HEALING * AGENT_NEED_TYPE_SOLDIER_TRAINING * AGENT_NEED_TYPE_VISIT_BUILDING * AGENT_PROFILE * ASSET * ASSIGNABLE_BUILDING_FUNCTION_LIST * ATLAS_CELL * BALANCING * BEHAVIOR_TREE * BIOME_LAYER * BLUEPRINT * BUILDING * BUILDING_FUNCTION * BUILDING_GAME_CONDITION_CONFIG * BUILDING_PART * BUILD_MENU_CONFIG * CHANGE_EDICT_MANDATE_TYPE * CHANGE_PRIVI…

behavior-trees

Anonymous (anonymous@undisclosed.example.com) — 2021-07-29T15:56:32+00:00

Behavior Trees You can find an example of behavior tree and behavior tree node creation in the following mods: * Example 01 (file wooden_keep_guard_locator.lua) * Example 02 (file scripts/behavior_tree.lua). Register new behavior trees You can now create custom behavior tree assets with

building-asset-processor

Anonymous (anonymous@undisclosed.example.com) — 2025-06-27T16:15:33+00:00

Building Asset Processor You can register a BUILDING_ASSET_PROCESSOR on any FBX to partially automatize the configuration of your building or monument building part nodes. Register the asset processor on a FBX like that: -- Apply building asset processor mod:registerAssetProcessor("models/MithrilFactory.fbx", { DataType = "BUILDING_ASSET_PROCESSOR" })

changelog

Anonymous (anonymous@undisclosed.example.com) — 2026-04-15T14:41:35+00:00

Changelog Foundation Full Release (1.11) * Full Changelog * 1.11.0.17 Changelog * 1.11.0.14 Changelog * 1.11.0.12 Changelog * 1.11.0.8 Changelog Foundation 1.10 * Full Changelog * 1.10.3.12 Changelog * 1.10.3.11 Changelog * 1.10.3.10 Changelog * 1.10.3.8 Changelog * 1.10.3.6 Changelog * 1.10.3.4 Changelog * 1.10.3.3 Changelog * 1.10.3.1 Changelog * 1.10.2.15 modding 4 Changelog * 1.10.2.15 modding 3 Changelog * 1.10.2.15 modding 2 Changelog Foundation 1.9 …

class-info

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T22:59:32+00:00

Class Info This is a table defining a custom class to be registered with the mod:registerClass() function. { TypeName = "MY_TYPE_NAME", ParentType = "ASSET", Properties = { { Name = "Property1", Type = "string", Default = "SomeString" }, { Name = "Property2", Type = "list" }, { Name = "Property3", Type = "integer", Default = 1, Flags = { "SAVE_GAME" } } } }

communityapi

Anonymous (anonymous@undisclosed.example.com) — 2022-05-02T09:57:38+00:00

Community API Foundation Extended Building Functions Mod Dependency: Foundation EBF ---------- Data & Assets * GROWING_STEP_LIST * UPS_OBJECT_SETUP * UPS_OBJECT_SETUP_LIST ---------- Building Functions Animations * BUILDING_FUNCTION_SINGLE_DOOR * BUILDING_FUNCTION_DOUBLE_DOOR * BUILDING_FUNCTION_PORTCULLIS * BUILDING_FUNCTION_SIMPLE_DRAWBRIDGE Particle Emitters * BUILDING_FUNCTION_ACTIVATED_PARTICLE_EMITTER * BUILDING_FUNCTION_DEACTIVATED_PARTICLE_EMITTER Resource P…

components

Anonymous (anonymous@undisclosed.example.com) — 2020-07-08T14:21:08+00:00

Components Components are small modules used to define the behavior of any game object. Game objects can have any number of components, but can have only one of each type. See the list of all available components. You can also define your own custom components. ---------- Components can be added to any FBX node with the

construction-steps

Anonymous (anonymous@undisclosed.example.com) — 2021-10-21T17:28:06+00:00

Construction steps Buildings and building parts are built step by step. The construction system is based on naming. You can specify a prefab to be used as construction visual. The system will parse the prefab and search for objects with a name starting with

custom-asset

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T22:19:18+00:00

ASSET classes are the basic registerable types in Foundation. For reference all available ASSET classes can be found in this section of the API. Creating & Using a Custom ASSET Object Step 1: Defining an ASSET Object using a Lua Table To create a custom ASSET object we will need to make use of the

custom-building-function

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T22:20:08+00:00

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

custom-classes

Anonymous (anonymous@undisclosed.example.com) — 2022-03-30T00:36:35+00:00

Custom Classes You can define new types with the mod:registerClass function. This function allows you to create new data types, or extend existing core classes. When you define a new type, you can assign it functions and properties. Properties are editable, usable in your type's behavior, and that can be saved in a savegame. Those properties must have a name and a type. They can also have a default value, flags, and access functions (getter and setter).

custom-data

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T22:49:27+00:00

DATA classes are the most basic type in Foundation that all other types are based on. For reference all available pure DATA classes can be found in this section of the API. Creating & Using a Custom DATA Object Step 1: Defining a DATA Object using a Lua Table

data-types

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:50:31+00:00

Data Types ---------- boolean local value = true ---------- integer and unsigned integer Integer number. Cannot be negative for unsigned integers. local value = 42 ---------- float Floating-point number with single precision local value = 17.44

debugging-mods

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:52:50+00:00

Debugging Mods Lua development environments can be configured to debug Foudation mods. Debuggee script The first step in debugging a mod is to setup the chosen debugger in the VM. This cannot be done by the mod scripts themselves as it requires escaping the sandbox they operate in; the required setup must be placed in a special

dependencies

Anonymous (anonymous@undisclosed.example.com) — 2020-07-14T17:15:29+00:00

Dependencies Hard dependency If your mod depends on features/content created in another mod, you can declare this other mod as a hard dependency of yours. Doing so will warn players if they try to use your mod without its dependencies. To declare dependencies for your mod, add a

enumerations

Anonymous (anonymous@undisclosed.example.com) — 2021-03-09T13:10:23+00:00

Enumerations An enumeration (or enum) is a data type containing a set of constant values. See the list of all available enumerations. ---------- Previously, you could only refer to enum elements as strings. For example, to define the building type of a building, you used BuildingType = “GENERAL”. Now, all enum values are stored in their enum type's table. This allows for a more clear syntax:

events

Anonymous (anonymous@undisclosed.example.com) — 2020-05-22T16:23:39+00:00

Events Some core types use events. These events can be used to run a function when a certain trigger happens on a specific object. Triggering events To trigger an event on an object, call this event from the chosen object. Events are designed to be triggered by their owner, and listened to by other objects.

example-mods

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:52:25+00:00

Example Mods You can find the example mods in your Foundation installation directory, under the mods folder. Example - Simple This example mod shows the basic structure of a Foundation mod and can be used as boilerplate code for getting started Example - Mithril Factory

foundation-library-functions

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:53:10+00:00

Foundation Library Functions createMod Creates and returns a new mod void foundation.createMod() ---------- isModEnabled Checks if a mod is enabled Returns true if the mod is found and it is enabled, false otherwise boolean foundation.isModEnabled

foundation

Anonymous (anonymous@undisclosed.example.com) — 2019-05-31T20:29:23+00:00

foundation createMod local myMod = foundation.createMod();

guides

Anonymous (anonymous@undisclosed.example.com) — 2021-05-10T15:15:47+00:00

Community Guides Building Set-Up * Adding Platform Collider to a Building * Defining Building's Worker Path * Having 2 Scales on the same Building * Options for Workplaces * How to Randomly set Doors and Windows on a Building ---------- Custom Components * Computing Ground or Water Elevation at a Point * Triggering Code on Villager Approaching a Point * Tips on Quaternions ----------

level-of-detail

Anonymous (anonymous@undisclosed.example.com) — 2020-04-28T22:24:13+00:00

Level Of Detail To reduce the rendering performance impact of models with high triangle counts or models with a lot of instances, Hurricane supports levels of detail (LOD). This allows models to be rendered with a different mesh at different distances to the camera.

material-sets

Anonymous (anonymous@undisclosed.example.com) — 2020-04-28T22:36:07+00:00

Material Sets Like the church, a monument can have material sets. This means that each material (base and replacement) must be listed in your monument asset property MaterialSetList. For each material set, all materials must be listed in the same order as their replacement:

migration

Anonymous (anonymous@undisclosed.example.com) — 2023-09-05T15:21:43+00:00

Migration Notes Foundation 1.9.6 Trading Village In 1.9.6, we simplified TRADING_VILLAGE's list of resources by simply requiring a list of assets. -- OLD WAY -- Register an addition neighbour to trade with. saltTrader:registerAsset({ DataType = "TRADING_VILLAGE", Id = SaltPrefix .. "_VILLAGE_NANTES", Heraldry = "ICON_" .. CommonResourceSalt, Description = SaltPrefix .. "_VILLAGE_NANTES_DESC", VillageName = "Nantes", --RESOURCE QUANTITY PAIR UnlockCost = { { Resource…

mod-io-functions

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:54:01+00:00

Mod IO Functions All these functions are available on your mod object fileExists Checks if a file exists in the mod directory. Returns true if the file is inside the mod directory and exists, false otherwise boolean myMod:fileExists(filePath) Name

mod-management-functions

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T22:02:38+00:00

Mod Management Functions All these functions are available on your mod object dofile Loads and runs a Lua script Returns the file's return values [...] myMod:dofile(scriptPath [, args...]) Name Type Description scriptPath string the relative path to the file, inside the mod directory

monuments

Anonymous (anonymous@undisclosed.example.com) — 2019-09-26T21:08:40+00:00

Monuments Monuments are complex buildings that let the player assemble different building parts. The different BUILDING_CONSTRUCTOR allow to create different type of parts, like scalable tower, bridges, etc. Here is an example of declaring a new monument, allowing a collection of building parts:

particle-effects

Anonymous (anonymous@undisclosed.example.com) — 2019-09-26T21:09:33+00:00

Particle Effects PARTICLE_SYSTEM asset configure a certain type of particle system. COMP_PARTICLE_EMITTER component is attached to a game object and emit the particle system in the scene. COMP_PARTICLE_EMITTER_TOGGLE is a particle emitter controller that will just stop and restart the COMP_PARTICLE_EMITTER attached to the same game object when disabled / enabled. It is especially used to control particle system emission during production cycle in workplaces to avoid directly turning on and of…

sidebar

Anonymous (anonymous@undisclosed.example.com) — 2025-11-26T17:38:33+00:00

* Home * Scripting API * Assets * Changelog * Migration notes * Community Guides * Community API * Texture Pack

start

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:51:56+00:00

Welcome to the Foundation Modding Wiki Warning Modding capabilities are very embryonic. Expect a lot of improvement and changes in the future. This documentation is a draft with a few guidelines, it will evolve gradually with the development of modding features.

texture-pack

Anonymous (anonymous@undisclosed.example.com) — 2026-01-05T20:14:08+00:00

Texture Pack Mods can reference game textures, making it easy to adopt the Foundation art style. To support modders, Polymorph Games provides a package of watermarked textures for use in 3D software. You can reference a Foundation texture into a mod using the texture file name, however:

texture-usage-policy

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:52:39+00:00

Game Texture Usage Policy Game textures may be called into a mod, this has the advantage of easily adopting the Foundation art style whilst also preventing copyright infringement. This method also has the added benefit of optimizing texture usage in the game engine by not duplicating textures.

version-library

Anonymous (anonymous@undisclosed.example.com) — 2026-02-23T21:53:34+00:00

Version Library cmp Compare two version numbers Returns: * 0 if version1 == version2 * -1 if version1 < version2 * 1 if version1 > version2 integer version.cmp(version1, version2) Name Type Description version1 string version2 string

walls

Anonymous (anonymous@undisclosed.example.com) — 2019-09-26T21:09:21+00:00

Walls See WALL_CONFIG api page. See Mod Example 02, scripts/sci_fi_wall/wall.lua. CrenationDistance Width Height UvTilingWall UvTilingTop WallOffsetY CrenationOffsetY CrenationOffsetZ

workplaces

Anonymous (anonymous@undisclosed.example.com) — 2019-09-26T21:08:00+00:00

Workplaces A workplace is a building containing a BUILDING_FUNCTION_WORKPLACE. Example of declaring a workplace building function -- Register the mithril factory extension B part mod:register({ DataType = "BUILDING_PART", Id = "MITHRIL_FACTORY_EXTENSION_B_ROOT_PART", -- [...] BuildingFunction = { DataType = "BUILDING_FUNCTION_WORKPLACE", WorkerCapacity = 1, RelatedJob = { Job = "MITHRIL_ARTISAN", Behavior = "WORK_BEHAVIOR" }, InputInventoryCapacity = {{ Resource = "MITHRIL_ORE",…