====== Tools Site ======

The Tools Site is a utility to help convert images into [[dev:zsprites|Zeromus sprites]], midi files into Harp songs, and set a specific sprite or song for an already generated FE ROM.

Once you've followed the [[dev:setup_guide|setup guide]] for being able to generate seeds from the command line, you can run the tools site from the ''fetools'' directory: ''python tool_site.py <rompath>'' and then navigate in a browser to ''localhost:8082''.

===== Zeromus Sprites =====
Once the site is running locally, click on ''Z Sprites Tool'' to navigate to that section of the site. There you can create new sprites, edit existing sprites, generate a test ROM, compile the sprite into the code necessary to get it into a ROM, download the ''.asset'' file for that sprite, and download all ''.asset'' files as a zip archive, or generate the catalog that you'll copy into the ''FreeEnt'' folder to actually have your sprites used by the randomizer generation.

=== Create New Asset ===
At the top of the ''/z'' page, there's a ''Create new asset'' link. Click that to navigate to ''/z/new'' which is the interface for adding a new sprite to your tools site. See [[dev:zsprites|Zeromus sprites]] for instructions and tips in actually making the image.

The create/edit page for an individual sprite has three sections:
  - Information/Metadata
  - Action buttons for testing/compiling the sprite
  - Save and Delete buttons

== Sprite Information and Metadata ==
This section has four properties: ''id'', ''name'', ''png'', and ''description''. The id is an auto-generated UUID, you don't have anything to do here. The name field has an implicit max length of 10 characters. You can have more, but the name will be truncated after 10 characters in game. It is, of course, tradition to have names end in ''mus''. The description field gets written into files, but is currently not used anywhere in the randomizer; it's probably a good idea to leave notes about the source of the image or maybe creator credit.

== Action Buttons ==
  * Download PNG - Downloads a png with the file using the full name you provided as the file's name.
  * Test ROM (and -vintage variant) - creates a ROM with a quick automated Z fight to show you your sprite and allow for quick iteration. 
  * Compile F4C (and -vintage variant) - creates a ''.f4c'' file suitable for replacing specific sprites in an already generated ROM.

== Save and Delete ==
  * Save saves the ''.asset'' to your ''./fe-tools/assets/z'' folder. This does not remove the sprite from the catalog of sprites that the generator will pull from for randomization
  * Deletes the ''.asset'' file for this Z sprite from your ''./fe-tools/assets/z'' folder. This does not remove the sprite from the catalog of sprites that the generator will pull from for randomization

==== Z Sprites list ====
This page in the tool lists all sprites that can be found under your ''./fe-tools/assets/z'' folder in a ''.asset'' file. From here, you can hover over each entry to see the ''.png'', generate a test ROM, create a ''.f4c'' file, and download the ''.asset'' file. There's also a link to download all ''.asset'' files, and a button to generate the full catalog of sprites.

The ''Generate full catalog'' button creates a ''.zip'' called ''zsprites_catalog.zip'' that contains ''.asset'' and ''.vintage.asset'' files for each of the assets in the ''./fe-tools/assets/z'' folder, as well as a ''catalog'' file. The ''catalog'' consists of the ids of all your ''.asset'' files, one per line.

To update the list of what sprites your generator will pull from when creating a seed, copy the unzipped contents of this folder to your ''./FreeEnt/compiled_zeromus_pics'' folder. You will want to make sure to overwrite files of the same name (or at least the ''catalog'') when you copy these files.

===== Harp Songs =====
Details coming sometime!

===== Rescripter =====
==== Overview ====
The Rescripter function allows the specification of Zeromus sprites and Harp songs after a seed is generated. Typically, this has been done to support donation incentives for marathons, or to showcase special selections for significant events.  In order to use Rescripter, you'll need a ROM, a ''.env'' file with at least the same ''FE_EMBEDDED_REPORT_KEY'' value, the ability to run an instance of the tools site, and the .f4c files for any sprites and songs you'd like to use.

The Rescripter tool has four sections, one for uploading the FE Rom you're adjusting, one for one or more Zeromus sprites to apply to the ROM, one for one or more harp songs to apply to the ROM, and finally a ''Generate rescripts button''.

=== The ROM ===
To start with, upload the ROM you're looking to adjust. If you're doing this for a marathon, see if you can get a vetted seed some days in advance. The rescripting itself doesn't take much time, but giving yourself some buffer is always a good idea. Remember uploading an FE seed, and not the base FFIV ROM.

=== Single Replacements ====
To just replace a single Zeromus sprite, all you have to do is upload the ''.f4c'' file for the sprite you want to patch in. You can, but do not need to, add a label. The easiest way to get the ''.f4c'' file is to download it from the ''Compile F4C'' button for a sprite in the Z Sprites list, or on the sprite's specific edit page. Substituting in a vintage sprite requires going to the edit page.

To just replace a single harp song, just add in the ''.f4c'' file for the song you'd like to patch in. Just like for a sprite, you can add in a label if you want, but it is not necessary.

You can replace both a single Z sprite and a single Harp song without using labels, and you can replace only a sprite or only a song when doing this; there is no need to replace both.

Once you have set your replacement data, click on the ''Generate rescripts'' button. The site will then perform the substitutions and download a `replacements.zip` file. Unzip that file to get your altered ROM, which will have ''.rescript'' appended just before the ''.smc'' in the file name.

=== Batch Replacements ===
If you are preparing a set of ROMs for a marathon with donation incentives, or otherwise need/want to do just one ''Generate rescripts'' button click, you can do so by using labels and uploading up to a total of four sprite and four songs. Each sprite and song will need their own label. The tool then will generate a Cartesian product of all the options (meaning: you will end up with a version of the seed with each possible pairing of a sprite and song), and when finished will download them all in a single `replacements.zip` file, which will unzip into a folder with the ROMs in it. Each ROM will be identified with the label you made for the sprite and for the harp song to help you select the correct one when it's time to provide it to the runners.