Polycode contains a 2D sprite system that you can use to create 2D animations from sprite sheets and use complex texture atlases for static and animated graphics.


Sprites overview.

The sprite system is based around the SpriteSet and SceneSprite classes.

A SpriteSet contains information about the sprite sheet image, the individual sprites within it and the different states defined for each sprite (which can be animations or single frame static states). SpriteSets can be created programmatically or visually inside the IDE's sprite editor.

A SceneSprite is a sprite instance of a sprite defined inside of a SpriteSet. It can be set to any of the states defined for that sprite and is an Entity subclass, so it can be added to a Scene or another entity. SceneSprites can also be placed visually in the IDE entity editor.

Creating sprite sets in the IDE.

The Polycode IDE allows you to edit a SpriteSet visually and save it as a .sprites file, which you can then load in your code or link to an entity in the entity editor so that you can place the sprites from the sprite set inside the entity.

To create a new sprite set, add a new file to your project and choose "Sprite Set" as the file template.

This will create an empty sprite set using the Polycode default texture and no defined sprites.

Working with sprite sheets.

To set the sprite sheet image that will be used by the sprite set, click on the "Change Image" button on the bottom of the sprite sheet pane. This will open the Asset Browser, which will allow you to choose an image inside of your project.

After choosing your sprite sheet image, you will see it displayed in the sprite sheet pane.

The next step is to define the sprite frames within the sprite sheet. You can either generate these automatically or manually define the frames. Usually you want to use the automatic generation and then correct it with manual frames if it gives you unwanted results.

To generate the frames automatically, you have to set the type of frame generation that you want from the drop down next to the "Generate" button below the sprite sheet. If you have a uniform sprite sheet that is a grid of equally sized rectangles, use the "Uniform Grid" option. If you have a sprite sheet where all of the images are packed together in different sizes, use the "Detect frames" option. To generate the frames, hit the "Generate" button.

The "Detect Frames" frame generation will attempt to detect each individual sprite in the sprite sheet. You can control the threshold of the minimum distance that individual sprites are away from each other from the "Options" toolbox, so if you have sprites that have disconnected parts, you can force the frame detection to treat them as a single sprite.

The "Uniform Grid" frame detection simply divides the sprite sheet into a grid of sprites. You can set the width and height of the sprites in the "Options" toolbox.

For both generation options, you can set the default frame anchor that will be set for each generated sprite frame. The frame anchor defines the origin point of the sprite frame that will be at 0,0 position of the sprite entity.

To create a sprite frame manually, simply click and drag anywhere in the sprite sheet outside of an existing sprite frame

To edit existing sprite frames, click on a sprite frame to select it, then use the handles on the edges of the frame to resize the frame rectangle or move its anchor point using the pink anchor dot. Use the delete key to remove the frame.

You can use the mousewheel to zoom in and out of the sprite sheet for more precise editing. Use alt-click and drag to pan around the sprite sheet.

Adding sprites to the sprite set.

After you define the frames of the sprite sheet, you can create the individual sprites and edit their states.

To add a new sprite to the sprite set, git the "+" button on the top of the sprite browser at the bottom of the sprite editor and name the new sprite. This will add a new sprite with a blank default state. Each sprite needs at least one state, so a default state is added automatically, which you can use for sprites that don't have any changing states.

Working with sprite states.

To add or remove sprite states within a sprite, select the sprite in the sprite browser and then use the "+" and "-" buttons on the top of the state browser to the side of the sprite browser to manage sprite states. To edit a sprite state, select it from the sprite state list.

Placing sprites in the IDE entity editor.

You can place sprites from a sprite set created in the IDE into entities in the entity editor by linking the sprite set file as an entity resource pool.

Using sprites in your code.

To use a sprite set created in the IDE in your code, you need to create a new SpriteSet instance and pass it the filename of the sprite set you created in the IDE. You can then create SceneSprite instances referencing this sprite set and place them in your scene.

SpriteSet *spriteSet = new SpriteSet("my_sprite_set.sprites");
SceneSprite *sceneSprite = new SceneSprite(spriteSet);
spriteSet = SpriteSet("Resources/sprite_set.sprites", Services.ResourceManager:getGlobalPool())
sceneSprite = SceneSprite(spriteSet)

To set the specific sprite and sprite state from the set, use the setSpriteByName and setSpriteStateByName methods.


sceneSprite->setSpriteStateByName("default", 0, false);
sceneSprite:setSpriteStateByName("default", 0, false)