fix(deps): update dependency excalibur to v0.29.3 (main)

[renovate]

This PR contains the following updates:

Package	Change	Age	Adoption	Passing	Confidence
excalibur	0.26.0 -> 0.29.3

---

Release Notes

excaliburjs/Excalibur (excalibur)

v0.29.3

Compare Source

Breaking Changes

• ex.Action now requires a unique id property
• Z-indexes are now relative to the parent's Z-index. You can get the global Z-index with the globalZ property on the Actor or TransformComponent.

Deprecated

Added

• Built in actions now have a unique id property
• globalZ property to Actor and TransformComponent

Fixed

• Fixed animation glitch caused by uninitialized state in ImageRenderer
• Fixed issue where ex.Loader.suppressPlayButton = true did not work. Only using the ex.Engine({suppressPlayButton: true}) worked

Updates

Changed

• ex.Vector.toAngle() now returns angles from [0 - 2 PI)

v0.29.2

Compare Source

Breaking Changes

Deprecated

• `

Added

• Added ability to configure image wrapping on ex.ImageSource with the new ex.ImageWrapping.Clamp (default), ex.ImageWrapping.Repeat, and ex.ImageWrapping.Mirror.

  const image = new ex.ImageSource('path/to/image.png', {
    filtering: ex.ImageFiltering.Pixel,
    wrapping: {
      x: ex.ImageWrapping.Repeat,
      y: ex.ImageWrapping.Repeat,
    }
  });

• Added pointer event support to ex.TileMap's and individual ex.Tile's
• Added pointer event support to ex.IsometricMap's and individual ex.IsometricTile's
• Added useAnchor parameter to ex.GraphicsGroup to allow users to opt out of anchor based positioning, if set to false all graphics members
  will be positioned with the top left of the graphic at the actor's position.

  const graphicGroup = new ex.GraphicsGroup({
    useAnchor: false,
    members: [
      {
        graphic: heartImage.toSprite(),
        offset: ex.vec(0, 0),
      },
      {
        graphic: heartImage.toSprite(),
        offset: ex.vec(0, 16),
      },
      {
        graphic: heartImage.toSprite(),
        offset: ex.vec(16, 16),
      },
      {
        graphic: heartImage.toSprite(),
        offset: ex.vec(16, 0),
      },
    ],
  });

• Added simplified ex.coroutine overloads, you need not pass engine as long as you are in an Excalibur lifecycle

  const result = ex.coroutine(function* () {...});

• Added way to bind 'this' to ex.coroutine overloads, you need not pass engine as long as you are in an Excalibur lifecycle

  const result = ex.coroutine({myThis: 'cool'}, function* () {...});

• Added optional ex.coroutine timing parameter to schedule when they are updated

  const result = ex.coroutine(engine, function * () {...}, { timing: 'postupdate' })

• Added GraphicsComponent.bounds which will report the world bounds of the graphic if applicable!
• Added ex.Vector.EQUALS_EPSILON to configure the ex.Vector.equals(v) threshold
• Added way to add custom WebGL context lost/recovered handlers for your game

  const game = new ex.Engine({
    handleContextLost: (e) => {...},
    handleContextRestored: (e) => {...}
  })

Fixed

• Fixed issue where ex.TileMap culling did not work properly when using fixed updates lower than refresh rate
• Fixed incomplete types for font options in ex.FontSource().toFont(options)
• Fixed issue with ex.Loader start button position when using CSS transforms
• Fixed issue where adding scenes with the same name did not work when it was previously removed
• Fixed issue when WebGL context lost occurs where there was no friendly output to the user
• Fixed issue where HiDPI scaling could accidentally scale past the 4k mobile limit, if the context would scale too large it will now attempt to recover by backing off.
• Fixed issue where logo was sometimes not loaded during ex.Loader
• Fixed issue where unbounded containers would grow infinitely when using the following display modes:
  • DisplayMode.FillContainer
  • DisplayMode.FitContainer
  • DisplayMode.FitContainerAndFill
  • DisplayMode.FitContainerAndZoom
• Fixed issue where ex.ParticleEmitter z-index did not propagate to particles
• Fixed incongruent behavior as small scales when setting transform.scale = v and transform.scale.setTo(x, y)
• Fixed ex.coroutine TypeScript type to include yielding undefined
• Fixed issue where Firefox on Linux would throw an error when using custom Materials due to unused attributes caused by glsl compiler optimization.
• Fixed issue where start transition did not work properly if deferred
• Fixed issue where transitions did not cover the whole screen if camera was zoomed
• Fixed issue where Color.toHex() produced invalid strings if the channel values are negative or fractional, or if the alpha channel was different than 1

Updates

Changed

• Significant 2x performance improvement to image drawing in Excalibur
• Simplified ex.Loader viewport/resolution internal configuration

v0.29.1: Excalibur v0.29.1 Release

Compare Source

Small release to fix transition bug!

What's Changed

• fix: Transition bug when camera is zoomed by @​eonarheim in https://github.com/excaliburjs/Excalibur/pull/2942

Full Changelog: excaliburjs/Excalibur@v0.29.0...v0.29.1

v0.29.0

Compare Source

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

  {
    /**
     * Optionally supply scene activation data passed to Scene.onActivate
    */
    sceneActivationData?: TActivationData,
    /**
     * Optionally supply destination scene "in" transition, this will override any previously defined transition
    */
    destinationIn?: Transition,
    /**
     * Optionally supply source scene "out" transition, this will override any previously defined transition
    */
    sourceOut?: Transition,
    /**
     * Optionally supply a different loader for the destination scene, this will override any previously defined loader
    */
    loader?: DefaultLoader
  }

• ex.Physics static is marked as deprecated, configuring these setting will move to the ex.Engine({...}) constructor

  const engine = new ex.Engine({
    ...
    physics: {
      solver: ex.SolverStrategy.Realistic,
      gravity: ex.vec(0, 20),
      arcade: {
        contactSolveBias: ex.ContactSolveBias.VerticalFirst
      },
    }
  })

• Changed the Font default base align to Top this is more in line with user expectations. This does change the default rendering to the top left corner of the font instead of the bottom left.

• Remove confusing Graphics Layering from ex.GraphicsComponent, recommend we use the ex.GraphicsGroup to manage this behavior

  • Update ex.GraphicsGroup to be consistent and use offset instead of pos for graphics relative positioning

• ECS implementation has been updated to remove the "stringly" typed nature of components & systems

  • For average users of Excalibur folks shouldn't notice any difference
  • For folks leveraging the ECS, Systems/Components no longer have type parameters based on strings. The type itself is used to track changes.
  • class MySystem extends System<'ex.component'> becomes class MySystem extends System
  • class MyComponent extends Component<'ex.component'> becomes class MyComponent extends Component
  • ex.System.update(elapsedMs: number) is only passed an elapsed time

• Prevent people from inadvertently overriding update() in ex.Scene and ex.Actor. This method can still be overridden with the //@​ts-ignore pragma

• ex.SpriteSheet.getSprite(...) will now throw on invalid sprite coordinates, this is likely always an error and a warning is inappropriate. This also has the side benefit that you will always get a definite type out of the method.

Deprecated

Added

• Added new ex.Tilemap.getOnScreenTiles() method to help users access onscreen tiles for logic or other concerns.

• Added ex.FontSource resource type

  const fontSource = new ex.FontSource('/my-font.ttf', 'My Font')
  loader.addResource(fontSource)
  
  game.start(loader).then(() => {
    const font = fontSource.toFont() // returns ex.Font
  })

  Font options can be defined either at the source or at the toFont() call. If defined in both, toFont(options) will
  override the options in the FontSource.

  const fontSource = new ex.FontSource('/my-font.ttf', 'My Font', { 
    filtering: ex.ImageFiltering.Pixel,
    size: 16, // set a default size
  })
  const font = fontSource.toFont({
    // override just the size
    size: 20,
  })

• Added fullscreen after load feature! You can optionally provide a fullscreenContainer with a string id or an instance of the HTMLElement

  new ex.Loader({
    fullscreenAfterLoad: true,
    fullscreenContainer: document.getElementById('container')
  });

• Added new ex.Debug static for more convenient debug drawing where you might not have a graphics context accessible to you. This works by batching up all the debug draw requests and flushing them during the debug draw step.

  • ex.Debug.drawRay(ray: Ray, options?: { distance?: number, color?: Color })
  • ex.Debug.drawBounds(boundingBox: BoundingBox, options?: { color?: Color })
  • ex.Debug.drawCircle(center: Vector, radius: number, options?: ...)
  • ex.Debug.drawPolygon(points: Vector[], options?: { color?: Color })
  • ex.Debug.drawText(text: string, pos: Vector)
  • ex.Debug.drawLine(start: Vector, end: Vector, options?: LineGraphicsOptions)
  • ex.Debug.drawLines(points: Vector[], options?: LineGraphicsOptions)
  • drawPoint(point: Vector, options?: PointGraphicsOptions)

• Experimental ex.coroutine for running code that changes over time, useful for modeling complex animation code. Coroutines return a promise when they are complete. You can think of each yield as a frame.

  • The result of a yield is the current elapsed time
  • You can yield a number in milliseconds and it will wait that long before resuming
  • You can yield a promise and it will wait until it resolves before resuming

    const completePromise = coroutine(engine, function * () {
      let elapsed = 0;
      elapsed = yield 200; // frame 1 wait 200 ms before resuming
      elapsed = yield fetch('./some/data.json'); // frame 2
      elapsed = yield; // frame 3
    });

• Added additional options in rayCast options

  • ignoreCollisionGroupAll: boolean will ignore testing against anything with the CollisionGroup.All which is the default for all
  • filter: (hit: RayCastHit) => boolean will allow people to do arbitrary filtering on raycast results, this runs very last after all other collision group/collision mask decisions have been made

• Added additional data side and lastContact to onCollisionEnd and collisionend events

• Added configuration option to ex.PhysicsConfig to configure composite collider onCollisionStart/End behavior

• Added configuration option to ex.TileMap({ meshingLookBehind: Infinity }) which allows users to configure how far the TileMap looks behind for matching colliders (default is 10).

• Added Arcade Collision Solver bias to help mitigate seams in geometry that can cause problems for certain games.

  • ex.ContactSolveBias.None No bias, current default behavior collisions are solved in the default distance order
  • ex.ContactSolveBias.VerticalFirst Vertical collisions are solved first (useful for platformers with up/down gravity)
  • ex.ContactSolveBias.HorizontalFirst Horizontal collisions are solved first (useful for games with left/right predominant forces)

    const engine = new ex.Engine({
      ...
      physics: {
        solver: ex.SolverStrategy.Realistic,
        arcade: {
          contactSolveBias: ex.ContactSolveBias.VerticalFirst
        },
      }
    })

• Added Graphics opacity on the Actor constructor new ex.Actor({opacity: .5})

• Added Graphics pixel offset on the Actor constructor new ex.Actor({offset: ex.vec(-15, -15)})

• Added new new ex.Engine({uvPadding: .25}) option to allow users using texture atlases in their sprite sheets to configure this to avoid texture bleed. This can happen if you're sampling from images meant for pixel art

• Added new antialias settings for pixel art! This allows for smooth subpixel rendering of pixel art without shimmer/fat-pixel artifacts.

  • Use new ex.Engine({pixelArt: true}) to opt in to all the right defaults to make this work!

• Added new antialias configuration options to deeply configure how Excalibur does any antialiasing, or you can provide antialiasing: true/antialiasing: false to use the old defaults.

  • Example;

  const game = new ex.Engine({
     antialiasing: {
         pixelArtSampler: false,
         filtering: ex.ImageFiltering.Pixel,
         nativeContextAntialiasing: false,
         canvasImageRendering: 'pixelated'
     }
  })

• Added new lineHeight property on SpriteFont and Font to manually adjust the line height when rendering text.

• Added missing dual of ex.GraphicsComponent.add(), you can now ex.GraphicsComponent.remove(name);

• Added additional options to ex.Animation.fromSpriteSheetCoordinates() you can now pass any valid ex.GraphicOptions to influence the sprite per frame

  const anim = ex.Animation.fromSpriteSheetCoordinates({
    spriteSheet: ss,
    frameCoordinates: [
      {x: 0, y: 0, duration: 100, options: { flipHorizontal: true }},
      {x: 1, y: 0, duration: 100, options: { flipVertical: true }},
      {x: 2, y: 0, duration: 100},
      {x: 3, y: 0, duration: 100}
    ],
    strategy: ex.AnimationStrategy.Freeze
  });

• Added additional options to ex.SpriteSheet.getSprite(..., options). You can pass any valid ex.GraphicOptions to modify a copy of the sprite from the spritesheet.

  const sprite = ss.getSprite(0, 0, {
    flipHorizontal: true,
    flipVertical: true,
    width: 200,
    height: 201,
    opacity: .5,
    scale: ex.vec(2, 2),
    origin: ex.vec(0, 1),
    tint: ex.Color.Red,
    rotation: 4
  });

• New simplified way to query entities ex.World.query([MyComponentA, MyComponentB])

• New way to query for tags on entities ex.World.queryTags(['A', 'B'])

• Systems can be added as a constructor to a world, if they are the world will construct and pass a world instance to them

  world.add(MySystem);
  ...
  
  class MySystem extends System {
    query: Query;
    constructor(world: World) {
      super()
      this.query = world.query([MyComponent]);
    }
  
    update
  }

• Added RayCastHitas part of every raycast not just the physics world query!

  • Additionally added the ray distance and the contact normal for the surface

• Added the ability to log a message once to all log levels

  • debugOnce
  • infoOnce
  • warnOnce
  • errorOnce
  • fatalOnce

• Added ability to load additional images into ex.Materials!

  const noise = new ex.ImageSource('./noise.avif');
  loader.addResource(noise);
  
  var waterMaterial = game.graphicsContext.createMaterial({
    name: 'water',
    fragmentSource: waterFrag,
    color: ex.Color.fromRGB(55, 0, 200, .6),
    images: {
      u_noise: noise
    }
  });

• Scene Transition & Loader API, this gives you the ability to have first class support for individual scene resource loading and scene transitions.

  • Add or remove scenes by constructor

  • Add loaders by constructor

  • New ex.DefaultLoader type that allows for easier custom loader creation

  • New ex.Transition type for building custom transitions

  • New scene lifecycle to allow scene specific resource loading

    • onTransition(direction: "in" | "out") {...}
    • onPreLoad(loader: DefaultLoader) {...}

  • New async goToScene() API that allows overriding loaders/transitions between scenes

  • Scenes now can have async onInitialize and async onActivate!

  • New scenes director API that allows upfront definition of scenes/transitions/loaders

  • Example:
    Defining scenes upfront

    const game = new ex.Engine({
      scenes: {
        scene1: {
          scene: scene1,
          transitions: {
            out: new ex.FadeInOut({duration: 1000, direction: 'out', color: ex.Color.Black}),
            in: new ex.FadeInOut({duration: 1000, direction: 'in'})
          }
        },
        scene2: {
          scene: scene2,
          loader: ex.DefaultLoader, // Constructor only option!
          transitions: {
            out: new ex.FadeInOut({duration: 1000, direction: 'out'}),
            in: new ex.FadeInOut({duration: 1000, direction: 'in', color: ex.Color.Black })
          }
        },
      scene3: ex.Scene // Constructor only option!
      } 
    })
    
    // Specify the boot loader & first scene transition from loader
    game.start('scene1',
    {
      inTransition: new ex.FadeInOut({duration: 500, direction: 'in', color: ex.Color.ExcaliburBlue})
      loader: boot,
    });

  • Scene specific input API so that you can add input handlers that only fire when a scene is active!

    class SceneWithInput extends ex.Scene {
      onInitialize(engine: ex.Engine<any>): void {
        this.input.pointers.on('down', () => {
          console.log('pointer down from scene1');
        });
      }
    }
    class OtherSceneWithInput extends ex.Scene {
      onInitialize(engine: ex.Engine<any>): void {
        this.input.pointers.on('down', () => {
          console.log('pointer down from scene2');
        });
      }
    }

Fixed

• Performance improvement in ex.TileMap finding onscreen tiles is now BLAZINGLY FAST thanks to a suggestion from Kristen Maeyvn in the Discord.
  • TileMaps no longer need a quad tree, we can calculate the onscreen tiles with math by converting the screen into tilemap space 😎
• Fixed bug where ex.TileMap.getTileByPoint() did not take into account the rotation/scale of the tilemap.
• Fixes issue where mis-matched coordinate planes on parent/children caused bizarre issues. Now children are forced to inherit their parent's coordinate plane, it will always be the coordinate plane of the top most parent.
• Fixed issue with Log ScreenAppender utility where it was not positioned correctly, you can now deeply configure it!

  export interface ScreenAppenderOptions {
    engine: Engine;
    /**
     * Optionally set the width of the overlay canvas
    */
    width?: number;
    /**
     * Optionally set the height of the overlay canvas
    */
    height?: number;
    /**
     * Adjust the text offset from the left side of the screen
    */
    xPos?: number;
    /**
     * Provide a text color
    */
    color?: Color;
    /**
     * Optionally set the CSS zindex of the overlay canvas
    */
    zIndex?: number;
  }

• Fixed errant warning about resolution when using pixelRatio on low res games to upscale
• Fixes an issue where a collider that was part of a contact that was deleted did not fire a collision end event, this was unexpected
• Fixes an issue where you may want to have composite colliders behave as constituent colliders for the purposes of start/end collision events. A new property is added to physics config, the current behavior is the default which is 'together', this means the whole composite collider is treated as 1 collider for onCollisionStart/onCollisionEnd. Now you can configure a separate which will fire onCollisionStart/onCollisionEnd for every separate collider included in the composite (useful if you are building levels or things with gaps that you need to disambiguate). You can also configure this on a per composite level to mix and match CompositeCollider.compositeStrategy
• Fixed issue where particles would have an errant draw if using a particle sprite
• Fixed issue where a null/undefined graphics group member graphic would cause a crash, now logs a warning.
• Fixed issue where Actor built in components could not be extended because of the way the Actor based type was built.
  • Actors now use instance properties for built-ins instead of getters
  • With the ECS refactor you can now subtype built-in Components and .get(Builtin) will return the correct subtype.

  class MyBodyComponent extends ex.BodyComponent {}
  
  class MyActor extends ex.Actor {
      constructor() {
        super({})
        this.removeComponent(ex.BodyComponent);
        this.addComponent(new MyBodyComponent())
      }
  }

v0.28.7

Compare Source

Breaking Changes

Deprecated

Added

Fixed

• Fixed issue where pointer events did not work properly when using [[ScreenElement]]s
• Fixed issue where debug draw was not accurate when using *AndFill suffixed [[DisplayMode]]s

Updates

Changed

• Changed the default ex.PointerComponent.useGraphicsBounds = true, users expect this to just work by default.
• Changed a rough edge in the ex.Material API, if a material was created with a constructor it was lazily initialized. However this causes confusion because now the two ways of creating a material behave differently (the shader is not available immediately on the lazy version). Now ex.Material requires the GL graphics context to make sure it always works the same.
• Changed a rough edge in the ex.Material API, if a material was created with a constructor it was lazily initialized. However this causes confusion because now the two ways of creating a material behave differently (the shader is not available immediately on the lazy version). Now ex.Material requires the GL graphics context to make sure it always works the same.

v0.28.6

Compare Source

Breaking Changes

Deprecated

Added

• Added arbitrary data storage in isometric tiles, ex.IsometricTile.data this brings it into feature parity with normal ex.Tile.data
• New graphics events and hooks that allow you to hook into graphics drawing before or after any drawing transformations have been applied
  • Actor.graphics.onPreTransformDraw with the corresponding event .on('pretransformdraw')
  • Actor.graphics.onPostTransformDraw with the corresponding event .on('posttransformdraw')
• New property and methods overloads to ex.Animation
  • ex.Animation.currentFrameTimeLeft will return the current time in milliseconds left in the current
  • ex.Animation.goToFrame(frameNumber: number, duration?: number) now accepts an optional duration for the target frame
  • ex.Animation.speed can set the speed multiplier on an animation 1 = 1x speed, 2 = 2x speed.

Fixed

• Fixed issue where nesting ex.CompositeColliders inside one another would cause a crash on collision
• Fixed issue where ex.CompositeColliders did not respect collider offset
• Fixed issue where parenting a entity with fixed updates on would cause a drawing flicker, transform interpolation now is aware of changing parents so it interpolates drawing continuously to prevent any flickering
• ex.Animation.reset() did not properly reset all internal state

Updates

Changed

v0.28.5

Compare Source

Breaking Changes

Deprecated

Added

• Added collision lifecycle convenience methods to Actor, you can now override the following events

  class MyActor extends ex.Actor {
    constructor(args: ex.ActorArgs) {
      super(args);
    }
    onPreCollisionResolve(self: ex.Collider, other: ex.Collider, side: ex.Side, contact: ex.CollisionContact): void {
      
    }
    onPostCollisionResolve(self: ex.Collider, other: ex.Collider, side: ex.Side, contact: ex.CollisionContact): void {
      
    }
    onCollisionStart(self: ex.Collider, other: ex.Collider, side: ex.Side, contact: ex.CollisionContact): void {
      
    }
    onCollisionEnd(self: ex.Collider, other: ex.Collider): void {
      
    }
  }

• Added Scene specific background color
• Added ability to apply draw offset to ex.IsometricMap and ex.Tilemap
• Added visibility and opacity to ex.IsometricMap
• Added base elevation for ex.IsometricMap so multiple maps can sort correctly
• Added method to suppress convex polygon warning for library code usage
• Added more configuration options to debug draw flags, including isometric map controls
• Added actionstart and actioncomplete events to the Actor that are fired when an action starts and completes

Fixed

• Fixed issue where the Camera wasn't interpolated during fixed update, which is very noticeable when using camera locked strategies
• Fixed issue where IsometricMap would debug draw collision geometry on non-solid tiles
• Fixed issue where CompositeCollider offset was undefined if not set
• Fixed Actor so it receives predraw/postdraw events per the advertised strongly typed events
• Fixed infinite loop 💣 when certain degenerate polygons were attempted to be triangulated!
• Fixed incorrect type on ex.Tilemap.getTileByPoint()
• Fixed TS type on GraphicsComponent and allow .material to be null to unset, current workaround is using .material = null as any

Updates

Changed

• All debug geometry settings are controlled from debug.collider now
• Removed dunder prefixed parameters from overrideable methods
• Tweaked debug draw to be less noisy by default
• Removed dependency on ex.IsometricMap in the ex.IsometricEntityComponent, this allows for greater flexibility when using the component when a map may not be known or constructed.

v0.28.4

Compare Source

Breaking Changes

Deprecated

Added

• Ability to configure TileMap debug drawing with the ex.Engine.debug.tilemap property.
• Materials have a new convenience method for updating uniforms

  game.input.pointers.primary.on('move', evt => {
    heartActor.pos = evt.worldPos;
    swirlMaterial.update(shader => {
      shader.trySetUniformFloatVector('iMouse', evt.worldPos);
    });
  });

Fixed

• Fixed issue where TileMap solid tiles tile packing algorithm would incorrectly merge tiles in certain situations.
• Sprite tint was not respected when supplied in the constructor, this has been fixed!
• Adjusted the FontCache font timeout to 400 ms and makes it configurable as a static FontCache.FONT_TIMEOUT. This is to help prevent a downward spiral on mobile devices that might take a long while to render a few starting frames causing the cache to repeatedly clear and never recover.

Updates

• Materials can now reference a new uniform for the screen texture and a screen uv attribute in their fragment shaders

  • u_screen_texture - This is the texture of the screen right before the material draw call
  • a_screenuv - The vertex attribute corresponding to the screen uv relative to the current graphic
  • v_screenuv - The fragment varying corresponding to the screen uv relative to the current graphic

• Materials can now reference the current time in their shaders

  • u_time_ms - This is the ms since page navigation (performance.now() under the hood)

Changed

• TileMap debug draw is now less verbose by default to save draw cycles when toggling to debug

v0.28.3

Compare Source

Breaking Changes

Deprecated

Added

• Added new feature to collision group raycasting, directly provide a collisionMask that you want to search for.

const playerGroup = ex.CollisionGroupManager.create('playerGroup');
const notPlayersMask = ~playersGroup.category;
const hits = engine.currentScene.physics.rayCast(
  new ex.Ray(player.pos, playerDir),
  {
    maxDistance: playerSightDistance,
    // Search for all categories that match the mask
    collisionMask: notPlayers,
    searchAllColliders: false
  });

Fixed

• Fixed issue where rendering multiple materials at once would crash the renderer
• Fixed issue where raycasting with more complex collision groups was not working as expected

Updates

Changed

v0.28.2

Compare Source

Breaking Changes

Deprecated

Added

• Added ex.Engine.version to report the current excalibur version build string
• Added new ex.Screen.events
  • screen.events.on('resize', (evt) => ) Will emit when the screen is resized
  • screen.events.on('fullscreen', (evt) => ) Will emit when the screen is changed into browser fullscreen mode
  • screen.events.on('pixelratio', (evt) => ) Will emit when the screen's pixel ratio changes (moving from a hidpi screen to a non, or vice versa)

Fixed

• Fixed issue where removing handlers by function reference only removed the first registered one
• Fixed issue where play button was hidden when going fullscreen mode
• Fixed issue where screen resizing caused artifacts on the loading screen
• Fixed bug in useCanvas2DFallback() where antialiasing settings could be lost
• Fixed bug in useCanvas2DFallback() where opacity was not respected in `save
• Fixed typo in trigger event signature entertrigger should have been enter
• Fixed typo in trigger event signature exittrigger should have been exit
• Fixed typo in animation event signature ended should have been end
• Fixed issue where some excalibur clear() implementations modified the collection they were iterating over
• Fixed async issue where sound could not be stopped if stop()/start() were called in rapid succession
• Fixed issue with input mapper where keyboard.wasPressed(...) did not fire
• Fixed issue issue where TileMaps would not properly draw Tiles when setup in screen space coordinates
• Fixed issue where the ex.Line graphics bounds were incorrect causing erroneous offscreen culling
• Fixed event type signature on ex.Engine.input.pointers.primary.on('wheel', ...) for wheel events

Updates

• Improved performance in TileMaps when drawing tiles using QuadTree data structure

Changed

• Changed the canvas 2d fallback default, no longer is enabled by default. Developers must opt in.
• Allow entity names to be set after construction! Entities will now default to a name "Entity#1234" followed by an id.

v0.28.1

Compare Source

v0.28.0

Compare Source

Breaking Changes

• Removed ex.Class base class type, this was a common base class for many excalibur types that provided old on/off event functionality. This functionality has been preserved on the types that had it before using ex.EventEmitter

Deprecated

• The ex.Input.* import site is deprecated, will be removed in v0.29.0. All the imports are still available on ex. now
• [[ex.Input.Gamepad]] isButtonPressed has been renamed to isButtonHeld
• ex.EventDispatcher is marked deprecated, will eventually be removed in v0.29.0

Added

• Added new ex.InputMapper for mapping multiple input sources into actions! This can be useful for providing accessibility into your games and allowing users to map inputs to different game commands.

   const moveRight = (amount: number) => { actor.vel.x = 100 * amount }
   const moveLeft = (amount: number) => { actor.vel.x = -100 * amount }
   const moveUp = (amount: number) => { actor.vel.y = -100 * amount }
   const moveDown = (amount: number) => { actor.vel.y = 100 * amount }
   engine.inputMapper.on(({keyboard}) => keyboard.isHeld(ex.Keys.ArrowRight) ? 1 : 0, moveRight);
   engine.inputMapper.on(({gamepads}) => gamepads.at(0).isButtonPressed(ex.Buttons.DpadRight) ? 1 : 0, moveRight);
   engine.inputMapper.on(({gamepads}) => gamepads.at(0).getAxes(ex.Axes.LeftStickX) > 0 ? gamepads.at(0).getAxes(ex.Axes.LeftStickX) : 0, moveRight);

• Added strongly typed events with ex.EventEmitter<TEventMap>

• Added new convenience properties for flipping all the graphics on an Actor

  • ex.Actor.graphics.flipHorizontal - Flips all the graphics horizontally
  • ex.Actor.graphics.flipVertical - Flips all the graphics vertically

• Added new ex.Scene.transfer(actor) method for transferring actors between scenes, useful if you want to only have an actor in 1 scene at a time.

• Added new ex.Material to add custom shaders per ex.Actor!

  • This feature cant be applied using the ex.Actor.graphics.material = material property or by setting the material property on the ex.ExcaliburGraphicsContext.material = material with .save()/.restore()
  • This feature opt out of batch rendering and issues a separate draw call
  • A custom vertex shader can be provided, otherwise a default will be provided
  • A number of default uniforms are available to shaders
    • Pre-built varyings:
      • in vec2 v_uv - UV coordinate
    • Pre-built uniforms:
      • uniform sampler2D u_graphic - The current graphic displayed by the GraphicsComponent
      • uniform vec2 u_resolution - The current resolution of the screen
      • uniform vec2 u_size; - The current size of the graphic
      • uniform vec4 u_color - The current color of the material
      • uniform float u_opacity - The current opacity of the graphics context

  const material = new ex.Material({
    name: 'test',
    color: ex.Color.Red,
    fragmentSource: `#version 300 es
    precision mediump float;
    // UV coord
    in vec2 v_uv;
    uniform sampler2D u_graphic;
    uniform vec4 u_color;
    uniform float u_opacity;
    out vec4 fragColor;
    void main() {
      vec4 color = u_color;
      color = texture(u_graphic, v_uv);
      color.rgb = color.rgb * u_opacity;
      color.a = color.a * u_opacity;
      fragColor = color * u_color;
    }`
  });

• Added updates to ex.PostProcessor

  • New optional ex.PostProcessor.onUpdate hook for updating custom uniforms
  • Added default uniforms that are automatically added
    • uniform float u_time_ms - total playback time in milliseconds
    • uniform float u_elapsed_ms - the elapsed time from the last frame in milliseconds
    • uniform vec2 u_resolution - the resolution of the canvas (in pixels)

• Added new helper called ex.Animation.fromSpriteSheetCoordinates to help build animations more tersely from SpriteSheets

   const spriteSheet = SpriteSheet.fromImageSource({...});
      const anim = Animation.fromSpriteSheetCoordinates({
    spriteSheet,
    frameCoordinates: [
      {x: 0, y: 5, duration: 100},
      {x: 1, y: 5, duration: 200},
      {x: 2, y: 5, duration: 100},
      {x: 3, y: 5, duration: 500}
    ],
    strategy: AnimationStrategy.PingPong
   });

• Added new FrameEvent to ex.Animation which includes the frame index of the current frame!

    const anim = new Animation();
  
    // TS autocompletes the handler
    anim.on('frame', (frame: FrameEvent) => {
      // Do stuff on frame
    });

• Added new typed ex.EventEmitter which will eventually replace the old ex.EventDispatcher, this gives users a way of strongly typing the possible events that can be emitted using a type map. This is loosely typed you can still emit any event you want, you only get type completion suggestions for the type map.

  export type AnimationEvents = {
    frame: FrameEvent;
    loop: Animation;
    ended: Animation;
  };
  
  export class Animation {
    public events = new EventEmitter<AnimationEvents>();
    ...
  }
  
  const anim = new Animation();
  
  // TS autocompletes the handler
  anim.on('frame', (frame: FrameEvent) => {
    // Do stuff on frame
  });

• Added ability to perform arbitrary ray casts into ex.Scene, the ex.PhysicsWorld can be passed a variety of options to influence the types of ray cast hits that
  are returned

    const engine = new ex.Engine({...});
    const enemyGroup = ex.CollisionGroupManager.create('enemy');
    const ray = new ex.Ray(ex.vec(0, 0), ex.Vector.Right);
    const hits = engine.currentScene.physics.rayCast(ray, {
      /**
       * Optionally specify to search for all colliders that intersect the ray cast, not just the first which is the default
       */
      searchAllColliders: true,
      /**
       * Optionally specify the maximum distance in pixels to ray cast, default is Infinity
       */
      maxDistance: 100,
      /**
       * Optionally specify a collision group to consider in the ray cast, default is All
       */
      collisionGroup: enemyGroup
    });

• Added word-wrap support for ex.Text using the optional parameter maxWidth

• Added the emitted particle transform style as part of ex.ParticleEmitter({particleTransform: ex.ParticleTransform.Global}), [[ParticleTransform.Global]] is the default and emits particles as if they were world space objects, useful for most effects. If set to [[ParticleTransform.Local]] particles are children of the emitter and move relative to the emitter as they would in a parent/child actor relationship.

• Added wasButtonReleased and wasButtonPressed methods to [[ex.Input.Gamepad]]

• Added clone() method to ex.SpriteSheet

Fixed

• Fixed issue with ex.TileMap collider consolidation where custom colliders would prevent normal solid tile colliders from being included.
• Fixed memory leak in the internal ex.EntityManager, it did not properly clear internal state when removing entities
• Fixed issue where scaling a ex.TileMap didn't properly offscreen cull due to the bounds not scaling properly.
• Fixed issue where ex.Text.flipHorizontal or ex.Text.flipVertical would not work
• Fixed issue where overriding existing components did not work properly because of deferred component removal
• Fixed issue where ex.ScreenElement pointer events were not working by default.
• Fixed issue where setting lineWidth on ex.Circle was not accounted for in the bitmap
• Fixed issue in macos where the meta key would prevent keyup's from firing correctly
• Fixed issue when excalibur was hosted in a x-origin iframe, the engine will grab window focus by default if in an iframe. This can be suppressed with new ex.Engine({grabWindowFocus: false})
• Fixed issue where ex.Camera.rotation = ... did not work to rotate the camera, also addressed offscreen culling issues that were revealed by this fix.
• Fixed issue where the ex.ScreenElement anchor was not being accounted for properly when passed as a constructor parameter.
• Fixed issue where you could not use multiple instances of Excalibur on the same page, you can now have as many Excalibur's as you want (up to the webgl context limit).
• Fixed issue where ex.ScreenElement would log a warning when created without a height or width
• Fixed issue where ex.Sound would get confused parsing and playing sound files with a querystring in their path
• Fixed issue where ex.ColliderComponent was not deeply cloning the stored ex.Collider causing them to be shared across clones.
• Fixed issue where ex.GraphicsComponent was not deeploy cloning the
  stored ex.Graphics causing them to be shared across clones.
• Fixed issue where Actor.clone() and Entity.clone() crashed.
• Fixed issue where zero mtv collisions cause erroneous precollision events to be fired in the ArcadeSolver and RealisticSolver
• Fixed issue where calling .kill() on a child entity would not remove it from the parent Entity
• Fixed issue where calling .removeAllChildren() would not remove all the children from the parent Entity
• Fixed issue where world origin was inconsistent when the using ex.DisplayMode.FitScreenAndFill when the screen was resized.
• Fixed issue where context opacity was not respected when set in a preDraw
• Fixed issue where ex.Sound.loop was not working, and switching tab visibility would cause odd behavior with looping ex.Sound
• Fixed issue where adding a ex.ParticleEmitter as a child did not position particles according to the parent
• Fixed issue where screenshots from ex.Engine.screenshot() did not match the smoothing set on the engine.
• Fixed incorrect event type returned when ex.Actor.on('postupdate', (event) => {...}).
• Fixed issue where using numerous ex.Text instances would cause Excalibur to crash webgl by implementing a global font cache.
• Fixed issue where child entities did not inherit the scene from their parent
• Fixed issue where ex.Font would become corrupted when re-used by multiple ex.Text instances
• Fixed engine.on('visible') event not firing
• Fixed EventDispatcher.emit converting falsy values to ex.GameEvent. It will only convert undefined or null values now.

Updates

Changed

• Excalibur will now use ex.EventEmitter to broadcast events, Excalibur types that have events support will also have an .events member.
• Excalibur resources by default no longer add cache busting query string to resources. All built in resources now expose a bustCache property to allow setting this before loading, for example ex.Sound.bustCache.

v0.27.0

Compare Source

Breaking Changes

• ex.Engine.snapToPixel now defaults to false, it was unexpected to have pixel snapping on by default it has now been switched.
• The ex.Physics.useRealisticPhysics() physics solver has been updated to fix a bug in bounciness to be more physically accurate, this does change how physics behaves. Setting ex.Body.bounciness = 0 will simulate the old behavior.
• ex.TransformComponent.posChanged$ has been removed, it incurs a steep performance cost
• ex.EventDispatcher meta events 'subscribe' and 'unsubscribe' were unused and undocumented and have been removed
• ex.TileMap tlies are now drawn from the lower left by default to match with ex.IsometricMap and Tiled, but can be configured with renderFromTopOfGraphic to restore the previous behavior.
• Scene onActivate and onDeactivate methods have been changed to receive a single parameter, an object containing the previousScene, nextScene, and optional data passed in from goToScene()

Deprecated

Added

• Added new configurable ex.TileMap option for rendering from the bottom or the top of the graphic, this matches with ex.IsometricMap and how Tiled renders renderFromTopOfGraphic, by default false and renders from the bottom.

  const tileMap = new ex.TileMap({
    renderFromTopOfGraphic: false
  })

• Added new ex.Future type which is a convenient way of wrapping a native browser promise and resolving/rejecting later

  const future = new ex.Future();
  const promise = future.promise; // returns promise
  promise.then(() => {
    console.log('Resolved!');
  });
  future.resolve(); // resolved promise

• Added new ex.Semaphore type to limit the number of concurrent cans in a section of code, this is used internally to work around a chrome browser limitation, but can be useful for throttling network calls or even async game events.

  const semaphore = new ex.Semaphore(10); // Only allow 10 concurrent between enter() and exit()
  ...
  
  await semaphore.enter();
  await methodToBeLimited();
  semaphore.exit();

• Added new ex.WatchVector type that can observe changes to x/y more efficiently than ex.watch()

• Added performance improvements

  • ex.Vector.distance improvement
  • ex.BoundingBox.transform improvement

• Added ability to clone ex.Vector.clone(destVector) into a destination vector

• Added new ex.Transform type that is a light weight container for transformation data. This logic has been extracted from the ex.TransformComponent, this makes it easy to pass ex.Transforms around. Additionally the extracted ex.Transform logic has been refactored for performance.

• Added new ex.AffineMatrix that is meant for 2D affine transformations, it uses less memory and performs less calculations than the ex.Matrix which uses a 4x4 Float32 matrix.

• Added new fixed update step to Excalibur! This allows developers to configure a fixed FPS for the update loop. One advantage of setting a fix update is that you will have a more consistent and predictable physics simulation. Excalibur graphics will be interpolated automatically to avoid any jitter in the fixed update.

  • If the fixed update FPS is greater than the display FPS, excalibur will run multiple updates in a row (at the configured update elapsed) to catch up, for example there could be X updates and 1 draw each clock step.
  • If the fixed update FPS is less than the display FPS, excalibur will skip updates until it meets the desired FPS, for example there could be no update for 1 draw each clock step.

  const game = new ex.Engine({
    fixedUpdateFps: 20 // 20 fps fixed update, or a fixed update delta of 50 milliseconds
  });
  // turn off interpolation on a per actor basis
  const actor = new ex.Actor({...});
  actor.body.enableFixedUpdateInterpolate = false;
  game.add(game);

• Allowed setting playback ex.Sound.duration which will limit the amount of time that a clip plays from the current playback position.

• Added a new lightweight ex.StateMachine type for building finite state machines

  const machine = ex.StateMachine.create({
    start: 'STOPPED',
    states: {
      PLAYING: {
        onEnter: () => {
          console.log("playing");
        },
        transitions: ['STOPPED', 'PAUSED']
      },
      STOPPED: {
        onEnter: () => {
          console.log("stopped");
        },
        transitions: ['PLAYING', 'SEEK']
      },
      SEEK: {
        transitions: ['*']
      },
      PAUSED: {
        onEnter: () => {
          console.log("paused")
        },
        transitions: ['PLAYING', 'STOPPED']
      }
    }
  });

• Added ex.Sound.seek(positionInSeconds) which will allow you to see to a place in the sound, this will implicitly pause the sound

• Added ex.Sound.getTotalPlaybackDuration() which will return the total time in the sound in seconds.

• Allow tinting of ex.Sprite's by setting a new tint property, renderers must support the tint property in order to function.

  const imageSource = new ex.ImageSource('./path/to/image.png');
  await imageSource.load();
  const sprite = imageSource.toSprite();
  sprite.tint = ex.Color.Red;

• Added ex.Sound.getPlaybackPosition() which returns the current playback position in seconds of the currently playing sound.

• Added ex.Sound.playbackRate which allows developers to get/set the current rate of playback. 1.0 is the default playback rate, 2.0 is twice the speed, and 0.5 is half speed.

• Added missing ex.EaseBy action type, uses ex.EasingFunctions to move relative from the current entity position.

• Added 2 new Action types to enable running parallel actions. ex.ActionSequence which allows developers to specify a sequence of actions to run in order, and ex.ParallelActions to run multiple actions at the same time.

  const actor = new ex.Actor();
  const parallel = new ex.ParallelActions([
    new ex.ActionSequence(actor, ctx => ctx.moveTo(ex.vec(100, 0), 100)),
    new ex.ActionSequence(actor, ctx => ctx.rotateTo(Math.PI/2, Math.PI/2))
  ]);
  actor.actions.runAction(parallel);
  // actor will now move to (100, 100) and rotate to Math.PI/2 at the same time!!

• Add target element id to ex.Screen.goFullScreen('some-element-id') to influence the fullscreen element in the fullscreen browser API.

• Added optional data parameter to goToScene, which gets passed to the target scene's onActivate method.

  class SceneA extends ex.Scene {
    /* ... */
  
    onActivate(context: ex.SceneActivationContext<{ foo: string }>) {
      console.log(context.data.foo); // bar
    }
  }
  
  engine.goToScene('sceneA', { foo: 'bar' })

  • Added the ability to select variable duration into Timer constructor.

  const random = new ex.Random(1337);
  const timer = new ex.Timer({
    random,
    interval: 500,
    randomRange: [0, 500]
  })

Fixed

• Fixed issue with ex.Canvas and ex.Raster graphics that forced their dimensions to the next highest power of two.

• Fixed issue with ex.Engine.snapToPixel where positions very close to pixel boundary created jarring 1 pixel oscillations.

• Fixed bug where a deferred goToScene would preserve the incorrect scene so engine.add(someActor) would place actors in the wrong scene after transitioning to another.

• Fixed usability issue and log warning if the ex.ImageSource is not loaded and a draw was attempted.

• Fixed bug in ex.Physics.useRealisticPhysics() solver where ex.Body.bounciness was not being respected in the simulation

• Fixed bug in ex.Physics.useRealisticPhysics() solver where ex.Body.limitDegreeOfFreedom was not working all the time.

• Fixed bug in Clock.schedule where callbacks would not fire at the correct time, this was because it was scheduling using browser time and not the clock's internal time.

• Fixed issue in Chromium browsers where Excalibur crashes if more than 256 Image.decode() calls are happening in the same frame.

• Fixed issue where ex.EdgeCollider were not working properly in ex.CompositeCollider for ex.TileMap's

• Fixed issue where ex.BoundingBox overlap return false due to floating point rounding error causing multiple collisions to be evaluated sometimes

• Fixed issue with ex.EventDispatcher where removing a handler that didn't already exist would remove another handler by mistake

• Fixed issue with ex.EventDispatcher where concurrent modifications of the handler list where handlers would or would not fire correctly and throw

• Tweak to the ex.ArcadeSolver to produce more stable results by adjusting by an infinitesimal epsilon

  • Contacts with overlap smaller than the epsilon are ignored
  • Colliders with bounds that overlap smaller than the epsilon are ignored

• Fixed issue with ex.ArcadeSolver based collisions where colliders were catching on seams when sliding along a floor of multiple colliders. This was by sorting contacts by distance between bodies.
  

• Fixed issue with ex.ArcadeSolver where corner contacts would zero out velocity even if the bodies were already moving away from the contact "divergent contacts".
  

• Fixed issue where ex.Sound wasn't being paused when the browser window lost focus

Updates

• Updated the collision system to improve performance
  • Cache computed values where possible
  • Avoid calculating transformations until absolutely necessary
  • Avoid calling methods in tight loops

Changed

• ex.Engine.configurePerformanceCanvas2DFallback no longer requires threshold or showPlayerMessage
• ex.Engine.snapToPixel now defaults to false
• Most places where ex.Matrix was used have been switched to ex.AffineMatrix
• Most places where ex.TransformComponent was used have been switched to ex.Transform

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.