Quick Start Guide

Gameface is meant to always run inside an external application that provides its frame control/input/file handling/etc. This means that in order to fully use it you need to integrate it inside you game engine first. This can be cumbersome when you want to get started with the product quickly, so this guide will give you a few approaches that can help you get up to speed as swiftly as possible. Keep in mind that no matter which approach you take, it is usually a good idea to take a look at the Gameface launcher first, which will take you through the most important parts of the archive you received. You can start the launcher by running the QuickStart.bat / QuickStart.sh in the root of the archive.

Ways to start using Gameface

For content developers

If you just want to check out the front-end functionalities of Gameface, integrating it in your game first is not actually needed. Instead, you can use the provided Player, which is basically a pre-built application that runs Gameface inside of it and lets you develop and preview HTML pages as if they were running inside a game engine, without having to implement a single line of integration code. You can even mock game data or change the player settings to simulate your actual game environment as closely as possible.

If you want to preview an existing integration first

The sample applications coming with Gameface are available in the /Samples folder. They showcase different features of Gameface, but all rely on the CohtmlApplication class. This class simulates a game engine and contains a full pre-written implementation of the steps needed to set up and run Gameface, which you can consult freely. Keep in mind that the CohtmlApplication contains lots of optional or feature-specific code, which makes it very comprehensive, but also quite noisy.

If you want to set up your initial integration in as few steps as possible

The bare minimum steps needed to run Gameface are as follows:

  1. Provide an external allocator and resource handler for Gameface to use. You can do this by implementing the cohtml::IAllocator and cohtml::IAsyncResourceHandler interfaces. All Gameface dynamic memory allocations and file requests are going to go through them.
  2. Initialize the Library object. It simply encapsulates the Gameface library and acts as a starting point to the initialization process and a container for some global settings. You should also dedicate (and possibly start) at least 1 worker thread and pass it to the Library object.
  3. Initialize the System object. This object can spawn and own multiple “screens” worth of UI (referred to as Views). User interfaces created with Gameface usually require only one System.
  4. Initialize the SystemRenderer and provide it with a backend. Gameface comes with several different pre-implemented backend integrations (i.e. Dx11/Dx12/OpenGL/etc.) - you simply need to initialize one of them and pass it to the SystemRenderer.
  5. Create your View object. It will hold and draw a single HTML page. All view have their respective ViewRenderer object. This object is in charge of drawing your page and should be passed a texture in which to draw.
  6. You can now load a page inside your View by passing in a URL. From now on, it is just a matter of updating your loaded page every frame.
  7. Somewhere inside your game loop, every frame you should:
    • Call Advance on the System and View(s). This will forward all internal timers, CSS animations, execute JavaScript, etc.
    • Call Paint for every View, using its respective ViewRenderer. This will output the final look of your HTML page for a given frame inside the provided texture.
    • Draw the provided texture on the screen somewhere in your game or application.
  8. After your game loop ends, uninitialize all components listed above in the order opposite of their creation.

In order to build your game with Gameface, you also need to:

  • Add the headers inside include/cohtml/ to your project include paths.
  • Set up the link dependencies of your project to contain the relevant Gameface libraries. On Windows those would be:
    • cohtml.WindowsDesktop.dll/lib and RenoirCore.WindowsDesktop.dll/lib for the core functionality
    • v8.dll and v8_base.dll for the JS Virtual machine
    • dx11backend.lib for the backend implementation

You can see a much more detailed explanation of all setup steps inside the Extended setup guide

Sample Framework →