phaser/README.md

Phaser - HTML5 Game Framework

Phaser is a fast, free, and fun open source HTML5 game framework. It offers WebGL and Canvas rendering across desktop and mobile web browsers. Games can be compiled to iOS, Android and native apps via 3rd party tools. You can use JavaScript or TypeScript for development.

Phaser is available in two versions: Phaser 3 and Phaser CE - The Community Edition. Phaser CE is a community-lead continuation of the Phaser 2 codebase and is hosted on its own repo. Phaser 3 is the next generation of Phaser.

Along with the fantastic open source community, Phaser is actively developed and maintained by Photon Storm. As a result of rapid support, and a developer friendly API, Phaser is currently one of the most starred game frameworks on GitHub.

Thousands of developers worldwide use Phaser. From indies and multi-national digital agencies, to schools and Universities. Each creating their own incredible games.

Visit: The Phaser website and follow on Twitter (#phaserjs)
Learn: API Docs, Support Forum and StackOverflow
Code: 700+ Examples (source available in this repo)
Read: Weekly Phaser World Newsletter
Chat: Slack and Discord
Extend: With Phaser Plugins
Be awesome: Support the future of Phaser

Grab the source and join in the fun!

20th February 2018

Updated: Thank you for the amazing response to the 3.0.0 release! We've been hard at work and have now prepared 3.1.1 for you, which is available today. Check out the Change Log for more details.

After 1.5 years in the making, tens of thousands of lines of code, hundreds of examples and countless hours of relentless work: Phaser 3 is finally out. It has been a real labor of love and then some!

Please understand this is a bleeding-edge and brand new release. There are features we've had to leave out, areas of the documentation that need completing and so many cool new things we wanted to add. But we had to draw a line in the sand somewhere and 3.0.0 represents that.

For us this is just the start of a new chapter in Phaser's life. We will be jumping on bug reports as quickly as we can and releasing new versions rapidly. We've structured v3 in such a way that we can push out point releases as fast as needed.

We publish our Developer Logs in the weekly Phaser World newsletter. Subscribe to stay in touch and get all the latest news from us and the wider Phaser community.

You can also follow Phaser on Twitter and chat with fellow Phaser devs in our Slack and Discord channels.

Phaser 3 wouldn't have been possible without the fantastic support of the community and Patreon. Thank you to everyone who supports our work, who shares our belief in the future of HTML5 gaming, and Phaser's role in that.

Happy coding everyone!

Cheers,

Rich - @photonstorm

Developing Phaser takes a lot of time, effort and money. There are monthly running costs as well as countless hours of development time, community support, and assistance resolving issues.

If you have found Phaser useful in your development life or have made income as a result of it please support our work via:

• A monthly contribution on Patreon.
• A one-off donation with PayPal.
• Purchase any of our plugins or books.

It all helps and genuinely contributes towards future development.

Extra special thanks to our top-tier sponsors: Orange Games and CrossInstall.

Every Monday we publish the Phaser World newsletter. It's packed full of the latest Phaser games, tutorials, videos, meet-ups, talks, and more. It also contains our weekly Development Progress updates, where you can read about what new features we've been working on.

Over 100 previous editions can found on our Back Issues page.

Phaser 3 is available via GitHub, npm and CDNs:

• Clone the git repository via https, ssh or with the Github Windows or Mac clients.
• Download as zip
• Download the build files: phaser.js and phaser.min.js

NPM

Install via npm:

npm install phaser

CDN

Phaser is on jsDelivr, a "super-fast CDN for developers". Include the following in your html:

<script src="//cdn.jsdelivr.net/npm/phaser@3.1.1/dist/phaser.js"></script>

or the minified version:

<script src="//cdn.jsdelivr.net/npm/phaser@3.1.1/dist/phaser.min.js"></script>

License

Phaser is released under the MIT License.

Phaser 3 is so brand new the paint is still wet. As such we don't yet have any guides or tutorials! This will change in the coming weeks and we'll update this area as they emerge. For now, please subscribe to the Phaser World newsletter as we'll publish them in there first.

Source Code Examples

During our development of Phaser 3 we created hundreds of examples, with the full source code and assets available. Until those are fully integrated with the Phaser web site, you'll have to browse them in the Phaser 3 Labs, or clone the examples repo. Note: Not all examples work, sorry! We're tidying them up as fast as we can.

Create Your First Phaser 3 Example

Create an index.html page locally and paste the following code into it:

<!DOCTYPE html>
<html>
<head>
    <script src="http://labs.phaser.io/build/phaser-arcade-physics.min.js"></script> 
</head>
<body>

    <script></script>

</body>
</html>

This is a standard empty web page. You'll notice it's pulling in a build of Phaser 3 in the script tag, but otherwise doesn't do anything yet. Now let's set-up the game config. Paste the following between the <script></script> tags:

var config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    physics: {
        default: 'arcade',
        arcade: {
            gravity: { y: 200 }
        }
    },
    scene: {
        preload: preload,
        create: create
    }
};

This is a pretty standard Phaser 3 Game Configuration object. We'll tell it to use the WebGL renderer if it can, set the canvas to a size of 800x600 pixels, enable Arcade Physics and finally call the preload and create functions. These don't exist yet, so if you run this it will just error. So add the following after the config object:

var game = new Phaser.Game(config);

function preload ()
{
    this.load.setBaseURL('http://labs.phaser.io');

    this.load.image('sky', 'assets/skies/space3.png');
    this.load.image('logo', 'assets/sprites/phaser3-logo.png');
    this.load.image('red', 'assets/particles/red.png');
}

function create ()
{
}

This creates a Phaser Game instance, using our configuration object. It also provides the two functions it needs. The preload function is a way to easily load assets into your game. Here we'll set the Base URL to be the Phaser server and grab down 3 PNG files.

The create function is empty, so it's time to fill it in:

function create ()
{
    this.add.image(400, 300, 'sky');

    var particles = this.add.particles('red');

    var emitter = particles.createEmitter({
        speed: 100,
        scale: { start: 1, end: 0 },
        blendMode: 'ADD'
    });

    var logo = this.physics.add.image(400, 100, 'logo');

    logo.setVelocity(100, 200);
    logo.setBounce(1, 1);
    logo.setCollideWorldBounds(true);

    emitter.startFollow(logo);
}

Here we're adding the sky image into the game. Over the top of this we have created a Particle Emitter. The scale value means the particles will start large and then scale away to nothing over the duration of their lifespan.

Then we add the logo image. Notice how this is a Physics Image, which means it is given a physics body by default. We set some properties on it: velocity, bounce (or restitution) and collision with the world bounds. This will make our logo bounce around the screen. Finally, we tell the particle emitter to follow the logo - so as it moves, the particles will flow from it.

Run it in your browser and you'll see the following:

(Got an error? Here's the full code)

It's just a tiny example, and we've hundreds more for you to explore, but hopefully it shows how expressive and quick Phaser is to use. With just a few easily readable lines of code we've got something pretty impressive up on screen!

Subscribe to our weekly newsletter for further tutorials and examples.

Phaser is provided ready compiled in the dist folder of the repository. There are both plain and minified versions. The plain version is for use during development, and the minified version for production. You can also create your own builds.

Custom Builds

Phaser 3 has to be built using Webpack. We take advantage of a number of Webpack features and plugins to allow us to properly tailor the build process. You can also elect exactly which features are bundled into your version of Phaser. We will release a tutorial covering the process shortly, but for now please look at our webpack config files to get an idea of the settings required.

Building from source

Should you wish to build Phaser 3 from source ensure you have the required packages by cloning the repository and then running npm install.

You can then run webpack to perform a dev build to the build folder, including source maps for local testing, or run npm run dist to create a minified packaged build into the dist folder.

Version 3.1.1 - 20th February 2018

Updates

• The entire codebase now passes our eslint config (which helped highlight a few errors), if you're submitting a PR, please ensure your PR passes the config too.
• The Web Audio Context is now suspended instead of closed to allow for prevention of 'Failed to construct AudioContext: maximum number of hardware contexts reached' errors from Chrome in a hot reload environment. We still strongly recommend reusing the same context in a production environment. See this example for details. Fixes #3238 (thanks @z0y1 @Ziao)
• The Webpack shell plugin now fires on onBuildExit, meaning it'll update the examples if you use webpack watch (thanks @rblopes)
• Added root: true flag to the eslint config to stop it scanning further-up the filesystem.

Bug Fixes

• Math.Fuzzy.Floor had an incorrect method signature.
• Arcade Physics World didn't import GetOverlapX or GetOverlapY, causing separateCircle to break.
• TileSprite was missing a gl reference, causing it to fail during a context loss and restore.
• The Mesh Game Object Factory entry had incorrect arguments passed to Mesh constructor.
• Removed unused _queue property from ScenePlugin class (thanks @rblopes)
• The variable static is no longer used in Arcade Physics, fixing the 'static is a reserved word' in strict mode error (thanks @samme)
• Fixed Set.union, Set.intersect and Set.difference (thanks @yupaul)
• The corner tints were being applied in the wrong order. Fixes #3252 (thanks @Rybar)
• BitmapText objects would ignore calls to setOrigin. Fixes #3249 (thanks @amkazan)
• Fixed a 1px camera jitter and bleeding issue in the renderer. Fixes #3245 (thanks @bradharms)
• Fixed the error WebGL: INVALID_ENUM: blendEquation: invalid mode. that would arise on iOS. Fixes #3244 (thanks @Ziao)
• The drawBlitter function would crash if roundPixels was true. Fixes #3243 (thanks @Jerenaux and @vulcanoidlogic)

Please see the complete Change Log for previous releases.

Looking for a v2 change? Check out the Phaser CE Change Log

The Contributors Guide contains full details on how to help with Phaser development. The main points are:

• Found a bug? Report it on GitHub Issues and include a code sample. Please state which version of Phaser you are using! This is vitally important.

• Before submitting a Pull Request run your code through ES Lint using our config and respect our Editor Config.

• Before contributing read the code of conduct.

Written something cool in Phaser? Please tell us about it in the forum, or email support@phaser.io

Phaser is a Photon Storm production.

Created by Richard Davey. Powered by coffee, anime, pixels and love.

The Phaser logo and characters are © 2018 Photon Storm Limited.

All rights reserved.

"Above all, video games are meant to be just one thing: fun. Fun for everyone." - Satoru Iwata