Excalibur 0.25.0

See migration guide for v0.24.5 → v0.25.0

We've had tons of community contributions since the last release. Heartfelt thanks to everyone in the discussions, issues and PRs!

Contributors:

• @jedeen
• @kamranayub
• @alanag13
• @DaVince
• @DrSensor
• @djcsdy
• @catrielmuller
• @AndrewCraswell
• @miqh
• @rledford
• @SirPedr
• @helloausrine
• @dpayne5
• @herobank110
• @didii
• @Charkui
• @muirch
• @rumansaleem
• @mogoh
• @kala2
• @MrBartusek
• @josh
• @LokiMidgard
• @romaintailhurat
• @EduardoHidalgo
• @jaredegan

Breaking Changes

• Actor Drawing: ex.Actor.addDrawing, ex.Actor.setDrawing, onPostDraw(), and onPreDraw() are no longer on by default and will be removed in v0.26.0, they are available behind a flag ex.Flags.useLegacyDrawing()

  • For custom drawing use the ex.Canvas

• ex.Actor.rx has been renamed to ex.Actor.angularVelocity

• Rename ex.Edge to ex.EdgeCollider and ex.ConvexPolygon to ex.PolygonCollider to avoid confusion and maintian consistency

• ex.Label constructor now only takes the option bag constructor and the font properties have been replaced with ex.Font

  const label = new ex.Label({
    text: 'My Text',
    x: 100,
    y: 100,
    font: new ex.Font({
      family: 'Consolas',
      size: 32
    })
  });
  

• ex.Physics.debug properties for Debug drawing are now moved to engine.debug.physics, engine.debug.collider, and engine.debug.body.

  • Old debugDraw(ctx: CanvasRenderingContext2D) methods are removed.

• Collision Pair's are now between Collider's and not bodies

• PerlinNoise has been removed from the core repo will now be offered as a plugin

• Legacy drawing implementations are moved behind ex.LegacyDrawing new Graphics implemenations of Sprite, SpriteSheet, Animation are now the default import.

  • To use any of the ex.LegacyDrawing.* implementations you must opt-in with the ex.Flags.useLegacyDrawing() note: new graphics do not work in this egacy mode

• Renames CollisionResolutionStrategy.Box collision resolution strategy to Arcade

• Renames CollisionResolutionStrategy.RigidBody collision resolution strategy to Realistic

• Collider is now a first class type and encapsulates what Shape used to be. Collider is no longer a member of the Body

• CollisionType and CollisionGroup are now a member of the Body component, the reasoning is they define how the simulated physics body will behave in simulation.

• Timer's no longer automatically start when added to a Scene, this Timer.start() must be called. (#1865)

• Timer.complete is now read-only to prevent odd bugs, use reset(), stop(), and start() to manipulate timers.

• Actor.actions.repeat() and Actor.actions.repeatForever() now require a handler that specifies the actions to repeat. This is more clear and helps prevent bugs like #1891

  const actor = new ex.Actor();
  
  actor.actions
    // Move up in a zig-zag by repeating 5 times
    .repeat((ctx) => {
      ctx.moveBy(10, 0, 10);
      ctx.moveBy(0, 10, 10);
    }, 5)
    .callMethod(() => {
      console.log('Done repeating!');
    });
  

• Removes Entity.components as a way to access, add, and remove components

• ex.Camera.z has been renamed to property ex.Camera.zoom which is the zoom factor

• ex.Camera.zoom(...) has been renamed to function ex.Camera.zoomOverTime()

• TileMap no longer needs registered SpriteSheets, Sprite's can be added directly to Cell's with addGraphic

  • The confusing TileSprite type is removed (Related to TileMap plugin updates https://github.com/excaliburjs/excalibur-tiled/issues/4, https://github.com/excaliburjs/excalibur-tiled/issues/23, https://github.com/excaliburjs/excalibur-tiled/issues/108)

• Directly changing debug drawing by engine.isDebug = value has been replaced by engine.showDebug(value) and engine.toggleDebug() (#1655)

• UIActor Class instances need to be replaced to ScreenElement (This Class it's marked as Obsolete) (#1656)

• Switch to browser based promise, the Excalibur implementation ex.Promise is marked deprecated (#994)

• DisplayMode's have changed (#1733) & (#1928):

  • DisplayMode.FitContainer fits the screen to the available width/height in the canvas parent element, while maintaining aspect ratio and resolution
  • DisplayMode.FillContainer update the resolution and viewport dyanmically to fill the available space in the canvas parent element, DOES NOT preserve aspectRatio
  • DisplayMode.FitScreen fits the screen to the available browser window space, while maintaining aspect ratio and resolution
  • DisplayMode.FillScreen now does what DisplayMode.FullScreen used to do, the resolution and viewport dynamically adjust to fill the available space in the window, DOES NOT preserve aspectRatio (#1733)
  • DisplayMode.FullScreen is now removed, use Screen.goFullScreen().

• SpriteSheet now is immutable after creation to reduce chance of bugs if you modified a public field. The following properties are read-only: columns, rows, spWidth, spHeight, image, sprites and spacing.

• Engine.pointerScope now defaults to a more expected ex.Input.PointerScope.Canvas instead of ex.Input.PointerScope.Document which can cause frustrating bugs if building an HTML app with Excalibur

Added

• New property center to Screen to encapsulate screen center coordinates calculation considering zoom and device pixel ratio
• New ex.Shape.Capsule(width, height) helper for defining capsule colliders, these are useful for ramps or jagged floor colliders.
• New collision group constructor argument added to Actornew Actor({collisionGroup: collisionGroup})
• SpriteSheet.getSprite(x, y) can retrieve a sprite from the SpriteSheet by x and y coordinate. For example, getSprite(0, 0) returns the top left sprite in the sheet.
  • SpriteSheet's now have dimensionality with rows and columns optionally specified, if not there is always 1 row, and sprites.length columns
• new Actor({radius: 10}) can now take a radius parameter to help create circular actors
• The ExcaliburGraphicsContext now supports drawing debug text
• Entity may also now optionally have a name, this is useful for finding entities by name or when displaying in debug mode.
• New DebugSystem ECS system will show debug drawing output for things toggled on/off in the engine.debug section, this allows for a less cluttered debug experience.
  • Each debug section now has a configurable color.
• Turn on WebGL support with ex.Flags.useWebGL()
• Added new helpers to CollisionGroup to define groups that collide with specified groups CollisionGroup.collidesWith([groupA, groupB])
  • Combine groups with const groupAandB = CollisionGroup.combine([groupA, groupB])
  • Invert a group instance const everthingButGroupA = groupA.invert()
• Improved Collision Simulation
  • New ECS based CollisionSystem and MotionSystem
  • Rigid body's can now sleep for improved performance
  • Multiple contacts now supported which improves stability
  • Iterative solver for improved stability
• Added ColliderComponent to hold individual Collider implementations like Circle, Box, or CompositeCollider
  • Actor.collider.get() will get the current collider
  • Actor.collider.set(someCollider) allows you to set a specific collider
• New CompositeCollider type to combine multiple colliders together into one for an entity
  • Composite colliders flatten into their individual colliders in the collision system
  • Composite collider keeps it's internal colliders in a DynamicTree for fast .collide checks
• New TransformComponent to encapsulate Entity transform, that is to say position, rotation, and scale
• New MotionComponent to encapsulate Entity transform values changing over time like velocity and acceleration
• Added multi-line support to Text graphics (#1866)
• Added TileMap arbitrary graphics support with .addGraphic() (#1862)
• Added TileMap row and column accessors getRows() and getColumns() (#1859)
• Added the ability to store arbitrary data in TileMap cells with Cell.data.set('key', 'value') and Cell.data.get('key') (#1861)
• Actions moveTo(), moveBy(), easeTo(), scaleTo(), and scaleBy() now have vector overloads
• Animation.fromSpriteSheet will now log a warning if an index into the SpriteSheet is invalid (#1856)
• new ImageSource() will now log a warning if an image type isn't fully supported. (#1855)
• Timer.start() to explicitly start timers, and Timer.stop() to stop timers and "rewind" them.
• Timer.timeToNextAction will return the milliseconds until the next action callback
• Timer.timeElapsedTowardNextAction will return the milliseconds counted towards the next action callback
• BoundingBox now has a method for detecting zero dimensions in width or height hasZeroDimensions()
• BoundingBox's can now by transform'd by a Matrix
• Added new Entity(components: Component[]) constructor overload to create entities with components quickly.
• Added Entity.get(type: ComponentType) to get strongly typed components if they exist on the entity.
• Added Entity.has(type: ComponentType) overload to check if an entity has a component of that type.
• Added Entity.hasTag(tag: string), Entity.addTag(tag: string), and Entity.removeTag(tag: string, force: boolean).
  • Tag offscreen is now added to entities that are offscreen
• Added Entity.componentAdded$ and Entity.componentRemoved$ for observing component changes on an entity.
• For child/parent entities:
  • Added Entity.addChild(entity: Entity), Entity.removeChild(entity: Entity), Entity.removeAllChildren() for managing child entities
  • Added Entity.addTemplate(templateEntity: Entity) for adding template entities or "prefab".
  • Added Entity.parent readonly accessor to the parent (if exists), and Entity.unparent() to unparent an entity.
  • Added Entity.getAncestors() is a sorted list of parents starting with the topmost parent.
  • Added Entity.children readonly accessor to the list of children.
• Add the ability to press enter to start the game after loaded
• Add Excalibur Feature Flag implementation for releasing experimental or preview features (#1673)
• Color now can parse RGB/A string using Color.fromRGBString('rgb(255, 255, 255)') or Color.fromRGBString('rgb(255, 255, 255, 1)')
• DisplayMode.FitScreen will now scale the game to fit the available space, preserving the aspectRatio. (#1733)
• SpriteSheet.spacing now accepts a structure { top: number, left: number, margin: number } for custom spacing dimensions (#1788)
• SpriteSheet.ctor now has an overload that accepts spacing for consistency although the object constructor is recommended (#1788)
• Add SpriteSheet.getSpacingDimensions() method to retrieve calculated spacing dimensions (#1788)
• Add KeyEvent.value?: string which is the key value (or "typed" value) that the browser detected. For example, holding Shift and pressing 9 will have a value of ( which is the typed character.
• Add KeyEvent.originalEvent?: KeyboardEvent which exposes the raw keyboard event handled from the browser.

Changed

• Gif now supports new graphics component
• Algebra.ts refactored into separate files in Math/
• Engine/Scene refactored to make use of the new ECS world which simplifies their logic
• TileMap now uses the built in Collider component instead of custom collision code.
• Updates the Excalibur ECS implementation for ease of use and Excalibur draw system integration
  • Adds "ex." namespace to built in component types like "ex.transform"
  • Adds ex.World to encapsulate all things ECS
  • Adds ex.CanvasDrawSystem to handle all HTML Canvas 2D drawing via ECS
  • Updates ex.Actor to use new ex.TransformComponent and ex.CanvasDrawComponent

Deprecated

• Timer.unpause() has be deprecated in favor of Timer.resume() (#1864)
• Removed UIActor Stub in favor of ScreenElement (#1656)
• ex.SortedList as deprecated
• ex.Promise is marked deprecated (#994)
• ex.DisplayMode.Position CSS can accomplish this task better than Excalibur (#1733)

Removed

Fixed

• Fixed allow ex.ColliderComponent to not have a collider
• Fixed issue where collision events were not being forwarded from individual colliders in a ex.CompositeCollider
• Fixed issue where ex.CompositeCollider's individual colliders were erroneously generating pairs
• Fixed issue where GraphicsOptions width/height could not be used to define a ex.Sprite with equivalent sourceView and destSize (#1863)
• Fixed issue where ex.Scene.onActivate/onDeactivate were called with the wrong arguments (#1850)
• Fixed issue where no width/height argmunents to engine throws an error
• Fixed issue where zero dimension image draws on the ExcaliburGraphicsContext throw an error
• Fixed issue where the first scene onInitialize fires at Engine contructor time and before the "play button" clicked (#1900)
• Fixed issue where the "play button" click was being interpreted as an input event excalibur needed to handle (#1854)
• Fixed issue where pointer events were not firing at the ex.Engine.input.pointers level (#1439)
• Fixed issue where pointer events propagate in an unexpected order, now they go from high z-index to low z-index (#1922)
• Fixed issue with Raster padding which caused images to grow over time (#1897)
• Fixed N+1 repeat/repeatForever bug (#1891)
• Fixed repeat/repeatForever issue with rotateTo (#635)
• Entity update lifecycle is now called correctly
• Fixed GraphicsSystem enterviewport and exitviewport event
• Fixed DOM element leak when restarting games, play button elements piled up in the DOM.
• Fixed issues with ex.Sprite not rotating/scaling correctly around the anchor (Related to TileMap plugin updates https://github.com/excaliburjs/excalibur-tiled/issues/4, https://github.com/excaliburjs/excalibur-tiled/issues/23, https://github.com/excaliburjs/excalibur-tiled/issues/108)
  • Optionally specify whether to draw around the anchor or not drawAroundAnchor
• Fixed in the browser "FullScreen" api, coordinates are now correctly mapped from page space to world space (#1734)
• Fix audio decoding bug introduced in https://github.com/excaliburjs/Excalibur/pull/1707
• Fixed issue with promise resolve on double resource load (#1434)
• Fixed Firefox bug where scaled graphics with anti-aliasing turned off are not pixelated (#1676)
• Fixed z-index regression where actors did not respect z-index (#1678)
• Fixed Animation flicker bug when switching to an animation (#1636)
• Fixed ex.Actor.easeTo actions, they now use velocity to move Actors (#1638)
• Fixed Scene constructor signature to make the Engine argument optional (#1363)
• Fixed anchor properly of single shape Actor #1535
• Fixed Safari bug where Sound resources would fail to load (#1848)