Extended Setup Guide

Custom Initialization

This guide focuses on the content of the Gameface package and the process of setting it up in greater detail. If you prefer a simplified version, you can refer to the Quickstart Guide. The Quick Start guide will show you how to create a simple CohtmlView and provide you with an overview of the Library, the System, and View components in the following sections. We will also show you how to customize the behavior of the native Cohtml components to fit your project’s requirements. While all resources in your UI can be loaded out of the box, there are several ways to improve the performance or flexibility, which you can check out below:

  1. Check out the Library parameters and optionally how to override the settings you want.
  2. Check out the system settings and optionally override its settings.
  3. Decide how you want to spawn your UI and where will be placed - UI or in-world.
    • Decide if you want your UI to reside inside a Unity UI, or to take a simpler component-based approach.
  4. Check out how to adjust the Input Handling according to your needs.
  5. Check out how to use various resource-handling mechanics:
  6. Consider checking out these features:
  7. Configure the UPM package before building your application.

Main package components

Library

The Library object has the following general purposes:

Override the Library Settings

You can configure some of the Library parameters through the Library Configuration window. To override settings of the Library, you should use the static event LibraryParamsManager.OnCustomizeExtendedParams event, which passes the object as a parameter, allowing you to modify before it the library is initialized. You can see the example below for reference.

LibraryParamsManager.OnCustomizeExtendedParams += libraryParams =>
{
    // Customize the libraryParams object here and return it
    return libraryParams;
};

You can check these major settings:

  • UseCSharpRenderingBackend - Using Unity’s C# rendering API, instead of the native rendering library provided by Gameface. More information here.
  • Default Style Font Family - Sets the default font family that will be used by all Elements in the Views. The default font style is analogous to setting the CSS property “font-family” of all elements to the value of this field. More information here.
  • EnableInternalAllocator - The internal memory allocator efficiently reuses already allocated memory, which enhances performance at the cost of some memory overhead The internal memory allocator is enabled by default. By disabling the internal allocator Cohtml will free any unused memory to the client immediately, which will reduce the overall memory footprint.
  • LoggingSeverity - Configure the level of logging information level displayed by Cohtml.

The Library is instantiated upon the first launch of the Unity3D editor or player and will not be released until the application is closed. If you want to change the settings, you need to restart the application to apply them. To modify the default settings of the Library, you can do so either through the inspector or through a script.

Cohtml Plugin Manager

The CohtmlPluginManager component is essential for integrating Gameface with Unity3D. It listens for important Unity3D method events, such as those related to initialization, updating each frame, and shutting down. This subscription allows it to manage the setup and cleanup of necessary resources and objects throughout the application’s life cycle. Specifically, it ensures that systems are properly initialized, updated every frame, and destroyed in the correct order when the application exits.

  • The component is created when the application starts and is unique for its entire lifetime until it is stopped. If an additional object is created, it will be automatically deleted.
  • The component’s object is marked to not be destroyed when switching scenes, so it is not recreated and its destruction should only occur when the application stops or editor closes. This ensures the correct destruction workflow for Cohtml native plugin objects.

System

The CohtmlUISystem component contains general contextual information shared between its created Views. The Gameface integration will ensure that when a CohtmlUISystem component is needed, it will be created if one does not already exist. It has the following features:

  • CohtmlView always requires a CohtmlUISystem at the time of its creation. If you create such a CohtmlView component and there is no CohtmlUISystem in the scene, will create a default CohtmlUISystem with default SystemSettings.
  • When you have a created CohtmlUISystem with custom CohtmlSystemSettings and create a CohtmlView without referencing it to the CohtmlUISystem, it will reference it automatically.
  • When you have more than one CohtmlUISystem on the scene, it is your responsibility to reference each created CohtmlView to the specific CohtmlUISystem; otherwise, you will encounter an error because automatic referencing cannot determine which CohtmlUISystem the CohtmlView pertains to.

Override the CohtmlUISystem Settings

If you want to customize the spawned system behavior of your Views, you need to add the CohtmlUISystem and CohtmlSystemSettings components to a game object. This can also be achieved with a script by subscribing to the CohtmlUISystem.OnSystemCreate callback. See the example below for reference.

CohtmlUISystem system = new GameObject("System with custom Settings").AddMissingComponent<CohtmlUISystem>();

system.OnSystemCreate += settings =>
{
    // Change the settings object's properties here. For example change the Resource handler implementation
    settings.ResourceHandler = new CustomResourceHandler();
    // Finally, return the modified object.
    return settings;
};

You can check these major settings:

  • ResourceHandler - Defines how and from where to load asynchronous requests when needed by CohtmlView. For more info, you can check the Native API documentation.
  • LocalizationManagerInstance - Implementing localization into your UI, allowing you to dynamically translate the content of an HTML page. Any HTML element created with the data-l10n-id attribute will get its text content replaced by the value returned from this object’s Translate method.
  • TextTransformationManager - Support text transformations. The class is used when the CSS text-transform property is used.

For more customization options, please refer to Custom Systems page.

These operations involve creating objects and adding components during runtime through the Unity3D Engine API, which is not the most optimal way of working. Therefore, the optimal option is to have it in the scene when launching the game, or you can use a Unity3D prefab object that contains everything necessary for the Cohtml System. For optimal performance, you can create a CohtmlUISystem at the start of the application and mark it to persist through scene loads using the Object.DontDestroyOnLoad method. This way, it won’t be destroyed when exiting a scene and won’t need to be reinitialized in the new scene. Each CohtmlView object that requires the system will automatically reference the persistent CohtmlUISystem upon creation.

public GameObject persistentSystemPrefab;
...
GameObject persistentSystem = Object.Instantiate(persistentSystemPrefab);
Object.DontDestroyOnLoad(persistentSystem);

View

The View represents a UI page with its DOM, styles, and JavaScript context. The View has a different type based on where you render it, On Screen - as a HUD or in-world - in the 3D space in the scene. To create a new Cohtml HUD View, you need to add the component to any game object. Then you can configure each of its available properties visible in the inspector. This can also be done through scripting. Use this example as a reference.

CohtmlView cohtmlViewComponent = Camera.main.gameObject.AddComponent<CohtmlView>();
cohtmlViewComponent.Page = "coui://UIResources/[your-html-path]/[your-html-page].html";

In-world Cohtml Views require additional setup involving MeshRenderer and MeshCollider components. For this purpose, there is the CohtmlView.AddMissingWorldViewComponents method, which you can call dynamically.

CohtmlView cohtmlViewComponent = new GameObject().AddComponent<CohtmlView>();
cohtmlViewComponent.AddMissingWorldViewComponents();

To modify the settings of a CohtmlView upon creation, you need to modify the ViewSettings through the CohtmlView.OnViewSettingsOverride event. This method executes at the specified moment before a native Cohtml View is created. Currently, this can only be done through scripting. Please, refer to the following example.

cohtmlViewComponent.OnViewSettingsOverride += settings =>
{
	settings.Listener = new CustomViewListener();
	return settings;
};

You can check these major settings:

  • EnableComplexCSSSelectorsStyling - Complex CSS selectors when doing style matching. By complex in this context, we mean any CSS selector that requires walking the DOM tree to match.
  • Listener - Allows to listen for various events in the View.
  • InterceptResourceRequests - Allows you to intercept resource requests for this view to restrict resource access of the view to only specified sets of URLs. To intercept requests, you need to override the Listener.OnResourceRequestIntercepted method.
  • TextInputHandler - Notifies of changes to HTML input elements. You can check more information here.
Plugin Architecture →