Template:Requirements/howto

From Millénaire Wiki
< Template:Requirements
Revision as of 00:30, 25 March 2013 by Trancid (talk | contribs) (Done for now. Next update after I've updated myself with the changes.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Intro[edit]

Starting a small guide here for those who have the need and rights to update the requirements template. This used to be done by Ghost1972 and in his absence I, Trancid, took over for a short while. Since we are both rather inactive, this guide might be useful. It will take a bit of time to construct though, since it has been a while that I've toyed with it. Keep in mind that despite the template looking like chaos, it actually has some form of structure to it. So let's try to make some sense of this organized chaos.

How it works[edit]

This template can be activated in a few possible ways. All of these ways are explained in the general page: Template:Requirements. To actually add new buildings, you will have to learn a few things. If this is your goal, keep reading on.

General Setup[edit]

The template is basically a huge file of tables containing the information for building upgrades. The template chooses which table to display by using a so called switch structure. The general layout for this is:

{{#switch: {{{1|{{BASEPAGENAME}}}}}
|BuildingName1 = <requirementstable>
|BuildingName2 = <requirementstable>
etc.
| #default = 
{{msgbox
| title = Requirements not found
| text = The requirements template couldn't find the upgrade table of the building you were looking for.
Please consult the building list at [[Template:Requirements|this page]] to find the correct name.}}
}}
<noinclude>
[[Category:Templates formatting|{{PAGENAME}}]]
{{documentation}}</noinclude>

Whenever you want to add a building, the above should not be altered. 'All' you have to do is add seperate entries for your buildings somewhere in between the first line and the line saying "| #default =".

Building Tables[edit]

As you might have deducted from the previous section, the entry for a specific building is:

|BuildingName = <requirementstable>

This might look easy, but there are a few tricks in here, starting with the name itself.

Building Name[edit]

There are four possibilities when it comes to the building name:

  • It has a unique name
  • It has a substructure or building
  • It has variations
  • It has a conflicting name with a completely different building.

The unique name is simply the real name of the building, for example: "|Elevage Ovin =".

When the building has a substructure and you only want to refer to that, then the tilde (~) is used: "|Tansetsu~japaneseforge ="

In the case of variations, there are two options. The first is specifically naming each variation. This is done with the _X tag, where X is replaced by the capital letter of the variation, like this: "|Noujou Nojo_A =", "|Noujou Nojo_B =", etc. It is also possible to use the name "|Noujou Nojo =". Ghost has chosen that when that is used, all the variations should be listed. (More on this later.)

In the case of conflicting names, I've kind of forgotten how we'd handle that, but there were cases of it in the past. All I remember at this moment is that when there are multiple entries with exactly the same name, the template will use the first one it encounters. I will look into it when I have the time again.

Building Table Syntax[edit]

This is the part that goes behind the "|BuildingName =". This all can be done on the same line, or you can place returns as you see fit to make it more easily readible, the wiki will ignore those anyway. With the exception of a building who displays all its variations, the code for a building table is as follows:

<table class="reqirements">
<tr>
<th scope="col" style="text-align:center;"></th>
<td>[[File:{Item1_Image_File}|32px|{Itemname1 OR Itemname1 with link}]]</td>
<td>[[File:{Item2_Image_File}|32px|{Itemname2 OR Itemname2 with link}]]</td>
</tr>

<tr>
<th scope="row">Construction</th>
<td>{Amount of item1 for construction}</td>
<td>{Amount of item2 for construction}</td>
</tr>

<tr>
<th scope="row">Update 1</th>
<td>{Amount of item1 for upgrade 1}</td>
<td>{Amount of item2 for upgrade 1}</td>
</tr>

<tr>
<th scope="row">Update 2</th>
<td>{Amount of item1 for upgrade 2}</td>
<td>{Amount of item2 for upgrade 2}</td>
</tr>

</table>

You may notice things that look like typos, but these are intended. I personally don't know why it says reqirements instead of requirements, nor why it says update and not upgrade. To not break stuff, you will need to use the reqirements, and for consistency sake you're better off to use Update.

Now onto how the above code actually works. Due to the <> and [] already being used, the 'comments' are in betwee {} brackets.

First off, we start by generating a default table with a specific format. (<table class="reqirements">).
Next, we initialize the first row by using <tr>. This is followed by <th scope="col" style="text-align:center;"></th>. This gives some specifications to make the table look ok and should not be altered.
Now we need to list all the items that are used in any of the phases. For each item that is used, add the following line:
<td>[[File:{Item1_Image_File}|32px|{Itemname1 OR Itemname1 with link}]]</td>
Replace {Item1_Image_File} with the actual filename on this wiki, for example "Wood_Any.gif". Also replace {Itemname1 OR Itemname1 with link} with either the actual itemname, like Wood, or if the specific item has its own page on this wiki, a link to that page.
As an example, the following lines:

<td>[[File:Wood_Any.gif|32px|Wood]]</td>
<td>[[File:Wood.png|32px|Oak Wood]]</td>
<td>[[File:ML_mudbrick.png|32px|link=Hindi:Mud brick|Mud Brick]]</td>

Produces the following images:

WoodOak WoodMud Brick

After you are done with all the items, the row is closed off by the </tr>.

The next row is for the construction requirements and starts off with a new <tr>. Then comes the row's name in this line: <th scope="row">Construction</th>
After this comes the amounts for each material. This must be done in the same amount and order in which you did the itemnames before. If none of a specific item is needed for this tier, then you leave it blank. So, for example, if we have four different items, and the construction phase requires 5 pieces of the first item, 0 of the second, 12 of the third and 0 of the fourth, it would give the following code:

<td>5</td>
<td></td>
<td>12</td>
<td></td>

As you can see, there is no number in between the second and fourth set of brackets, but the brackets themselves are placed. It is very important that the amount of <td></td> matches the amount of <td></td> used in the 'itemrow'.
Finally, this row is closed again by a </tr>.

The method for the construction row is repeated for the upgrade rows as well, with the only difference being that the word "Construction" is replaced by "Update X", where X is replaced by the number of the update, starting from 1. An example will be given at the end of this section to clarify this.

Lastly, when all the upgrades are in place, we need to close the table of the section you want to add. This is done by simply placing the last </table>. Now you are done.

As for the promised example, here is the code for the Chota Saraay:

|Chota Saraay = 
<table class="reqirements">
<tr>
<th scope="col" style="text-align:center;"></th>
<td>[[File:Wood_Any.gif|32px|Wood]]</td>
<td>[[File:Wood.png|32px|Oak Wood]]</td>
<td>[[File:ML_mudbrick.png|32px|link=Hindi:Mud brick|Mud Brick]]</td>
<td>[[File:ML_whitewashedbricks.png|32px|link=Hindi:Cooked brick|Cooked Brick]]</td>
</tr>
<tr>
<th scope="row">Construction</th>
<td>34</td>
<td>8</td>
<td>130</td>
<td></td>
</tr>
<tr>
<th scope="row">Update 1</th>
<td></td>
<td></td>
<td></td>
<td>82</td>
</tr>
<tr>
<th scope="row">Update 2</th>
<td>4</td>
<td></td>
<td></td>
<td>55</td>
</tr>
</table>

And this is what it will look like:

WoodOak WoodMud BrickCooked Brick
Construction348130
Update 182
Update 2455

Building Table with all variations[edit]

It is also possible to make an entry for a building with variations that displays all the possible variations at once. Unfortunately, the way that this is accomplished is a bit ugly. Please keep in mind though, that it is the habit of putting both an entry for all variations combined as well as seperate entries for each variation into the requirements template.

To make this 'supertable', is basically combining all the variation tables into one bigger table. The syntax for this is as follows:

|BuildingName = 
<table>
<tr>
<td style="vertical-align:top;">
{Buildingtable Variation A}
</td>
<td style="vertical-align:top;">
{Buildingtable Variation B}
</td>
</tr>
</table>

You can add as many <td.... /td> sections as you want, one for each of the variations you want to list.
As for the {Buildingtable Variation X}, there is a tiny adjustment that you need to make to the building table of that variation, compared to what is explained in the previous section.
Normally, in the row where you place the item images, it starts with something like <th scope="col" style="text-align:center;"></th>. What you need to do when using the current structure, is add an extra name into it, so that it looks like this:

<th scope="col" style="text-align:center;">Variation X</th>

In here, you replace X by the correct letter of the variation, of course.
If this is confusing you, then here is an example of the Daidokoro. Please note that everything inside the {}, including the brackets themselves should be read as comments and are not to be copied over.

|Daidokoro = 
<table> {Start of the 'supertable'}
<tr>
<td style="vertical-align:top;">
{Underneath here comes the actual first table, the table of Variation A.}
<table class="reqirements">
<tr>
<th scope="col" style="text-align:center;">Variation A</th> {Note the extra title here}
<td>[[File:Wood_Any.gif|32px|Wood]]</td>
<td>[[File:Wood.png|32px|Oak Wood]]</td>
<td>[[File:ML_Thatch.png|32px|link=Japanese:Thatch|Thatch]]</td>
<td>[[File:Gravel.png|32px|Iron Ore]]</td>
<td>[[File:Cobblestone.png|32px|Cobblestone]]</td>
<td>[[File:ML_colombages_plain.png|32px|link=Norman:Colombages|Plain Timber Frame]]</td>
</tr>
<tr>
<th scope="row">Construction</th>
<td>8</td>
<td>16</td>
<td>132</td>
<td></td>
<td>16</td>
<td></td>
</tr>
<tr>
<th scope="row">Update 1</th>
<td>1</td>
<td>9</td>
<td>4</td>
<td>30</td>
<td>22</td>
<td></td>
</tr>
<tr>
<th scope="row">Update 2</th>
<td></td>
<td>1</td>
<td></td>
<td></td>
<td>31</td>
<td></td>
</tr>
<tr>
<th scope="row">Update 3</th>
<td>30</td>
<td>18</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<th scope="row">Update 4</th>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>24</td>
</tr>
</table> {End of the table of variation A}
</td>
<td style="vertical-align:top;">
{Under here is the start of variation B}
<table class="reqirements">
<tr>
<th scope="col" style="text-align:center;">Variation B</th> {Again, note the extra title}
<td>[[File:Wood_Any.gif|32px|Wood]]</td>
<td>[[File:Wood.png|32px|Oak Wood]]</td>
<td>[[File:Wood_Pine.png|32px|Pine Wood]]</td>
<td>[[File:ML_Thatch.png|32px|link=Japanese:Thatch|Thatch]]</td>
<td>[[File:Gravel.png|32px|Iron Ore]]</td>
<td>[[File:Cobblestone.png|32px|Cobblestone]]</td>
<td>[[File:ML_paperwall.png|32px|link=Japanese:Paper Wall|Paper Wall]]</td>
<td>[[File:ML_colombages_plain.png|32px|link=Norman:Colombages|Plain Timber Frame]]</td>
<td>[[File:Stone.png|32px|Stone]]</td>
<td>[[File:White_Wool.png|32px|White Wool]]</td>
</tr>
<tr>
<th scope="row">Construction</th>
<td>7</td>
<td>24</td>
<td>47</td>
<td>152</td>
<td></td>
<td>51</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<th scope="row">Update 1</th>
<td>1</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>19</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<th scope="row">Update 2</th>
<td>50</td>
<td>10</td>
<td>8</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<th scope="row">Update 3</th>
<td></td>
<td></td>
<td></td>
<td></td>
<td>8</td>
<td></td>
<td>4</td>
<td>28</td>
<td></td>
<td>2</td>
</tr>
<tr>
<th scope="row">Update 4</th>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>200</td>
<td></td>
</tr>
</table> {End of the table for variation B}
{The last three lines are to correctly close the 'supertable'}
</td>
</tr>
</table>

The code above will result into:

Variation AWoodOak WoodThatchIron OreCobblestonePlain Timber Frame
Construction81613216
Update 11943022
Update 2131
Update 33018
Update 424
Variation BWoodOak WoodPine WoodThatchIron OreCobblestonePaper WallPlain Timber FrameStoneWhite Wool
Construction7244715251
Update 1119
Update 250108
Update 384282
Update 4200

The example used above is actually a good example why the template itself looks like chaos. If we would do it in a readable way, it would take up quite a lot of space. This is probably the reason why Ghost and I tend to do everything in one line per building, instead of nicely putting returns and indentations. For one building, this isn't such a huge deal by the way, but keep in mind that there are quite a lot of buildings and variations and such. (Yup, we really need a better way for this template to function. Perhaps one day someone is bothered enough to rewrite it.)

Anyhow, that is the wiki-side of the requirements template. If you think that that part was hard, then I'm about to disappoint you. There is actually another part that needs to be done, which, at least for me, felt a lot less structured and more annoying to do. But then again, that was roughly a year ago. Perhaps things have changed.

Getting the data[edit]

The major timehog in updating the requirements template is to actually get the data that you need to do this. I am unsure as to how Ghost1972 did this, and my method might be outdated nowadays. I will try to research this soon again, but for now I will share what I can remember of what I used to do.

The main source of the data is a file named "resources_used.txt". This used to be auto-generated, but nowadays I believe you need to enable an option in the settings. Basically, you need to run Millenaire once to get the file created, and then start converting it.
The data you find in this file is the data that Millenaire uses in the mod itself for all of the buildings. Unfortunately, the format that Millenaire uses is completely different from the wiki-format. Adjusting one of the two formats is no good, so there is no way around it, you will need to convert the data yourself.
The 'easiest' way to do this, is to program a small program or script, or possibly even use Regex combined with a search and replace function like in Notepad++.
Since it has been so long, I cannot remember the exact details. What I do remember is that I wrote a simple program in Java to accomplish the conversion. You could alternatively try to disassemble the code of Millenaire and adjust it so that it saves in a format that is ready for the template or more easily converted to it. However, I would advise strongly against this! Besides the chance of making mistakes, you are breaking into the code of Kinniken himself. For all that he did to bring us his mod, I find this dishonourable and a big don't. I hope you'd think the same.
The things that I remember that I need to do, besides actually converting the data into a wiki-format, is to watch out for double entries, converting (French) itemnames into (English) itemnames accompanied by their wiki-image and possibly also their link. Variations also had to be treated in a special way, and another important thing was that per upgrade level, only the items that were actually needed, and their numbers, were noted.

But anyhow, I don't know the current format of "resources_used.txt" (yet), so the above might all be obsolete information. Whichever might be the case, my intend is to expand the information mentioned here into something more useful. If you attempt to convert the data, I would suggest doing it by hand for the first few buildings. Also, take different kind of buildings, some with variations, some with none, etc. After you've become accustomed to it, I would strongly recommend you to write a script or program to automate these conversions. That way you will only go mad once, during the writing of it, and have it easy when Millenaire updates, instead of going mad with each update.

I wish whoever is going to attempt to update the requirements template the best of luck. You might need it.