The GameTank SDK uses generated header files for providing references to imported game assets.
Every subfolder of the assets folder in the project root will have a corresponding header file created under src/gen/assets after running make or make import.
These header files will contain a handful of macros for each file in that assets subfolder. These macros are generated from the filename and parent folder name as follows:
ASSET__{dir name}__{file name without extension}_{extension}
or
ASSET__{dir name}__{file name without extension}_{extension}_{suffix}
The version without _suffix is a reference that can be passed into functions expecting consecutive pointer and bank number arguments.
The versions with _suffix are used to give specific generated properties used to reference the asset:
_ptr gives the address where the asset can be found when its bank is active
_bank gives the number of the ROM bank where the asset data resides
_ID gives the index of the asset within its respective Extension Table (see below)
_size if present gives the size of the original unconverted file (so it's mainly useful when the file is a binary copied straight into the ROM, such as .bin or .sfx)
play_song(ASSET__audio__gameloop_mid, REPEAT_LOOP);
Here, play_song actually takes three arguments and ASSET__audio__gameloop_mid provides the first two. The macro resolves to ASSET__audio__gameloop_mid_ptr, ASSET__audio__gameloop_mid_bank and saves you a lot of typing.
In addition to the header files for each asset folder, the assets are also indexed by their file extension so that some functions can refer to them by a numeric ID. This means that each file extension present under the assets folder will get a pair of arrays defined in assets_index.h:
extern const void* ASSET__{extension}_ptr_table[]; //Table of pointers to asset data
extern const unsigned char ASSET__{extension}_bank_table[]; //Table of asset bank numbers
Of special note are the tables for .bmp and .sfx which will be created even if they are empty. These are used by SDK functions so they need to always be defined.
These tables make it possible to pass a reference to an asset by a single byte argument instead of three bytes of argument. This helps avoid invoking the C soft stack and increases performance.