Banished Toolkit 1.0.7

[catty-cb 4,413]

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.

• The Visual Studio 2012 Redist is also required.

• 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
   xWMAEncode.exe                      ->    Audio encoding tool (from DXSDK June2010)
   /WinData                            ->    Location where pack files need to be.
   /x64
        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
        CompileWin-x64-profile.dll     ->    Used to compile game resources on windows
        VideoCompiler-x64-profile.dll  ->    Used to compile SRSL shaders
        libfbxsdk.dll                  ->    FBX loader (from FBXSDK)
        cmd.txt                        ->    Command line parameters that are always used.
   /x32 
        Application-x32-profile.exe    ->    Developer version of the game. 
        Tools-x32.exe                  ->    Tool to compile resources, build mods.
        Runtime-x32-profile.dll        ->    Game engine dll
        VideoDX9-x32-profile.dll       ->    DirectX 9 Renderer
        VideoDX11-x32-profile.dll      ->    DirectX 11 Renderer
        CompileWin-x32-profile.dll     ->    Used to compile game resources on windows
        VideoCompiler-x32-profile.dll  ->    Used to compile SRSL shaders
        libfbxsdk.dll                  ->    FBX loader (from FBXSDK)
        cmd.txt                        ->    Command line parameters that are always used.
/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.
        /limitresource                 ->    Example of how to use custom resource limits
        /buildrequirement              ->    Example of how to use more than 3 build requirements for a building.
/resource                              
        /.                             ->    Lots of game data for examples and modification
BuildExamples.bat                      ->    Quickly build all the mod kit examples.
BuildResources.bat                     ->    Build all game resources contained in /resource

3. Command Line Parameters

Common command line Parameters

• /bin <path> Set the location of the bin folder relative to the executable. This defaults to nothing, but the cmd.txt file sets it to ..\

• /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 BuildResources.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/x64/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.

As of version 1.0.5 Beta, materials now use a new shading language. The old format will no longer work and any custom previous shaders built for 1.0.4 will have to be reworked. Old materials from old mods will still load in game and work properly.

If you're going add audio to the game, be aware that at some time in the future, you'll probably have to make changes to support other audio systems as the game is ported to other platforms. If you don't add any new audio, you're mod is probably ok, but may require extra work if you end up working on it when new versions are released.

Sharing Mods

Once you've developed mods, it's best to upload them both to steam workshop and to locations where non-steam users can download your mod. Some of these include http://banishedinfo.com/, and http://www.nexusmods.com/banished/

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. Steam Workshop

Once you've developed a mod, you can upload it to steam workshop to share it with the steam community. To do this, you'll have to use the Steam version of the game. Put your mod in:
C:\Program Files (x86)\Steam\SteamApps\common\Banished\WinData\
When you start the game, the mod will show up in the Mod menu. Click on the '...' button for the mod - it's right under the button to enable the mod in game.
Uploading to Steam requires that the original compiled data before packaging remain on disk where it was compiled for the Add and Update buttons to be available.
If you're uploading the mod to Steam Workshop for the first time, click on the 'Add to Workshop' button. You'll be guided through a series of prompts and questions to get the mod on the workshop. Once the mod is uploaded, you'll be presented with a link to view the mod on the Steam Workshop, and change any of its properties.
If you're updating a mod that you already published to the Steam Workshop, click on the 'Update Mod on Workshop' button. Again you'll be guided through a series of prompts and questions. When you are asked which mod you want to update, makes sure you pick the correct previously published mod. Once the mod is uploaded, you'll be presented with a link to view the mod on the Steam Workshop, and change any of its properties.
There are users that don't use Steam, so it's best to also upload the mod elsewhere for those users to install.