News:

Welcome to World of Banished!

Main Menu

Beginner's Guide to Modding for Banished PART 5 - ModKit / a simple fence

Started by scoutae4, December 14, 2023, 01:29:31 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

scoutae4

PART 5 - ModKit / Beginner's Guide to Modding for Banished: a simple fence

Last chapter! We're here thanks to a lot of help from @kid1293 ...and a little bit because I have ridiculous hubris. What the heck was I thinking to start a tutorial from a start position of ZERO? Anyway, one day I owe @kid1293 a beer or two (or twenty) for enduring my many questions with patience. :)

Start with a copy of the "building" example from the ModKit and rename it TutorialFence. Compare what was changed and added with kid's attached build out. You can delete the "profession" folder right away as we don't need that for our fence mod.

These are the 3 files we should have from the tutorial:

FenceWood01.png (downloaded in part 3) file this in TutorialFence>Models>MaterialInstance>
TutorialFenceAO.png (we created in part 4) file this in TutorialFence>Models>MaterialInstance>
TutorialFence.fbx (also created in part 4) file this in TutorialFence>Models>

You will also need the icons for the menus and toolbar. @kid1293 has provided these as well in the attached so you have them as templates when you're creating your own mods:

Icon.png (48x48) file this in TutorialFence>
BuildTutorialFence.png (32x32) file this in TutorialFence>UI>Sprite>
RemoveTutorialFence.png (32x32) file this in TutorialFence>UI>Sprite>

If you're serious about modding, you'll eventually want to take a look at the excellent personal toolbar @RedKetchup created here: https://worldofbanished.com/index.php?topic=1467.0 but for now, the files from kid in your Dialog folder will do the trick!

About the build code in case this is helpful - if you create your TutorialFence mod in a MyMods folder like so BanishedKit>MyMods>TutorialFence then the code would be:

..\..\bin\x64\Tools-x64.exe /build TutorialFenceResources.rsc:resource /pathres ../MyMods/TutorialFence /pathdat ../MyMods/TutorialFence/bin
..\..\bin\x64\Tools-x64.exe /mod Package.rsc:TutorialFence /pathres ../MyMods/TutorialFence /pathdat ../MyMods/TutorialFence/bin


And last note: if you make a mistake and the kit doesn't execute correctly, DELETE the "bin" and "Build" files that are created in your mod folder instead of overwriting them on your next try. Not sure if you also have to delete the corrupted mod that will output into your bin>WinData folder but I do delete that as well.


All text and code that follow, and the attached files are courtesy of @kid1293 :)


I find learning to write the code free-hand is almost impossible with all variables. I take an existing mod, copy it and change the necessary things.






You need 5 files in the mod's folder.

Build.bat, which contains the instructions to build and package the mod. You edit the paths to suit your setup.

..\bin\x64\Tools-x64.exe /build TutorialFenceResources.rsc:resource /pathres ../TutorialFence /pathdat ../TutorialFence/bin
..\bin\x64\Tools-x64.exe /mod Package.rsc:TutorialFence /pathres ../TutorialFence /pathdat ../TutorialFence/bin


Icon.png, which is visible when you choose Mods from the Banished start menu.

Package.rsc, which is a description that is visible in the same menu as above.

TutorialFenceResources.rsc points to the file TutorialFence.rsc. It is called from Build.bat

TutorialFence.rsc contains the main description for the toolbar.






FOLDERS






Dialog contains files with code that are called from your Template files.






Models, with the sub-folder MaterialInstance. Here you put your model and textures.
For the most occasions a model needs two definition files.
The first is named after the name of the mesh in your FBX file.
The second is is named after the model used when you select it in game.

In this case we have only two files for the fence:
TutorialFence>Models>TutorialFenceMesh.rsc
TutorialFence>Models>TutorialFencePicking.rsc

and the Points file:
TutorialFence>Models>TutorialFencePoints.rsc

The textures in MaterialInstance also need two file (in most cases)
Our FenceWood01.png will have
TutorialFence>Models>MaterialInstance>FenceWood01.rsc
TutorialFence>Models>MaterialInstance>FenceWood01Texture.rsc

The first file tells about material used such as snow/no snow/transparent/...
The second file hold a pointer to the actual picture used and information how the picture should be treated.
If you want the picture to wrap around you write

ImageBuffer resource : "Texture/ModelTexture.rsc"
{
String _imageName = "Models\MaterialInstance\FenceWood01.png";
AddressMode _addressU = Repeat;
AddressMode _addressV = Repeat;
}


If you want the picture to be limited by its edges, change "Repeat" to "Clamp"


AddressMode _addressU = Clamp;
AddressMode _addressV = Clamp;







Template files are the actual handling of your model to display it in the game, with menus and all.

It starts with some descriptions which calls external or internal code (see code in TutorialFence.rsc)

ComponentDescription resource
{
// how often to update
UpdatePriority _updatePriority = Fourth;

// declare types that will be used
Description _descriptions
[
"ui",

"map",
"zone",
"toolbar",
"createplaced",
"picking",
"model",
"highlight",
"interact",
"storage",
"work",
"statusicon",
"tracker",

"statemachine",
"cleararea",
"build",
"workplace",
"destroy",
]
}


Some of these are not really needed in every mod. There are also other entries added by some mods. I will not go through them all, just a few.

---

ClearAreaDescription cleararea
{
bool _flattenGround = false;
}


Can be set to true or false. It tells if you want your model to flatten the
ground where it stands.

---

ToolbarDescription toolbar

Just change the names and paths to fit your mod.

---


CreatePlacedDescription createplaced
{
PathBits _placeBitArray
[
Normal | Obstacle,
Normal | Obstacle | Fast | Faster,
]
int _width = 0;
int _height = 0;
int _footprintRotation = 0;

String _placeBitmap =
"1";

ComponentDescription _allowAndRemove = "Template/Clear.rsc";
}

MapDescription map
{
PathType _pathType = Immovable;
String _pathBitmap =
"#";

bool _addToOverhead = true;
Color _mapColor = 0xFF545454;
}


Here you tell how large your model is.
In this case I have set it to 0x0. (we call it ghosted)
It does not require any tile to be built. It can be placed anywhere.

OTHER EXAMPLE

CreatePlacedDescription createplaced
{
PathBits _placeBits = Normal | Obstacle;

int _width = 7;
int _height = 5;
int _footprintRotation = 0;

PathBits _placeBitArray
[
Normal | Obstacle,
Normal | Obstacle | Fast | Faster,
]
String _placeBitmap =
"0000000
0000000
0000000
0000000
1111111";

ComponentDescription _allowAndRemove = "Template/Clear.rsc";
}

MapDescription map
{
PathType _pathType = Immovable;
String _pathBitmap =
"#######
####### 
##__###
____###
.......";

bool _addToOverhead = true;
Color _mapColor = 0xFF545454;
}


Here your model can be placed where there is a road. (the 1s)
The 0s shows it must be a free tile.

#=block _=walkable .=can build road

---

Next three entries are Picking, Map, and Highlight.
They show which files to call under certain conditions.
Check other source code for more example. It is not all that hard.

---

BuildDescription build
{
int _workRequired = 0;
}


Tells how much resources and how much work it takes to build your model.
I have set it to 0, free to build.

OTHER EXAMPLE

It can cost a lot. Example from the vanilla Hostel.

BuildDescription build
{
int _workRequired = 150;

BuildRequirement _buildRequirement
[
{
ComponentDescription _rawMaterial = "Template/RawMaterialWood.rsc";
int _count = 100;
}
{
ComponentDescription _rawMaterial = "Template/RawMaterialStone.rsc";
int _count = 45;
}
]
}


---

Now comes an important entry - UI
There are so many things to talk about, I leave it up to you to learn from templates in the vanilla 'resource' folder.

One thing though.

This section is inserted to create a remove-button on the fence.

{
ObjectType _type = UpgradeUI;
ElementDescription _element = "Dialog/RemoveTutorialFence.rsc:RemoveTutorialFence";
String _insertAt = "userButton0";
DialogControllerConfig _config = "upgradeConfig";
}



it loads a file in the Dialog folder (RemoveTutorialFence.rsc) then it points to upgradeConfig lower down, which loads a file in the Template folder.


UpgradeUIConfig upgradeConfig
{
ComponentDescription _upgradeTo = "Template/RemoveTutorialFence.rsc";
}







The Texture folder contains information about textures for the modkit. Leave it alone for now.






The UI folder holds a folder Sprite, where you put your toolbar icons. (Not Icon.png)
You can check the files in the UI folder how they are set up.
It is the same for all mods. Only the name changes.







Abandoned

Good job.  :)  I am sure those learning to mod will really appreciate all the work you put into these tutorials.  :)

scoutae4

Thanks @Abandoned  :) I hope it's easy to follow and encourages more modding. Looking forward to digging into that myself!

scoutae4

@kid1293 I was curious about the Work.rsc file in the Dialog folder: what is it's function here? Do we need this when creating a ghosted item? I noticed it's only included in the, "limitresource" example provided by the developer so I'm wondering if you include this by default with mod builds in case it's needed, or if it serves a particular function.

kid1293

I do not think that Work.rsc is always needed. I include files out of habit. They will not be compiled if not needed.


catty-cb

I left it out of that wheelwright mod I'm working on over at simtropolis

https://community.simtropolis.com/forums/topic/762782-installing-the-banished-modkit-on-linux/

and I got a number of error messages, so its definitely needed for some mods