excalibur

Excalibur is a free game engine written in TypeScript for making 2D games in HTML5 canvas. Our goal is to make it easier for you to create 2D HTML/JS games, whether you're new to game development or you're an experienced game developer. We take care of all of the boilerplate engine code, cross-platform targeting (using browserstack 😎), and more! Use as much or as little as you need!

Excalibur is an open source project licensed under the 2-clause BSD license (this means you can use it in commercial projects!). It's free and always will be. We welcome any feedback or contributions! If you make something with Excalibur, please let us know!

Get Started

Our user documentation is at https://excaliburjs.com/docs (and you can contribute to the docs at https://github.com/excaliburjs/Excalibur/tree/main/site)

• Follow our Installation guide to learn how to install Excalibur.
• Follow our Getting Started guide if you're looking to get started.
• Learn what Features are available for you to leverage in your games.
• View the 1.0 Release roadmap to see what's coming next.

:exclamation: Note: Excalibur is still in version 0.x, which means this project and its associated plugins may be a little rough around the edges. We try to minimize API changes, but breaking changes will occur in new released versions. Excalibur is a labor of love and the product of many hours of spare time. Thanks for checking it out!

API Reference

Visit the API Reference section for fully-annotated documentation of the API.

Questions

• :question: Ask us anything in the GitHub Discussions area.
• :bug: If you find a bug, report it on the GitHub issues page (please review our guidelines for reporting bugs).
• :mega: You can also follow us on Twitter @excaliburjs or read the blog.

Samples

Compiled examples can be found in the Excalibur Samples collection.

Contributing

Please read our Contributing Guidelines and our Code of Conduct. Whether you've spotted a bug, have a question, or think of a new feature, we thank you for your help!

Mac/Linux

Prerequisites

• Docker for Mac https://docs.docker.com/desktop/mac/install/
• In the root, run docker compose build (setup build environment and installs dependencies, only needed once)
• To run tests in watch mode docker compose run --rm dev npm run test:watch
• To run a build docker compose run --rm dev npm run all

Writing Documentation

We love when people help improve our documentation. You can contribute to the docs in this repo under /site

Environment Setup

The Excalibur.js team primarily uses Visual Studio Code as a platform agnostic editor to allow the widest contributions possible. However, you can always use your own preferred editor.

Testing

Excalibur is committed to supporting the latest 2 versions of popular desktop and mobile browsers. We leverage browserstack automated testing to ensure that Excalibur is automatically tested as thoroughly as possible on all our supported platforms.

Prerequisites

• Required: Node.js LTS Version
• Recommended: ESLint plugin for VS Code

After cloning the repository, run:

npm install

You can then run the npm tasks for various purposes:

# Run compilation, linting, and all unit & visual tests
# Recommend to do this before finalizing pull requests
npm run all

# Run engine core compilation only
# Useful for quick checks to ensure everything compiles
npm run build

# Run engine tests only (does not run compile task)
# Useful to run tests ad-hoc
npm test
npm run test

# Start Storybook-based sandbox
# Used for creating interactive visual tests and examples for docs
npm run sandbox

# Build a nuget package and specify a version
npm run nuget -- 1.1.1

License

Excalibur is open source and operates under the 2-clause BSD license:

BSD 2-Clause License

Copyright (c) 2014, Erik Onarheim
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Changelog

[v0.31.0]

Breaking Changes

Deprecated

Added

• Added new ex.Camera.setStrategies() and ex.Camera.strategies for additional control of strategy order
• Fixed ex.Font measureText always using 10px sans-serif on the first call on some browsers
• Added a new ex.Sound({...}) option back constructor to set all the same props available on sound
• Added a new ex.SoundManager type for managing groups of audio/sound effects/music volume in an easier way

const soundManager = new ex.SoundManger({
  channels: ['fx', 'music', 'background'],
  sounds: {
    jumpSnd: { sound: jumpSnd, volume: 0.4, channels: ['fx'] },
    forestSnd: { sound: forestSnd, volume: 0.2, channels: ['music', 'background'] },
    challengeMusic: { sound: challengeMusic, volume: 0.2, channels: ['music'] },
    guitarLoop: { sound: guitarLoop, volume: 0.2, channels: ['music'] }
  }
});

// play a specific sound
soundManager.play('jumpSnd');

// mute a specific channel with all member sounds
soundManager.channel.mute('music');

// mute all sound
soundManager.mute();
// unmute all sound that was previously muted, and resume playing from the current location
soundManager.unmute();

// unmute a specific channel that was muted
soundManager.channel.unmute('music');

// play a specific channel
soundManager.channel.play('music');

// set the max volume of an entire channel
soundManager.channel.setVolume('music', 0.9);

• Added ex.Animation.data to store arbitrary meta data for an animation. Data can be directly added in the constructor as an option, by using the optional data argument in fromSpriteSheet(...) and as an option in fromSpriteSheetCoordinates({...})
• Added a new configuration option to ex.Engine({global: ...}) where you can provide a keyboard global to override if iframe detection fails for anyway.
• Added new way to output data from scenes onDeactivate(), returning data will be passed to the next SceneActivationContext in the previousSceneData property!
• Added new transitionstart and transitionend events to ex.Scenes
• Pipe navigation* events to ex.Engine
• Added ability to use ex.Vector to specify offset and margin in SpriteSheet.fromImageSource({..})
• New PostProcessor.onDraw() hook to handle uploading textures
• Adds contact solve bias to RealisticSolver, this allows customization on which direction contacts are solved first. By default there is no bias set to 'none'.
• Queries can now take additional options to filter in/out by components or tags.

const query = new Query({
  // all fields are optional
  components: {
    all: [ComponentA, ComponentB] as const, // important for type safety!
    any: [ComponentC, ComponentD] as const, // important for type safety!
    not: [ComponentE]
  },
  tags: {
    all: ['tagA', 'tagB'],
    any: ['tagC', 'tagD'],
    not: ['tagE']
  }
})

// previous constructor type still works and is shorthand for components.all
new Query([ComponentA, ComponentB] as const)

• Queries can now match all entities by specifying no filters

const query = new Query({})

• Adds maxVel attribute to MotionComponent, which clamps velocity on separated X and Y axes
• Add Clock.clearSchedule(id) and have Clock.schedule return an ID so you can clear a scheduled callback before it fires

Fixed

• Fixed issue where ParticleEmitter Particle did not receive z index value from emitter when in World space
• Fixed issue where an animation that was anim.reset() inside of an animation event handler like anim.once('end', () => anim.reset()) would not work correctly
• Fixed issue where GpuParticleEmitter did not rotate with their parents
• Fixed issue where Cpu ParticleEmitter did not respect ParticleTransform.Local
• Fixed issue where same origin iframes did not work properly with keyboard & pointer events
• Fixed issue where the initial scene onPreLoad was not being run
• Fixed unecessary coupling with ex.ColliderComponent/ex.BodyComponent that prevented collider tracking on entities that have ex.TransformComponent/ex.ColliderComponent, this influenced users doing Entity level ECS with pointer events.
• Fixed issue where passing 0 to ex.Sound.play(0) would not set the volume to 0, instead the previous volume would play.
• Fixed issue where the Actor.color did not respect being set
• Fixed offscreen culling issue when using parallax on TileMaps
• Fixed division by 0 when timescale is 0 in actions
• Fixed onTransition on the initial scene transition
• Fixed ex.TriggerOptions type to all optional parameters
• Fixed issue where the ActorArgs type hint would not error when providing a color causing confusion when it didn't produce a default graphic.
• Fixed false positive warning when adding timers
• Fixed issue where gamepad buttons wouldn't progress the default loader play button
• Add defense around middling Safari fullscreen support and update documentation
• Fixed issue where non-standard gamepad buttons would not be emitted by Excalibur
  • Added an additional param to the ex.GamepadButtonEvent indexto disabiguate between ex.Buttons.Unknown
• Fixed issue where Realistic solver would not sort contacts by distance causing some artifacts on seams
• Fixed issue with CompositeCollider where large TileMaps would sometimes causes odd collision behavior in the Realistic Solver when the body & collider components are far apart in a TileMap.
• Fixed crash on Xiaomi Redmi Phones by lazy loading the GPU particle renderer, GPU particles still do not work on these phones
• Add warning if World.add() falls through! This is caused by multiple versions of Excalibur usually
• Fixed CollidePolygonPolygon crash with some defense against invalid separation
• Fixed issue with PostProcessor where it would not run correctly if no actors present
• Removed warning in development for unadded entities
• Fixed memory leaks from retained entities in Map<Entity>

Updates

Changed

• Updated ex.Camera.addStrategy() to accept multiple strategies
• Changed the behavior of fromSpriteSheet(...), fromSpriteSheetCoordinates({...}) and clone() of ex.Animation to return the subclass if called from there
• Optimized BoundingBox.rayCast and BoundingBox.rayCastTime
• Optimized BoundingBox.intersect(otherBoundingBox)
• Change logging behavior for entities not in scenes, only log in dev builds