HuC Directives

• incpal : This top level instruction allows to include a palette coming from a .pcx file. It's basically a wrapper for the magic kit equivalent instruction. It exists in 3 flavors :
  1. #incpal(identifier_name, “filename”);
     Creates a series of palette identified by identifier_name coming from the file called filename. It extracts 16 palettes from the 0th to the 15th.
  2. #incpal(identifier_name, “filename”, start_pal);
     Extract only from palette start_pal to the 15th
  3. #incpal(identifier_name, “filename”, start_pal, number_pal);
     Extract number_pal palettes from palette start_pal.
• incspr : This instruction includes data for sprite patterns from a .pcx file.
  1. #incspr(identifier_name, “filename”);
     Extract all possible 16×16 sprites from the file called filename.
  2. #incspr(identifier_name, “filename”, col, row);
     Extract only row rows and col columns of 16×16 sprites from the file.
  3. #incspr(identifier_name, “filename”, begin_x, begin_y, col, row);
     Extract row rows and col columns of 16×16 sprites starting at position (begin_x, begin_y)
• incchr : This instruction includes data for character patterns from a .pcx file.
  1. #incchr(identifier_name, “filename”);
     Extract all possible 8×8 tiles from the file called filename.
  2. #incchr(identifier_name, “filename”, col, row);
     Extract only row rows and col columns of 8×8 tiles from the file.
  3. #incchr(identifier_name, “filename”, begin_x, begin_y, col, row);
     Extract row rows and col columns of 8×8 tiles starting at position (begin_x, begin_y)
• incchr_ex : This instruction includes data for character patterns from a series of .pcx files, and sets up for the “new style” of 8×8 scroll-tiling.
  1. #incchr(identifier_name, “filename_1”, begin_x, begin_y, col, row, pal_idx1, \
     “filename_2”, begin_x, begin_y, col, rox, pal_idx2, \
     “filename_n”, begin_x, begin_y, col, rox, pal_idxn );
     Extract row rows and col columns of 8×8 tiles starting at position (begin_x, begin_y), and using the stated pal_idx from filename_1 (etc.), assembling them as a single list of tiles in memory, available for use in the map and scrolling functions
• inctile : This instruction includes data for tile patterns from a .pcx file.
  1. #inctile(identifier_name, “filename”);
     Extract all possible 16×16 tiles from the file called filename.
  2. #inctile(identifier_name, “filename”, col, row);
     Extract only row rows and col columns of 16×16 tiles from the file.
  3. #inctile(identifier_name, “filename”, begin_x, begin_y, col, row);
     Extract row rows and col columns of 16×16 tiles starting at position (begin_x, begin_y)
• inctile_ex : This instruction includes data for character patterns from a series of .pcx files, and sets up for the “new style” of 16×16 scroll-tiling.
  1. #inctile(identifier_name, “filename_1”, begin_x, begin_y, col, row, pal_idx1, \
     “filename_2”, begin_x, begin_y, col, rox, pal_idx2, \
     “filename_n”, begin_x, begin_y, col, rox, pal_idxn );
     Extract row rows and col columns of 16×16 tiles starting at position (begin_x, begin_y), and using the stated pal_idx from filename_1 (etc.), assembling them as a single list of tiles in memory, available for use in the map and scrolling functions
• incbat : This is a special instruction that include a kind of map used to recreate a background picture in conjunction with inclusion of tiles pattern. We've set another pseudo instruction that does that but it's not completely flexible (see load_background).
  1. #incbat(identifier_name, “filename”, pcx_offset);
     Extract the map for displaying the whole pcx containing in the file filename. pcx_offset is the position in the video ram where will be stored the pattern to draw the picture. I advise you to let 0x1000 for this argument, if you want to use the load_background instruction for now.
  2. #incbat(identifier_name, “filename”, pcx_offset, col, row)
     Extract only col columns and row rows from the file.
  3. #incbat(identifier_name, “filename”, pcx_offset, begin_x, begin_y, col, row);
     Extract only col columns and row rows starting at position (begin_x, begin_y)
• defpal : This instruction allows you to define a palette data in your code. Instead of referencing it from a picture, you will simply tell the RGB components for each color of the palette.
  1. #defpal(identifier_name, <color component> * 16);
     You are not obliged to define all 16 colors of a palette. As for the components, they are easy to use if you use the hexa decimal notation in which only the 3 last digits are used and represent (from left to right) red, green and blue. The maximum for each component is 7, thus a perfect while is 0x777, while a purple is something like 0x607…
• defspr : With this one, you'll define your own sprites using also inline data, not coming from a picture.
  1. #defspr(identifier_name, vram_address, default_palette, <8 pixels data> * 32);
     The vram_address is a value in the range 0-0x10000 which tell the assembler where you want to see these data in the video ram. Don't forget that before using a sprite and such, you'll have to load data into video ram before the real use. In fact, this argument just tells a preference and its value doesn't oblige you to respect this. This is also true for the default_palette (there are 16 palettes for sprites). As for the data, I recommand you to use the hexadecimal notation, in which each 32 bits number easily represent 8 pixels using a digits for each. I bet a little example will make this appear clearer. To declare 8 pixels beginning by 3 pixels of color 5, then 2 of color 10 and finishing by color 1, you'll use the number 0x555AA111. Since we're defining 16×16 sprites, we need two of these numbers to define a line and thus we'll have 32 arguments to define the whole sprite pattern.

• defchr : basically, you should have guessed what this one is for :) (I'm also pretty tired to make documentation *yawn* )
  1. #defchr(identifier_name, vram_address, default_palette, <8 pixels data> * 8);
     See defspr for most information. I just want to confirm that you also have 16 palettes for tiles data (which makes a total of 32 differents palettes). And since a tile is only 8×8, you have only one hexa number per line and 8 of these numbers. You can have a look at the debug.c file which has the font used for printing defined this way (notice how the vram_address is useless :)

• Offset can be added to far pointers. Offset are those name/pointer created when including tiles or sprites and such. This feature enables you to write such a piece of code :

  #include(tiles, "tiles.pcx", 1, 16);
  load_vram(0x1400, tiles + (1 << 6), 64);

• All included data through #INC and #DEF directives can be accessed as const array too. #INCBIN directive creates a char array while others create int arrays.
  After having wrote

  #INCBIN(level1, "level1.fmp");

  It's exactly as if you had wrote

  const char level1[] = { <stuff inside level1.fmp> };

• Some functions have been added to the libC, get_tile(x,y) to return the index of the tile at position x,y in the current map (for sprite/tile collision checking, isn't it, gravis ?). get_map_width() and get_map_height() which work on the current map.
  HUGE maps are supported! 16384×16384 tiles (which is 262144×262144 pixels) is what I call huge Well, all maps functions are still limited to 256×256 maps but we can now gather all of them using a special array and a special function, scan_map_table() . This function returns the map at the requested position.
  Here's an example :

        #incbin(level1, "level1.fmp") /* 256x256 */
        #incbin(level2, "level2.fmp") /* 256x256 */
        #incbin(level3, "level3.fmp") /* 256x256 */
        #incbin(level4, "level4.fmp") /* 256x256 */

        const int big_map[] = {
        /* width & height of all the maps
         * put together
         */
          512, 512,

        /* the following lines declare all
         * the small maps, one line per map :
         *
         * the two first values are the top/left
         * coordinates of the small map inside
         * the big map, the two followings values
         * are bottom/right coordinates (inclusive),
         * and the two last values are the map
         * address in ROM
         */

          0,   0, 255, 255, bank(level1), level1,
        256,   0, 511, 255, bank(level2), level2,
          0, 256, 255, 511, bank(level3), level3,
        256, 256, 511, 511, bank(level4), level4,

        /* -1 closes the table */

        -1
};