How to draw your sprites

We've included a several components to make it easier to get started drawing sprites for entities. Here we'll go over how to set up your art and your components to get your sprites on the screen. For more details on how CreateJS handles rendering check out the documentation and examples at the EaselJS website.

#Formatting Your Art For animation, EaselJS expects game art to be in spritesheets. This means that your art should be arranged in a grid of same-sized cells with each cell containing a portion you want to render. A single entity can use more than one tilesheet, but if cells are not the same size on all sprite sheets, each frame will need to be defined in JSON independently.

For non-animating entities, the art can be an image in its own file but it's also possible for multiple entities to share the same image file with each displaying a different portion of the image.

#Adding Your Art to the Game Before you can render anything you need the game to load it. To do this, add a new entry to the 'assets' section of the src/data/config.json. An entry looks like this:

{
    "id": "briar",
    "src": "../images/briar.png",
    "data": {"rows": 1, "columns": 4}
}

id - This is how you'll refer to the art from within the engine. src - This is the source file you want to load. data - This informs the engine of the number of rows and columns are in your spritesheet.

#Adding a Render Handler For an entity to render, it needs to receive ticks from the game. We pass these on from the layer using a handler. We've created Handler-Render-Createjs for this purpose. You can add this component to the JSON definition of the layer that contains the entity. Make sure to add it to the layer JSON definition after any components that will determine where entities will be located (e.g. logic and collision). Adding the handler to the JSON definition looks like this.

{"type": "handler-render-createjs"}

#Picking a Render Component Now we need to decide which render component to use on the entity. We have provided a primary render component that you can use, although you're welcome to make your own. The provided component is Render-Sprite. This component needs to be added to the JSON definition of your entity as shown below.

##Render-Sprite This component renders animated entities.

###Setting Up Your JSON Below is an example of a Render-Sprite component JSON definition.

{
	"type": "render-sprite",
	"spriteSheet": {
		"images": ["mookie"],
		"frames": {
			"width":  144,
			"height": 93,
			"regY":   93,
			"regX":   72
		},
		"animations": {
			"standing-right":[2],
			"standing-left": [5],
			"walking-right": {"frames": [3, 0, 1, 2], "speed": 0.25},
			"walking-left":  {"frames": [4, 7, 6, 5], "speed": 0.25},
			"jumping-right": {"frames": [0]},
			"jumping-left":  {"frames": [6]}
		}
	},
	"animationMap":{
		"air,left":     "jumping-left",
		"air,right":    "jumping-right",
		"moving,left":  "walking-left",
		"moving,right": "walking-right",
		"left":         "standing-left",
		"right":        "standing-right",
		"default":      "standing-right"
	}
	
}

At the highest level there are three parts to the JSON: id - This is the name of the component we're using. As stated above, we're using Render-Sprite. spriteSheet - This is where we put the information about the sprite sheet and the animations that come from it. This field is used to create the CreateJS SpriteSheet object. What parameters the spritesheet object accepts and how to lay them out can be found in the SpriteSheet documentation. The one difference in our implementation is that the image names are the ids of the assets in the config.js file. animationMap - This is a map of entity states to animations. For example: "air,left": "jumping-left" The field name is a comma delimited list of entity states. The value is the id of the animation to play (defined in the spritesheet object). When all the states in the field name are true Render-Sprite will play the associated animation. The order of the fields in the animationMap object is important because it is the order in which the fields are evaluated. If there are multiple fields in which all the states are true, the first field that is true will have its animation played. For example, in the JSON definition above, if an object's 'moving' and 'right' states are both true, the 'walking-right' animation will play even though all the states for the 'standing-right' animation are also true because the 'walking-right' animation comes before the 'standing-right' animation in the list.

In cases where two sets of states should result in the same animation being played, you should list them as two different fields. For example: "right": "standing-right", "default": "standing-right"

###How to Set An Object's State What animation is played is determined by the state of the object. To set the state, send a 'logical-state' message containing an object that holds boolean fields for the states you want to set true or false. For example:

this.owner.trigger('logical-state', {left: true, air: false});

When Render-Sprite is ticked, it will display the animation that matches the current state. Render-Sprite preserves the state between ticks, so states set to true will remain true until they are explicitly set to false.

It is possible to send multiple 'logical-state' calls in a single game tick by one or more components. Render-Sprite updates the state in the order it receives the messages, so developers should be aware of what components of an entity are sending 'logical-state' messages and what states they are setting. In our example game we made all our calls to 'logical-state' in logic components that are handled by Handler-Logic. If an entity has multiple components that are associated with the same handler, the order those components are added to the JSON file determines their call order by their handler. So, the first logic component will be called before the second logic component, etc.

###How Animations are Positioned The position of the animated image will be based on the entity's x and y values and the regX and regY values of the frames. To set an entity's x and y position in a component use: this.owner.x this.owner.y The regX and regY are set in the JSON definition of the sprite sheet and describe the sprite's offset in relation to the x and y position of the entity.