Toolbars Tutorial

[slink]

A toolbar "parent" is created in the root of your mod directory structure.  A toolbar "child" (the button you press to build the actual building) is created partially in the root and partially in the template file for the building.  The button mechanics are inside the UI directory of your mod directory structure.

Here is the root of the Mathieuso Houses mod.  It only uses "child" buttons because the houses are attached to the housing button on the main toolbar.



The contents of the Resource file are shown in the code section below.

Code: [Select]

ExternalList resource
{
External _resources
[
// toolbar - references building and everything else - nothing else need be listed here

smallwoodhouse
mediumstonehouse
inn

]
}

Toolbar smallwoodhouse
{
Toolbar _parent = "Game\Toolbar.rsc:housing";
int _sortPriority = 20;

Action _action = Tool;
ComponentDescription _tool = "Template/SmallWoodHouse.rsc";

bool _autoHotKey = false; 
}

Toolbar mediumstonehouse
{
Toolbar _parent = "Game\Toolbar.rsc:housing";
int _sortPriority = 300;

Action _action = Tool;
ComponentDescription _tool = "Template/mediumstonehouse.rsc";

bool _autoHotKey = true; 
}

Toolbar inn
{
Toolbar _parent = "Game\Toolbar.rsc:housing";
int _sortPriority = 600;

Action _action = Tool;
ComponentDescription _tool = "Template/Inn.rsc";

bool _autoHotKey = true;
}
In each of the templates there is a section as shown below, for the Inn.

Code: [Select]

ToolbarDescription toolbar
{
SpriteSheet _spriteSheet = "UI/MathieusoHousesSpriteSheet.rsc";
String _spriteName = "BuildInn";

StringTable _stringTable = "UI/MathieusoHousesStringTable.rsc";
String _stringName = "Inn";
String _stringNameLwr = "InnLwr";
String _toolTip = "InnTip";

String _statusStrings
[
"CreateOk",
"CreateBlocked",
]

int _group = 2;
}

The files under the UI directory are shown below.



MathiesoHousesSpriteSheet.rsc contains the following text.

Code: [Select]

SpriteSheet resource
{
String _materialName = "MathieusoHousesSpriteSheetMaterial.rsc";
String _imageName = "Build/MathieusoHousesSpriteSheet.png";
int _imageWidth = 256;
int _imageHeight = 256;
bool _padForFiltering = true;

Sprite _sprites
[

{ String _name = "BuildSmallHouse"; String _source = "UI/Sprite/BuildSmallWoodHouse.png"; }
{ String _name = "BuildMediumHouse"; String _source = "UI/Sprite/BuildStoneHouse.png"; }
{ String _name = "BuildInn"; String _source = "UI/Sprite/BuildInn.png"; }
]
}
And finally, the Sprite directory contains the three PNG files listed in the text file above.

Making a "parent" toolbar button is a little more complicated, but only a little.  The text required in the resources file is slightly different depending on whether you are adding the parent to an existing tree, or adding it to the base of the toolbar structure.

Here I added my markets to the storage button, under a button of my own.

Code: [Select]

Toolbar sjglsmallmarkets
{
StringTable _stringTable = "UI/SJGLSmallMarketsStringTable.rsc";
SpriteSheet _spriteSheet = "UI/SJGLSmallMarketsSpriteSheet.rsc";

Toolbar _parent = "Game\Toolbar.rsc:storage";
int _sortPriority = 500;

String _toolTip = "SmallMarketsItemsTip";
String _image = "SmallMarketsItems";
Action _action = ShowGroup;

bool _autoHotKey = true; 
}
And here I added a new button to the base of the toolbar, and attached a nesting of two levels to include the hedges in Mathiesuo Decorations.  This required that I include a definition of the standard "base" in my resource file.  The first of the actual hedge buttons is also in the code shown.  Notice that the bottom-most button has not got a parent line.  Attempting to define the decorations button with a '_parent line' and no ': "base"' in the title causes the button not to appear.  I have no idea why.  Probably it has to do with other code locating the main toolbar on the screen and so forth.
 

Code: [Select]

Toolbar base
{
StringTable _stringTable = "Dialog/StringTable.rsc:toolBar";
SpriteSheet _spriteSheet = "Dialog/SpriteSheet.rsc";
}

Toolbar decorations : "base"
{
StringTable _stringTable = "UI/DecorationsStringTable.rsc";
SpriteSheet _spriteSheet = "UI/DecorationsSpriteSheet.rsc";

int _sortPriority = 900;

String _toolTip = "DecorationsItemsTip";
String _image = "DecorationsItems";
Action _action = ShowGroup;

bool _autoHotKey = false; 
}

// HEDGES

Toolbar hedges
{
StringTable _stringTable = "UI/DecorationsStringTable.rsc";
SpriteSheet _spriteSheet = "UI/DecorationsSpriteSheet.rsc";

Toolbar _parent = decorations;
int _sortPriority = 100;

String _toolTip = "HedgesTip";
String _image = "Hedges";
Action _action = ShowGroup;

bool _autoHotKey = false;
}

Toolbar hedge
{
Toolbar _parent = hedges;
int _sortPriority = 100;

Action _action = Tool;
ComponentDescription _tool = "Template/Hedge.rsc";

bool _autoHotKey = false;
}

One point to notice is that "parent" buttons contain this line:

   Action _action = ShowGroup;

whereas "child" buttons contain this line:

   Action _action = Tool;   

[RedKetchup]

is it a question or a tuto ?

[slink]

is it a question or a tuto ?

What's it look like?   

It is a tutorial.  I will change the title.

[RedKetchup]

oh ok, because at the end you said ..... i have no idea why. ^^ i wasnt sure anymore ^^

[slink]

oh ok, because at the end you said ..... i dont know why. ^^ i wasnt sure anymore ^^

Well, I don't know why.  I can guess, but I don't know for certain.  It doesn't matter as long as it works.

[RedKetchup]

ah ok my bad.

[salamander]

It is a tutorial....

And a nice one, too.  It's got me thinking about 'parents' and what else in the mod kit can have a parent and could be treated this way.  It seems like a good way to extend something instead of completely replacing it.  Replacement essentially limits you to one 'modding level' for a resource (eg, a particular string table) that different mods might want to change -- you can either let mod A change the table, or mod B can change it, but you can't have mod A make its change and then have mod B extend the table further.

As an example, if both the Great Plains and Lake Region mods are enabled, only the first in the mod list will show up in the map type dialog when starting a new map.  I wonder if the 'parent' approach would work with these so all map-type mods would show in the dialog at the same time.

[slink]

The terrain is controlled from a drop-down menu in the main game menus system.  That seems to be defined from TerrainList.rsc.  If everyone wrote their own string table files (which I did not in my modding tutorial), and you could override their copies of TerrainList.rsc with a combined list of your own, it should work.

I am moving this thread to tutorials, by the way.

[salamander]

The Lake Region map type was one of my first attempts at a mod and was made using your Great Plains example as a template, only changing the file names, strings and the map generation values as needed.  So ... Lake Region knows nothing of Great Plains, and vice versa.  If the game's original StringTable.rsc:terrainType string list for the drop-down could be extended by these mods, rather than replaced, then it seems like new map-type mods wouldn't have to take into account other previous mods that change the same string list.  I think this would require some sort of standardized approach followed by all mod creators to allow for future extension by others.

Of course, it's entirely possible that I'm missing something here ... I'm still having a hard time understanding how mods are used by the game and how they might interact with each other.

[slink]

If everyone made their own string tables then multiple mods could co-exist.  However, you cannot get around TerrainList.rsc and ClimateList.rsc.  They do not simply add to the lists in the game.  They override them.  I don't think we can get the game to look in two separate files for the lists of possible map conditions.

However, if you knew the names of the files you might be able to override everyone's terrain and climate lists with ones of your own that include all of them.  You can get those names from the "..." lists for the mods, except for the Colonial mod which seems to have somehow been blocked.  Possibly they are using an Asian alphabet.

Anyway, give that a try.

[salamander]

I might have to give it a try if I get a little more comfortable with the modding in general.  In this particular case, if string lists can have a parent, and if I can figure out exactly how the ":" notation works (it almost seems like it might be like class inheritance), it might be possible.  The clues are there in the section of the mod kit readme on shared resources, but it doesn't seem all that well-explained there or in the coded example it refers to in the kit.

But, if TerrainList.rsc won't allow extension, it probably won't work, anyway. 

[slink]

I hate to say it, but overrides are easy enough for a programmer, within our ability to figure out what Luke meant at any given place, that it is probably easier to do it yourself rather than to try to make everyone else's work together.

[salamander]

No doubt you're right.  For the most part I keep thinking about it just out of curiosity about whether it's possible -- I like to know how things work, and it bothers me some if I don't.

Even if it is possible, I don't think it's going to revolutionize Banished modding, but it might help to eliminate some of the conflicts that appear when you have multiple mods available in the mods list.  And, personally, I think it would be convenient (nothing more than that) not to have to enable/disable multiple mods depending on how you want to play a new game; I'd much rather be able to choose from multiple options from the usual new game dialogs in the game.

I'm hoping that once the semester ends I'll have some time to play around with it.  With your tutorial here, maybe I'll be able to make some sense of what's still a mystery to me.