Adding Buildings and Professions into Banished

[catty-cb 4,413]

This example mod adds a new building, a new edible item, and a new profession. In this case the building is an apiary, the building produces honey, and the profession is a bee keeper. If you want to build and test the mod...

bin\x64\Tools-x64.exe /build apiaryResources.rsc /pathres ../example/building /pathdat ../example/building/bin

You should now be able to run the game and see that the apiary is available from the food menu. Note that before the mod is packaged, you have to explicitly tell the game to load the resources using the /ref parameter. In the translation example, resources were simply overridden so no reference was required - the game references them already. Without the reference the new resources won't be loaded.

bin\x64\Application-x64-profile.exe /ref apiaryResources.rsc /pathres ../example/building /pathdat ../example/building/bin

Start a new game, and click on the Food Production icon - you should see the new building listed with an icon of honeycomb. You can place the building, have it built, and assign workers to it. In the professions dialog, the new profession of Bee keeper should be listed as well.

As with the translation example, you can build the mod as a package like so:

bin\x64\Tools-x64.exe /mod Package.rsc:apiary /pathres ../example/building /pathdat ../example/building/bin

To test the mod by itself, you can run the game forcing it to only use packages.

bin\x64\Application-x64-profile.exe /onlypkg

The game should have the new mod listed in the Mods dialog and you can enable it.

Adding a new building requires many resources that are tied together - meshes, textures, materials, entity descriptions, text, sprites, and terrain decals. Below are the general steps to making a new building.

General steps to making a new building and profession.

1. Model the building and all intermediate construction models.
   • See /example/building/Models/apiary.fbx
2. Make sure the objects are properly centered around their pivot. For example, a building that is 4x5m and it's corner is at (0, 0, 0) should have the pivot at (2, 2.5, 0)
3. Assign materials to the building. The name of the material defines the material name on disk. Materials need to be in a MaterialInstance folder, in the same directory as the model. If not found there, the tool will check parent directories up until the resource root for a properly named material.
4. Add dummy helper objects to define locations for use.
   • Helpers named build_XXX are where workers will stand when constructing the building
   • Helpers named use_XXX are where workers will stand when working at the building.
   • Helpers named create_XXX are resources will be created at the building.
   • Helpers for particle system attachments can be named arbitrarily, for example, the smoke from the building.
5. Unwrap the model for texturing.
6. The first UV channel for a building is used by the material with the primary texture (unless you make new shaders with different behavior).
7. The second UV channel is used for an ambient occlusion texture. Each construction model needs its own AO texture.
8. If the building has sections above the terrain, make a very low res 'floor' object that citizens will walk on. (The apiary doesn't need or use one.)
   • See /resource/Models/Buildings/FishermansDock/FishermansDockFloor.rsc
   • See /resource/Template/FishermansDock.rsc
9. Export the model in FBX format.
10. Build a material resource for the game to use.
    • See /example/building/Models/MaterialInstance/Apiary.rsc
11. Build a texture resource for the game to use.
    • See /example/building/Models/MaterialInstance/ApiaryTexture.rsc
12. Build AO texture resources.
    • See /example/building/Models/MaterialInstance/ApiaryAO.rsc
13. Make a model resource for the building and each step of construction. This is the visual display of the model. These files also contain an 'edge mesh' that allows the game to display the highlight around the visual mesh when selected.
    • See /example/building/Models/ApiaryMesh.rsc, ApiaryBuild01Mesh.rsc, ApiaryBuild02Mesh.rsc
14. Make a picking resource for the building and each step of construction. This is used for picking buildings with the mouse.
    • See /example/building/Models/ApiaryPicking.rsc, ApiaryPicking01Mesh.rsc, ApiaryPicking02Mesh.rsc
15. Make a point resource for the building that defines where workers will stand when creating, using, and building the building. This point file references the dummy helper points setup when modelling.
    • See /example/building/Models/ApiaryPoints.rsc
16. Make a floor resource if the building has parts that citizens walk on that are above the terrain.
17. Make a decal that will be placed on the terrain. If you're making multiple buildings you can put all the decals on the same texture. Putting more than one decal on a texture is better for rendering performance.
    • See /example/building/Models/MaterialInstance/ApiaryFootprint*
18. Make any sprites that are associated with the building. If you're making multiple buildings you can put all the sprites on the same sheet. Putting as many sprites in one sprite sheet is better for rendering performance.
    • See /example/building/UI/ApiarySpriteSheet*
19. Make any strings that are associated with the building. If you're making multiple buildings you can put all the strings in a single string table.
    • See /example/building/UI/ApiaryStringTable.rsc
20. Make a new profession if needed.
    • See /example/building/Profession/Profession.rsc
21. Make any new resources that may be needed by the building. Note that this type of resource has additional models, sprites, textures, and strings associated with it. You create them just like in the previous steps of creating a model of a building.
    • See /example/building/Template/RawMaterialHoney.rsc
    • See /example/building/Models/honey.fbx
    • See /example/building/Models/HoneyMesh.fbx
    • See /example/building/Models/MaterialInstance/Honey*
22. Setup an entity that ties together all the resources and defines how the building works. Setting up entities is complicated. For more examples, see all the game entities in /resource/Template/.
    • See /example/building/Template/Apiary.rsc
23. Add a toolbar item that adds the building to the main game toolbar.
    • See /example/building/Apiary.rsc
24. Make a resource reference file that will load all resources. This resource needs to be named <ModName>Resources.rsc:resource. If not, it will not load properly when packaged in mod format.
    • See /example/building/apiaryResources.rsc

In many cases it's easier to iterate on models and textures while viewing them in game. If you build simple stub versions of the textures and models and get them into game - you can have the game reload them while you add details. Simply leave the game running and it will detect changes when you export fbx or pngs. Only Application-profile will detect changes. The final release executable does not. Note that this only works with loose resources. A mod already packaged into a single file will not reload resources, especially if the /onlypkg flag is used.

You can also change other resources, such as the entity definition, however some changes may make the game crash, especially if you change the number of items in an array. For example, changing the list of dummy node helpers and re-exporting while the game is running generally causes a crash. Other items, such as UI definitions, will reload, but won't take effect until the UI is closed and then reopened. Other values, such as storage amounts in buildings don't take effect until you build a new building.

For performance reasons it's best practice to have a building be a single object with one material. The game supports multiple objects with multiple materials, but it will take the game longer to rendering these objects.

  Edited November 12, 2023 by catty-cb  
Banished Toolkit 1.0.7