From 209c4979450ee721107e1c2028bfd3fdb822c181 Mon Sep 17 00:00:00 2001 From: Cjad Elstad Date: Tue, 16 Jan 2024 22:48:40 -0600 Subject: [PATCH] docs: cleanup work part one: 00-welcome, 00-your-first-game, 01-installation, 03-bundlers, and 03-actors (#2890) * docs corrections part 1 * added back in two slash syntax * Update site/docs/02-fundamentals/03-actors.mdx Co-authored-by: Erik Onarheim --------- Co-authored-by: Erik Onarheim --- site/docs/00-welcome.mdx | 24 ++--- site/docs/00-your-first-game.mdx | 47 ++++------ .../01-getting-started/01-installation.mdx | 2 + site/docs/01-getting-started/03-bundlers.mdx | 88 ++++++++++--------- site/docs/02-fundamentals/03-actors.mdx | 36 ++++---- 5 files changed, 99 insertions(+), 98 deletions(-) diff --git a/site/docs/00-welcome.mdx b/site/docs/00-welcome.mdx index 02e34520e..90069abf1 100644 --- a/site/docs/00-welcome.mdx +++ b/site/docs/00-welcome.mdx @@ -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 diff --git a/site/docs/00-your-first-game.mdx b/site/docs/00-your-first-game.mdx index 06f867b9b..a654f77ab 100644 --- a/site/docs/00-your-first-game.mdx +++ b/site/docs/00-your-first-game.mdx @@ -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 @@ -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 @@ -43,40 +43,39 @@ Excalibur can be used as a script reference, see [standalone script](/docs/insta -... ``` ```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]() 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]() 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'; ``` @@ -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"}` @@ -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"}` @@ -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). -[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 diff --git a/site/docs/01-getting-started/01-installation.mdx b/site/docs/01-getting-started/01-installation.mdx index 2b2c239df..b9d005a21 100644 --- a/site/docs/01-getting-started/01-installation.mdx +++ b/site/docs/01-getting-started/01-installation.mdx @@ -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: diff --git a/site/docs/01-getting-started/03-bundlers.mdx b/site/docs/01-getting-started/03-bundlers.mdx index 73ee70bb6..b409052fe 100644 --- a/site/docs/01-getting-started/03-bundlers.mdx +++ b/site/docs/01-getting-started/03-bundlers.mdx @@ -6,11 +6,13 @@ section: Getting Started To get started, first install Excalibur through npm (TypeScript typings are best supported in npm): + ```bash npm install excalibur + ``` ### TypeScript Configuration -In a TypeScript project, you can reference Excalibur with the ES6 import style syntax: +In a TypeScript (or modern JavaScript) project, you can reference Excalibur with the ES6 import style syntax: ```js // Excalibur is loaded into the ex global namespace @@ -24,6 +26,19 @@ or import { Actor, Engine } from 'excalibur'; ``` +To support tree-shaking, you should use _named imports_: + +```js +import { Actor } from 'excalibur'; +``` + +:::warning + +Excalibur doesn't do the best optimization to support tree-shaking--likely +you'll end up importing everything at the moment but this is slowly getting better. + +::: + #### TSConfig We have a base recommended tsconfig.json that the TypeScript compiler uses as configuration. In this example we assume all the source is in a `./src/` directory. @@ -52,40 +67,31 @@ We have a base recommended tsconfig.json that the TypeScript compiler uses as co } ``` -In a module loader system, such as Webpack or Parcel, it will automatically bundle Excalibur. See the [webpack example repo](https://github.com/excaliburjs/template-ts-webpack) or [parcel repo](https://github.com/excaliburjs/template-ts-parcel) - -To support tree-shaking, you should use _named imports_: - -```js -import { Actor } from 'excalibur'; -``` - -:::warning - -Excalibur doesn't do the best optimization to support tree-shaking--likely -you'll end up importing everything at the moment but this is slowly getting better. - -::: +In a module loader system, such as Webpack or Parcel, it will automatically bundle Excalibur. See the [webpack example repo](https://github.com/excaliburjs/template-ts-webpack) or [parcel repo](https://github.com/excaliburjs/template-ts-parcel-v2) ### Parcel -Parcel is by far the easiest way to get a bundler up and running with excalibur. We recommend looking at the [template](https://github.com/excaliburjs/template-ts-parcel). +Parcel is by far the easiest way to get a bundler up and running with Excalibur. We recommend looking at the [template](https://github.com/excaliburjs/template-ts-parcel-v2). :::warning -Adding an `import "regenerator-runtime/runtime";` in your entry file is needed to force parcel to understand async/await inside excalibur +Adding an `import "regenerator-runtime/runtime";` in your entry file is needed to force Parcel to understand async/await inside Excalibur. ::: -Using npm to install parcel, excalibur, and typescript +Using npm to install Parcel, Excalibur, and TypeScript: + ```bash npm install parcel-bundler excalibur typescript + ``` -Configure you tsconfig.json +Configure your tsconfig.json: + ```bash tsc --init + ``` -Build your game script +Create your game script: ```typescript // ./src/index.ts @@ -97,7 +103,7 @@ const game = new Engine({ game.start(); ``` -Include the **typescript** file in your html +Include the **TypeScript** file in your html: ```html @@ -108,9 +114,11 @@ Include the **typescript** file in your html ``` -Build and run with parcel! +Build and run with Parcel! + ```bash parcel index.html --no-autoinstall + ``` ### Webpack @@ -118,9 +126,9 @@ Webpack is the battleship solution, and if you need a lot of control over your b :::warning -Configuring webpack is not for the faint of heart, we recommend thoroughly reading webpack's documentation on how to understand and configure webpack. +Configuring Webpack is not for the faint of heart, we recommend thoroughly reading webpack's documentation on how to understand and configure webpack. -[Our template](https://github.com/excaliburjs/template-ts-webpack) is a good starting point. +[Our Webpack template](https://github.com/excaliburjs/template-ts-webpack) is a good starting point. ::: @@ -128,13 +136,13 @@ Configuring webpack is not for the faint of heart, we recommend thoroughly readi [Deno](https://deno.land/) is a runtime for JavaScript and TypeScript and much more than a bundler, but we put this section here since you'll be doing a lot of bundling :). -For Excalibur to work in a Deno environment, use a Content Delivery Network for making Node.js packages compatible with Deno: two popular ones are [esm.sh](https://esm.sh/) and [skypack.dev](https://www.skypack.dev/). +For Excalibur to work in a Deno environment, use a Content Delivery Network (CDN) for making Node.js packages compatible with Deno. Two popular ones are [esm.sh](https://esm.sh/) and [skypack.dev](https://www.skypack.dev/). To keep it simple, we use `esm.sh` in the following examples, but feel free to make your own choice - at the time of writing the procedure for `esm.sh` and `skypack.dev` is nearly identical (for a difference, see the section [Types and IntelliSense](#types-and-intellisense)). #### Importing within an HTML file -Sometimes, you just want to start hacking. You can do so by using Deno to get a bundled version of Excalibur and directly applying the module to your HTML. +Sometimes, you just want to start hacking. You can do so by using [Deno](https://deno.land/) to get a bundled version of Excalibur and directly applying the module to your HTML. Either [esm.sh](https://esm.sh/excalibur) or [skypack.dev](https://www.skypack.dev/view/excalibur) should generate a bundle that works: @@ -161,27 +169,27 @@ Using as a native module works in Chrome without any extras: ``` -The drawback to this method is that it doesn't give you type annotations in your IDE, like [the following method](#importing-into-a-javascript-or-typescript-file). - :::note Learn more about the `type="module"` attribute [on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). ::: +The drawback to this method is that it doesn't give you type annotations in your IDE, like the following method. + #### Importing into a JavaScript or TypeScript File :::note -We have tested the following examples with version 0.26.0-alpha.264 of the excalibur package. We recommend you run at least that version for this to work. You can get [the latest excalibur version on npm](https://www.npmjs.com/package/excalibur). +We have tested the following examples with version `0.26.0-alpha.264` of the excalibur package. We recommend you run at least that version for this to work. You can get [the latest excalibur version on npm](https://www.npmjs.com/package/excalibur). ::: More likely, you will want to import Excalibur into a JavaScript or TypeScript file. -Since it goes very well with Deno, we use TypeScript in the following examples. We will have to set up our TypeScript compiler and pick our import syntax before we can make our bundle. +Since it goes very well with [Deno](https://deno.land/), we use TypeScript in the following examples. We will have to set up our TypeScript compiler and pick our import syntax before we can make our bundle. -A custom `tsconfig.json` has to be used with `strict` turned off and a few DOM libraries added: +A custom `tsconfig.json` must be used with `strict` turned off and a few DOM libraries added: ```json // tsconfig.json @@ -194,7 +202,7 @@ A custom `tsconfig.json` has to be used with `strict` turned off and a few DOM l } ``` -Then Excalibur can be imported. This can be done in two ways: +After that, Excalibur can be imported. This can be done in one of two ways: **Recommended: Named Import** @@ -207,7 +215,7 @@ const game = new Engine(); game.start(); ``` -**Alternative: Namespace Import ** +**Alternative: Namespace Import** ```typescript // index.ts @@ -222,17 +230,17 @@ game.start(); There are two main reasons: -- We find named imports more [expressive](https://stackoverflow.com/questions/42051588/wildcard-or-asterisk-vs-named-or-selective-import-es6-javascript) and [explicit](https://javascript.info/import-export#import) than the wildcard `*` syntax. It's easier for you and your collaborators to see what parts of the module are actually being used if they are all listed in the import statement. +- We find named imports more [expressive](https://stackoverflow.com/questions/42051588/wildcard-or-asterisk-vs-named-or-selective-import-es6-javascript) and [explicit](https://javascript.info/import-export#import) than the wildcard `*` syntax. It's easier for you and your collaborators to see what parts of the module are actually being used when they are all listed in the import statement. - They can help with _tree shaking_, as explained in [this relatively beginner-friendly developers.google tutorial](https://developers.google.com/web/fundamentals/performance/optimizing-javascript/tree-shaking/#finding_opportunities_to_shake_a_tree). :::note -_Tree shaking_ means dropping unused code, reducing the size of your bundle so that your app can load faster for the end-user. This can be done by build tools such as [Rollup](https://rollupjs.org/guide/en/#tree-shaking) and [Webpack](https://webpack.js.org/guides/tree-shaking/). +_Tree shaking_ means removing unused code, reducing the size of your bundle so that your app can load faster for the end-user. This can be done by build tools such as [Rollup](https://rollupjs.org/guide/en/#tree-shaking) and [Webpack](https://webpack.js.org/guides/tree-shaking/). ::: -Both approaches work. you might have your reasons for using namespace imports. We encourage you to do your own research! +Both approaches work. You may have reasons for using namespace imports. We encourage you to research your options. :::note @@ -242,7 +250,7 @@ The official MDN documentation is a great place to start learning about [modules #### Bundling and Applying -Set up your `tsconfig.json` and your `index.ts` as described in [the section above]((#importing-into-a-javascript-or-typescript-file). Then Deno should successfully bundle: +Set up your `tsconfig.json` and your `index.ts` as described in the [Importing into a JavaScript or TypeScript File](#importing-into-a-javascript-or-typescript-file) section above. Then Deno should successfully bundle: ```bash deno bundle index.ts game.bundle.js --config tsconfig.json @@ -254,7 +262,7 @@ Learn more about the `deno bundle` command in the official [Deno docs](https://d ::: -And you can apply it in your `index.html` with a regular script tag: +You can then apply it in your `index.html` with a regular script tag: ```html @@ -264,13 +272,13 @@ And you can apply it in your `index.html` with a regular script tag: ![Screenshot demonstrating IntelliSense](intellisense_screenshot.png) -To enable type annotations and IntelliSense in a Deno environment, you might need to install a special extension in your IDE, like this one for VSCode: [Deno extension by denoland](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno). +To enable type annotations and IntelliSense in a Deno environment, you might need to install a special extension in your IDE, such as this one for VSCode: [Deno extension by denoland](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno). Make sure to read the instructions of the extension. you might also need to install the Deno CLI and later initialize the extension in your IDE workspace. :::warning -It might also take a few seconds until the IntelliSense starts working. Deno is resolving the import URLs and downloading the necessary files in the background. +It may take a few seconds for IntelliSense to start working. Deno is resolving the import URLs and downloading the necessary files in the background. ::: diff --git a/site/docs/02-fundamentals/03-actors.mdx b/site/docs/02-fundamentals/03-actors.mdx index 1bd2cec51..a1d9edb12 100644 --- a/site/docs/02-fundamentals/03-actors.mdx +++ b/site/docs/02-fundamentals/03-actors.mdx @@ -7,9 +7,9 @@ import ActorCollisionExample from '!!raw-loader!./examples/collision.ts'; # Actors [[Actor|Actors]] are prebuilt Excalibur [[Entity|Entities]] that come with the batteries included for most applications. -Like [[TransformComponent|position]], [[MotionComponent|velocity]], [[GraphicsComponent|graphics]], and [[ColliderComponent|collision detection]]. +Such as [[TransformComponent|position]], [[MotionComponent|velocity]], [[GraphicsComponent|graphics]], and [[ColliderComponent|collision detection]]. -[[Actor|Actors]] are the recommended way to use Excalibur, they are the primary way to show something on the screen. +[[Actor|Actors]] are the recommended way to use Excalibur to show something on the screen. If you don't want these built-ins and you want to build only what you want, read about entities [here](/docs/entities) @@ -20,10 +20,10 @@ declare const game: ex.Engine; ## Basic actors -For quick and dirty games, you can just create an instance of an [[Actor]] +For quick and dirty games, you may be able to create an instance of an [[Actor]] and manipulate it directly. -Actors (and other entities) must be added to a [Scene](/docs/scene) to be drawn +Actors (and other entities) must be added to a [Scene](/docs/scenes) to be drawn and updated on-screen. {ActorCollisionExample}