Learn the PlayCanvas API with the Engine Examples Browser

PlayCanvas has a rich JavaScript API that allows you to build just about any type of interactive content imaginable – games, playable ads, product configurators, AR, VR and more! But learning a new API can be tough. Reading API reference documentation is all well and good, but many people prefer to learn by experimentation. And by examining the code of real world examples. This led the PlayCanvas team to build a new application: the Engine Examples Browser.

Starting exploring the Examples Browser now:

https://playcanvas.github.io/

The browser is written entirely in Typescript and uses a Webpack build process. Naturally, it is 100% open source (MIT license) and the source can be found here.

The Examples Browser has some pretty cool features:

  • Gallery panel. Select any of the 86 examples from the (filterable) list on the left, either by name or thumbnail.
  • Inspect Source. Expand the source panel (built on the awesome Monaco code editor) on the right to inspect any example’s source code.
  • Edit and hot reload. Edit any example and hit the Play button to refresh the running example. Monaco uses PlayCanvas’ Typescript definitions to provide inline API hints.
  • Embed links. Want to embed PlayCanvas examples in your own site? Simply hit the embed icon and copy the URL!
  • Share to Twitter. Want to share a specific example with the world? Just hit the Twitter icon!

If you would like to request an example to be added to the browser, submit an issue here. Or if you’re feeling creative, submit a pull request of your own to the repo! Stay tuned for newly added examples in the coming months. Enjoy!

Transitioning to the New Render Component and Fill Mode API

Hi everyone!

This is a different blog post to what we normally do but with some big changes coming soon, we wanted to give context and advance notice of said changes and more importantly, how they may affect you across the PlayCanvas platform.

Moving from Model Component model import pipeline to new Render Component

As part of the work to enable the import of a model’s hierarchy into the scene, we have introduced Render Asset and Render Component as new features of the Engine and Editor.

Import hierarchy preview

Going forward, this will be the default way to render imported models and gives developers greater flexibility in manipulating mesh instances in the model directly in the Editor. For example, with the new pipeline you can import a house FBX model and only use the door mesh instance in the scene instead of the whole model.

However, please note that while the Model Component is compatible with both the Animation and Anim (State Graph) Component, the Render Component/Import Hierarchy feature is only compatible with the Anim (State Graph) Component.

(More details will be shared in an upcoming announcement, stay tuned for that!)

For existing projects using the Model Component, please do not worry. None of the existing functionality is being removed and you will not be forced to update projects to the new pipeline for continued development. Although no new features will be added to the Model Component, the PlayCanvas team will continue to fix bugs with the existing pipeline.

You can even mix both pipelines in the same project if you wish to take advantage of the features in the new pipeline in an existing project. However, please bear in mind that this can add complexity to the project code.

The expected changes over the upcoming months are as follows:

  • Add/Rename a Project Setting to switch between the two mesh import pipelines (Currently, this is the ‘Import Hierarchy’ setting).
  • Newly created projects will default to using the Render Component pipeline.
  • developer.playcanvas.com tutorials will be updated to use Render Component (playcanvas.github.io engine examples have already been updated).
  • The template projects (Blank Project, Model Viewer Starter Kit, VR Starter Kit) will be updated to use Render Component.
  • User Manual updates and mitigation steps from using the Model Component to Render Component pipelines.

Breaking change to PlayCanvas Fill Mode API

We want to make the PlayCanvas engine as flexible as it can be for the widest range of use cases for web developers. To do so, we occasionally have to break existing APIs that may have made sense when they were first introduced, but not today.

One such API is the Fill Mode related functions on pc.Application:

These functions affect the canvas element size in the DOM as it was long assumed that apps made with PlayCanvas are either be iframed or fullscreen/full document apps.

However, there has been more requests about having more control of the canvas element rather than using iframes. The main reason is that it’s easier to communicate between the page and the PlayCanvas app without having to deal with iframe messaging.

Some examples:

Currently, there is no way for an end user to have full control of the canvas without patching the engine.

Also, from an architecture point of view, the Engine shouldn’t handle the size or position of the element that it is rendering in. The responsibility should be on the web document and how it wants to layout the elements on the page (e.g through stylesheets).

These changes will affect you directly if you are:

  • An engine only user as the HTML boilerplate will handle the resizing and positioning of the canvas. We will provide examples in the examples folder.
  • Any developer that changes the fill mode or resizes the Canvas at runtime. Some developers do this to handle landscape and portrait mode more effectively.

The current plan is deprecate these functions and move them to globally accessible functions on the page on the PlayCanvas Editor environment with as little (if any) downtime for projects or developers. At worst, you should only get a few warnings in the console log regarding deprecated function use.

The steps will be as a gradual rollout:

  • Add globally accessible JS functions in the Editor and publish HTML templates to replace the fill mode functions from the Engine.
  • Change the PlayCanvas Editor and published build templates to patch the Engine functions to call the global functions above with warnings that they should use the global functions instead.
  • Update the User Manual to document these global functions.
  • Deprecate the affected engine functions with warnings and reference the User Manual page.

Questions and Feedback

If there are any questions or areas that you would like to be made more clear, please post in the forums and the PlayCanvas team will be there to answer.

The PlayCanvas team are appreciative of your patience and continued support as we go through this transition!

Introducing the Anim State Graph

We’re excited to be able to release a new system for creating fantastic and high fidelity animations in PlayCanvas!

Animation systems receive a set of inputs (button presses, current player speed, health, etc) and output a models animation pose for the current frame. How an animation system goes from a particular set of inputs to the desired animation pose can become quite complicated, especially when writing this in code.

With the release of the Anim component, Anim State Graph assets and Anim State Graph Editor, you will be able to design and develop intricate animation behavior for your game objects right in the PlayCanvas editor. 

It’s now easier than ever to make your game characters move just the way you’d like, while writing minimal code in the process!

Having recently beta tested this feature with a number of developers, we’ve already seen some fantastic results! For instance, the developer of the popular online shooter venge.io is utilising the anim state graph to drive character animations in their up and coming online RPG. 

A clip of an early build of this game can be seen below, showcasing the blending of multiple animation clips. When combined together in a state graph they create realistic and fluid movement for the main character.

This animation system was entirely developed in the PlayCanvas editor using the anim state graph user interface. The state graph for the main character can be seen below:

We can’t wait to see what other developers can create with this system!

Features

Graph Layers – Split your animation behavior into separate layers. For instance: locomotion animations can be separated from facial expressions. 

Multiple characters – Because anim state graphs are stored as assets, a single graph can be used to drive the animation of as many entities as you want by assigning your graph asset to multiple entity anim components.

Multiple characters utilising the same anim state graph

While these two characters use different animations for their various actions, they share the same behavior. With the anim state graph you can update this behavior in one place while still using it with as many characters as you like.

How does it all work?

When opening an Anim State Graph asset you’ll be presented with a visual graph editor which allows you to define all of the different animation states your game object can be in. You can then connect these states using transitions. 

Create anim state graphs using the editor ui

Each transition blends between two animations over a specified amount of time. You can adjust and tweak transitions to your liking and see the results in real time in the PlayCanvas launch page. You can then assign parameter conditions to each transition to define the circumstances under which that transition can fire. These parameter values can be modified in your scripts to control the behavior of your animation system.

Control anim state graph behavior in scripts using the anim component API

Once you’ve created your Anim State Graph you can assign it to your entity using the Anim component. At this point you can attach your animation assets to each state which will play when transitioning to that state.

Looking ahead

Today only marks the initial release of our new animation system. We’ve got grand plans on how to push the system further. Here’s a few features we’ve got in the works:

Animation Events – These events can be set up to fire and specific points during the lifetime of an animation, allowing you to hook game logic into the behavior of your anim state graph. For example you could spawn a set of dust particles during the exact frame that your character lands on the ground after a jump.

Layer Masking – You’ll be able mask your character animations on a particular state graph layer. For instance you could have only the bottom half of a character driven by a particular anim state graph layer.

Blend Trees – Directly control the blend between multiple animations in real time.

Blending three animations using a 2D cartesian blend tree

Animation Clips – Currently the anim state graph supports animation assets that have been imported into PlayCanvas. Clips will allow you to create extra animation assets within the PlayCanvas editor yourself! These will be great for quickly adding smaller animated flourishes to your game objects.

If you’re interested in using anim state graphs in your PlayCanvas projects, here’s some useful links:

Build Facebook Playable Ads with PlayCanvas!

PlayCanvas are very excited to announce official support for Facebook Playable Ads! 🚀

What are Playable Ads?

Playable ads are small, interactive previews of a game or app that give a taste of the experience before the user choses to download it. These ads from Facebook are normally shown in the news feed or with ‘rewarded ads’ in other games and apps in exchange for an in-game/app reward.

Facebook case studies consistently show that playable ads:

  • Increase click-through rates
  • Increase install conversion over traditional ads
  • Increase return on ad spend
  • Reduce cost per install

Combine that with the fully featured PlayCanvas game engine which includes:

  • Best in class visual editor with live updates across multiple devices
  • 3D models and animation with physically based rendering (PBR)
  • 2D animated sprites
  • Responsive user interface authoring

And you have a very powerful combination to create fantastic and engaging experiences to reach your audience.

Sounds great! How do I get started?

We’ve published the official exporter tool on GitHub with instructions in our User Manual Documentation. It’s very simple to set up!

Once configured, creating the file(s) for upload to Facebook is just a single command, shown in real time below.

That is how quick and easy it is! 💪 And it supports both the single 2MB HTML and 5MB zip bundle formats used by Facebook. 🙌

If you’re new to PlayCanvas, why not sign up today for free. We can’t wait to see what you make! Let us hear your feedback in the forums!

Useful links:

P.S We are considering doing a follow up technical post on how the tool works under the hood. Let us know in the comments below if that is something you would be interested in. 👇

WebGL Case Study: Rebuilding the Star-Lord PBR Demo

Way back in 2014, PlayCanvas was the first WebGL Engine to integrate PBR (Physically Based Rendering). To mark the event, we built the Star-Lord tech demo:

In the intervening 6 or so years, PlayCanvas has moved on dramatically. So we decided to leverage all of the latest engine features and republish it.

The most significant improvements are related to load time. Let’s start out by comparing some key stats:

Star-Lord 2014Star-Lord 2021% Change
HTTP Requests22039↓ 82.3%
Preload Transfer (MB)10.15.6↓ 44.6%
Total Transfer (MB)13.79.9↓ 27.7%
Total Resources (MB)26.012.1↓ 53.5%
Load Time (s) *1.81.2↓ 33.3%
* Cache disabled on 100Gbps connection

Those are some pretty significant wins! So what are the differences between the two builds of the demo? Let’s step through them one by one.

Convert JSON Meshes to GLB

In October 2020, PlayCanvas officially switched from JSON to glTF 2.0 (GLB) for storing all model and animation data. While gzipped GLB is reasonably similar in size to gzipped JSON, it is up to an order of magnitude faster to parse a GLB file once it has been downloaded. Plus, a GLB file occupies less system memory than the equivalent JSON file. Converting all of the assets from JSON to GLB is a simple process. First, flip the project setting ‘Convert to GLB’ in the ‘Asset Tasks’ group to true:

Now, simply reupload all FBX files and a .glb asset will be generated rather than a .json asset. The last step is to use the Replace command in the right-click context menu to replace the .json asset with the .glb asset (plus any materials as well).

You can then delete the old JSON asset (plus any unreferenced related materials).

Basis Compress Textures

Last month, we announced the integration of Basis texture compression into the Editor. Star-Lord was originally configured to use DXT, PVR and ETC compressed textures. A download size comparison is as follows:

Texture FormatDownload Size (MB)
DXT7.56
PVR6.09
ETC17.18
Basis2.38

This explains much of the download savings in the updated version.

Fortunately, applying Basis compression to the app’s textures is literally a two-click operation:

Prefilter Cubemaps in the Editor

When PBR first arrived in PlayCanvas, the Editor could not prefilter cubemaps. This conversion had to be performed externally with RGBM format cubemap faces being added to the Editor:

Each cubemap had 6 mip levels with 6 faces for each level. And with 5 different cubemaps, that meant 180 of the demo’s 220 HTTP requests were for these PNGs!

These days, the Editor makes is super easy to import 6 HDR cubemap faces, build a cubemap and then prefilter it.

So instead of loading 180 PNGs, the demo now loads just 5 DDS files. Much faster. 🚀

Asynchronously Load Assets

To achieve an optimal load time, it is important to only load what is required to make your app functional. It is arguable that music is not strictly a necessary precondition for your app to start. Therefore, the demo now asynchronously loads the mp3 asset that contains the music track and auto-plays it as soon as it is downloaded. It is 3.9MB which accounts for nearly 40% of the app’s payload! So be sure to carefully audit your app for assets that can be streamed instead of preloaded.

Read more about preloading and streaming of assets in the User Manual.

Useful Links

Basis Texture Compression arrives in PlayCanvas

PlayCanvas implemented the fantastic hardware texture compression workflow in 2016 which allowed users to build bigger and better WebGL apps, even on low memory devices like mobile phones.

JPGs and PNGs are great formats for transmission over a network because they tend to compress nicely. But once the images are downloaded and handed over to WebGL, they must decompressed to raw RGB(A) data. Using hardware compressed textures is important as decompression is performed in silicon on the GPU which avoids the need to utilize lots of memory.

This 4096 x 2048 Earth texture is a 1.81MB JPG but takes a huge 33.6MB of VRAM when uncompressed!

With hardware supported texture formats, we can retain a similar file size while massively reducing the amount of VRAM as seen below.

Now, what if you reduce file sizes as well as the VRAM usage?!

That is what Basis gives us and it is available right now to all PlayCanvas users! Compressing the same Earth texture above, produces a 521KB Basis Texture.That’s a 68% saving over the smallest file size from the hardware supported formats 💪

Basis is an open sourced, texture codec that produces a highly compressed intermediate file format (.basis) that can be converted at runtime to a format that the hardware supports in GPU hardware. This means that there is only a single (and often smaller) file that is created to support a wide range of platforms.

As shown by the numbers above, Basis offers huge savings in download times for the end user which in turn, can lead to improved user engagement and click to open metrics for your application.

Let’s check out a real world example. The Space Base Texture Compression Demo from our previous blog article achieves the following VRAM usage and download sizes (gzipped) on desktop in Chrome:

Note that VRAM usage for Basis would ordinarily be the same as with legacy compression. However, PlayCanvas compresses normal maps to YYYX format instead of XYZ for improved quality so utilization is marginally higher.

That’s a big saving of 52% (19.5 MB) in download size from updating the project to use Basis while using a similar amount of VRAM!

And all it takes is a couple of clicks in the asset inspector to get started with Basis compression!

To recap

  • Only need one compressed file vs many (DXT, PVR, ETC1, ETC2, etc) for every texture
  • Up to 2.8 times smaller files and faster download times for your users
  • Up to 10x faster compression times with Basis
  • Similar savings in VRAM usage as hardware supported formats
  • Same one click process to compress textures

Basis texture compression is available to everyone right now so start crunching down those textures! More information can be found in the documentation including a migration guide.

And if you’re new to PlayCanvas, why not sign up today. We can’t wait to see what you make! Let us hear your feedback in the forums!

PCUI 1.1.0 Adds Tree Control and Array Control

Back in October, we launched PCUI, an easy to use framework for building web-based tools. It already powers the PlayCanvas Editor and glTF Viewer applications.

Today, we’re excited to announce our next major release for the library: PCUI 1.1.0. Check out the release notes for the details. But let’s take a look at some of the highlights.

TreeView – Tree Control

Many web tools display data in a hierarchical or tree-based representation. But building a tree control in HTML and CSS can be tricky. PCUI 1.1.0 introduces a very easy to use tree control. And it incorporates some useful features such as:

  • Drag and drop of tree view items
  • Built-in ‘double-click to rename’

ArrayInput – Array Control

Also arriving in PCUI is ArrayInput. It allows you to create input controls for arrays of numbers, strings, booleans or vectors.

Resizable TextAreaInput Control

The TextAreaInput control has been augmented with a new resizable property that can be set to ‘none’, ‘horizontal’, ‘vertical’ or ‘both’.

To get started making awesome web tools with PCUI, here are some useful links:

Introducing JSON Script Attributes

JSON Script Attributes Preview

We have levelled up the Script Attributes that makes it much easier to organize and group related attributes together.

Using JSON, developers are able to define a schema for a data object that has multiple attributes and have them grouped together in the Inspector.

In the example below, we have created a JSON schema with the name ‘settings’ and has the attributes ‘gravity’, ‘startingHealth’ and ‘godMode’.

GameManager.attributes.add('settings', {
    type: 'json',
    schema: [{
        name: 'gravity',
        type: 'number',
        default: -9.8
    }, {
        name: 'startingHealth',
        type: 'number',
        default: 20
    }, {
        name: 'godMode',
        type: 'boolean',
        default: false
    }]
});

In the Inspector, the data object is shown as a collapsible section:

Collapsible script settings

Even better, these data objects can made into an array! This is a huge improvement over having to organize multiple attribute arrays that was difficult to update and error prone to maintain.

Example JSON schema for an array of enemies:

GameManager.attributes.add('enemies', {
    type: 'json',
    schema: [{
        name: 'health',
        type: 'number',
        default: 10
    }, {
        name: 'type',
        type: 'number',
        enum: [
            { 'Close Combat': 1 },
            { 'Range': 2 },
            { 'Both': 3 }
        ]
    }, {
        name: 'templateAsset',
        type: 'asset',
        assetType: 'template'
    }],
    array: true
});

Becomes the following in the inspector which is so much cleaner!

Arrays of JSON objects

Read more in the documentation and let us hear your feedback in the forums!

Copy and Paste Assets between Projects

PlayCanvas has a pretty cool (but not widely known about) feature that allows you to copy and paste entities and entity hierarchy between two instances of the Editor. This can save a lot of time, particularly when setting up new projects.

Many of you have requested the ability to do the same with assets. Well, we listened – and now you can! 🚀

So if you need to grab some assets from another project, no more need to download from Project A and then upload to Project B. Just copy and paste in seconds, directly from project to project.

This makes it super easy to share reusable code and assets with your team and the rest of the PlayCanvas community, especially in combination with the recent launch of Templates to setup preconfigured Entities.

Use the context menu or the Ctrl/Cmd + C and Ctrl/Cmd + V hotkeys to copy assets across to your projects. 💪

Check out the documentation for more details.

Faster Load Times with glTF’s GLB Format!

The PlayCanvas team is super excited to announce the Editor support of glTF GLB conversion with model and animation imports.

This gives developers an order of magnitude reduction in load times compared to the JSON format while keeping similar gzipped download size.

Using the Stanford Dragon model (2,613,679 vertices, 871,414 triangles), we can compare GLB and JSON parse times on a Macbook Pro 16 inch.

The JSON format took over 3 secs just to parse the data, a peak memory usage of ~498 MB and a gzipped package size of 28.1MB.

JSON

GLB speeds ahead taking only 0.193 secs which is 17x faster, uses a peak of ~25.2 MB of memory and a gzipped package size of 25.7MB 🚀!

GLB

That’s a huge saving in time and means applications will become snappier and more responsive to users, especially for content heavy games and product showcases.

We will be deprecating the use of JSON and the default format that model and animations files. Newly created projects will default to converting to GLB and in existing projects, this can be enabled in the projects settings:

If you would like to replace your current JSON assets with GLB, the User Manual has more information about the process to migrate over.

The conversion to GLB supports the importing of multiple animations in a single FBX which will help improve content workflows.

Remember our awesome glTF 2.0 Viewer? That is now integrated into the Editor to inspect any GLB asset from the project. Just right and select ‘Open In Viewer’!

Also, we have exposed Animation Import Settings under Asset Tasks in project settings. These will allow developers to adjust a balance between animation quality and fidelity against file size.

Animation Import Settings

Our next steps are to add support for viewing and editing a model hierarchy in the Editor which will lead onto support for the importing of GLB files.

The team is hard at work designing and implementing these features so watch this space!