HEBitmap Lua Docs

⚙️ Initialization

void he_library_init(PlaydateAPI *pd, int enableLua);

Initialize the library in C, call it in kEventInitLua. Pass 1 as the second parameter to enable Lua support.

🎨 Graphics

he.graphics.setClipRect(x, y, w, h)

Set the clip rect.

he.graphics.clearClipRect()

Clear the clip rect.

he.graphics.pushContext()

Push the graphics context.

he.graphics.popContext()

Pop the graphics context.

🖼️ Bitmap

he.bitmap.new(path)

Loads a new HEBitmap from a Playdate image file (similar to playdate.graphics.image.new).

he.bitmap.loadHEB(path)

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.

he.bitmap:draw(x, y)

Draws the bitmap at the given position.

he.bitmap:getSize()

Gets bitmap size as (width, height).

he.bitmap:colorAt(x, y)

Gets the color at the given position. It returns a Playdate color such as playdate.graphics.kColorBlack.

🖼️ Bitmap Table

he.bitmaptable.load(path)

Loads a new HEBitmap from a Playdate image table file (similar to playdate.graphics.imagetable.new).

he.bitmaptable.loadHEBT(path)

Loads a new HEBitmapTable from a .hebt file (use the Python encoder to create it).

he.bitmaptable:getBitmap(index)

Gets the bitmap at the given index in a table (1-based indexing).

he.bitmaptable:getLength()

Gets the table length.

👾 Sprite system

The sprite system allows to efficiently move, check collisions and draw sprites.

It's optional. If you don't want to include it, open he_api.h and set #define HE_SPRITE_MODULE 0. You can then remove he_sprite.h/c from your project.

Sprite basics

he.sprite.new()

Creates a new sprite. You can create your own sprite instance by extending HESprite

class("Player").extends("HESprite")

local player = Player()
player:setBitmap(bitmap)

he.sprite:add()

Adds the sprite to the system. This is required.

he.sprite:setBitmap(bitmap)

Sets a bitmap for the sprite.

he.sprite:setPosition(x, y)

Sets the sprite position ignoring collisions.

he.sprite:moveTo(x, y)

Moves the sprite.

he.sprite:setCenter(cx, cy)

Sets the sprite center as a fraction in the range 0.0 - 1.0.

he.sprite:setZIndex(z)

Sets the z-index for the sprite. Default value is 0.

he.sprite:getPosition()

Gets the sprite position.

he.sprite:getSize()

Gets the sprite size.

he.sprite:remove()

Removes the sprite from the system.
Removing a sprite could be slow. If you plan to reuse it, consider hiding your sprite instead.

Functions

he.sprite.move(deltaTime)

Call this function to move the sprites and check the collisions. Pass a delta time as the first parameter.

he.sprite.update()

Call this function to determine the visible sprites.

he.sprite.draw()

Call this function to draw the sprites. You are responsible to clear the screen before drawing.

he.sprite.resizeGrid(x, y, w, h, 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.

he.sprite.getAll()

Gets all the sprites. You shouldn't free the returned array.

he.sprite.removeAll()

Removes all the sprites.

he.sprite.setDrawOffset(dx, 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).

he.sprite.setScreenClipRect(x, y, w, h)

Set a screen clip rect.

Sprite full docs

he.sprite:setTileBitmap(bitmap)

Sets a bitmap to be used as a tile (repeated bitmap).

he.sprite:setTileOffset(dx, dy)

Sets the tile offset. For example, you can use it to scroll a repeated background.

he.bitmap:setDrawCallback(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.

he.bitmap:setDrawCallback(function(sprite, x, y, w, h)
	gfx.setColor(gfx.kColorBlack)
	gfx.fillRect(0, 0, w, h)
end)

he.sprite:setEmpty()

Sets a sprite as empty. This is the default state when a new sprite is created and not configured.

he.sprite:setSize(width, height)

Sets the size for the sprite. This method has no effect if a bitmap is set.

he.sprite:isVisible()

Gets the sprite visibility.

he.sprite:isVisibleOnScreen()

Returns true if the sprite is currently visible on screen. It should be called after he.sprite.update()

he.sprite:setClipRect(x, y, w, h)

Sets a clip rect for the sprite.

he.sprite:setClipRectReference(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.

he.sprite.kClipRectRelative
he.sprite.kClipRectAbsolute

he.sprite:clearClipRect()

Clears the clip rect for the sprite.

he.sprite:setIgnoresDrawOffset(flag)

Call this method to ignore the draw offset. Useful for UI elements or a background sprite at a fixed position.

he.sprite:setIgnoresScreenClipRect(flag)

Call this method to ignore the screen clip rect.

he.sprite:setUpdateCallback(callback)

Set an update callback for the sprite. The update callback is called only when the sprite is visible on screen.

sprite:setUpdateCallback(function(sprite)
	--update the sprite
end)

💥 Collisions

he.sprite:setCollisionsEnabled(flag)

Enable or disable the collisions for the sprite. By default, collisions are not enabled.

he.sprite:setCollisionType(type)

Set the collision type, you can pass in a constant or a function to be used as a callback.

Example with a constant. This is the preferred and most efficient way.

sprite:setCollisionType(he.sprite.kCollisionTypeSlide)

Example with a callback. By default, the result of the callback is cached and should be invalidated when needed.

sprite:setCollisionType(function(sprite, otherSprite)
	return he.sprite.kCollisionTypeOverlap
end)

For the best performance, set or return he.sprite.kCollisionTypeIgnore if you don't need collisions detection for a specific pair.

Types

he.sprite.kCollisionTypeSlide

Set slide if you want the sprite to slide over other sprites.

he.sprite.kCollisionTypeFreeze

Set freeze if you want the sprite to stop when touches other sprites.

he.sprite.kCollisionTypeOverlap

Set overlap if you want to get notified when the sprite collides with other sprites.

he.sprite.kCollisionTypeBounce

Set bounce if you want the sprite to bounce touching other sprites.

he.sprite.kCollisionTypeIgnore

Set ignore if you want to ignore the collision early and skip other calculations (good for performance).

he.sprite:getCollisionType()

Gets the collision type.

he.sprite:invalidateCollisionType()

It invalidates the cached collision type (only if you use a callback).

he.sprite:cacheCollisionType(flag)

Enable or disable the cache for the collision type callback. In Lua, the cache is enabled by default.

he.sprite:collisionTypeIsBeingCached()

Returns true if the cache is enabled for the collision type callback.

he.sprite:setFastCollisions(flag)

Enable or disable fast collisions for the sprite. If enabled, detection will be faster but tunnelling won't be supported.

he.sprite.getCollisions() -> collisions, length

Get the collisions occurred in the latest move call. It returns an array of he.spritecollision objects and a length.

Collision

he.spritecollision:getType()

Gets the collision type.

he.spritecollision:getSprite()

Gets the sprite being moved.

he.spritecollision:getOtherSprite()

Gets the other sprite.

he.spritecollision:getNormal() -> nx, ny

Returns the two components of the normal (nx, ny). 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.

he.spritecollision:getTouch()

Gets the sprite position where it started touching other.

he.spritecollision:getGoal()

Gets the goal position for the sprite.

he.spritecollision:getRect()

Gets the sprite rect where it started touching other.

he.spritecollision:getOtherRect()

Gets the other sprite rect where it started touching sprite.

he.sprite:checkCollisions() -> collisions, length

Returns an array of collisions like he.sprite.getCollisions() but without moving the sprite.

he.sprite.queryWithRect(x, y, w, h) -> sprites, len

Returns all the sprites (with collisions enabled) in the given rect.

he.sprite.queryWithSegment(x1, y1, x2, y2) -> sprites, len

Returns all the sprites (with collisions enabled) intersecting the given segment.

he.sprite.queryWithPoint(x, y) -> sprites, len

Returns all the sprites (with collisions enabled) containing the given point.

➡️ Animation

he.sprite:setFollowTarget(sprite)

Sets a target to follow. Pass nil to unfollow the current target.

he.sprite:setFollowVelocity(velocity)

Sets the velocity with which the target is followed (pixel per second).

he.sprite:setFollowOffset(dx, dy)

Sets an offset for the target position. Offset is calculated from the center of the sprite.

he.sprite:setFollowRefreshRate(rate)

Sets a refresh rate in order to update the target position at regular intervals (sprite movement will be delayed).