Using entities - AnselmeClergeot/FisoEngine GitHub Wiki

Here you can learn how to use the entities system to add characters, etc. to your world.

1) What is the entities system?

The entities system is one of the very important part of the engine: this is the functionality you will use to add objects (characters, item objects, etc.). This system take cares of interposing your entities in the right drawing order for that your entities be hide behind tiles in front of them.

2) Adding our first entity to our world!

We gonna add our first entity to our little map. But first, I advise to create a map looking like a labyrinth, for that you can see if your entity is well hidden behind tiles.
Start by creating an image for your entity: to test a simple rectangle will be ok. When it's done, put this image on your project's folder and let's go on.

2)a Adding an entity to the world

We have to create an entity and add it to the world by doing:

carte.entities().createEntity();

This will add an entity to the list.

Important: when you wants to operate on any entity, this is how it works:

myMap.entities().entityAt(objectIndex)/*.someCoolOperation();

objectIndex is the object number from the creating order. If player2 is the second object created in the order, then you will operate on player2 like that:

myMap.entities().entityAt(0)/*.operate();

Remember: like in arrays, we start counting from zero.

2)b Adding an image to our entity

Add your entity image you have created to your entity by doing:

myMap.entities().entityAt(0).setImagePath("your/path/to/image...");

That's all.

2)c Setting the dimensions of your entity

You have to inform the entities system about the dimensions of your entity.
Note: the entity dimensions don't have to be the same as the image entity dimensions. But for the test, set the entity dimensions as the same of the image ones.

myMap.entities().entityAt(0).setDimensions(Vector2(20, 40));
//Or 
myMap.entities().entityAt(0).setDimensions(20, 40);

And it's ok.

2)c Setting the entity base coordinates of your entity

Wait, what is the "base coordinates" of my entity?
The base coordinates of the entity is the relative-to-the entity-dimensions coordinates that generally corresponds to the point on which the entity is touching the floor. I advise to set the base coord of your entity to the feet, I mean to the middle-bottom of your image. For example, if your entity dimensions are 20x40 pixels, set the base coords to (10; 40).
Let's do it:

myMap.entities().entityAt(0).setBaseCoord(Vector2(10, 40));
//Or
myMap.entities().entityAt(0).setBaseCoord(10, 40);

Let's go next.

2)d Setting the layer of your entity

To set on which map-layer the entity is supposed to progress, you have to set the active layer of your entity by doing:

myMap.entities().entityAt(0).setLayer(yourLayer);

When it's done, you can go on.

2)e Setting the position of your entity

Of course, you would like to set the position of your entity. This is very simple:

myMap.entities().entityAt(0).setPosition(Vector2(x, y));
//Or
myMap.entities().entityAt(0).setPosition(x, y);

Note that you can also move your entity like that:

myMap.entities().entityAt(0).move(Vector2(x, y));
//Or
myMap.entities().entityAt(0).move(x, y);

2) Set your entity to be drawn

The last thing to do is setting your entity drawing status to on. You have to use the fe::Status enumeration.

myMap.entities().entityAt(0).setDrawStatus(fe::Status::On/*Or*/fe::Status::Off);

Now your entity should be drawn and interposed on the map layer you choosed!

Editing the entity image

Hey! I want my character to be animated... So how can I manipulate directely the image of my entity?
You can easily get a reference to the image of your entity by doing:

myMap.entities().entityAt(0).getSprite(objectIndex)/*.doSomeCoolOperation();

Updating the tile position of your entity

In very particular case, you could want to directely call the tile coord updating of your entity. To do that:

myMap.entities().entityAt(yourEntity).calculateTilePosition();

Removing entities

Obviously, you can remove entities from the world. To remove a specific entity, you have to call:

myMap.entities().removeEntity(entityNumber);

To clear the map from all its current entities, do:

myMap.entities().removeAll();

Well done! You now master the entities system of FisoEngine!