Learn Phaser: Basics

It's time to make a game that we can actually play! Phaser gives us ways to handle mouse and keyboard input, so that we can trigger events to happen in the game. In this exercise we're going to look at ways to use the mouse, but we'll be covering keyboard input in our next exercise.

In order to interact with a GameObject, we need to call the `setInteractive()` method on it. The `setInteractive()` method tells Phaser to listen in for interactive events on the GameObject.

After calling `setInteractive()` we can provide the GameObject with an _event handler_. The event handler is a function that gets called when a specific interaction has happened to the GameObject. We're going to look at four different possible events in this exercise:

- `'pointerdown'`: this event gets called when the mouse button has been pressed (but not released) on the GameObject.
- `'pointerup'`: this event gets called when the mouse button has been released over a GameObject.
- `'pointerover'`: this event gets called when the mouse pointer hovers over the GameObject.
- `'pointerout'`: this event gets called when a mouse pointer that was hovering over a GameObject is moved somewhere else.

It's interesting to consider `'pointerdown'` and `'pointerup'` are completely separate events. "A mouse click is a mouse click, you can't say it's only half" one might say. Not to meander too far into the dark forests of user experience and game _design_, let's just clarify that pressing down the mouse is done much more haphazardly than releasing the mouse. A player may realize they had not intended to click somewhere, drag their cursor away to release. If we capture the `'pointerup'` event, we'll only do things after the mouse click has been finished. If we only use the `'pointerdown'` event, we'll ignore a player who realized they have misclicked.

Now let's say we wanted to make our famous `circle` GameObject change colors at the click of a mouse. We would use the `'pointerup'` event for that, because that means the mouse has been clicked and released. We would add an event listener to change the color on the `'pointerup'` event. Here's how that would look:

```js
const gameState = {}

function create() {
  gameState.circle = this.add.circle(50, 50, 20, 0xFF0000);
  gameState.circle.setInteractive();
  gameState.circle.on('pointerup', function() {
    this.fillColor = 0x00FF00;
  });
}

const config = {
  scene: { create }
}

const game = new Phaser.Game(config)
```

The above code creates a red circle in a Scene's `create()` method, then makes it interactive by calling `setInteractive()` on it. Now that it's interactive, we can add an event listener for the `'pointerup'` event. This is done by calling the `.on()` method on the GameObject. 

The `.on()` method takes two arguments: the name of the event (`'pointerup'`) and the callback function. We create a new function as the second argument, with one line inside of it: reassigning `this.fillColor`. Updating `this.fillColor` changes the color of the circle (that's why `this` is here). 

Notice that we have a change in our game's state without defining an `update()` function. Event listeners can be defined in the `create()` function because they're part of the definition of the GameObject and the setup of the Game.


Input

With all of the tools we just learned, we have everything we need to make a huge number of games. Think about games that you've played and try to imagine how they break down into the following steps:

- Loading in assets (all the sounds and images for your game: 3D models and textures would also be assets here although that isn't something we're going to be handling in Phaser).
- Setting up a scene by creating all of the interactive game objects.
- Adding event listeners and handlers to those game objects.
- Updating the scene each frame, detecting if buttons are pressed and triggering events based on those button presses.

Here's a quick review of the concepts we've covered in [cheat sheet form](https://content.codecademy.com/courses/learn-phaser/Phaser%20Quick%20Guide.pdf). 

These are all core _game development_ strategies at the heart of nearly every game you'll play, and you've conquered them in Phaser! Congratulations!


Review

It's nice to have our games made to be a specific size with a specific background color, but where do we define game logic? Phaser games are composed of _Scenes_ that we define and pass to Phaser in the config! A Phaser Scene can have any of the following functions:

`preload()`, where we load in external files (or "assets") to our game. 
`create()`, where we define the GameObjects that are necessary at the start of our game.
`update()` where we define animation and interaction in our game (more on this in later exercises!)

When defining a Scene, it's only necessary to define the functions we need. So we don't need to define a `preload()` function for a game that doesn't use external assets, for instance.

After these functions are defined, they're passed in as an object to the Phaser config! Here's how that looks altogether:

```js
function preload() {
  this.load.image('codey', 'assets/images/codey.png');
}

function create() {
  this.add.image(130, 100, 'codey');
}

const config = {
  width: 300,
  height: 600,
  
  scene: {
    preload,
    create
  }
};
```

Above, we created `preload()` and `create()` methods for our Scene. The `this` object which we refer to so often in these methods refers to the Scene itself! Relatedly, `this.load` and `this.add` are helper libraries the Scene provides with methods (like `this.load.image()` and `this.add.circle()`) that allow us to load in files and create game objects respectively.

In our `config` we added in a new key, `scene`, and pass an object to it. The object maps our `preload()` function to the scene and our `create()` function to the scene. Note that we are using JavaScript's property-value shorthand, the code above would be the same if we passed `{ preload: preload, create: create }` to the `scene` instead.


Start Making A Scene

Welcome to Learn Phaser! Phaser.js is a _game framework_ built with JavaScript that you can use to make video games on the web! Phaser gives us a set of utilities that we can use so that we don't have to start from scratch when we want to make a game. In this lesson we're going to cover how we can use Phaser to do the following things:

- Draw shapes and images
- Play sounds and music
- Add realism with animations
- Introduce interactivity with the mouse

All in a way that can be quickly transitioned into a website that you can share with anyone! We're also going to cover setting up a basic Phaser project. Along the way we'll learn about what Phaser is and what it does for us so that we can add more complex logic to our games later!

This course is going to cover Phaser 3, older versions of Phaser (most notably Phaser 2/Phaser CE) will *not* work in this course. Experienced JavaScripters may notice the `function` keyword frequently used instead of the newer arrow syntax &mdash; this and other choices are for compatibility and simplicity with Phaser's design. In all other cases we'll be using up-to-date JavaScript features to allow you to carry the skills you learn here with you in the future. 

This course will not be covering JavaScript syntax, so you might be interested in brushing up on our JavaScript course before taking the plunge here. We'll try to keep everything accessible no matter what level programmer you are, so you might prefer to wait until you get stuck before you explore more about the language itself. As the saying goes: "All roads lead to [developing a series of awesome browser games with Phaser]".

In order to stay up-to-date with Phaser related news, consider subscribing to the official [Phaser World newsletter](http://phaser.io/community/newsletter), run by the original creator and maintainer of Phaser.


Hello World

Games aren't just idle toys. Many games cultivate experiences, blurring the distinction between a momentary diversion and artwork that you can interact with. To this end, there's few things that can prop up the player's immersion like good music and sound design. Since sounds are assets (like sprites and images), we load them in during the `preload()` function. First let's handle playing music for a scene, here's how we'd do that:

```js
const gameState = {};

function preload() {
  this.load.audio('theme', 'assets/music/theme.wav');
}

function create() {
  gameState.music = this.sound.add('theme');
  gameState.music.play();
}

const config = { scene: { preload, create }};
const game = new Phaser.Game(config);
```

First we load in the our theme song asset in `preload()`. We provide `this.load.audio()` with the key `'theme'`, similar to how we give keys to our visual assets. After the key, we also need to provide `this.load.audio()` with the path to the asset. Then we put the loaded asset in our scene in our `create()` function using `this.sound.add()`. This creates a sound object that we can `.play()`. We save that sound object as the value for `gameState.music` and immediately call the `.play()` method.

We might also want a sound to play whenever a specific action takes place. Let's say we want a little beep to play when the mouse has been clicked. Here's how we'd do that:

```js
const gameState = {}

function preload() {
  this.load.audio('chime', 'assets/sounds/chime.wav');
}

function create() {
  gameState.circle = this.add.circle(100, 100, 30, 0xFF0000);
  gameState.circle.setInteractive();

  gameState.chimeSound = this.sound.add('chime');

  gameState.circle.on('pointerup', function() {
    gameState.chimeSound.play();
  });
}

const config = { scene: { preload, create }};
const game = new Phaser.Game(config);
```

Above, we load in the sound located at `assets/sounds/chime.wav` and save that sound with the key `'chime'`. We then create a circle in our Scene and set it to be interactive. Then we add our `'chime'` sound to our Scene. We then add in a new event listener so that when our circle gets clicked, we play our `chime` sound.


Sounds

Because we handle all of our Scene information in different functions, it becomes important to pass information between our Scene functions. Something we created in `create()` will need to be updated in `update()`, for instance. There are a few ways we can accomplish this:

* Create global variables for everything.
* Attach important variables to the Scene itself by creating a new property for `this` from within a Scene method.
* Create a `gameState` object and keep track of the state there.

Each solution is a valid technique, but we're going to focus on creating a `gameState` object and manipulating that from now on. Here's one way that we'll apply this solution:

```js
const gameState = {};

function create() {
  gameState.circle = this.add.circle(20, 20, 5, 0xff0000);
  gameState.rectangle = this.add.rectangle(40, 60, 90, 10, 0x00ff00);
}

function update() {
  gameState.circle.x += 1;
  gameState.rectangle.y += 1;
}
```

In the above code, we started by defining a `gameState` as a new JavaScript object. In `create()` we create a circle and a rectangle and assign them to properties of our `gameState` object. Then in `update()` we can refer to `gameState.circle` and `gameState.rectangle` to manipulate them!


Storing State

We've been making GameObjects in an existing game, but let's take a step back and think about how to create a Phaser game from the beginning. We can do that by calling `new Phaser.Game()`. `Phaser.Game()` by itself creates a new `<canvas>` element and appends it to your HTML document. This element allows Phaser to draw sprites and shapes to a website.

In order to make games of our own design, we call `Phaser.Game()` with an object that specifies some meta-information about the game. We define that object beforehand and conventionally name the variable `config`. Here are some of the keys we can define in a `config`:

- `height`: the height, in pixels, of the `<canvas>` Phaser creates.
- `width`: the width, in pixels, of the `<canvas>` Phaser creates.
- `parent`: the HTML element that Phaser will place the `<canvas>` element inside of.
- `backgroundColor`: the background color of our game, usually given in hexadecimal.
- `type`: the Renderer Phaser will use: either `Phaser.WEBGL` which offers some additional features while drawing or `Phaser.CANVAS` which can run on more browsers. The default, `Phaser.AUTO`, checks if the browser supports WebGL and, if not, switches to canvas.

There is plenty more data that we could possibly add to configure our games, but these basics will get us pretty far. If you wish to learn more about the fields a `config` supports, check out the [Phaser documentation](https://photonstorm.github.io/phaser3-docs/Phaser.Core.Config.html) (the docs!).


Create A Config

Now that we've covered drawing a sprite, let's talk about drawing a background image. A background image is not a sprite &mdash; usually the player will not interact with the background at all. Because of this, we don't need a `sprite` object for our background images. We still need to load in the image in our `preload()` function but we can use `this.add.image()` instead of `this.add.sprite()`:

```js
function preload() {
  this.load.image('bg', 'assets/images/bg.png');
}

function create() {
  this.add.image(200, 200, 'bg');
}
```

Above, we load in our background image from the path `assets/images/bg.png` and use the key `bg` to refer to it. In `create()` we add the image, centered at (200, 200) &mdash; 200 pixels to the right of the left edge and 200 pixels down from the top edge.


Draw A Background Image

Now we're going to add motion to our Phaser game! You might recall that we can add an `update()` function to our Scene that adds motion, animation, and interaction! We're going to start with something very simple: moving an object across the screen. If we create a GameObject centered at (0, 100), that is, if we create a GameObject with its `x` value equal to 0 and its `y` value equal to 100, we can move it across the screen in the `update()` function like so:

```js
let circle;

function create() {
  // create a red circle with radius 20 at (0, 100)
  circle = this.add.circle(0, 100, 20, 0xff0000);
}

function update() {
  // move that circle to the right
  circle.x += 1;
}
```

First, we define a global variable called `circle` because we're going to be referring to the same object in two different functions. There are a few ways to do this, but for small games, it's OK to make a few global variables.

Afterwards, in `create()` we assign a new GameObject to `circle` that we instantiate using `this.add.circle()` with `x`, `y`, `radius`, and `fillColor` arguments.

Then in `update()` we update our `circle`'s `x` value. `update()` is called every frame the game is in view.

`update()` has two optional parameters: `time` and `delta`. The first is the number of milliseconds that your Phaser game has been running, the second is the difference (in milliseconds) since the last time `update()` was called. Phaser does its best to call `update()` 60 times per second, so `delta`'s values will normally be around `16.6`. This is good enough for us, so we'll frequently define `update()` without parameters.


Move Your Bodies

In this exercise, we're going to cover how to make a simple geometric shape in Phaser. A Circle! To do this, we're going to use the method `this.add.circle()`. This creates a `GameObject` that we can use to represent a circle in the game. `GameObject`s can have different animations or interactions that we can add to them, but for now, we're going to focus on drawing them. To make a circle we provide `this.add.circle()` with four arguments in the following order:

- The `x` coordinate for the center of the circle. A larger `x` value means the circle will be further to the right in the game.
- The `y` coordinate for the center of the circle. A larger `y` value means the circle will appear further down in the game.
- The `radius`, a value for how large the circle should be.
- The `fillColor`, a number representing the color for the circle. We will be providing hexadecimal values for all colors in this lesson. Feel free to use an online color picker when choosing yours, most will supply a hexadecimal value. Hexadecimal colors in JavaScript look like `0xFF8030` where `0x` indicates the value is hexadecimal and `FF8030` is the color code for the color we want.

For example:

```js
this.add.circle(20, 50, 10, 0xFF0000);
```

This line of code would create a new circle that is `20` pixels to the right and `50` pixels down from the top-left corner (sometimes called "the origin"). This circle will be `10` pixels in radius (i.e., `20` pixels across), and bright red due to the color we supplied `0xFF0000`.

Draw A Circle

Phaser gives us very similar tools to create a `GameObject` for sprites that we provide. A _sprite_ is an image that is intended to represent a character, enemy, or some other object in a game. We use image files for a lot of different things in games, including backgrounds and icons, but sprites represent a person or item inside the game itself.

In order to add a sprite we can call `this.add.sprite()`. However, we need to load in the image we want to use as a sprite in an earlier step. `preload()` is the name of the function that happens before `create()`. Where `create()` is about setting up all the game objects to set the stage for our game, `preload()` is about loading in all _asset_ files that we'll be using. "Assets" could refer to lots of things but, for now, our assets will consist of sprites, background images, in-game sounds, and background music.

So the two steps to creating a sprite in your game are:
Loading the image in `preload()` with `this.load.image()` which takes two arguments: a `key` that you'll use to refer to it and the `path` to the image itself. The `path` can be a local file or the URL for a resource hosted elsewhere on the web.

Creating the GameObject in `create()` with `this.add.sprite()` which requires three arguments: the `x` value, the `y` value, and the `key` used when you loaded the image.

```js
function preload() {
  this.load.image('dragon', 'assets/sprites/dragon.png');
}

function create() {
  this.add.sprite(40, 80, 'dragon');
}
```

In `preload()` we loaded an image into our game and gave it a `key` value of `'dragon'`. The location of the image we loaded was `assets/sprites/dragon.png`.

Then we created the GameObject itself in `create()`. We set it 40 pixels to the right and 80 pixels down and informed Phaser to use the image we loaded in earlier under the `key` "dragon". It's important to note that our `x` and `y` values of 40 and 80 indicate the *center* of the sprite. So calling `this.add.image(0, 0, 'dragon');` would only display the bottom right quarter of the image.


Draw A Sprite

Only some games exclusively use the mouse to play. Plenty of browser games, especially those with more complex gameplay, require keyboard input. Before, we assigned mouse events to specific GameObjects. This helped us tell if a mouse cursor was hovering over, or clicking on, an object in our game. Where mouse clicks take place at a specific point in our game with `x` and `y` coordinates, a keyboard offers a different interface without that positional information. So our keyboard handlers will handle any keypress that happens while our game is in focus &mdash; for this reason, they won't be registered as events to particular GameObjects in our game.

The first way of adding a keypress handler is by calling `this.input.keyboard.on()`. This takes two arguments: first, the name of the event &mdash; something like `'keydown-A'` for the <kbd>A</kbd> keypress. Next, the function to be called when handling the keypress. We can pass a function we've defined elsewhere, but unless you're duplicating functionality (say to avoid replicating the same code for a keyboard and a gamepad) it's fine to define an anonymous function. Here's how that would look:

```js
const gameState = {};

function create() {
  gameState.circle = this.add.circle(30, 30, 10, 0xFF0000);
  this.input.keyboard.on('keydown-W', function() {
    gameState.circle.fillColor = 0xFFFF00;
  });
}
```

This code creates a red circle and then, when a <kbd>W</kbd> is pressed on the keyboard, the circle turns yellow.

<hr>

### createCursorKeys()

Another way of adding a keyboard event listener is by using a shortcut that Phaser offers, `createCursorKeys()`. This creates an object that maps the names of some usual cursor keys (<kbd>UP</kbd>, <kbd>DOWN</kbd>, <kbd>LEFT</kbd>, <kbd>RIGHT</kbd>, <kbd>SHIFT</kbd>, and <kbd>SPACE</kbd>) to a cursor object that we can use to detect when they've been pressed. We can save those as a property in our `gameState` object and then check if they're pressed within our `update()` function.

```js
const gameState = {};

function create() {
  gameState.circle = this.add.circle(50, 50, 20, 0xFF0000);
  gameState.cursors = this.input.keyboard.createCursorKeys();
}

function update() {
  if (gameState.cursors.left.isDown) {
    // move the circle left!
    gameState.circle.x -= 3;
  }
}

const config = { scene: { create, update }};
const game = new Phaser.Game(config);
```

Above, we created a `cursors` property for our `gameState` and assigned the result of `.createCursorKeys()` to it. In our `update()` method we checked if the left key is being pressed by checking if `gameState.cursors.left.isDown` is truthy. If the left button is pressed, we move the circle to the left.