Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/excaliburjs/Excalibur. 🎮 Your friendly TypeScript 2D game engine for the web 🗡️ excaliburjs.com
excalibur excaliburjs game-development game-engine game-framework gamedev games html5-canvas typescript
Something went wrong. Try again.
11 kB · 339 lines
MDX
at Graph
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340---slug: /getting-startedtitle: Building Breakoutsection: Tutorialtags: ["#Tutorial"]---
```twoslash include ex/// <reference path="../src/engine/excalibur.d.ts" />const Engine = ex.Engine;const Actor = ex.Actor;const Color = ex.Color;const CollisionType = ex.CollisionType;const vec = ex.vec;```
:::info
Be sure to check out our new tutorial, building a [flappy bird clone](/docs/excalibird-flappy-bird)
:::
## Introduction
Excalibur uses a theater-style metaphor to organize your games. There are `Actor`'s which can move around and do things in the currently active `Scene`. All of that lives in the `Engine` container.
## Hello Excalibur: Building Breakout!
In this example we'll build a simple version of the popular game Breakout. [Breakout](<https://en.wikipedia.org/wiki/Breakout_(video_game)>) is a game where you break bricks at the top of the screen using a ball that bounces off a player paddle. You must break all the bricks to win and avoid the ball falling off the bottom of the screen.
The whole code example in this guide is on [GitHub](https://github.com/excaliburjs/sample-breakout) if you want to skip to the code.
:::note
This example creates the game in a single file for simplicity, we recommend splitting your game into separate files to keep your project more manageable.
:::
### Basic Engine Start
Create a script in your project, for example, `game.ts`. Excalibur games are built with the [Engine](/docs/engine) container.
:::note
It is important to call `game.start()` once you are done configuring your game otherwise it won't start!
:::
```typescript// ES style import from Excaliburimport { Engine } from 'excalibur';```
```ts twoslash// @include: ex// ---cut---// Create an instance of the engine.// I'm specifying that the game be 800 pixels wide by 600 pixels tall.// If no dimensions are specified the game will fit to the screen.const game = new Engine({ width: 800, height: 600,});```
```ts twoslash// @include: exdeclare const game: ex.Engine;// ---cut---// Start the engine to begin the game.game.start();```
Open a browser and view the blank blue screen of goodness.
## Creating the paddle with an Actor
Game elements that have a position and are drawn to the screen are called an [Actor](/docs/actors). Actors are the primary way to draw things to the screen.
Think of actors like you would the actors in a play. If you change scenes different actors might be on stage.
:::note
Actors must be added to a scene to be drawn or updated! `game.add(actor)` will add an actor to the current scene.
:::
Below we are going to create the paddle Actor for our Breakout game. Actors can be given many parameters such as position, width, and height.
```ts twoslash// @include: exdeclare const game: ex.Engine;// ---cut---// Create an actor with x position of 150px,// y position of 40px from the bottom of the screen,// width of 200px and a height of 20pxconst paddle = new Actor({ x: 150, y: game.drawHeight - 40, width: 200, height: 20, // Let's give it some color with one of the predefined // color constants color: Color.Chartreuse,});
// Make sure the paddle can participate in collisions, by default excalibur actors do not collide with each other// CollisionType.Fixed is like an object with infinite mass, and cannot be moved, but does participate in collision.paddle.body.collisionType = CollisionType.Fixed;
// `game.add` is the same as calling// `game.currentScene.add`game.add(paddle);```
Open up your favorite browser and you should see something like this:
That’s neat, but this game is way more fun if things move around. Let’s make the paddle follow the mouse around in the x direction. The paddle will be centered on the mouse cursor.
```ts twoslash// @include: exdeclare const game: ex.Engine;declare const paddle: ex.Actor;// ---cut---// Add a mouse move listenergame.input.pointers.primary.on("move", (evt) => { paddle.pos.x = evt.worldPos.x;});```
:::note
**Important!** Actors have a default [anchor](/docs/graphics-component/#component-specific-overrides) of (0.5, 0.5) which means their graphics are positioned in their center (not top-left).
:::
## Creating the ball with Actors
What’s Breakout without the ball? Excalibur comes pre-built with a physics collision system to help you out with things like balls bouncing off other objects.
To make the ball, we switch the collider to a circle with the `useCircleCollider(radius)` helper.
In this case we want to handle the resolution ourselves to emulate the the way Breakout works. We use the `ex.CollisionType.Passive` which will send an event that there has been an intersection but will not resolve the positions.
Read more about the different [CollisionTypes](/docs/physics/#collision-types) that Excalibur supports.
```ts twoslash// @include: exdeclare const game: ex.Engine;declare const paddle: ex.Actor;// ---cut---// Create a ball at pos (100, 300) to startconst ball = new Actor({ x: 100, y: 300, // Use a circle collider with radius 10 radius: 10, // Set the color color: Color.Red,});// Start the serve after a secondconst ballSpeed = vec(100, 100);setTimeout(() => { // Set the velocity in pixels per second ball.vel = ballSpeed;}, 1000);
// Set the collision Type to passive// This means "tell me when I collide with an emitted event, but don't let excalibur do anything automatically"ball.body.collisionType = CollisionType.Passive;// Other possible collision types:// "ex.CollisionType.PreventCollision - this means do not participate in any collision notification at all"// "ex.CollisionType.Active - this means participate and let excalibur resolve the positions/velocities of actors after collision"// "ex.CollisionType.Fixed - this means participate, but this object is unmovable"
// Add the ball to the current scenegame.add(ball);```
The ball is now setup to move at 100 pixels per second down and right. Next we will make the ball bounce off the side of the screen. Let’s take advantage of the `postupdate` event.
```ts twoslash// @include: exdeclare const game: ex.Engine;declare const ball: ex.Actor;declare const ballSpeed: ex.Vector;// ---cut---// Wire up to the postupdate eventball.on("postupdate", () => { // If the ball collides with the left side // of the screen reverse the x velocity if (ball.pos.x < ball.width / 2) { ball.vel.x = ballSpeed.x; }
// If the ball collides with the right side // of the screen reverse the x velocity if (ball.pos.x + ball.width / 2 > game.drawWidth) { ball.vel.x = ballSpeed.x * -1; }
// If the ball collides with the top // of the screen reverse the y velocity if (ball.pos.y < ball.height / 2) { ball.vel.y = ballSpeed.y; }});```
## Creating the bricks with Actors
Breakout needs some bricks to break. To do this we calculate our brick layout and add them to the current scene.
```ts twoslash// @include: exdeclare const game: ex.Engine;declare const ball: ex.Actor;declare const ballSpeed: ex.Vector;declare type Actor = any;// ---cut---// Build Bricks
// Padding between bricksconst padding = 20; // pxconst xoffset = 65; // x-offsetconst yoffset = 20; // y-offsetconst columns = 5;const rows = 3;
const brickColor = [Color.Violet, Color.Orange, Color.Yellow];
// Individual brick width with padding factored inconst brickWidth = game.drawWidth / columns - padding - padding / columns; // pxconst brickHeight = 30; // pxconst bricks: Actor[] = [];for (let j = 0; j < rows; j++) { for (let i = 0; i < columns; i++) { bricks.push( new Actor({ x: xoffset + i * (brickWidth + padding) + padding, y: yoffset + j * (brickHeight + padding) + padding, width: brickWidth, height: brickHeight, color: brickColor[j % brickColor.length], }) ); }}
bricks.forEach(function (brick) { // Make sure that bricks can participate in collisions brick.body.collisionType = CollisionType.Active;
// Add the brick to the current scene to be drawn game.add(brick);});```
When the ball collides with bricks, we want to remove them from the scene. We use the `collisionstart` handler to accomplish this. This handler fires when objects first touch, if you want to know every time resolution is completed use `postcollision`.
```ts twoslash// @include: exdeclare const game: ex.Engine;declare const ball: ex.Actor;declare const ballSpeed: ex.Vector;declare type Actor = any;declare const bricks: ex.Entity[];// ---cut---// On collision remove the brick, bounce the balllet colliding = false;ball.on("collisionstart", function (ev) { if (bricks.indexOf(ev.other.owner) > -1) { // kill removes an actor from the current scene // therefore it will no longer be drawn or updated ev.other.owner.kill(); }
// reverse course after any collision // intersections are the direction body A has to move to not be clipping body B // `ev.content.mtv` "minimum translation vector" is a vector `normalize()` will make the length of it 1 // `negate()` flips the direction of the vector var intersection = ev.contact.mtv.normalize();
// Only reverse direction when the collision starts // Object could be colliding for multiple frames if (!colliding) { colliding = true; // The largest component of intersection is our axis to flip if (Math.abs(intersection.x) > Math.abs(intersection.y)) { ball.vel.x *= -1; } else { ball.vel.y *= -1; } }});
ball.on("collisionend", () => { // ball has separated from whatever object it was colliding with colliding = false;});
```
Finally, if the ball leaves the screen by getting past the paddle, the player loses!
```ts twoslash// @include: exdeclare const game: ex.Engine;declare const ball: ex.Actor;declare const ballSpeed: ex.Vector;declare type Actor = any;declare const bricks: ex.Entity[];// ---cut---// Loss conditionball.on("exitviewport", () => { alert("You lose!");});```
Congratulations! You have just created your first game in Excalibur! You can download this example [here](https://github.com/excaliburjs/sample-breakout).
Some things you could do on your own to take this sample further* Add [[Sprite|sprite]] [[Graphic|graphics]] to the paddle, ball, and bricks* Add a fun background instead of the blue* Interpolate the paddle position between move events for a smoother look* Make the ball ricochet differently depending where the paddle hits it
It's time to [get introduced](/docs/engine) to the Engine for more examples. Once you're ready, you can browse the [API Reference](/docs).
<CodeSandboxEmbed src="https://codesandbox.io/embed/github/excaliburjs/sample-breakout/tree/main/?fontsize=14&hidenavigation=1&theme=dark&view=preview" title="excaliburjs/sample-breakout"/>