From 2aff71d744974ac3f66ae9989f56d197e8746ea6 Mon Sep 17 00:00:00 2001 From: Erik Onarheim Date: Wed, 17 Jan 2024 09:31:52 -0600 Subject: [PATCH] docs: fix remaining embedded snippets --- site/docs/04-graphics/04.2-canvas.mdx | 26 ++++++++- .../05.3-systems.mdx | 56 ++++++++++++++++++- site/docs/12-other/11-patterns.mdx | 35 +++++++++++- 3 files changed, 114 insertions(+), 3 deletions(-) diff --git a/site/docs/04-graphics/04.2-canvas.mdx b/site/docs/04-graphics/04.2-canvas.mdx index 6feb2f85b..1db2083e7 100644 --- a/site/docs/04-graphics/04.2-canvas.mdx +++ b/site/docs/04-graphics/04.2-canvas.mdx @@ -4,6 +4,10 @@ slug: /canvas section: Graphics --- +```twoslash include ex +/// +``` + For drawing hooks the `ExcaliburGraphicsContext` replaces the browser `CanvasRenderingContext2D`. However, if you need to do some custom drawing using the `CanvasRenderingContext2D` the new [[Canvas]] graphic has your back. The canvas is a special type of graphic that acts like a shim between direct CanvasRenderingContext2D drawing and the [ExcaliburGraphicsContext](#ExcaliburGraphicsContext). @@ -28,6 +32,26 @@ const canvas = new Canvas({ ## Example -`embed:excalibur-snippets/src/canvas/main.ts{snippet: "canvas"}` +```ts twoslash +// @include: ex +declare const game: ex.Engine; +// ---cut--- +const canvas = new ex.Canvas({ + width: 200, + height: 200, + cache: true, // If true draw once until flagged dirty again, otherwise draw to Canvas every frame + draw: (ctx) => { + console.log('With cache=true I draw once'); + ctx.fillStyle = 'red'; + ctx.fillRect(0, 0, 200, 200); + } +}) + +const actor = new ex.Actor({ + pos: game.screen.center +}); + +actor.graphics.use(canvas); +``` diff --git a/site/docs/05-entity-component-system/05.3-systems.mdx b/site/docs/05-entity-component-system/05.3-systems.mdx index 6e2a703fd..78745cf9e 100644 --- a/site/docs/05-entity-component-system/05.3-systems.mdx +++ b/site/docs/05-entity-component-system/05.3-systems.mdx @@ -4,6 +4,11 @@ slug: /systems section: Entity Component System --- +```twoslash include ex +/// +declare const game: ex.Engine; +``` + Core behavior in Excalibur is implemented by Systems. Systems process all entities that have matching component types and perform some action. Examples of systems are the [[GraphicsSystem]], [[MotionSystem]], [[CollisionSystem]], and [[DebugSystem]] @@ -59,7 +64,56 @@ For custom component types it is recommended you prefix your types, like `type = In this example, we create a "search" type component, that searches for a target position. Notice how this component implementation is mostly data. -`embed:excalibur-snippets/src/ecs/main.ts{snippet: "ecs"}` +```ts twoslash +// @include: ex +// ---cut--- +class SearchComponent extends ex.Component<'search'> { + public readonly type = 'search' + constructor(public target: ex.Vector) { + super(); + } +} + +class SearchSystem extends ex.System { + // Types need to be listed as a const literal + public readonly types = ['ex.transform', 'search'] as const; + + // Lower numbers mean higher priority + // 99 is low priority + public priority = 99; + + // Run this system in the "update" phase + public systemType = ex.SystemType.Update + + private _searchSpeed = 100 // pixels/sec + + public update(entities: ex.Entity[], delta: number) { + for (let entity of entities) { + const target = entity.get(SearchComponent)!.target; + // ex.TransformComponent is a built in type + const transform = entity.get(ex.TransformComponent) as ex.TransformComponent; + + const direction = target.sub(transform.pos); + const motion = direction.normalize().scale(this._searchSpeed); + + // Moves these entities towards the target at 10 pixels per second + transform.pos = transform.pos.add(motion.scale(delta / 1000)) + } + } +} + +const scene = new ex.Scene(); +scene.world.add(new SearchSystem()); + +// Actors come with batteries included built in features +const actor = new ex.Actor({ + pos: ex.vec(100, 100), + width: 30, + height: 30, + color: ex.Color.Red +}); +actor.addComponent(new SearchComponent(ex.vec(600, 400))); +``` diff --git a/site/docs/12-other/11-patterns.mdx b/site/docs/12-other/11-patterns.mdx index 20d196c92..ed30035ef 100644 --- a/site/docs/12-other/11-patterns.mdx +++ b/site/docs/12-other/11-patterns.mdx @@ -4,6 +4,11 @@ slug: /patterns section: Other --- +```twoslash include ex +/// +declare const game: ex.Engine; +``` + Here are a few patterns and guidelines that you can use in your Excalibur projects. ## Project Structure @@ -37,7 +42,35 @@ Keep the `main.ts` entrypoint as small as possible (this is where we create a ne Keep all of our assets/resources in one file `resources.ts` and load them all at once in the `main.ts` -`embed:excalibur-snippets/src/resources/main.ts{snippet: "resources"}` +```ts twoslash +// @include: ex +declare interface Object { + values(res: any): ex.Resource[]; +} +// ---cut--- +// Because snippets uses a bundler we load the image with an import +// Optionally do this +// import playerUrl from './player.png'; + +// If you aren't using a bundler like parcel or webpack you can do this: +// const imagePlayer = new ex.ImageSource('./player.png') +const Resources = { + ImagePlayer: new ex.ImageSource('./player.png'), + //... more resources +} as const; // <-- Important for strong typing + +const loader = new ex.Loader(); +for (let res of Object.values(Resources)) { + loader.addResource(res); +} + +class Player extends ex.Actor { + public onInitialize(engine: ex.Engine) { + // set as the "default" drawing + this.graphics.use(Resources.ImagePlayer.toSprite()); + } +} +```