Sprite Engine Basics

Welcome to Unit 4 — Building Games! HyperXTalk includes a powerful built-in sprite engine that lets you create 2D games with moving characters, collision detection, and smooth animation. In this lesson you'll learn the fundamentals: placing sprites, making them move, tracking keyboard input, and detecting when sprites collide.

🎮 Overview

The HyperXTalk sprite engine revolves around three things: a Sprite Canvas widget that does the rendering, a set of commands for creating and controlling sprites, and a tick loop that calls your card script many times per second so you can update game state.

The engine script is included with HyperXTalk. Add it to your stack once and all the sprite commands become available everywhere. The basic structure of any sprite game looks like this:

🖼️ The Sprite Canvas

The Sprite Canvas is a widget — add it to your card from the Tools palette just like any other control. Resize it to fill whatever area you want your game to occupy. Give it a memorable name in the Property Inspector (e.g. GameCanvas) then tell the engine about it at the start of openCard:

If you only have one Sprite Canvas on the card you can skip this — the engine will find it automatically. But calling it explicitly is good practice and avoids confusion if you ever add a second canvas.

You can also set the canvas background colour:

🧩 Creating Sprites

A sprite is a named image that lives on the canvas. Create one with createSprite, passing its name, image source, and optionally its starting position and size:

The image source can be a file path or the name of a HyperXTalk image object stored in the stack. If you don't provide an image, a magenta placeholder rectangle is drawn instead — useful for testing layout before your art is ready.

You can show and hide sprites, swap their images, and remove them:

🏃 Movement and Velocity

The most natural way to make sprites move is to set their velocity — the number of pixels to move each tick. The engine adds this to the sprite's position automatically on every tick:

Positive X moves right, negative X moves left. Positive Y moves down, negative Y moves up — the canvas coordinate system has (0,0) at the top left.

⏱️ The Tick Loop

The tick loop is the heartbeat of your game. Every tick (about 60 times per second), the engine sends a spriteTick message to your card. Handle it to update game logic — check for collisions, apply physics, respond to input:

You can pause and resume the tick loop at any time:

⌨️ Key Tracking

For smooth player movement you need to know which keys are currently held down, not just which key was last pressed. The standard pattern is to track this yourself using rawKeyDown and rawKeyUp handlers in your card script, storing held keys in local variables:

Key codes for common game keys:

Key	Code	Key	Code
A	97	D	100
W	119	S	115
↑ Up arrow	65362	↓ Down arrow	65364
← Left arrow	65361	→ Right arrow	65363
Space	32	Return	13

💥 Collision Detection

The engine checks for sprite collisions automatically every tick and sends a spriteCollision message to your card whenever two sprites overlap. Handle it to react to collisions:

You can also check for collision manually at any point using spritesCollide:

For precise collision with complex sprites, you can define a custom hitbox — a rectangle smaller than the visible sprite that's used for collision testing. This avoids false collisions at the transparent edges of an image:

📊 Reading Sprite State

spriteInfo returns a comma-delimited string with everything you need to know about a sprite. There are also convenience functions for reading individual values: