docs: update for v0.29.0 (#2937)

* Remove alpha markings

* update docs for v0.29.0

CHANGELOG.md

@@ -7,6 +7,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Breaking Changes
 
+=======
 -
 
 ### Deprecated
@@ -36,7 +37,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [v0.29.0]
 
 ### Breaking Changes
-
+- `ex.Entity.tags` is now a javascript `Set` instead of an `Array` this will affect methods that inspected tags as an array before.
 - `ex.Engine.goToScene`'s second argument now takes `GoToOptions` instead of just scene activation data
   ```typescript
   {

site/docs/01-getting-started/01-installation.mdx

@@ -7,7 +7,7 @@ tags: ["#Explanation"]
 
 :::tip First time here?
 
-If this is your first time using Excalibur, we recommend you start with our [Hello Excalibur](02-your-first-game.mdx) tutorial where you can learn Excalibur in the browser.
+If this is your first time using Excalibur, we recommend you start with our [Hello Excalibur](/docs/getting-started) tutorial where you can learn Excalibur in the browser.
 
 :::
 
@@ -22,6 +22,7 @@ If you want to get up and running quickly with a familiar toolchain, we have sev
 - [Webpack and TypeScript](https://github.com/excaliburjs/template-ts-webpack)
 - [Rollup and TypeScript](https://github.com/excaliburjs/template-ts-rollup)
 - [Vite and TypeScript](https://github.com/excaliburjs/template-ts-vite)
+- [Electron](https://github.com/excaliburjs/template-electron)
 
 ### Samples
 
@@ -36,7 +37,6 @@ If you want to get up and running quickly with a familiar toolchain, we have sev
 - [Universal Windows Platform (UWP)](https://github.com/excaliburjs/example-uwp)
 - [Apache Cordova](https://github.com/excaliburjs/example-cordova)
 - [Xamarin Forms](https://github.com/excaliburjs/example-xamarin)
-- [Electron](https://github.com/excaliburjs/example-electron)
 
 ## Starting from Scratch
 

site/docs/02-fundamentals/02-conventions.mdx

@@ -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)

site/docs/02-fundamentals/04-events.mdx

@@ -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>();
+}
+
+```

site/docs/02-fundamentals/04-scenes.mdx

@@ -150,7 +150,7 @@ class Level extends Scene {
 }
 ```
 
-## Loading 🧪
+## Loading
 
 Scenes can now load resources specific to them by implementing the [[Scene.onPreLoad]].
 

site/docs/02-fundamentals/05-transitions.mdx

@@ -1,5 +1,5 @@
 ---
-title: Scene Transitions 🧪
+title: Scene Transitions
 slug: /transitions
 section: Fundamentals
 ---
@@ -13,14 +13,6 @@ class MyScene extends ex.Scene {}
 class MyOtherScene extends ex.Scene {}
 ```
 
-:::warning
-
-This is currently an alpha feature, and will be released in the next version! API might change/fluctuate until it lands in a supported version.
-
-:::
-
-🧪 `npm install excalibur@0.29.0-alpha.835` or greater
-
 Many times in your game you'll want to smoothly go from one scene to the next, or provide a custom effect when transitioning!
 
 ## Using Pre-Defined Scene Transitions

site/docs/02-fundamentals/06-loaders.mdx

@@ -8,14 +8,6 @@ Games typically will have assets like image files, sound files, level data, etc.
 
 To build a custom designed loader check out the [custom loaders](/docs/custom-loaders) docs.
 
-:::warning
-Parts of this page contain features that are alpha only marked with 🧪!
-
-Available `npm install excalibur@0.29.0-alpha.835` or greater
-
-Alpha features will be released in the next version! API might change/fluctuate until it lands in a supported version.
-:::
-
 ## Loader
 
 Excalibur has a built in type [[Loader]] with the Excalibur.js logo, progress bar and a play button.
@@ -32,7 +24,7 @@ To unlock the audio context as part of a user action handler (clicking for examp
 :::
 
 
-## DefaultLoader & Customizing Loaders 🧪
+## DefaultLoader & Customizing Loaders
 
 [[DefaultLoader]] is the new base loader type that all excalibur loaders must derive from, in fact the built in [[Loader]] derives from this type.
 
@@ -88,7 +80,7 @@ Present a button or something else for the user to interact, resolve `onUserActi
 
 
 
-## Scene Loading 🧪
+## Scene Loading
 
 Excalibur can now load resources specific to a scene instead of all up front!
 

site/docs/02-fundamentals/07-debugging.mdx

@@ -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 });
+}
+
+```

site/docs/04-graphics/06.0-pixel-art.mdx

@@ -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
+
+:::

site/docs/04-graphics/4.2-material.mdx

@@ -116,13 +116,7 @@ game.input.pointers.primary.on('move', evt => {
   code={SimpleMaterial}
 />
 
-## Additional Textures in Materials 🧪
-
-:::warning
-
-This is currently an alpha feature, and will be released in the next version! API might change/fluctuate until it lands in a supported version.
-
-:::
+## Additional Textures in Materials
 
 You can now specify as many additional textures into your [[Material]] as your GPU has texture slots! You may provide a dictionary of uniform names to excalibur [[ImageSource]] and it will be loaded into the material.
 

site/docs/05-entity-component-system/05-entity-component-system.mdx

@@ -6,13 +6,13 @@ section: Entity Component System
 
 Excalibur has a built in Entity Component System (ECS for short), which is a popular software technique in the video game industry
 for managing behavior in a game in a composable and reusable way. Many ECS implementations also focus on memory cache optimization
-techniques, that is not a goal of the current Excalibur implemenation.
+techniques, that is not a goal of the current Excalibur implementation.
 
 ## What is an Entity-Component-System
 
 The [wikipedia](https://en.wikipedia.org/wiki/Entity_component_system) article does a pretty good job of explaining the design pattern, but here is the gist:
 
-- [[Entity]] - Any "thing" in the game that has behavior, it has an id place to to put components.
+- [[Entity]] - Any "thing" in the game that has behavior, it has an `id` place to to put components.
 - [[Component]] - Any state for a particular entity, generally these are state only, but can contain small amounts of logic
 - [[System]] - Implementation of behavior given a set of components on an entity
 

site/docs/05-entity-component-system/05.1-entities.mdx

@@ -8,7 +8,7 @@ An [[Entity]] in is an empty container for [[Component|Components]] which store
 
 They are useful for defining bare bones game objects with custom behavior.
 
-If you want a batteries included prebuilt Entity use an [[Actor]], read more [here](/docs/actor).
+If you want a batteries included prebuilt Entity use an [[Actor]], read more [here](/docs/actor). Remember an Excalibur [[Actor]] is just an Entity with a list of prebuilt components and some useful apis built over them.
 
 ## Entity
 
@@ -88,9 +88,9 @@ const components: Component[] = entity.getComponents()
 
 Tags are special components that are only types. Useful when the presence of a component is all that is needed.
 
-- `Entity.addTag("sometag")` - Add a tag to an entity
-- `Entity.removeTag("sometag")` - Remove a tag on an entity
-- `Entity.hasTag("sometag")` - Check if a tag exists
+- `Entity.addTag("someTag")` - Add a tag to an entity
+- `Entity.removeTag("someTag")` - Remove a tag on an entity
+- `Entity.hasTag("someTag")` - Check if a tag exists
 
 ## Templates aka Prefab