groups to create game scenes and manage similar sprites together as a single unit. Pixi has an object called a Container that lets you do this. Let's see how it works.
Imagine you want to display three sprites: cat, hedgehog and tiger. Create them, and set their positions - but don't add them to the stage.
//The cat var cat = new Sprite(id["cat.png"]); cat.position.set(16, 16); //The hedgehog var hedgehog = new Sprite(id["hedgehog.png"]); hedgehog.position.set(32, 32); //The tiger var tiger = new Sprite(id["tiger.png"]); tiger.position.set(64, 64);
Next, create an animals container to group them all together like this:
var animals = new Container();
Then use addChild to add the sprite to the group.
animals.addChild(cat); animals.addChild(hedgehog); animals.addChild(tiger);
Finally add the group to the stage.
stage.addChild(animals); renderer.render(stage);
(You know, the stage object is also a Container. It's the root container for all Pixi sprites.)
Here's what this code produces:
The animals that are not visible in this image are the invisible groups that contain the sprites.
You can now treat the animals group as a unit. You can think of a Container as a special type of sprite without a texture.
If you need a list of animals with all child sprites, use its children array to find out.
console.log(animals.children) //Displays: Array [Object, Object, Object]
This tells you that animals have three sprites as children.
Since the animals group is just like any other sprite, you can change its x and y values for alpha, scale and all other sprite properties. Any property values you change on the parent container will affect the child sprites in a relative manner. So if you set the group x and y position, all child sprites will be repositioned relative to the top left corner of the group. What happens if you set the animals's x and y positions to 64?
animals.position.set(64, 64);
The entire group of sprites will move 64 pixels to the right and 64 pixels down.
The animals group also has its own dimension, which is based on the area occupied by the contained sprites. You can find its width and height values as follows:
console.log(animals.width); //Displays: 112 console.log(animals.height); //Displays: 112
What happens if you change the width or height of the group?
animals.width = 200; animals.height = 200;
All child sprites will scale to accommodate this change.
You can nest as many Containers as you like inside other Containers, creating deep hierarchies if you need to. However, a DisplayObject (like a Sprite or another Container) can only belong to one parent at a time. If you use addChild a sprite is a child of another object, Pixi will automatically remove it from the current parent. It's a useful management that you don't have to worry about.
2. Local and global positions
When you add a sprite to a Container, its x and y positions are relative to the top left corner of the group. This is the local position of the sprite For example, what do you think the position of the cat is in this image?
let's see:
console.log(cat.x); //Displays: 16
16? Yes! This is because the cat is only offset by 16 pixels from the upper left corner of the group. 16 is the cat's local location.
Sprites also have a global location. The global position is the distance from the upper left corner of the stage to the sprite's anchor point (usually the upper left corner of the sprite). You can find the global position of the sprite with the help of the toGlobal method. That's it:
parentSprite.toGlobal(childSprite.position)
This means you can find the cat's global location within the animals group like this:
console.log(animals.toGlobal(cat.position));
//Displays: Object {x: 80, y: 80...};
This gives you an x and y of 80 bits which is exactly the cat's global position relative to the upper left corner of the stage.
What if you want to find the global location of a sprite, but don't know what the sprite's parent container is? Each sprite has a property called parent that will tell you what the sprite's parent is. If you add a sprite directly to the stage, then the stage will be the parent of the sprite. In the above example, the cat parent is animals. This means you can get the cat's global location by writing:
cat.parent.toGlobal(cat.position);
It will work even if you don't know what the current parent container is.
There is also a way to calculate global location! And, it's actually the best way, so come forward! If you want to know the distance from the top left corner of the canvas to the sprite, and don't know or care what the sprite's parent container is, use the getGlobalPosition method. Here's how to use it to find the tiger's global location:
tiger.getGlobalPosition().x tiger.getGlobalPosition().y
In the example we used, this would give you an x and y value of 128. The special getGlobalPosition is that it is highly accurate: it will give you the exact global position of the sprite whenever its local position changes. I asked the Pixi development team to add this feature specifically for accurate collision detection in games.
What if you want to convert a global location to a local location? You can use the toLocal method. It works similarly, but in this general format:
sprite.toLocal(sprite.position, anyOtherSprite)
Use toLocal to find the distance between a sprite and any other sprite. Here's how to find the tiger's native location, relative to the hedgehog.
tiger.toLocal(tiger.position, hedgehog).x tiger.toLocal(tiger.position, hedgehog).y
The x value is 32 and the y value is 32. You can see in the example image that the upper left corner of the tiger is 32 pixels and the left is the upper left corner of the hedgehog.
3. Use ParticleContainer to combine sprites
Pixi has an alternative, high-performance method to combine sprites called ParticleContainer (PIXI.ParticleContainer). Any sprites inside a ParticleContainer will render 2 to 5 times faster than if they were inside a regular Container. This is a great performance boosting game.
Create a ParticleContainer like this:
var superFastSprites = new ParticleContainer();
Then use addChild to add the sprite to it, just like you would with any normal Container.
If you decide to use ParticleContainer, you have to make some compromises. A ParticleContainer inside a sprite has only a few basic properties: x, y, width, height, scale, pivot, alpha, visible - that's it. Also, the sprites it contains cannot have their own nested children. A ParticleContainer also cannot use Pixi's advanced visual effects such as filters and blend modes. Each ParticleContainer can use only one texture (so you have to use a spritesheet if you want the sprite to have a different look). But for the huge performance boost you get, these compromises are usually worth it. You can use both Containers and ParticleContainers in the same project, so you can fine-tune your optimizations.
Why is sprite so fast in Particle Container? Because the sprite's position is calculated directly on the GPU. The Pixi development team is working hard to offload as much sprite processing as possible on the GPU, so the latest version of Pixi you're using may have a ParticleContainer that's much more feature-rich than what I've described here. Check out the current ParticleContainer documentation for details.
Where you create a ParticleContainer, you can provide two optional parameters: the maximum number of sprites the container can hold, and an options object.
var superFastSprites = new ParticleContainer(size, options);
The default value for size is 15,000. So, if you need to include more sprites, set it to a higher number. The options parameter is an object that can set 5 boolean values: scale, position, rotation, uvs and alpha. The default value of position is true, but the rest are set to false. This means that if you want to change the rotation, scale, alpha, or uvs in the sprite's ParticleContainer, you have to set these properties to true, like this:
var superFastSprites = new ParticleContainer(
size,
{
rotation: true,
alpha: true,
scale: true,
uvs: true
}
);
However, if you don't think you need to use these properties, keep them set to false to squeeze out maximum performance.
What are the uvs options? Only set it to true if you have particles that change their textures as they animate. (All sprite textures also need to be in the same tileset image for this to work.)
(Note: UV mapping is a 3D graphics display term that refers to the x and y coordinates that are being mapped to the 3D surface texture (image). U is the x-axis and V is the y-axis WebGL already uses. x, y and z are for 3D spatial positioning, so U and V are chosen to represent x, and y for 2D image textures.)