The Untold Engine supports Sprites and Spritesheets. The Untold Engine represents a sprite as a U4DEngine::U4DSprite object.
Preparing the Spritesheet
To render a sprite, the spritesheet is loaded into a U4DEngine::U4DSpriteLoader object, which holds the rendering data necessary to render the sprite. There is an excellent tool that makes this process easy. It is called Texture Packer.
The Untold Engine process the output of the Texture Packer, a spritesheet (.xml and .png files), to render a sprite.
I strongly recommend you get a copy of Texture Packer.
Creating the Spritesheet
Open up Texture Packer and load the desired sprites onto it. In this example, I loaded several images representing Space Invader sprites.
Next, make sure to set the following settings as described below:
- Framework: Select XML (Generic). The Untold Engine will use this .xml to properly render the sprite
- Data File: Make sure to store the .xml file into the Untold Engine’s Resource Folder
- Texture File: Again, make sure to store the .png file into the Untold Engine’s Resource Folder
- Texture format: Select PNG-8 (indexed)
- Pixel format: RGBA8888
Once the Configurations have been set, click on Publish Sprite Sheet. The .xml and .png files will be saved in the Resource Folder of the Untold Engine.
Make sure to drag these files into Xcode as shown below:
Create a Sprite Object
To render a sprite, you must first instantiate a U4DEngine::U4DSpriteLoader object (line 1). Once instantiated, you load spritesheet information (.xml and .png) files into the loader by using method U4DEngine::U4DSpriteLoader::loadSpritesAssetFile (line 2).
Next, create an instance of a U4DEngine::U4DSprite object by passing the sprite loader as a parameter (line 3).
At this point, you are ready to select which sprite in the spritesheet to render. To do so, provide the name of the sprite you want to render (line 4). In this case, I want to render the sprite whose name is “spaceinvaderoctopus1.png”.
Next, add the sprite to the scenegraph (line 5).
Since the demo has a skybox, I’m setting the z-depth in the addChild method to -2. The z-depth provides the rendering order.
Finally, I translate the sprite 0.5 units up (line 6). Recall that the coordinate system for 2D objects is different than for 3D objects. For 2D objects, the coordinate system ranges between [-1.0,1.0].
//Line 1. create a a sprite loader object U4DEngine::U4DSpriteLoader *spriteLoader=new U4DEngine::U4DSpriteLoader(); //Line 2. load the sprite information into the loader spriteLoader->loadSpritesAssetFile("spaceinvaderspritesheet.xml", "spaceinvaderspritesheet.png"); //Line 3. Create a sprite object U4DEngine::U4DSprite *mySprite=new U4DEngine::U4DSprite(spriteLoader); //Line 4. Set the sprite to render mySprite->setSprite("spaceinvaderoctopus1.png"); //Line 5.Add it to the world addChild(mySprite,-2); //Line 6. translate the sprite mySprite->translateTo(0.0,0.5,0.0);
Here is the result:
- To properly render the sprites, the spritesheet (.png) image needs to be flipped vertically as shown below. In this instance, I use Gimp to flip the .png file vertically.