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 into the folder with all the icons 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 the images to the wiki. Do not change their names. Makes sure to put them in the, and to add them to Feed The Beast Wiki:Placeholder.

The next part 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  (without the quotations, but with the space) 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 50 or 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, log in, go to Special:TileList, search for items within the mod you want to update, and copy the entire list without the headline into a text file called "import.txt" (saved using UTF-8 Without BOM encoding). Add one blank line at the end of the file. The list in the "import.txt" must then look something like in the picture. Several things in the list are important:
 * 1) All columns from "Edit" to "Size of the images (16px, 32px)" are in the list.
 * 2) One blank line must be inserted at the bottom.
 * 3) It should be checked whether in the last column "16px, 32px" stands, with a space between the comma and the 3.

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.

Compile error on Windows
running: "gcc.exe" "-O0" "-ffunction-sections" "-fdata-sections" "-g" "-m64" "-o " "D:\\Daten\\Rust\\ftb-rs-master\\target\\debug\\build\\miniz-sys-6a96c81df5f92 18f\\out\\miniz.o" "-c" "miniz.c" ExitStatus(ExitStatus(1))

command did not execute successfully, got: exit code: 1

--- stderr gcc.exe: error: CreateProcess: No such file or directory thread ' ' panicked at 'explicit panic', C:\Users\LuminousLizard\.cargo\reg istry\src\github.com-88ac128001ac3a9a\gcc-0.3.19\src\lib.rs:771

Solution: For Win 64bit install "MinGw-w64" from this page and set in the system variables the path to the "bin" folder in the installation (standard for 64bit: C:/Program Files/mingw-w64/x86_64-5.2.0-win32-seh-rt_v4-rev1/mingw64/bin)

Error when updating a tilesheet (1)
Import command accepted but program stops and nothing is created. D:\Daten\Rust\ftb-rs-master>cargo run --release -- import PR    Running `target\release\ftb.exe import PR`

D:\Daten\Rust\ftb-rs-master>

Solution: Your "import.txt" is not readable. Name of the file may be incorrectly written, or saved in the wrong format or encoding.

Error when updating a tilesheet (2)
Import command accepted but program stops and the "Tilesheet ABBRV.txt" is created but empty. D:\Daten\Rust\ftb-rs-master>cargo run --release -- import PR    Running `target\release\ftb.exe import PR` Importing Tilesheet

D:\Daten\Rust\ftb-rs-master>

Solution: In the list of your "import.txt" is something incorrectly written. Read Updating an Existing Tilesheet again.

Error when creating a tilesheet
Update command accepted but program returns following error message and nothing is created: $ sudo cargo run --release -- update MSC Running `/home/luminouslizard/Rust/ftb-rs-master/target/release/ftb update MSC`

Loading tilesheet No tilesheet found. Creating new tilesheet. Updating tilesheet

thread ' ' panicked at 'called `Result::unwrap` on an `Err` value: Error { repr: Os { code: 2, message: "No such file or directory" } }', ../src/libcore/result.rs:688 Process didn't exit successfully: `/home/luminouslizard/Rust/ftb-rs-master/target/release/ftb update MSC` (exit code: 101)

Solution: The command prompt is opened in the wrong folder. Open the command prompt in the folder where you placed the program you downloaded (standard: ftb-rs or ftb-rs-master where the "target" and "src" folder is located).