Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs cleanup work part one: 00-welcome, 00-your-first-game, 01-installation, 03-bundlers, and 03-actors #2890

Merged
merged 6 commits into from
Jan 17, 2024
Merged

Docs cleanup work part one: 00-welcome, 00-your-first-game, 01-installation, 03-bundlers, and 03-actors #2890

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
40ddecd
docs corrections part 1
cdelstad Jan 16, 2024
20690f5
Merge branch 'excaliburjs:main' into main
cdelstad Jan 16, 2024
d70aae3
Merge branch 'excaliburjs:main' into main
cdelstad Jan 17, 2024
048430a
added back in two slash syntax
cdelstad Jan 17, 2024
79d94c4
Merge branch 'main' of https://github.com/cdelstad/Excalibur
cdelstad Jan 17, 2024
0c64036
Update site/docs/02-fundamentals/03-actors.mdx
cdelstad Jan 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions site/docs/00-welcome.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,23 @@ Excalibur has a ton of features to help you make games!

- Objected-Oriented TypeScript first API
- [Actors](/docs/actors) come prebuilt everything you need
- SpriteSheet, Sprites, and Animations
- Text and Font support
- Built in Math utilities like Matrix and Vector
- Collision Detection
- Arcade Style and Realistic Physics
- 2D and Isometric TileMaps
- Tiled and Aseprite integrations
- Optionally write custom WebGL Renderers
- Optionally use Entity-Component-System style development

There are a lot of great tools out there to build games on the web, no tool is perfect, use whatever tool makes you happiest 😊
- [SpriteSheet](/docs/spritesheets), [Sprites](/docs/sprites), and [Animations](/docs/animation)
- [Text and Font](/docs/text) support
- Built in Math utilities like [Matrix](/docs/matrix) and [Vector](/docs/vector)
- [Collision Detection](/docs/colliders)
- [Arcade](/docs/physics#arcade) Style and [Realistic](/docs/physics#realistic) Physics
- [2D](/docs/tilemap) and [Isometric](/docs/isometric) TileMaps
- [Tiled](/docs/tiled-plugin) and [Aseprite](/docs/aseprite-plugin) integrations
- Optionally write [custom WebGL Renderers](/docs/custom-renderer-plugins)
- Optionally use [Entity-Component-System](/docs/entity-component-system) style development

There are a lot of great tools out there to build games on the web and no tool is perfect. Use whichever tool makes you happiest. 😊

## Excalibur's Design Philosophy

1. Excalibur aims to be the best 2D game development experience for the web.
2. Excalibur is flexible with sensible defaults.
3. Excalibur is a "batteries included" game engine, you can just do the things you want
3. Excalibur is a "batteries included" game engine, you can just do the things you want.

## Excalibur is FOSS

Expand Down
47 changes: 19 additions & 28 deletions site/docs/00-your-first-game.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ tags: ["#Tutorial"]

## Introduction

Excalibur uses a theater-style metaphor to organize your games. There are `Actor`'s which can move around and do things in a currently active `Scene`, and all of that lives in the `Engine` container.
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.

## Global Namespace vs. Imports

Expand All @@ -32,7 +32,7 @@ const actor = new Actor();

If you are using a standalone script, the excalibur types will have a `ex.` in front of them.

Excalibur can be used as a script reference, see [standalone script](/docs/installation#script-reference-or-download) for more info
Excalibur can be used as a script reference, see [standalone script](/docs/installation#script-reference-or-download) for more info.

```html
<html>
Expand All @@ -43,40 +43,39 @@ Excalibur can be used as a script reference, see [standalone script](/docs/insta
<script src="game.js"></script>
</body>
</html>
...
```

```ts
// game.js
// Standalone style 'ex' global exists ambiently from an included script.
// Standalone style 'ex' global exists from an included script.

const actor = new ex.Actor();
```

## 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 of a player paddle. You must break all the bricks to win and avoid the ball falling off the bottom of the screen.
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 you game into separate files to keep your project more manageable.
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, here I’ve named it `game.ts`. Excalibur games are built off of the [Engine](/docs/engine) container. It is important to start the engine once you are done building your game.
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()` otherwise the game wont start!
It is important to call `game.start()` once you are done configuring your game otherwise it won't start!

:::

```typescript
// ES style import from excalibur
// ES style import from Excalibur
import { Engine } from 'excalibur';
```

Expand All @@ -91,19 +90,17 @@ 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 [Actor][docs-actor]. Actors are the primary way to draw things to the screen.

Actors must be added to a [Scene][docs-scene] to be drawn and updated.
Game elements that have a position and are drawn to the screen are called an [Actor][/docs/actor]. 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.
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 a position, width, and height.
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.

`embed:sample-breakout/src/main.ts{snippet: "create-paddle"}`

Expand All @@ -117,23 +114,23 @@ That’s neat, but this game is way more fun if things move around. Let’s make

:::note

**Important!** Actors have a default [anchor][docs-graphics-component-anchor] of (0.5, 0.5) which means their graphics are positioned in their center (not top-left) by default.
**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 of other objects.
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 not resolve the positions.
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.
Read more about the different [CollisionTypes](/docs/physics/#collision-types) that Excalibur supports.

`embed:sample-breakout/src/main.ts{snippet: "create-ball"}`

The ball is now setup to move at 100 pixels per second down and right. Next we will make the ball bounce with the side of the screen, let’s take advantage of the `postupdate` event.
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.

`embed:sample-breakout/src/main.ts{snippet: "screen-collision"}`

Expand All @@ -147,24 +144,18 @@ When the ball collides with bricks, we want to remove them from the scene. We us

`embed:sample-breakout/src/main.ts{snippet: "ball-brick-collision"}`

Finally, if the ball leaves the screen, the player loses!
Finally, if the ball leaves the screen by getting past the paddle, the player loses!

`embed:sample-breakout/src/main.ts{snippet: "lose-condition"}`

![Final Breakout screenshot](00-welcome/breakout-final.png)

Congratulations! You have just created your first game in Excalibur! You can download this example here https://github.com/excaliburjs/sample-breakout
Congratulations! You have just created your first game in Excalibur! You can download this example [here](https://github.com/excaliburjs/sample-breakout).

It's time to [get introduced][docs-intro] to the engine for more examples or advanced users can browse the [API Reference][docs-api].
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/api/edge).

<CodeSandboxEmbed
src="https://codesandbox.io/embed/github/excaliburjs/sample-breakout/tree/main/?fontsize=14&hidenavigation=1&theme=dark&view=preview"
title="excaliburjs/sample-breakout"
/>

[docs-install]: /docs/installation
[docs-intro]: /docs/engine
[docs-actor]: /docs/actors
[docs-scene]: /docs/scenes
[docs-graphics-component-anchor]: /docs/graphics-component/#component-specific-overrides
[docs-api]: /docs/api/edge
2 changes: 2 additions & 0 deletions site/docs/01-getting-started/01-installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,9 @@ If you intend to use Excalibur in a primarily .NET-based project (like Xamarin,

With the [.NET SDK installed](https://docs.microsoft.com/en-us/dotnet/framework/install/), run the following on the command-line:

```bash
Install-Package Excalibur
```

Nuget will automatically place the Excalibur files in the `Content/Scripts` folder of your project:

Expand Down
Loading