Login / Register

Banished Modding - getting started with the toolkit

Banished Toolkit 1.0.4 Beta © 2014 Shining Rock Software.

1. Banished Toolkit Prerequisites #

  • The Banished toolkit requires Banished version 1.0.4 Beta or better. While the shipped game runs under Windows XP, the toolkit does not. The toolkit was developed and used under Windows 7. Other operating systems have not been heavily tested.
  • The toolkit requires all graphics SDKs that the game supports to properly compile shaders. At the moment DirectX 11 and DirectX 9 are required. OpenGL support will be required in new releases.
  • The data files from your purchased game are required.
  • The DirectX End User Runtime will have to be installed. You can find it here: http://www.microsoft.com/en-us/download/details.aspx?id=35
  • The Visual Studio 2012 Redist is also required. It can be downloaded here: http://www.microsoft.com/en-us/download/details.aspx?id=30679 The toolkit may be compiled with newer versions of MSVC in the future - if so you'll have to install the redist for the newer versions.
  • For machines (mostly laptops) that have both an Intel card and Nvidia card, make sure you set the tool and game executables to use the high powered video card, rather than the integrated one.
  • The game uses the font FrancophilSans. You may need it installed depending on what you are modding.

2. Toolkit Contents #

The toolkit has the following structure

/bin
	Application-x64-profile.exe    ->    Developer version of the game.
	Tools-x64.exe                  ->    Tool to compile resources, build mods.
	Runtime-x64-profile.dll        ->    Game engine dll
	VideoDX9-x64-profile.dll       ->    DirectX 9 Renderer
	VideoDX11-x64-profile.dll      ->    DirectX 11 Renderer
	xWMAEncode.exe                 ->    Audio encoding tool (from DXSDK June2010)
	fbxsdk_20113_1_amd64.dll       ->    FBX loader (from FBXSDK)

	This folder also contains 32 bit builds of the game as well.
/example
	/animal                        ->    Example of making a new animated animal and adding it to a pasture.
	/building                      ->    Example of adding a new building that takes one resource and makes another.
	/crop                          ->    Example of adding a new farm crop.
	/translation                   ->    Example of font, character sets, and translations.
	/tree                          ->    Example of making a tree and adding it to an orchard.
/resource
	/.                             ->    Lots of game data for examples and modification

3. Command Line Parameters #

Common command line Parameters

  • /pathres <path> Set the resource directory. This directory is relative to /bin. The default is /bin/../resource
  • /pathdat <path> Set the compiled resource directory. This directory is relative to /bin. The default is /bin/WinData
  • /pathpkg <path> Set the package directory. This directory is relative to /bin. The default is /bin/WinData

Command line parameters for Application-x64-profile.exe

  • /onlypkg Only use .pkg (game package) and .pkm (game mod) files when loading. Otherwise anything in the resource folder will be loaded first.
  • /launcher Start the game with the launcher. You can also hold CTRL as the game starts to bring up the launcher.
  • /nomods Start the game with all mods disabled. This can be useful if a mod causes a crash and the game can't start.
  • /ref <resource> Specify an mod resource list to load when starting the game. This can be used to load resources before a mod is packaged. For example: /ref Package.rsc:modName

Command line parameters for Tools-x64.exe

  • /build <resource> Build a resource and all dependencies. Example /build Game/GameResources.rsc:resource
  • /mod <pkgresource> Build a mod package. Any changes that differ from original data and new files will be packaged into one file.
  • /texpad <pngfile> Fill any alpha = 0 pixels in a texture with expanded border color. This is useful for making textures that mipmap nicely.

4. Getting Started #

After unpacking the archive, you'll want to test the toolkit environment to make sure everything is working properly.

  1. Copy the .pkg files from the game data directory to where ever the toolkit is located. In this example, assume the toolkit it installed at C:\BanishedKit\. You'll copy to C:\BanishedKit\bin\WinData. If you're using Steam, the data files are probably in C:\Program Files (x86)\Steam\SteamApps\common\Banished\WinData. Non Steam builds default to C:\Program Files\Shining Rock Software\Banished\WinData
  2. Open a command prompt and change directory to the toolkit. (C:\BanishedKit)
  3. Run the batch file BuildResource.bat. This is going to take a few minutes.

  4. If all goes well, all resources will be compiled to binary format and be placed in /bin/WinData. You'll see a lot of output along the lines of Compiled ImageBuffer: Terrain\TerrainDirtTexture.rsc:resource. Generally the tool will notify of any error with a dialog box or text in the output. Or it might crash.

    If it does have errors or crash, make sure you've got the game .pkg files in the right place and you've installed all the prerequisites.

  5. Start the developer build of the game, /bin/Application-x64-profile.exe. The game should run as normal. It's loading the newly compiled resources - which should match what's in the game package file.
  6. Check to see if you can modify a resource and have it effect the game.
    1. Open /resource/Dialog/StringTable.rsc in a text editor.
    2. Search for StringTable mainMenu.
    3. Look for and change the entry that looks like
      { String _name = "NewGame"; String _text = "New"; }
      to
      { String _name = "NewGame"; String _text = "MODDED!!!"; }
    4. Save the file.
    5. Restart Application-x64-profile.exe. The game will notice the change to the string table and recompile it. You could also rerun the BuildResources batch file, but this isn't required - the game is capable of compiling all resources, however you don't get detailed text output as you would on the command line with Tools-x64.exe.
    6. When the game loads, you should see that the new game button now has the modified text.
  7. You're now setup to modify the game. Obviously, you'll want to undo your change to the string table.

5. Best Practices #

Most of the game configuration data is provided as an example for how everything in the game is put together. You can modify it as you please, however if you plan on distributing your mod to others, there's a few things to keep in mind so that your mod will working well with other mods.

Take care with resources that might be shared!

It's ill advised to make changes to core resources. If multiple mods reference new resources in these files, only one set will be loaded, causing unintended behavior. Some examples of these resources are:

  • Game/Toolbar.rsc Items that appear on the game toolbar.
  • Dialog/StringTable.rsc Most all text for the game.
  • Dialog/SpriteSheet.rsc Sprites that the game uses to render the user interface.

If you need to load new text, sprites, raw materials, natural resources, livestock, etc, you should make your own list of resources and tell the game to load it. You'll make an ExternalList resource. The mod in /example/building has a good example of this.

For example, if you're adding the apiary, bee keeper, and honey, in a file apiaryResources.rsc:

ExternalList resource
{
	External _resources
	[
		"Apiary.rsc:apiary"		// this references everything for the apiary
	]
}

When running the game, start it like so:
Application-x64-profile.exe /ref apiaryResources.rsc

After you package your mod, this file will be loaded automatically when the mod is enabled if it is named correctly.

If you're just modifying text, user interface layout or look, models, textures, settings for citizens, etc you can just override the original resources. If your mod does conflict with another users mod, they will be notified of the conflict if both mods are loaded and enabled at the same time.

Working on multiple mods.

If you have multiple mods you are working on, and as you work through the examples in this document, it's best to either clear out the bin folder of compiled resources when switching between mods, or use the /pathdat command line flag to make sure that binary resources are separated.

When mods are packaged, any file in the current binary folder that differs from the one in the original game packages is put into the package.

Be aware of new materials and audio.

If you're going to make new vertex or pixel shaders, or add audio to the game, be aware that at some time in the future, you'll probably have to make changes to support OpenGL and other audio systems as the game is ported to other platforms. If you don't add any new vertex or pixel shaders or audio, you're mod is probably ok. Maybe.

6. A Note on Save Games #

Save games store which mods were enabled when they are saved. When they are reloaded, all mods are first disabled, and then only those that were previously enabled in the save are loaded. When new games start, the mods setup in the main menu are the ones that the game will start with.

While a game is running, you can enable mods, so that you can add new buildings to an already existing map. However if resources that shipped with the game are changed, unexpected behavior might occur. For example if the size on the map of a storage barn changes because of a mod, when old barns are removed, they can cause pathing issues and crashes.

Additionally if you disable a mod while a game is running, crashes can also occur. If you've enabled a mod that adds buildings, and those buildings are placed, disabling the mod will cause a crash.

Save games will also detect changes to a mod. If a new mod version has been published and you've overwritten the mod with the new version, the game will warn you that the mod is different or has changed version and that unexpected behavior can possibly occur.

7. Examples #

There's far too much complexity and detail to describe all the things you can change or add to the game (without spending months on documentation), so you'll have to learn by example with the game configuration data and trial and error. These few examples should get you started, but you'll want to get familiar with most things in the /resource folder.

A. A Simple Mod - Translation, Font, and Character Set #

The first example, in /example/translation, shows a translation of all the strings in the game. It also changes the font and adds new characters to the font that are in use. Take a look in the /example/translation folder. It contains a mirror of some of the resources in the game, except they've been changed.

The example translation makes all text uppercase, and changes any vowels to have accents above them. Note that there are special characters in strings you'll want to keep intact - the help files have things like (^f0, ^jl, etc). Strings also have '~~' (for tilde) '~"' for quote, and @N (for substitution, where N is 0..9). During translation, you'll have to keep the escape characters intact.

First, you need to define the character set you want to use. You can view a character set example in /example/translation/Font/CharacterSet.rsc

// this file needs to be UTF16 little endian if it contains characters over index 255
// fonts that use this character set need to support all the characters listed here.
// This file is used to keep the font textures small, instead of having to include thousands of characters
// ~ is a special escape character, so ~~ is required to add tilde to the set, ~" is needed for quotation marks
CharacterSet resource
{
	String _characters = "
		// Special escape characters
		~~ ~"
		// Punctuation
		`!@#$%^&*()_+-={}|[]\:;'<>?,./©
		// Numbers
		01234567890
		// characters for English (no lower case, note: help text will not display correctly)
		ABCDEFGHIJKLMNOPQRSTUVWXYZ
		abcdefghijklmnopqrstuvwxyz
		// additional characters for this example
		ÂÊÎÔÛ
	";
}

Next, you'll change the fonts for the game. There are four main fonts, each a different size. A font resource looks like this:

Font resource
{
	// reference character set
	CharacterSet _characterSet = "Font/CharacterSet.rsc";

	// whatever font you want, has to be loaded into windows
	String _fontName = "Arial";

	// height in pixels of the font
	int _fontHeight = 24;

	// name of the sprite sheet to create, and its size. You may have to increase the size of
	// the sheet to contain all the characters
	String _sheetName = "Build/FontSheet.rsc";
	int _sheetWidth = 256;
	int _sheetHeight = 128;

	// name of the material that uses this font. The material needs to reference
	// the correct texture.
	String _materialName = "Font/FontMaterial.rsc";

	// the texture to output with all the glyphs on it.
	String _imageName = "Build/uiFontImage.png";
}

Finally, you can translate all the text. All text is contained in string tables that look like this:

StringTable common
{
	Entry _strings
	[
		{ String _name = "Ok";					String _text = "ÔK"; }
		{ String _name = "Cancel";				String _text = "CÂNCÊL"; }
		{ String _name = "Yes";					String _text = "YÊS"; }
		{ String _name = "No";					String _text = "NÔ"; }
		{ String _name = "Apply";				String _text = "ÂPPLY"; }
		{ String _name = "Next";				String _text = "NÊXT"; }
		{ String _name = "Quit";				String _text = "QÛÎT"; }
	]
}

Note: If Unicode characters are required to support characters, resources files can be saved as USC-2, little endian. If you're unsure, the CharacterSet.rsc file is already in this format.

Depending on the translations and size of the text, some dialogs may not contain the text, or become misshapen. To remedy this, you could also modify parts of the user interface layout to accommodate the translation more fully.

For ease of building the mod, a single ExternalList resource is provided that references all the changed resources. To build this mod, run the command

bin\Tools-x64.exe /build Package.rsc:list /pathres ../example/translation /pathdat ../example/translation/bin

You should now be able to run the game with the command:

bin\Application-x64-profile.exe /pathres ../example/translation /pathdat ../example/translation/bin

You'll see that the translation has taken effect. However, this has just modified the game data locally - this is great for quick development and iteration, but if you wanted to give this mod to others, you'd need to package it.

First, you'll create a definition for the package (see /example/translation/Package.rsc) 

PackageFile translationExample
{
	String _name = "Translation Example";
	String _author = "Shining Rock Software, LLC";
	String _description = "This mod changes the font from the default to Arial.
		It also modifies the default character set. All text strings
		are made uppercase and vowels have accents over them.";
	String _icon = "icon.png";	// must be 48x48
	int _userVersion = 1;

	// all files in resource directory (each item is searched recursively)
	String _includeList
	[
		"*"
	]

	// exclude package files, mod files, file used for building packages
	String _excludeList
	[
		"Package_*.crs"
		"*.pkg"
		"*.pkm"
	]
}

Next, you'll compile the package using the /mod parameter.

bin\Tools-x64.exe /mod Package.rsc:translationExample /pathres ../example/translation /pathdat ../example/translation/bin

Building the mod package may take some time, depending on how many resources are in the data directory and how many have been modified.

The tool checks the new resources against the ones contained in the game, and only packages files that have changed or are new.

The tool will output files that it is packaging, so you can see what you've modified or added.

In the end, this will output a file called translationExample.pkm in the bin/WinData folder.

Next, test the mod properly.

  1. When you start the game, start it so it only uses packages. 
    bin\Application-x64-profile.exe /onlypkg
    All the text should be as normal.
  2. Open the Mod dialog by pressing the 'Mods' button.
  3. The Translation Example mod should be listed in the dialog.
  4. Enable it by checking the X button next to the text that says Enable.
  5. Press OK.
  6. The menu will prompt you to reload, and after doing so the mod will be in effect.
  7. Once everything is working as intended in a mod, you can distribute the .pkm file to other users. All they have to do is place the .pkm file in the WinData folder, and then enable the mod in game.

B. A Building and Profession #

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\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\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\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\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.

C. Debug Options #

For testing, it's useful to enable debug mode so you can place buildings without needing resources. You can also add resources, citizens, change time of year, change the color of fog and lighting, cause disasters, and see general performance statistics.

To enable it, you can edit /resource/Game/Toolbar.rsc and find the 'debug' Toolbar item. Change the bool _visible = false; to bool _visible = true; Next time you load the Tools & Reports toolbar, there will be a debug option, which will bring up a dialog with many debugging tools. Note that the game isn't guaranteed to work properly with debug/cheating enabled. You can break the game by changing the time slider for seasons, and invalidate some state that may cause crashes.

If you're building a mod in a separate directory from the normal resource folder, you'll have to copy the Toolbar resource into your directory in the same relative place so that the game will see the change.

D. Adding a new crop #

This example adds a new crop to fields. In this case the crop is lettuce.

If you want to build and test the mod...

bin\Tools-x64.exe /build lettuceResources.rsc /pathres ../example/crop /pathdat ../example/crop/bin

You should now be able to run the game and see that lettuce can now be used when you plant crops in a field. You'll most likely want to enable debug mode to be able to use the lettuce seeds before buying them from a trading post. You'll have to copy the toolbar resource (from the previous example) into the /example/crop/Game folder so that you can enable debug mode. The debug menu is available from the Tools & Reports menu item. There's an icon of a bug on it. When you bring up the debug dialog, there's a button to give all seeds to the player. Just hover over the buttons and read the tooltips.

Before giving a mod to others, make sure you've turned the debug option off if it isn't your intent to leave it enabled.

Before the mod is packaged, you have to explicitly tell the game to load the resources using the /ref parameter.

bin\Application-x64-profile.exe /ref lettuceResources.rsc /pathres ../example/crop /pathdat ../example/crop/bin

Start a new game, and use the debug menu to give all seed types to the player. Then place a crop field - you should be able to select Lettuce as the crop. This crop works like any other.

You can build the mod into a package like so:

bin\Tools-x64.exe /mod Package.rsc:lettuce /pathres ../example/crop /pathdat ../example/crop/bin

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

bin\Application-x64-profile.exe /onlypkg

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

If you've been working through all these examples, you can see you can load multiple mods at once. You can start a game with both the lettuce mod and the apiary mod.

General steps for adding a new crop

  1. You'll need to model two objects. One for this display of the crop in the field, and one for the crop when it is harvested.
    • See /example/crop/Models/Lettuce.fbx
  2. Like in the building example you need to build Textures, Materials, and Meshes for the objects. The process is the same.
    • See /example/crop/Models/MaterialInstance/Lettuce* and LettuceLeaf*
    • See /example/crop/Models/LettuceLeafMesh.rsc and LettuceLeaf.rsc
  3. Like in the building example you need to build String Tables and Sprites.
    • See /example/crop/UI/CropSpriteSheet.rsc
    • See /example/crop/UI/CropStringTable.rsc
  4. Finally you'll have to make entity definitions (again, similar to the building example)
    • See /example/crop/Template/NaturalResourceLettuce.rsc
    • See /example/crop/Template/RawMaterialLettuce.rsc
  5. To package and reference the new entities, you'll need a package resource and a list of referenced objects.
    • See /example/crop/lettuceResources.rsc
    • See /example/crop/Package.rsc

E. Adding a new tree #

This example adds a new tree to orchards. In this case the tree produces figs.

If you want to build and test the mod...

bin\Tools-x64.exe /build figResources.rsc /pathres ../example/tree /pathdat ../example/tree/bin

You should now be able to run the game and see that fig trees can now be used when you plant trees in a orchard. Like the crop example, you'll need to enable debug mode in this mod to be able to give yourself fig seeds without buying them at a trading post.

Before the mod is packaged, you have to explicitly tell the game to load the resources using the /ref parameter.

bin\Application-x64-profile.exe /ref figResources.rsc /pathres ../example/tree /pathdat ../example/tree/bin

Start a new game, and use the debug menu to give all tree types to the player. Then place a orchard - you should be able to select Figs as the fruit. This tree works like any other.

You can build the mod into a package like so:

bin\Tools-x64.exe /mod Package.rsc:fig /pathres ../example/tree /pathdat ../example/tree/bin

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

bin\Application-x64-profile.exe /onlypkg

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

General steps for adding a new tree

Adding a new tree is almost identical to adding a new crop, just the entity definitions are different, and modeling the tree can be slightly challenging.

  1. You'll need to model two objects. One for this display of the tree in the field, and one for the fruit when it is harvested. There is a slight difference is the modelling of the tree.

    Deciduous trees in the game use the a vertex shader to always make the leaf billboards point at the camera. When modelling the leaves only a small quad (0.01m) is needed for each billboard. The billboards have a third texture coordinate that tells each vertex how far to expand and in what direction.

    In general the billboards are also mapped to a location on the Ambient Occlusion texture that is fully white - and actual AO information is only used on the tree trunk.

    On other parts of the tree, such as the trunk, make sure the third texture coordinate is mapped to uv (0, 0), otherwise the trunk will sway in the wind along with the leaves. If you're adding a new conifer style tree, the third texture coordinate just defines how much the leaves sway in the wind.

    • See /example/tree/Models/FigTree.fbx
  2. Like in the crop example you need to build Textures, Materials, and Meshes for the objects. The process is the same.
    • See /example/tree/Models/MaterialInstance/Fig* and FigTree*
    • See /example/tree/Models/FigMesh.rsc and FigTreeMesh.rsc
  3. Like in the crop example you need to build String Tables and Sprites.
    • See /example/tree/UI/FigSpriteSheet.rsc
    • See /example/tree/UI/FigStringTable.rsc
  4. Finally you'll have to make entity definitions (again, similar to the building example)
    • See /example/tree/Template/NaturalResourceFig.rsc
    • See /example/tree/Template/RawMaterialFig.rsc
  5. To package and reference the new entities, you'll need a package resource and a list of referenced objects.
    • See /example/tree/figResources.rsc
    • See /example/tree/Package.rsc

F. Adding a new animal #

This example adds a new animal to pastures. In this case the animal is a white chicken. It behaves just like the other chickens in the game.

If you want to build and test the mod...

bin\Tools-x64.exe /build whiteChickenResources.rsc /pathres ../example/animal /pathdat ../example/animal/bin

You should now be able to run the game and see that 'Leghorns' can now be used when you select an animal in a pasture. 'White Chicken' does fit on all the UI very well, so 'Leghorns' which is a type of white chicken, is used instead. This is something to keep in mind as you mod the game - make sure your text fits in the UI. The UI will expand controls to fit the text, however this may cause the entire UI to stretch in unexpected ways.

Like the crop example, you'll need to enable debug mode in this mod to be able to give yourself all the animal types without buying them at a trading post.

Before the mod is packaged, you have to explicitly tell the game to load the resources using the /ref parameter.

bin\Application-x64-profile.exe /ref whiteChickenResources.rsc /pathres ../example/animal /pathdat ../example/animal/bin

Start a new game, and use the debug menu to give all animal types to the player. Then place a pasture - you should be able to select 'Leghorns' as the animal. This animal works like any other. There's another debug button to fill pastures with animals without waiting for them to grow. Press it a few times to add the animals.

You can build the mod into a package like so:

bin\Tools-x64.exe /mod Package.rsc:whiteChicken /pathres ../example/animal /pathdat ../example/animal/bin

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

bin\Application-x64-profile.exe /onlypkg

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

General steps for adding a new animal

Adding a new animal is almost identical to adding a new crop or tree, just the entity definitions are different, and the model requries bones, skinning, and animations.

  1. You'll need to model two or three objects. One for this display of the animal in the field, and one for the meat when it is harvested. You may also need a model for another produced resource - chickens produce eggs, and cows produce milk.

    After modelling the animal, you'll need to rig it with bones and weight the mesh to the bones using a skin modifier. You can setup any sort of animation controllers, ik controllers, etc, as long as when you export the FBX file you bake the animation into the file, so that all animation frames are explicit, instead of relying on the controllers.

    It's important to keep the number of bones low. A maximum of 51 bones is supported, however for the game to render many animals quickly (in DirectX 9 mode), you'll want to keep the bone count much lower than that. The lower the bone count, the more models the game can render simultaneously.

    • See /example/animal/Models/WhiteChicken.fbx
  2. Like in the crop example you need to build Textures, Materials, and Meshes for the objects. The process is the same.
    • See /example/animal/Models/MaterialInstance/WhiteChicken*
    • See /example/animal/Models/WhiteChickenMesh.rsc
  3. You'll need to define an animation file that tells the game the ranges of animation for various motions. Animals need a walk, and three idles. It's important to make sure animations that are played often on many of the same object be properly instanced, and that the number of different instances running is fairly low.
    • See /example/animal/Models/WhiteChickenAnims.rsc
  4. Like in the crop example you need to build String Tables and Sprites.
    • See /example/animal/UI/WhiteChickenSpriteSheet.rsc
    • See /example/animal/UI/WhiteChickenStringTable.rsc
  5. Finally you'll have to make entity definitions (again, similar to the all the other examples, just different configuration). The white chicken reuses the meat and eggs resources that already exist in the game, so there aren't new resources for them.
    • See /example/animal/Template/WhiteChicken.rsc
  6. To package and reference the new entities, you'll need a package resource and a list of referenced objects.
    • See /example/animal/whiteChickenResources.rsc
    • See /example/animal/Package.rsc