Differences

This shows you the differences between two versions of the page.

--- development:csdk:1.0:sprites [2024/11/08 01:57] – removed - external edit (Unknown date) 127.0.0.1
+++ development:csdk:1.0:sprites [2024/11/08 01:57] (current) – ↷ Page moved from development:csdk:sprites to development:csdk:1.0:sprites clyde
@@ Line 1: / Line 1: @@
+====== Importing and Drawing Sprites ======
+The SDK makes it easy to bring images into your game after you've [[development:aseprite|exported them]], particularly from Aseprite. This page will go into a bit more detail on how to incorporate the image files into your project and then how to load and draw them in your code.
+**Warning**: when exporting BMP images from GIMP, make sure to check "Do not write color space information" in the Compatibility options.
+=====Import=====
+The 2MB Cartridges have 128 banks of 16KB each, and the SDK scripts are designed to assign image assets to these banks based on the contents of the //assets// folder. Each subfolder of //assets// comprises one of the cartridge banks. Files dropped directly into the //assets// folder are ignored by the import scripts.
+After adding files to folders inside //assets//, run <code bash>make import</code>
+For example, in the games/tanks branch of the SDK there are three assets folders: "font", "gfx", and "music". For these folders the import script outputs
+<code bash>
+[ 'bios8.bmp' ]
+[
+  'countdown.bmp',
+  'countdown.json',
+  'exlposion.bmp',
+  'exlposion.json',
+  'green_tank.bmp',
+  'green_tank.json',
+  'ground.bmp',
+  'title.bmp'
+]
+[ 'tank_intro.mid' ]
+</code>
+In addition these files will be created in src/gen/assets with names based on the subfolders.
+  * font.h
+  * gfx.h
+  * music.h
+=====Drawing=====
+Drawing sprites on the GameTank is a two-step process. Before a sprite can be drawn it must be loaded into Sprite RAM. Once it is loaded into one of the sprite banks, it can be drawn either by specifying a rectangular portion of a sprite bank, or by an index into frame data exported by Aseprite.
+The function //load_spritesheet// takes a pointer to compressed sprite data, the ROM bank number where that data resides, and a sprite bank number to extract the image to. However, you don't actually need to specify the pointer or ROM bank directly.
+The generated header files, eg. src/gen/gfx if you created a "gfx" folder, provide convenience macros that contain the location of each image file.
+<code c>
+//Near top of file
+#include "../gen/assets/gfx.h"
+...
+//During your init process
+load_spritesheet(&ASSET__gfx__ship_bmp, 0); //Stores the ship graphics in sprite bank 0
+load_spritesheet(&ASSET__gfx__bug_bmp, 1); //Stores the bug graphics in sprite bank 1
+</code>
+=====Drawing by rectangle=====
+Once your graphics are loaded into a sprite bank, you can draw them with //draw_sprite//
+<code c>
+draw_sprite(X,Y,W,H,GX,GY,RAMBANK);
+</code>
+X and Y indicate coordinates on the screen. W and H are the width and height. GX and GY are the coordinates in the source image which you'd use to pick a tile or frame of animation from a sheet. RAMBANK is the bank number that you earlier specified to load_spritesheet.
+//draw_sprite// is part of the queued drawing API, so you can consecutively call other queued drawing functions and they'll be proeccessed one at a time, in order.
+When there's no more drawing or computation to do for the current frame, use //await_draw_queue()//, //sleep(1)//, and //flip_pages()// to present your frame to the TV!
+=====Drawing by frame number=====
+If you've exported a packed sprite sheet alongside JSON frame data, you can use //draw_sprite_frame//. This function can not only select the rectangle in your sprite sheet from a frame number, it also centers your sprite on the canvas center used in Aseprite and had a parameter for flipping horizontally and/or vertically.
+<code c>
+void draw_sprite_frame(
+    const Frame *sprite_table,
+    char sprite_table_bank,
+    char x, char y,
+    char frame,
+    char flip,
+    char bank);
+</code>
+Referring to the JSON data is similar to referring to the sprite data in //load_spritesheet// and combines the first two arguments into one macro.
+<code c>
+draw_sprite_frame(&ASSET__gfx__ship_json, ship_x, ship_y, anim_frame, SPRITE_FLIP_NONE, 0);
+</code>