Warnings and Errors

This page covers the command line semantics of the various warning options, as well as the details of each specific warning. Warnings can occur in compilation or decompilation modes. However, most warnings are specific to one more or the other. I suggest you always enable -Wall, no matter which mode you are using.

Warning Options

`-Wsome-warning`

Enable the warning some-warning (see below for a full list of warnings).

`-Wno-some-warning`

Disable the warning some-warning (see below for a full list of warnings).

`-Wall`

Enable all warnings.

`-Wnone`

Disable all warnings.

`-Werror`

Set all enabled warnings to generate errors instead.

`-Werror=some-warning`

Enable warning some-warning, and set it to generate an error.

`-Wno-error=some-warning`

Downgrade warning some-warning from an error to a regular warning. If some-warning is already at the warning level, or some-warning is not enabled, this will no op.

Warning Option Semantics

By default, Porytiles disables most warnings, since input assets that generate warnings upon (de)compilation will technically still (de)compile to a valid tileset. However, I recommend that you enable warnings to catch silly mistakes or usage misundertandings. The best setting is to just enable -Wall and be done with it. However, you can enable or disable particular warnings with -Wsome-warning, where some-warning is the name of some warning listed in the next section.

Warning Command Line Precedence

Warning options on the command line follow some simple precedence rules. Higher priority options always take precedence over lower priority options. The option priority is as follows, from highest to lowest:

-Wnone
1. This option will supersede any other supplied warning option. If -Wnone is suppled anywhere on the command-line, all warnings will be disabled regardless of any other supplied warning options.
-Werror / -Werror=some-warning
1. The next highest priority is -Werror and family. This means that specifying both -Wsome-warning and -Werror=some-warning on the same command line will always result in some-warning generating an error, no matter in which order these two options were supplied. Please note that a bare -Werror by itself will not actually enable any warnings/errors. Rather, it will upgrade any already-enabled warnings to errors. -Werror is most commonly used in conjuction with -Wall, like this: -Wall -Werror, which means "enable all warnings as errors."
-Wsome-warning
1. -Wsome-warning takes priority only over -Wall. This is useful because you may want to enable all warnings, and then specifically disable a particular warning like: -Wall -Wno-some-warning or -Wno-some-warning -Wall
-Wall
1. -Wall takes the lowest priority of all options. Specific warning or warning-as-error requests will always override the general -Wall setting.

Warning options at the same level of precedence are evaluated such that the right-most supplied option always takes precedence. For example, the following commandline would result in some-warning being enabled: -Wsome-warning -Wno-some-warning -Wsome-warning, since -Wsome-warning is the right-most option related to some-warning.

Specific Warnings

Compilation Warnings

`-Wcolor-precision-loss`

The GBA uses BGR15 colors while Porytiles input tile assets use 32 bit RGBA, so there will be some precision loss when converting the input colors into GBA colors (i.e. 8 bit RGBA channels get turned into 5 bit BGR15 channels). This means that you can possibly provide two distinct RGBA colors in the input that ultimately collapse into the same BGR color in the output. This warning alerts you when that happens, so you can know when some color detailing that may be apparent on the RGBA sheets won't show up on the GBA display. This precision loss is left as a warning because it is quite common, and doesn't technically break your tileset in any real way. Defaults to off.

`-Wkey-frame-no-matching-tile`

The animation frame specified in key.png, for a given animation, should be used on the layer sheets to specify that a particular tile is animated. This warning alerts you when the tiles specified in a certain animation's key.png do not appear anywhere on the layer sheet. This typically indicates an oversight on your part. Defaults to off.

`-Wkey-frame-missing-colors`

This warning alerts you when a subtile in an animation key frame does not contain all colors used across the rest of that subtile's animation frames. In some cases, this can lead to the issue described here. For backwards compatibilty reasons, the key frame missing color detection functionality defaults to the warning level. However, it's recommended that you enable it as an error via -Werror=key-frame-missing-colors for future compilations, since proper key frame coloring will prevent footguns related to Issue #60. Defaults to on.

`-Wattribute-format-mismatch`

This warning alerts you when the attributes specified in the header of attributes.csv do not match the target base game. Base games pokeemerald/pokeruby and pokefirered have different attribute formats. Specifically, pokefirered metatiles contain the same id and behavior attributes as pokeemerald/pokeruby, but they additionally contain terrain_type and encounter_type attributes. This warning will display if attributes.csv is missing these extra attributes while the target base game is set to pokefirered. It will also display if you specify fields beyond id and behavior for target base games pokeemerald/pokeruby. Defaults to off.

`-Wmissing-attributes-csv`

This warning alerts you when attributes.csv is missing. When there is no attributes.csv in the source folder, Porytiles will apply the default values to all metatile attributes. Defaults to off.

`-Wunused-attribute`

This warning alerts you when attributes.csv specifies an attribute for a metatile ID that does not exist in the layer sheet. Defaults to off.

`-Wtransparency-collapse`

As noted in the description for -Wcolor-precision-loss, the GBA uses BGR15 colors while Porytiles input tile assets use 32 bit RGBA. This warning is like -Wcolor-precision-loss, except that it notifies you when a non-transparent RGBA color in the input tile assets will collapse to the transparent BGR15 color. For example, the default Porytiles transparent color is set to RGBA=255,0,255, which translates to BGR15=248,0,248 when precision loss is accounted for. This means that if you use e.g. RGBA=250,0,250 in the input tile assets, it will collapse to the transparent color upon compilation. This warning will alert you to the collapse, which was probably unintentional. Defaults to off.

`-Wunused-manual-pal-color`

This warning alerts you when there is a color present in one of your palette primers or palette overrides that is not present in your layer PNGs or anim PNGs. Leaving unused colors in your primers or overrides wastes palette slots and makes it more difficult for Porytiles to automatically assign your palettes.

Note

-Wunused-manual-pal-color does not account for BGR conversion. This means that if e.g. one of your primers contains 254 19 0, and your layer PNGs contain 252 21 3, you will see a -Wunused-manual-pal-color showing 254 19 0 as unused, as well as a -Wcolor-precision-loss showing that both 254 19 0 and 252 21 3 collapsed to the same BGR. Your tileset will still compile, and the layer tile containing 252 21 3 will be correctly mapped to the primer containing 254 19 0. However, it's recommended that you fix these warnings, since they usually indicate careless asset copy-paste. You should always carefully consider which new colors you are introducing when making edits. This makes debugging issues much easier.

Defaults to off.

Decompilation Warnings

`-Wtile-index-out-of-range`

This warning alerts you when one of the input metatile entries contains a tile index that is out of range. This issue exists in the vanilla tilesets, whose metatile entries occasionally contain garbage tile indexes. It can also occur in a manually-managed tileset if you are not careful when making edits. You usually don't notice this problem because the pokeemerald engine doesn't actually care if a tile index is out of range. It will happily display the garbage VRAM content corresponding to the out-of-range index. However, for Porytiles decompilation, this won't work. Porytiles must choose something to display. So by default, it will simply substitute primary tile 0 (i.e. the transparency tile) for the invalid index and continue decompilation. Defaults to off.

`-Wpalette-index-out-of-range`

Similar to the -Wtile-index-out-of-range warning above, but triggers when the palette index is out of range. By default, Porytiles will substitute palette index 0 and continue decompilation. Defaults to off.

To wiki home page.

To project home page.