Feed The Beast Wiki:Tilesheet update guide

This is that manual.

Introduction
You may have noticed around the wiki we have Crafting Grid, Infobox, and Navbox Templates that show icons of blocks and items from mods. These images need to come from somewhere. The number of items covered would make individual image files incredibly impractical. And as such, the Tilesheet Extension was developed. The Extension has two components that are commonly interacted with: the sheet list and the item list. A Tilesheet is a single image file built out of images of all of the blocks and items that exist in a mod; the sheet list is a list of all tilesheets that have been created. The Item List is a list of every single block and item that exists on all tilesheets on the wiki, what mod's tilesheet the item comes from, and where exactly on the tilesheet that item is. Whenever Gc or NI references a mod name and item name, those values are fed into the tilesheet extension, and it returns the relevant item icon.

Preparation
has written a program that does most of the actual work for us. However, there are still certain prerequisites to updating a tilesheet.


 * 1) The program is written in Rust. In particular, it is written in Rust and compiled against Rust Nightly builds; it will likely fail to compile against stable or beta builds of Rust. As such, the first thing necessary to use it is an installation of Rust Nightly.
 * 2) The program itself. Put the folder of it in some obvious place.
 * 3) The program uses OptiPNG to compress the resulting tilesheet images and make them more suitably sized for upload. Place optipng.exe in the ftb-rs folder. Note: A PNG compression program other than OptiPNG can be used, however if you intend to do so you will need to modify the ftb-rs source code to tell it to use your other program, and you may need to write additional scripting to process inputs and outputs.
 * 4) Because every single change to an entry in the item list causes a change to appear in Special:RecentChanges, to reduce spam all full tilesheet updates must be done on a bot account with Staff user rights. To acquire a staff bot account, contact a wiki administrator.

Preparing the Tilesheet Program
Go to the folder where you placed the program you downloaded (ftb-rs), and open a command prompt in it. Type these two lines into it: set path=C:\Program Files\Rust nightly 1.3\bin cargo build path= represents the file path where your Rust Nightly was installed. (When this guide was written, the most recent Rust Nightly version was 1.3.) These commands will cause Rust to download all dependencies for the tilesheet builder program and compile it to run. If anything goes wrong, hope it doesn't, then contact on IRC.

After you have done this, create a new folder in ftb-rs named "work". In that folder, create a folder named "tilesheets".

Note: You will need to enter the set path= command in each new command prompt you open for this.

Preparing to Update or Create a Tilesheet
The first portion of this is done in Minecraft itself, and unfortunately at present can only be done easily on Minecraft 1.7.10 or newer. You will need a Minecraft instance containing the mod you want to build a tilesheet of, and NEI. Open a world, and in NEI, search for @Mod.Mod Name (where Mod Name is the name of the mod you want a tilesheet for). This will make NEI display only the items from that mod. Next, open the NEI Options menu (bottom left corner of the inventory screen). Go to Tools -> Data Dumps, then in Item Panel toggle the type (initially CSV) to PNG, increase the size to 64x64, and press Dump. This will create a new "dumps" subfolder in the folder where the current Minecraft instance is stored. That dumps folder will contain the folder itempanel_icons, which will contain a 64x64 .png image file of every single block and item in the mod. This is the easy part.

The hard part (hard because judgement-intensive) is searching through this folder to find images with duplicate names, or names that contain underscores (_). There are two reasons a file name can contain an underscore: inappropriate characters (:, /, etc.) in the actual item name, and duplicate item names. Fixing duplicate item names requires judgement on the part of you. The resulting images will be called Itemname.png, Itemname_2.png, Itemname_3.png, etc. Each of them must be renamed to reflect what the image actually represents. This does not mean renaming them to Itemname (1).png, Itemname (2).png, Itemname (3).png, etc. This means actually figuring out what they represent and naming them appropriately. If, and only if, the items with the same names are exactly the same image, then the duplicate images can be deleted. Otherwise, do not delete images. Fixing inappropriate characters is somewhat easier. To account for them, create a text file called renames.txt. In that text file, enter all incorrect file names and their correct names, using the following format: Type one item per line and nothing else in the file. Save the file using the encoding UTF-8 Without BOM.
 * Incorrect_ Name=Incorrect: Name

Open the ftb-rs/work/tilesheets folder, copy the itempanel_icons folder into the tilesheets folder, and rename it with the mod's abbreviation. A list of mod names and abbreviations can be found here. If the mod's abbreviation does not exist, consult with other staff and administrators on IRC.

Creating a New Tilesheet
Once the dependencies are lined up, you can get around to actually running the tilesheet builder. This is done through this command: cargo run --release -- update ABBRV where ABBRV represents the mod abbreviation. For future use, it may be useful to make a .bat file to make this easy, and modify the .bat file with different mod abbreviations. set path=C:\Program Files\Rust nightly 1.3\bin cargo run --release -- update ABBRV pause If it works correctly, this will create four new files: Tilesheet ABBRV 16.png, Tilesheet ABBRV 32.png, Added.txt, and Tilesheet ABBRV.txt. Upload both of these files to the wiki. Do not change their names. This is where having a bot account comes into play. Log in to that bot account yourself, and go to the Sheet Importer. In this page, enter the mod abbreviation, enter 16,32 in Tilesheet sizes, and then open Added.txt and copy its content into the Import data box. Unless you are entirely recreating a tilesheet, you do not need to pay attention to Tilesheet ABBRV.txt.

Note: Most tilesheets are very large, and if you attempt to import all entries at the same time the extension can easily time out. To prevent this, import entries in sets of 100 at a time.

Note 2: At the bottom of the Sheet Importer is a checkbox, "Overwrite existing." Do not check this box. Doing so will result in the deletion of all existing entries to that mod's tilesheet.

Updating an Existing Tilesheet
Note: This section follows the earlier "Preparing the Tilesheet Program" section. When updating an existing tilesheet, the goal is really just building a new tilesheet, but starting from the previous tilesheet rather than starting from scratch. As such, the existing tilesheet must be imported first.

To do this, first download the two already present tilesheet files from the wiki (Tilesheet ABBRV 16.png and Tilesheet ABBRV 32.png). Next, go to Special:TileList, search for items within the mod you want to update, and copy the entire list into a text file called imports.txt (saved using UTF-8 Without BOM encoding). Add one blank line at the end of the file. This file, along with the two downloaded images, goes in the work/tilesheets folder.

Next (assuming you already have a folder of new images and renames.txt), go back to ftb-rs, open a command line, and enter the line: cargo run --release -- import ABBRV where ABBRV represents the mod abbreviation. For future use, it may be useful to make a .bat file to make this easy, and modify the .bat file with different mod abbreviations. set path=C:\Program Files\Rust nightly 1.3\bin cargo run --release -- import ABBRV pause Running this command will create a text file, Tilesheet ABBRV.txt. Next, go back to the above section on Creating a New Tilesheet, and carry out the same process again.

As stated above, after all entries have been imported, to check that everything was a success, go to the mod's Navbox, and refresh your cache. If the correct item icons appear, you're done here. If incorrect items appear, refresh your cache again. If incorrect items still appear, check with other editors, and if they still appear then you screwed something up and we're going to have to figure out what and how to fix it. If something did get screwed up, contact an administrator immediately, preferably via IRC. (Try not to screw this up.)

Fully Recreating a Tilesheet
Note: This is not a common process. If you wish to fully recreate a tilesheet, consult an administrator for approval.

Fully recreating a tilesheet is done almost the same as creating a new tilesheet, with one important exception: At the bottom of the Sheet Importer page is a checkbox, "Overwrite existing". This is the only time that box should be checked, and it should only be used for the first page of the recreation. Also note that it takes a long time to delete each existing tile, so if the tilesheet has over 100 tiles you have to manually delete each tile (with a bot account!) until it is small enough to be overwritten. Also, if an existing tilesheet really is that big, that should be a huge warning to not try to recreate it, as you're very likely to be better off just updating it.