⚙️ Macros
Macros are in the he_api.h header. You can edit them in the header, or add them as preprocessor macros.
#define HE_LUA_BINDINGS 1
Set to 1 or 0 to compile/not compile the Lua bindings (default value is 1).
#define HE_SPRITE_MODULE 1
Set to 1 or 0 to compile/not compile the sprite system (default value is 1).
#define HE_GFX_STACK_SIZE 1024
Set the graphics stack size (default value is 1024).
🖼️ Bitmap
HEBitmap* HEBitmap_load(const char *filename);
Loads a new HEBitmap from a Playdate image file (similar to playdate->graphics->loadBitmap).
HEBitmap* HEBitmap_loadHEB(const char *filename);
Loads a new HEBitmap from a .heb file (use the Python encoder to create it). Heb files are faster to load but larger on disk compared to the Playdate image format.
HEBitmap* HEBitmap_fromLCDBitmap(LCDBitmap *lcd_bitmap);
Create a HEBitmap from a LCDBitmap.
void HEBitmap_draw(HEBitmap *bitmap, int x, int y);
Draws the bitmap at the given position.
int width;
Bitmap width (HEBitmap struct)
int height;
Bitmap height (HEBitmap struct)
LCDColor HEBitmap_colorAt(HEBitmap *bitmap, int x, int y);
Gets the color at the given position, it returns an LCDColor.
void HEBitmap_getData(HEBitmap *bitmap, uint8_t **data, uint8_t **mask, int *rowbytes, int *bx, int *by, int *bw, int *bh);
Gets the bitmap data, mask, rowbytes and bounds (surrounding transparent pixels are trimmed).
void HEBitmap_free(HEBitmap *bitmap);
Frees the bitmap.
🖼️ Bitmap Table
HEBitmapTable* HEBitmapTable_load(const char *filename);
Loads a new HEBitmap from a Playdate image table file (similar to playdate->graphics->loadBitmapTable).
HEBitmapTable* HEBitmapTable_loadHEBT(const char *filename);
Loads a new HEBitmapTable from a .hebt file (use the Python encoder to create it).
HEBitmap* HEBitmap_atIndex(HEBitmapTable *bitmapTable, unsigned int index);
Gets the bitmap at the given index in a table.
unsigned int length;
Table length (HEBitmapTable struct)
void HEBitmapTable_free(HEBitmapTable *bitmapTable);
Frees the bitmap table.
Sprite basics
HESprite* HESprite_new(void);
Creates a new sprite.
void HESprite_add(HESprite *sprite);
Adds the sprite to the system. This is required.
void HESprite_setBitmap(HESprite *sprite, HEBitmap *bitmap);
Sets a bitmap for the sprite.
void HESprite_setPosition(HESprite *sprite, float x, float y);
Sets the sprite position ignoring collisions.
void HESprite_moveTo(HESprite *sprite, float x, float y);
Moves the sprite.
void HESprite_setCenter(HESprite *sprite, float cx, float cy);
Sets the sprite center as a fraction in the range 0.0 - 1.0.
void HESprite_setZIndex(HESprite *sprite, int z);
Sets the z-index for the sprite. Default value is 0.
HEVec2 HESprite_getPosition(HESprite *sprite);
Gets the sprite position.
void HESprite_getSize(HESprite *sprite, int *width, int *height);
Gets the sprite size.
void HESprite_remove(HESprite *sprite);
Removes the sprite from the system.
Removing a sprite could be slow. If you plan to reuse it, consider hiding your sprite instead.
Functions
void he_sprites_move(float deltaTime);
Call this function to move the sprites and check the collisions. Pass a delta time as the first parameter.
void he_sprites_update(void);
Call this function to determine the visible sprites.
void he_sprites_draw(void);
Call this function to draw the sprites. You are responsible to clear the screen before drawing.
void he_sprites_resizeGrid(float x, float y, float width, float height, float cellSize);
A grid-based partioning system is used to determine collisions and visibility. Call this method to resize the grid and adapt it to your game. Resizing the grid could be slow, consider calling it before adding the sprites.
The default rect is (0, 0, display_width, display_height) with cellSize = 64.
HESprite** he_sprites_getAll(int *len);
Gets all the sprites. You shouldn't free the returned array.
void he_sprites_removeAll(void);
Removes all the sprites.
void he_sprites_setDrawOffset(int dx, int dy);
Set the draw offset, this is the same as moving a camera in a world (e.g. a player moving horizontally in a platform game).
void HESprite_setScreenClipRect(int x, int y, int width, int height);
Set a screen clip rect.
Sprite full docs
void HESprite_setTileBitmap(HESprite *sprite, HEBitmap *bitmap);
Sets a bitmap to be used as a tile (repeated bitmap).
void HESprite_setTileOffset(HESprite *sprite, int dx, int dy);
Sets the tile offset. For example, you can use it to scroll a repeated background.
void HESprite_setDrawCallback(HESprite *sprite, HESpriteDrawCallback *callback);
Sets a draw callback to customize the drawing. Drawing coordinates are relative to the sprite. Remember to set a size for the sprite to use it.
typedef void(HESpriteDrawCallback)(HESprite *sprite, HERect rect);
void HESprite_setEmpty(HESprite *sprite);
Sets a sprite as empty. This is the default state when a new sprite is created and not configured.
void HESprite_setSize(HESprite *sprite, float width, float height);
Sets the size for the sprite. This method has no effect if a bitmap is set.
int HESprite_isVisible(HESprite *sprite);
Gets the sprite visibility.
int HESprite_isVisibleOnScreen(HESprite *sprite);
Returns true if the sprite is currently visible on screen. It should be called after he_sprites_update()
void HESprite_setClipRect(HESprite *sprite, int x, int y, int width, int height);
Sets a clip rect for the sprite.
void HESprite_setClipRectReference(HESprite *sprite, HESpriteClipRectReference reference);
Set the reference used to calculate the clip rect (relative or absolute). Default value is
relative which means that the clip rect is in local coordinates. If you set
absolute, the clip rect is in screen coordinates.
typedef enum {
HESpriteClipRectRelative,
HESpriteClipRectAbsolute
} HESpriteClipRectReference;void HESprite_clearClipRect(HESprite *sprite);
Clears the clip rect for the sprite.
void HESprite_setIgnoresDrawOffset(HESprite *sprite, int flag);
Call this method to ignore the draw offset. Useful for UI elements or a background sprite at a fixed position.
void HESprite_setIgnoresScreenClipRect(HESprite *sprite, int flag);
Call this method to ignore the screen clip rect.
void HESprite_setUserdata(HESprite *sprite, void *userdata);
Sets the userdata for the sprite.
void* HESprite_getUserdata(HESprite *sprite);
Gets the userdata for the sprite.
void HESprite_setUpdateCallback(HESprite *sprite, HESpriteUpdateCallback *callback);
Set an update callback for the sprite. The update callback is called only when the sprite is visible on screen.
typedef void(HESpriteUpdateCallback)(HESprite *sprite);
💥 Collisions
void HESprite_setCollisionsEnabled(HESprite *sprite, int flag);
Enable or disable the collisions for the sprite. By default, collisions are not enabled.
void HESprite_setCollisionType(HESprite *sprite, HESpriteCollisionType type);
Set the collision type.
For the best performance, set HESpriteCollisionTypeIgnore if you don't need collisions detection from this sprite.
void HESprite_setCollisionTypeCallback(HESprite *sprite, HESpriteCollisionTypeCallback *callback);
Set the collision type as a callback.
typedef HESpriteCollisionType(HESpriteCollisionTypeCallback)(HESprite *sprite, HESprite *other);
For the best performance, return
HESpriteCollisionTypeIgnore if you don't need collisions detection for a specific pair.
Types
HESpriteCollisionTypeSlide
Set slide if you want the sprite to slide over other sprites.
HESpriteCollisionTypeFreeze
Set freeze if you want the sprite to stop when touches other sprites.
HESpriteCollisionTypeOverlap
Set overlap if you want to get notified when the sprite collides with other sprites.
HESpriteCollisionTypeBounce
Set bounce if you want the sprite to bounce touching other sprites.
HESpriteCollisionTypeIgnore
Set ignore if you want to ignore the collision early and skip other calculations (good for performance).
HESpriteCollisionType HESprite_getCollisionType(HESprite *sprite, int *isCallback);
Gets the collision type.
void HESprite_invalidateCollisionType(HESprite *sprite);
It invalidates the cached collision type (only if you use a callback).
void HESprite_cacheCollisionType(HESprite *sprite, int flag);
Enable or disable the cache for the collision type callback. In C, the cache is disabled by default.
int HESprite_collisionTypeIsBeingCached(HESprite *sprite);
Returns true if the cache is enabled for the collision type callback.
void HESprite_setFastCollisions(HESprite *sprite, int flag);
Enable or disable fast collisions for the sprite. If enabled, detection will be faster but tunnelling won't be supported.
HESpriteCollision* he_sprites_getCollisions(int *len);
Get the collisions occurred in the latest move call. You shouldn't free the returned array.
Collision
HESpriteCollision
typedef struct HESpriteCollision {
HESpriteCollisionType type;
HESprite *sprite;
HESprite *otherSprite;
HEVec2 normal;
HEVec2 touch;
HEVec2 goal;
HERectF rect;
HERectF otherRect;
} HESpriteCollisionHESpriteCollisionType type
Collision type.
HESprite *sprite
Sprite being moved.
HESprite *otherSprite
Other sprite.
HEVec2 normal
Normal. Allowed values are: -1, 0, 1. You can use it to determine which side collided with the other sprite. For nx, -1 is the left side, 1 is the right side. For ny, 1 is the bottom side, -1 is the top side.
HEVec2 touch
Sprite position where it started touching other.
HEVec2 goal
Goal position for the sprite.
HERectF rect
Sprite rect where it started touching other.
HERectF otherRect
Other sprite rect where it started touching sprite.
HESpriteCollision* HESprite_checkCollisions(HESprite *sprite, int *len);
Returns an array of collisions like he_sprites_getCollisions but without moving the sprite. You are responsible to free the array (check if array is NULL first).
HESprite** he_sprites_queryWithRect(float x, float y, float width, float height, int *len);
Returns all the sprites (with collisions enabled) in the given rect. You are responsible to free the array (check if array is NULL first).
HESprite** he_sprites_queryWithSegment(float x1, float y1, float x2, float y2, int *len);
Returns all the sprites (with collisions enabled) intersecting the given segment. You are responsible to free the array (check if array is NULL first).
HESprite** he_sprites_queryWithPoint(float x, float y, int *len);
Returns all the sprites (with collisions enabled) containing the given point. You are responsible to free the array (check if array is NULL first).
➡️ Animation
void HESprite_setFollowTarget(HESprite *sprite, HESprite *target);
Sets a target to follow. Pass NULL to unfollow the current target.
void HESprite_setFollowVelocity(HESprite *sprite, float velocity);
Sets the velocity with which the target is followed (pixel per second).
void HESprite_setFollowOffset(HESprite *sprite, float dx, float dy);
Sets an offset for the target position. Offset is calculated from the center of the sprite.
void HESprite_setFollowRefreshRate(HESprite *sprite, float rate);
Sets a refresh rate in order to update the target position at regular intervals (sprite movement will be delayed).