Using Ionic in PlayCanvas

  • What is Ionic?
  • Why use it with PlayCanvas?
  • How to use the template project?
  • What to be careful of?

This tutorial aims to introduce the Ionic to PlayCanvas template project. Using the Ionic Framework PlayCanvas applications can deliver a great mobile-friendly UX with a minimal effort.

This tutorial assumes a minimal knowledge in using the PlayCanvas editor.

Ionic to Playcanvas gif

 

What is Ionic?

Ionic is an HTML5 mobile app development framework targeted at building hybrid mobile apps. It is open-source and uses Cordova for mobile deployment. With the advent of PWA (Progressive Web Apps) Ionic supports deployment in web browsers and can be used as an excellent UI library for 3D apps that require heavy duty interfaces.

When Ionic was first released?

The original version was released in 2013 and built on top of AngularJS and Apache Cordova. Ionic was created by Drifty Co. in 2013. Drifty's previous products have included Codiqa and Jetstrap, which are drag-and-drop interface building tools building on jQuery Mobile and Bootstrap, respectively. Taking feedback from customers who tried to build mobile apps, the team decided to build their own framework that would focus on performance and be built to modern Web standards. In 2015, Ionic developers reportedly created over 1.3M apps with the SDK.

The current version of Ionic (v3) uses Angular 3 and the due to be released version 4 will use the latest Angular 4 build.

Ionic uses Typescript as its main development language.

What is Angular?

AngularJS is a JavaScript-based open-source front-end web application framework mainly maintained by Google and by a community of individuals and corporations to address many of the challenges encountered in developing single-page applications. Angular is a platform that makes it easy to build applications with the web.

What is Typescript?

TypeScript is a free and open-source programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript, and adds optional static typing to the language. TypeScript is designed for development of large applications and compiles to JavaScript. As TypeScript is a superset of JavaScript, existing JavaScript programs are also valid TypeScript programs.

 

Why use it with PlayCanvas?

Ionic iOSPlayCanvas projects most of the time feature single-page applications that contain a canvas rendering 2D/3D, with some form of UI. Following the release of the new 2D API creating a user interface became much easier and quite powerful. Using the new Screen and Element components is the recommended way of drafting and deploying user interfaces for games and game-like applications that don't require special and complex UI widgets.

For applications though that require a complex interface the common way in approaching this is using HTML/CSS. This opens up many possibilities due to the popularity of those languages and here is where Ionic can help.

Ionic provides an extensive list of ready-to-use components and takes care of compatibility issues in styling and user interaction between browsers (deployment environments).

Here you can find a list of the available components.

 

How to use the template project?

We have released a template project in PlayCanvas that makes the integration of Ionic easy and straightforward.

The project can be found here.

It allows integrating an Ionic app with the project inside the PlayCanvas editor. An easier way to integrate might be exporting a PlayCanvas build and using it in an iframe in your Ionic project. 

Both solutions have their pros and cons depending on the use case and the development pipeline. We will use the first one here, to integrate Ionic inside the PlayCanvas editor.

How do we begin?

From the Ionic side what we need is a finished build. Ionic supports several platforms through its Cordova integration, iOS, Android and lately a Browser platform has been added to support the PWA (Progressive Web Apps).

What are PWA?

A Progressive Web App (PWA) is a web app that uses modern web capabilities to deliver an app-like experience to users. These apps meet certain requirements (see below), are deployed to servers, accessible through URLs, and indexed by search engines. This can work in conjunction with Cordova to provide a multiple deploy targets for all your users. You can deploy your app as a PWA as well as Native app and take advantage of both channels. Ionic allows you to ship your app to not only the app store, but also deploy to the mobile web as a PWA.

If you plan in wrapping your Ionic project with Cordova you can use a cordova build, for this tutorial though we are will be using a simple browser build.

A single script is provided in the template project called ionic-load.js which exposes properties in the editor to push the files from the Ionic build.

Ionic to PlayCanvas integration script.

Let's walk the properties one by one.

  • css: The minified style file (.css) exported from the Ionic build. Usually it is named main.css.
  • scripts: The scripts found inside the Body tag in the index.html file of the Ionic build. Important: their extension needs to be changed to .txt and not .js when uploaded and attached. As we can't use the default PlayCanvas script asset type for this scripts, we will be loading them in async, using Javascript. Also, they have to be inserted here in the order found in the index.html, which is the order they will be executed.
  • ico: The favico file, for the HTML header, which is usually found in assets/icon/ of the Ionic build. This is optional and can be omitted.
  • PlayCanvas texture POT setting.imagesTag: Images used in the Ionic project which need to be uploaded and tagged with this tag. Be careful when uploading the images to PlayCanvas to disable the automatic conversion to PO2, as this will make your Ionic images stretch. The setting can be found in your project settings under Asset Tasks.
  • imagesLocalFolder: Folder path, relative to the base folder the images are found in the Ionic project.
  • fontsTag: Fonts used in the Ionic project which need to be uploaded and tagged with this tag. Important: the extension of all .ttf fonts needs to be changed to .txt before uploading. This is because PlayCanvas will automatically detect your ttf fonts and convert them to bitmap fonts to use with 3D rendering. So we need to keep them out of the conversion pipeline and upload them as simple text files.
  • fontsLocalFolder: Folder path, relative to the base folder the fonts are found in the Ionic project.

So, the process to load and run your Ionic interface on top of PlayCanvas goes like this:

  1. Grab the Ionic files from your build.
  2. Upload them following the guidelines explained above in your PlayCanvas project.
  3. Attach the ionic-load.js script in an entity (usually the Root) and fill the properties.

You can launch the project and enjoy your powerful new UI! Here is a sample Flickr project that loads popular photos in random and renders them in a space TV set.

Ionic to PlayCanvas build
https://playcanv.as/index/hGaliqeL/

 

What to be careful of?

Some things to keep in mind while developing in Ionic for PlayCanvas.

Ionic < - > PlayCanvas communication

If your project requires some kind of communication between the two framework instances, that can be done easily using the PlayCanvas events API.

You can grab an instance of the PlayCanvas application running in your Ionic codebase and fire and receive events to and from PlayCanvas.

To do that declare a pc variable on top of your Ionic class like this:

import { Component } from '@angular/core';
import { NavController } from 'ionic-angular';

declare var pc: any;

@Component({
  selector: 'page-about',
  templateUrl: 'about.html'
})
export class AboutPage { ...

And inside the class you can use the following code to handle events:

ionViewDidEnter(){

  if( pc.app !== undefined ){
    pc.app.fire('ionic:aboutPageEntered');
  }
}

The event will be fired and can handled in your PlayCanvas project in the same manner as the usual events. One thing to keep in mind is that because Typescript is strictly typed we need to insert the PlayCanvas engine script in our index.html while developing. To avoid the compiler complaining all the time.

Add in the head section of your Ionic index.html file the following:

<script src="https://code.playcanvas.com/playcanvas-latest.js"></script>

This code will grab the latest build of the PlayCanvas engine and make the compiler happy. Keep in mind that there is no need to keep that in place when you compile the final build, but only while developing with Ionic. When you push the ionic build to integrate with PlayCanvas, just comment that line out.

Ionic < - > PlayCanvas user input collisions

PlayCanvas by default grabs all mouse/touch input happening in the app window. This usually creates collisions with HTML/CSS interfaces built on top of it.

We can fix this easily by using a special CSS rule, called pointer-events.

For example in the template project we had to put the following rules to allow PlayCanvas to grab the events in the main content area between the header and the footer, but also allow clicking on the tab elements on the footer.

// --- custom css rules to allow UI interaction with the Canvas element
jQuery('#ionic-app').css('pointer-events', 'none');
                
jQuery('#ionic-app .tabbar').css('pointer-events', 'auto');

jQuery('body').on('mousedown mousemove mouseup mousewheel', '#photos-list', function(evt) {
   evt.stopPropagation();
});
    
jQuery('page-contact .scroll-content').css('pointer-events', 'auto');

If we would like an additional element/component from Ionic to listen/interact with user input events we will add the pointer-events CSS property and set it to auto.

Check this github issue from the PlayCanvas bug tracker to learn more about this.

 

Isn't that exciting?!

Yes, truly is! Ionic is an excellent framework that makes it easy to build great UI experiences for all kind of devices.

PlayCanvas is an amazing tool providing interactive content experiences in the web.

The combination of these two can unleash your creative powers!

If you like these tutorials and you would like to see them coming, please support us on Patreon. Every contribution helps to push more and more tutorials and projects to the community.