Enhanced Asset API

Today we’re pleased to update the engine and tools with a new Asset API. We’ve finessed the API to make it more intuitive and also added some extra features to make it easier for you to preload or stream in assets at any stage of your application.

This post should introduce some of the new APIs, plus give you an upgrade guide for areas of the API which have changed.

First some terms. When we talk about a “resource” we are referring to some data, usually stored in a file, that can be loaded by a PlayCanvas application. When the resource data is loaded, the engine creates a instance of some class that came from that data. e.g. the resource “image.png”, is loaded to a creates an instance of a `pc.Texture`. The same applies for a 3D model, an animation or sound effect.

When we talk about as “asset” we are referring to a reference to a resource, with some associated data. For example a texture asset looks something like this:

{
 "id": 14761,
 "name": "Cerberus_G",
 "type": "texture",
 "preload": true,
 "file": {
  "url": "files/assets/14761/1/Cerberus_G.jpg",
  "size": 816084,
  "hash": "dc49dac4f4775191b7643b4583b3ac3f",
  "filename": "Cerberus_G.jpg"
 },
 "data": {
  "minfilter": "linear_mip_linear",
  "name": "Cerberus_G",
  "magfilter": "linear",
  "addressu": "repeat",
  "addressv": "repeat",
  "anisotropy": 1
 },
}

You can see the asset data for this texture as an ID, a Name, a reference to the file where the resource data is, plus some additional data which isn’t stored in the image file. This data is used to create the texture resource. Some assets contain lots of data (materials) some none (a text file).

Once loaded into the engine, you can use the asset registry to find assets, and you can access the loaded resource (if it is loaded) from the asset using the `asset.resources` property.

On to the changes:

Editor Changes

Asset Preloading

preload

The first new feature is asset preload. Previously we would load any assets that were referenced by your scene. We changed this behaviour so that now assets have a specific preload property which you can enable or disable. Any asset marked as preload, and we default this to true for new assets, will be loaded during the loading screen stage and will be ready to use when your application starts. Any that are not marked as preload, will remain on the server, ready to be loaded when you need them.

We’ve updated existing assets to mark all existing target assets are preload. So you may need to uncheck this option on some assets if you don’t actually need them.

Export and Publishing

When you publish an app or choose to download an export of your app, we now include all assets in the package. As you can choose whether or not to preload assets, this means that you can select only a subset of your assets to be loaded before your application starts. Then you can load other assets at any other stage later on. This lets you use many more assets in your games and applications but not worry about start up time. Just stream your assets in later on.

Script Loading Order

Script loading has had an overhaul, we now load scripts in parallel with other assets so load times should be reduced. We have also changed which scripts are loaded. Previously, we’d only load scripts which are referenced in scenes. We now load all scripts in your repository. Because of this we’ve introduced a way to set the order in which your scripts are loaded.

script-priority

Found in the menu, you can use the script loading priority dialog to choose scripts you wish to load first.

API changes

Asset Registry

The `AssetRegistry` object has changed slightly in the new API. The core methods are shown below. As before the `AssetRegistry` object is available in your scripts as `app.assets`.

app.assets.get(id) - get by id
app.assets.find(name, type) - search by name, return first result
app.assets.findAll(name, type) - search by name, return all
app.assets.load(asset) - load remote resource for asset

The main change here is that `load()` no longer accepts a list of assets and it no longer returns a promise. We’re removing promise from the engine in favour of node.js style callbacks and events.

Note, we have left in a compatibility version of assets.load which accepts a list of assets and returns a promise. You should update your code to remove this as it will not be in the engine forever.

Asset Events

The asset registry (and the asset object) fire a consistent set of events which you can use to react to changes on the registry. These can be used to monitor loading progress or respond if you wish to dynamically add assets to the registry.

assets.on("add", callback) - triggered when asset added to registry
assets.on("add:{id}", callback) - triggered when asset added to registry
assets.on("add:url:{url}", callback) - triggered when asset added to registry
assets.on("remove", callback) - triggered when asset added to registry
assets.on("remove:{id}", callback) - triggered when asset added to registry
assets.on("remove:url:{url}", callback) - triggered when asset added to registry
assets.on("load", callback) - triggered on successful load
assets.on("load:{id}", callback) - triggered on successful load
assets.on("error", callback) - triggered on asset loading error
assets.on("error:{id}", callback) - triggered on asset loading error
asset.on("change", callback) - triggered when asset data changes

A good pattern for loading and using an asset is like this:

asset.ready(function (asset) {
    // use asset.resource here 
});
assets.load(asset);

asset.ready() will call the callback when if when the asset is loaded. It’s it’s already loaded from before, the callback is called immediately. asset.load() does nothing if the asset is already loaded.

Resource Loader

The resource loader is a lower level interface than the asset registry. Most users won’t need to access this directly as they will use the asset registry to load data. But this API has changed significantly. We’ve made it much simpler:

app.loader.load(url, type, callback);

I’ll just leave it there, see the API docs if you need more information.

Application Scene Loading

We’ve added a simple API for loading new scene data via the `app` object

app.loadSceneHierarchy(url, callback) - load a scene file, get hierarchy, append hierarchy to app.root
app.loadSceneSettings(url, callback) - load a scene file, apply settings (lighting/physics) to current scene

These two functions accept the URL of the scene file which will be in the format “scene_id.json” e.g. “100.json”.

Upgrade guide

Hopefully you’ll find your application continues work as before, only now it loads faster and you have more options available to you for dynamically loading assets. However, this is a breaking API change so you may need to update your projects.

app.assets.load(asset)

If you are using this and passing in a single asset, we no longer return a promise. You should replace your code with this:

asset.ready(function (asset) {
  // use asset
});
app.assets.load(asset);

app.assets.load(assets);

If you are loading a list of assets, our compatible load should still work. However, you should update your code to use the new loading format. As below

var toload = []; // list of assets
var count = 0;
toload.forEach(function (asset) {
   asset.ready(function (asset) {
   count++;
   if (count === toload.length) {
     // done
   }
 });
 app.assets.load(asset); 
});

app.loader.request()

If you were using this to make resource requests like loading Packs or asking for texture data. This is all new. You should be able to replace these calls with some other method. Maybe `app.loadSceneHierarchy()` or by using asset preloading to delay loading texture data. However if you really need to load a resource directly. You can use the resource loader API:

app.loader.load(url, function (err, resource) {
  if (!err) {
    // use resource
  }
});

That’s it! If you notice any problems or have trouble upgrading, get in touch on the forum.

The DevLog – PlayCanvas Community Feature

We’ve just rolled out the Developer Log or DevLog. The first of several community features coming soon into PlayCanvas.

Keeping people informed

DevLog___Dashboard___swooop___PlayCanvas___3D_HTML5___WebGL_Game_Engine

 

To create a game you have to complete thousands of little tasks over the course of development. Each day you tick off a few items in your todo list, squash a few bugs or updated a few models. When you are using source control with each change you commit to your code you include a commit message. This tells the rest of your team what’s changed and gives you a good reference point to look back on what state the code was in.

We wanted to introduce something similar into PlayCanvas, so that you can log messages which you and your team can use to track development of your game. But we wanted to do more than just that. A PlayCanvas project is more than just a collection of your assets, it’s your link to your game’s fans; it’s an advert for your game and what you want your game to be; and it’s a place to gather feedback about what people love (or don’t love) about your game.

So introducing:

The DevLog

Every PlayCanvas project now has a DevLog, you can find yours on the right-side of the navigation bar with a little speech bubble icon. (Yeah, we know it’s pretty hidden away at the moment, we’re working on that).

Think of the DevLog as part commit message, part blog, part twitter stream. Use it to let people know what you’ve been working on. Perhaps each day you will do a update summary, maybe you’ll do 5 a day, or one a week. Whatever works for you. People who come to your project page can read your log to find out about your project. In the coming weeks we’ll be featuring log posts on the front page of the site so that everyone can see what is going on across PlayCanvas’s thousands of users.

Features

Primary, the DevLog is a place for you to write about your game. But you’re a creative bunch so we wanted to give you a little more than just a text box.

Markdown

Markdown is a simple way to let you add styles, links, images to your text. The markdown syntax is easy to learn and remember. We don’t host images (yet) so you’ll have to make do with images that are already on the web somewhere else (for the moment).

Emoji

Emoji is like smileys++. Use the emoji cheat sheet and enter your emoji by including a keyword between to colons. Like 🙂

Preview

Use the preview tab to see what your post will look like with all the styles, images and emoji.

Let us know what you think of the new feature.

WebGL on iPhone in less than a minute

If you’ve been following the tech news over the last few months you’ll have noticed that Apple is about to launch the latest version of their mobile operating system iOS 8. For us game developers this is awesome news because iOS 8 supports WebGL in mobile Safari (the news we broke on this blog a few months ago).

It’s not just browser support for PlayCanvas games we’re interested in though. We also want to make sure you can get your PlayCanvas into the App Store. So, in advance of the iOS 8 release, we’re really pleased to be launching a new feature today for our Pro users.

PlayCanvas iOS Export

It’s now dead simple to get your PlayCanvas game running as a native iOS application. Take a look at our little video introduction.

It’s just one click to get a XCode project which is easy to build into a iPhone application.

Web vs Native

PlayCanvas is designed to use all the best features of the web, online collaboration, accessible from every device and shareable links. But that doesn’t mean we don’t see the advantages of native applications, especially on mobile. Installed games are run offline and can be easier to monetize.

You can now get the best of both worlds by releasing your games on the web and on iOS. Use the web to build viral, shareable games and release the same game on iOS, where the audience is ready to monetize.

Give it a try

If you’re a Pro account holder, you’ll see the iOS download right now in your exports tab. Get yourself a copy of the XCode 6 GM from the Apple Developer site and try it out. If you’re not a Pro account holder, what are you waiting for? Get yourself upgraded right now! 😉

PlayCanvas Update 20/06/14

Now it really has been a busy week for us and we have so much to tell you about. Here’s a run down on improvements to the engine and what happened behind the scenes at PlayCanvas this week. 

User Camera View

You can now view your scene from any Entity that has a camera component in your scene. Either right-click in the 3D view and select the camera you want from there, or alternatively do it from this new combo box (below). You can also move the selected camera wherever you want using the normal camera controls in the Designer.

Cam combo

Entity Context Menu

We added a new Entity context menu that appears when you right-click on an Entity in the 3D view. From there you can see all the parent Entities of the selected Entity up to the root and you can select a parent Entity easily. You can also see more options for Entities like Delete, Add Component, etc.

Entity context

Error Console

Whenever you try to launch a game from the Designer you will see errors in a new console, so you no longer need to wonder why the game is not loading. You can click on the problematic script and get transferred to the code editor at the offending line.

error console

Shadow Distance

We added Shadow Distance in the Scene Settings, a value that controls that maximum distance from the camera from which shadows coming from Directional Lights are visible. Just toggle your scene settings to adjust it. This makes shadows from Directional Lights visible in the Designer as they no longer rely on the frustum of the camera. Read about Shadow Distance here.

Events & Oculus Rift Support

We also showed our faces at a number of events this week. Dave showed off some of our work with the Oculus Rift at the Scenario Bar (as seen above) and we ran a Swooop high score challenge at the IDEA London summer party.

VR night

Stay In The Loop

Follow us on Twitter, @playcanvas, for updates on PlayCanvas.

Like the PlayCanvas Facebook page for our whimsical views on the game dev scene.

Join and start discussions on the PlayCanvas Forum.

Get expert responses to your questions on PlayCanvas Answers.

PlayCanvas Update 13/06/14

construction_kit-001

After a busy week here in the PlayCanvas office, we thought what better way to champion our efforts than to give you a taste of whats happened at HQ. We plan to start a series of weekly updates so you know what is keeping PlayCanvas at its best. This week; 

  • We completely reworked our back-end API. All page loads are now 50% to 1000% times quicker.
  • We have also made an improvement to the manoeuvrability of Entities as we introduced a new default Snap option. This function allows you to move incrementally within the PlayCanvas Designer (find more information on the Snap function here).
  • Lastly we are happy to introduce a brand new platform starter kit which features a contribution from the artist who worked with us on Swooop! (read all about it here).

Stay In The Loop

Follow us on Twitter, @playcanvas, for largely technical updates on PlayCanvas.

Like the PlayCanvas Facebook page for our whimsical views on the game dev scene.

Join and start discussions on the PlayCanvas Forum.

Get expert responses to your questions on PlayCanvas Answers.

Snappy New Update

Game developers and the idea of perfection are never far apart and we are pleased to announce a new feature that allows you to be as precise as your project demands. If you were thinking what we were thinking then…SNAP!

snap screenshot

Due to popular demand (coming in particular from PlayCanvas user Crefossus), Entities now move incrementally as default. This feature allows you to quickly measure and perfectly place where your Entities need to be, no need to rotate the camera to make sure your items are perfectly in line.

However if the fate of your game rests on being between our increments, have no fear. Holding shift will disable Snap while in the PlayCanvas Designer, you can also check and toggle the status of the snap function by using the magnet icon on your toolbar. Here’s some help, just in case.

snap_tool

http://developer.playcanvas.com/user-manual/designer/designer-settings/

Happy Snapping!

Primitives are dead! Long live the Model!

One of our most requested features has landed today, and with it, it brings new power (and no new responsibility). Our most requested feature? Applying textures and materials to primitive shapes in the Designer.

A bit of history

When we created the primitive component, we had simplicity in mind. Create box, set the color. That’s it. Also, this was another time, when material editing wasn’t available as part of the PlayCanvas Designer. So we created two components, the model, which allowed you to upload a 3D asset complete with materials and textures; and the primitive, the little brother, which only allowed you to set a color.

To get us going this was great, but pretty soon you all started demanding more from the primitive. First it was a lack of a setVisible() method which existed on the model. Then you wanted to set a texture map, but in reality you wanted a full-on material.

Long live the Model Component!

Once we realized we were going to be recreating the primitive component with these new features, we gave it a bit of thought and came to the conclusion that the primitive is just a model component with a special built-in set of models, i.e.  box, sphere, capsule, etc. So, combining the two makes perfect sense. We give you the power and flexibility of the model component, but with the ease and speed of the primitive component.

How it works

He’s a quick 4 step guide to create a primitive and applying a material.

1. Upload some textures. For example these brick textures from gametextures.com

2. Create a New Box. From the Entity menu select “New Box”

3. Click on the Box to select it, then click on the Box again to select the material.

4. Click Create Material, then open up the diffuse and normal panels in the Material Editor and drag the assets from the Asset Explorer into the material slots.

Primitive Materials

We hope you enjoy the new power we’ve given you today. Just enjoy it responsibly. 😉

For more information on materials see the page in our documentation

Incoming Breaking Changes – New Maths API

Our new maths API will make your life so much easier, but it will require updating your game.

Maths

One of the first things that is written for a new game engine is the Maths library. A critically important base for your engine and used by almost every game that is written using the engine. The Maths library must be fast, consistent and succinct.

The PlayCanvas engine was first started almost 3 years ago, so the Maths library is already a venerable old friend. But it’s a friend that is in need of a facelift. (!? – Ed) So in the next few days we’ll be releasing Maths v2.0 for our Engine.

What does this mean for you?

First let’s give you a little sample of how the Maths library is going to work.

Here is some code from our recent Ludum Dare game Going Around.

 // In this code, we get the camera position,
// We convert a mouse click into world space
// Then we calculate the ray end point from
// the mouse click using a variety of vector operations
 pc.math.vec3.copy(camera.getPosition(), this.rayStart);
camera.camera.screenToWorld(event.x, event.y, 1, this.rayEnd);
pc.math.vec3.subtract(this.rayEnd, this.rayStart, this.rayEnd);
pc.math.vec3.normalize(this.rayEnd,this.rayEnd);
pc.math.vec3.scale(this.rayEnd, RAY_LENGTH, this.rayEnd);
pc.math.vec3.add(this.rayStart, this.rayEnd, this.rayEnd);

context.systems.rigidbody.raycastFirst(this.rayStart, this.rayEnd, this.onRayHit.bind(this));

This is what this will look like in the new API.

this.rayStart.copy(camera.getPosition());
camera.camera.screenToWorld(event.x, event.y, 1, this.rayEnd);
// subtract, then normalize, then scale by RAY_LENGTH, then add
this.rayEnd.sub(this.rayStart).normalize().scale(RAY_LENGTH).add(this.rayStart);
context.systems.rigidbody.raycastFirst(this.rayStart, this.rayEnd, this.onRayHit.bind(this));

As you can see we now support chaining vector operations together. This makes the code more concise, and also more readable. If you read through the line you can see we subtract, normalize, scale then add. All into the same vector.

This shows you how it will work for vector3’s, but these changes apply to all our maths primitives, such as Matrices and Quaternions.

So, hopefully, you can see that the new maths library is going to be an all round better beast, but obviously it does mean breaking changes. Even though our engine is pre-1.0, we never issue breaking changes lightly. It’s a pain for you and it’s a pain for us. But in this case it’s important that such a fundamental piece of the engine is easy to use and “just right”.

When is it going to break?

We doing the final round of testing at the moment, just to make sure everything works perfectly. We’ll be deploying the into the engine very soon  (today or tomorrow). This is a heads up so you know why we’re doing it.

After we deploy, we’ll be updating all the samples and examples to use the new API. This will take a little bit of time, so some of them may not but up-to-date immediately

 

Friday Assets mega-update

Drag and Drop, uploading and thumbnails, no longer a pain in the asset.

This week has been the week of the Asset at PlayCanvas. We taken a long hard look at how we add and use Assets and we’ve buffed and polished the process, taking off the ragged edges so that your workflow is now super smooth. Plus our big new feature, the PlayCanvas Asset Library. Find out more below

Use pre-made 3D models in your game

Use pre-made 3D models in your game

Uploading to the Designer

You can now drag and drop files from your desktop straight into the Designer. This means you never need to leave the Designer tab. Even better, if you drag an 3D model file (like an FBX) into the 3D view, your model will be uploaded, converted and a new Entity with model component all set up will be created for you. So it’s super easy to get models into your Pack.

Asset Explorer Polish

Up until now the Asset Explorer wasn’t terribly useful. We hid it away at the bottom of the screen and we didn’t really tell anyone about it, because there wasn’t much to it. Now, though, we’ve given it a complete revamp. We’ve added one-click filters for listing only the assets you’re interested in. Plus, now there are texture thumbnails and you can now drag assets from the Explorer into other part app, but more of that next…

Drag and Drop Everywhere

You can now drag Assets from the Asset Explorer and drop them into many different places. The first is simple, if you drop a model asset into the 3D view, you’ll get a new Model Entity. But also you can drag Assets and drop them into Asset pickers in any of the components that accept assets. This applies to models, animations, audio, etc, but also when you are editing Materials, you can just drop the textures into the slots. Speaking of textures…

Texture Thumbnails

Texture assets now have thumbnails

Texture assets now have thumbnails

We’ve started working on thumbnails for all Assets, but as a quick starter, textures now display with the proper thumbnail. No more guessing which one is the normal map when you’re setting up your materials. Thumbnails for more Asset will be done soon.

Asset Library

Have we saved the best feature until last? Maybe. Certainly the Asset Library is going to make it much easier for our new users to get something looking pretty. We’ve teamed up with lovely folks at http://3dmodels-textures.com/ and http://www.propsplanet.com/ to give you a selection of 3D models which you can use to get started. Click the big red Asset Library button to open up a list of models and one-click to add them to your Project.

We encourage you to check the free assets from the kind folks and then head over to their websites and see all the other awesome stuff they have on offer.

See Your Friends!

See what all your friends are looking at, as remote user cameras show up in the Designer.

The new features keep on coming from the PlayCanvas mines of awesome, and today’s is a biggie.

We’re now displaying the camera’s of all the users who are viewing your pack. Now it’s really starting to feel like a collaborative process when you are building your game.

So, invite your friends and get building!

Let us know what you think about this feature in the forums