-
-
Notifications
You must be signed in to change notification settings - Fork 190
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Remove alpha markings * update docs for v0.29.0
- Loading branch information
Showing
26 changed files
with
513 additions
and
178 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
--- | ||
title: Conventions | ||
slug: /conventions | ||
--- | ||
|
||
There are a few things that Excalibur does that are good to know before you start building games! | ||
|
||
# Conventions | ||
|
||
1. Excalibur uses a theater metaphor, for example: [[Scene|Scenes]], [[Actor|Actors]], and [Actions](/docs/actions). | ||
|
||
2. Excalibur uses [Resources](docs/category/resources) to load external files like [images](/docs/ImageSource) and [sounds](/docs/Sound). They can also be used to load other things like data or config. | ||
|
||
2. The negative y direction is up, and the positive y direction is down. | ||
|
||
2. Distance units are in pixels, velocity in pixels per second, and acceleration in pixels per second per second. | ||
|
||
3. Rotation units are in radians. | ||
|
||
4. All elapsed times and durations in Excalibur in are milliseconds. | ||
|
||
5. Actor z-index's follow the browser way of doing things. | ||
* Things with larger positive numbers are on top of lower numbers. | ||
|
||
6. Excalibur handles offscreen draw culling for you! No need to manage that! | ||
|
||
7. Excalibur uses pre-multiplied alphas when drawing which is important to know if you use [Material](/docs/materials) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
--- | ||
title: Events | ||
slug: /events | ||
section: Fundamentals | ||
--- | ||
|
||
```twoslash include ex | ||
/// <reference path="../src/engine/excalibur.d.ts" /> | ||
declare const engine: ex.Engine; | ||
``` | ||
|
||
Nearly everything in Excalibur has a way to listen to events! This is useful when you want to know exactly when things happen in Excalibur and respond to them with game logic. [[Actor|Actors]], [[Scene|Scenes]], [[Engine|Engines]], [[ActionsComponent|Actions]], [[Animation|Animations]], and various components have events you can hook into just look for the `.events` member! | ||
|
||
:::info | ||
|
||
Excalibur events are handled synchronously, which is great for debugging and reducing timing bugs. | ||
|
||
::: | ||
|
||
## Strongly Typed Events | ||
|
||
Excalibur has types on all it's event listeners, you can check these types with intellisense in vscode or by following the typescript definition. | ||
|
||
![event auto complete](events.png) | ||
|
||
Excalibur also allows you to listen/send any event you want to as well, but you'll need to provide your own types for that. | ||
|
||
```typescript | ||
|
||
interface MyEvents { | ||
coolevent: MyCoolEvent; | ||
forsure: ForSureEvent; | ||
} | ||
|
||
class MyActor extends Actor { | ||
public events = new EventEmitter<ActorEvents & MyEvents>(); | ||
} | ||
|
||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
--- | ||
title: Debugging | ||
slug: /debugging | ||
section: Fundamentals | ||
--- | ||
|
||
There are a couple gotchas that can bite new developers in excalibur. We recommend using the [Excalibur Debug Browser Extension](https://github.com/excaliburjs/excalibur-extension) | ||
|
||
:::tip | ||
|
||
Check the browser console for warnings! These will often hint at something being wrong, so if you're game is behaving unexpectedly look there first! | ||
|
||
::: | ||
|
||
## Why is my event not firing | ||
|
||
1. Are you sure that's the right event name? For example `pointerdown` vs. `click`, Excalibur will let you listen to `click` event though it's not a supported event. | ||
|
||
## Why is my Actor not showing up on screen? | ||
|
||
1. Have you added it to a scene? Is it the current one? | ||
2. Do you have graphics assigned? `actor.graphics.use(graphic)` | ||
3. Give your actor a name `new ex.Actor({name: 'myCoolActor'})`, turn on names `game.debug.entity.showName = true` and toggle debug mode `game.toggleDebug()` to show debug drawing. | ||
4. Use the excalibur debug extension to help visualize https://github.com/excaliburjs/excalibur-extension | ||
|
||
### Issue: My game only shows a white screen | ||
|
||
- Did you remember to call `game.start()`? | ||
|
||
### Issue: Poor/laggy game performance | ||
|
||
- Consult our [performance guide](/docs/performance) | ||
|
||
### Issue: My images show up as black rectangles on mobile or other platforms | ||
|
||
- Ensure your images are less than 4k pixels in width or height, this is usually the limit for mobile devices in WebGL. | ||
|
||
## How do I visualize values for debugging | ||
|
||
Use the [[Debug]] static drawing helpers! They can be called from anywhere without a graphics context and can be very useful for debugging your game. You will need to `game.toggleDebug()` to see them. | ||
|
||
```typescript | ||
const game = new ex.Engine({...}) | ||
game.toggleDebug(); | ||
|
||
const player = new ex.Actor({...}); | ||
player.onPostUpdate = () => { | ||
ex.Debug.drawLine( | ||
player.pos, | ||
player.pos.add(ex.Vector.Down.scale(100)), { | ||
color: ex.Color.Red | ||
}); | ||
ex.Debug.drawPoint(player.pos, { | ||
size: 1, | ||
color: ex.Color.Violet | ||
}); | ||
ex.Debug.drawCircle(player.pos, 100, { | ||
color: ex.Color.Transparent, | ||
strokeColor: ex.Color.Black, | ||
width: 1 | ||
}); | ||
ex.Debug.drawBounds(player.collider.bounds, { color: ex.Color.Yellow }); | ||
} | ||
|
||
``` |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
--- | ||
title: Pixel Art | ||
slug: /pixel-art | ||
section: Graphics | ||
--- | ||
|
||
# Pixel Art | ||
|
||
Pixel art is deceptively challenging to get right. There are a few rendering artifacts that can plague pixel art games in this guide hopefully we'll get you to the prettiest possible pixel art. | ||
|
||
## Basic Approach: Nearest Neighbor and No Antialiasing | ||
|
||
This is the first approach that most people try, and for some games might be fine if you are snapping to whole pixel values and scale your graphics by integer amounts. In fact many games are shipped this way. | ||
|
||
If you set Excalibur to `new ex.Engine({antialiasing: false})` this is what you'll get! | ||
|
||
### Cons: Artifacts | ||
|
||
Using the basic approach comes with some downsides: shimmering artifacts (inconsistent line widths) and jaggies when rotating objects. | ||
|
||
Solution might be to use `new ex.Engine({pixelRatio: 3})` to "upscale" lower resolutions to more pixels. | ||
|
||
## New Approach: Texture Filtering, Scaling, and special Antialiasing | ||
|
||
Excalibur has a special pixel art mode that will put you into this mode released in v0.29.0! | ||
|
||
```typescript | ||
const game = new ex.Engine({ | ||
pixelArt: true // and that's it! | ||
}); | ||
``` | ||
|
||
This will set a few presets in excalibur, this above setting is equivalent to the following | ||
|
||
```typescript | ||
const game = new ex.Engine({ | ||
antialiasing: { | ||
pixelArtSampler: true, // turns on the sub-pixel shader for pixel art | ||
nativeContextAntialiasing: false, // turns off canvas aa | ||
multiSampleAntialiasing: true, // turns on msaa which smooths quad boundaries | ||
filtering: ImageFiltering.Blended, // hints the image loader to use blended filtering | ||
canvasImageRendering: 'auto' // applies the 'auto'-matic css to the canvas CSS image-rendering | ||
} | ||
}) | ||
``` | ||
|
||
This is great article explaining the approach | ||
|
||
* https://jorenjoestar.github.io/post/pixel_art_filtering/ | ||
|
||
Here is a shader toy demonstrating | ||
* Shader Toy showing https://www.shadertoy.com/view/mdSXWy | ||
|
||
:::note | ||
|
||
If you have very low resolutions less than 500x500, you might want to consider artificially scaling the graphics by setting `pixelRatio: 2` or `pixelRatio: 3` this increases the internal resolution (effectively up-scaling) giving Excalibur more pixels to work with and smooth. This produces more pleasing results when simulating a very low res game | ||
|
||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.