excaliburjs/Excalibur v0.25.0 on GitHub

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:

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 excaliburjs/excalibur-tiled#4, excaliburjs/excalibur-tiled#23, excaliburjs/excalibur-tiled#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 excaliburjs/excalibur-tiled#4, excaliburjs/excalibur-tiled#23, excaliburjs/excalibur-tiled#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 #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)

excaliburjs/Excalibur v0.25.0 Excalibur v0.25.0 Release on GitHub