Unity Plugin Integration Guide

Tutorial

A full video walkthrough covers the integration from Unity Hub to publishing.

Prerequisite

Installing Unity

GamePix Unity Plugin officially supports the following versions of Unity:

• 6000.0 - 6000.5
• 2023.*
• 2022.*
• 2021.*
• 2020.*
• 2019.*

Not recommended Unity releases:

• 2021.1 and older (issue #1178725, issue #1325989)
• 2021.2 (issue #1411380)

To publish your game on GamePix portal you need to install Unity with WebGL Build support:

Click to enlarge

In this guide we will use Unity 2020.1.17f

Obtaining the project

Download our sample project from here

This is a fully functional game designed to help you getting started with Unity and GamePix plugin.

Installing GamePix plugin

• Download latest version of GamePix plugin for:
• Unity 2019.1 - 2021.1
• Unity 2021.2 - 2022.1
• Unity 2022.2 - 2023.1
• Unity 2023.2 - 6000.4
• Unity 6000.5
• Extract the contents of this archive inside the sample project's Assets folder.

At the end, the plugin should be in the Assets/Plugins/GamePix directory.

Using the Plugin

Building the project

Open the project in Unity and then switch the platform to WebGL in "Build Settings".

Click to enlarge

IMPORTANT: Ensure that there are no errors in Unity console. If you have some, please fix them before going forward.

It's also recommended to update all your packages to their recent versions.

Set default canvas width and height for the game (Menu "Edit" -> Project Settings -> Player -> Resolution and Presentation).

Click to enlarge

Default canvas width and height will be used to calculate the game aspect ratio.

IMPORTANT: In browser the size of the game canvas will change automatically depending on the screen size, but the aspect ratio value will remain constant.

If GamePix plugin was correctly installed, then the Unity Editor will show the GamePix menu item.

Click to enlarge

IMPORTANT: Recommended to make a backup copy of the project or use a version control system.

IMPORTANT: Before build make sure that there are no important data in the folder html5. It will be cleared.

Gamepix plugin will change texture and sound settings for WebGL platform to ensure their maximum quality. All previous settings for all textures and sounds for WebGL platform will be lost.

Overridable settings for other platforms will remain unchanged.

Press Build and Run from the menu.

Click to enlarge

If needs to save your texture and sound settings for WebGL, select for build:

• GamePix>Safe builds->Build and Run (No override textures\sounds)

However this is not recommended, because the quality of the game may be insufficient.

You should wait until the build process is finished. It may take a long time. However, at the end of the build process Unity will automatically start the browser with your game. Please check that the game works correctly in the browser.

Click to enlarge

Publishing the project

After a successful build, the archive with the game will be placed in the folder html5 and will have a name like CompanyName_GameName_GameVersion.gpx.

Open the GamePix dashboard and follow the instructions to publish gpx archive. Don't worry that the file is very big, the game will be optimized and minified by GamePix publishing system.

Integrating GamePix SDK

The GamePix game SDK provides a series of utility methods needed for running your game in the GamePix ecosystem. They enhance the user experience of your game and complete the integration with our ads network and revenues system. We assume that you already read the SDK Documentation.

Automatic integration

GamePix Unity plugin will try to automate everything as much as possible. The below features will be automatically integrated, do not try to integrate them manually:

• Build will already have the latest SDK linked to it
• GamePix.loading, GamePix.loaded, GamePix.pause, GamePix.resume will be managed by the plugin itself.
• GamePix.localStorage will be used by Unity under the hood. You can use default unity storage system, it will be mapped to GamePix.localStorage automatically.

Manual integration (Optional)

Inside the plugin SDK features are logically structured and put inside GPX global object. You may need to manually integrate:

• GPX.CurrentLanguage - gets the current preferred language by the player
• GPX.Ads.InterstitialAd - request to show interstitial advertisement
• GPX.Ads.rewardAd - request to show reward advertisement
• GPX.Events.UpdateScore - should be called immediately every time the current score is updated

The sample project already uses some of this features in Assets/Scripts/Gameplay/PlayerEnteredVictoryZone.cs

Pause

Interstitial and reward ads require the game to be paused, but browsers can't completely block the main thread, like on other platforms.

The plugin pauses Unity time-dependent event (animations, time-dependent moves, coroutines, etc) and sounds internally.

If needs to pause time-independent functions, you can use bool value (read-only):

Gpx.IsGamePaused

which shows that an ad is being displayed.

For example, the following code pauses the rotation while an ad is running:

public class SampleScript : MonoBehaviour
{
    [SerializeField] private float tilt;

    private void Update()
    {
        if (Gpx.IsGamePaused)
        {
            return;
        }

        transform.Rotate(Vector3.up * tilt);
    }
}

Interstitial Advertising

The Intersitial ad should be shown periodically, for example: you can show this ad when the player finishes the level.

The InterstialAd method has only one optional argument - a callback that will be called when the ad is finished. However, you can omit it and use it like this:

Gpx.Ads.InterstitialAd();

Another example with callback:

using GamePix;
using Platformer.Core;
using Platformer.Mechanics;
using Platformer.Model;

namespace Platformer.Gameplay
{
  // <summary>
  // This event is triggered when the player character enters a trigger with a VictoryZone component.
  // </summary>
  // <typeparam name="PlayerEnteredVictoryZone"></typeparam>
  public class PlayerEnteredVictoryZone : Simulation.Event<PlayerEnteredVictoryZone>
  {
      public VictoryZone victoryZone;

      PlatformerModel model = Simulation.GetModel<PlatformerModel>();

      public override void Execute()
      {
          // show interstital ads
          Gpx.Ads.InterstitialAd(OnInterstitalAdSuccess);

          model.player.animator.SetTrigger("victory");
          model.player.controlEnabled = false;
      }

      private void OnInterstitalAdSuccess()
      {
          Gpx.Log("Interstitial advertising was shown successfully");
      }
  }
}

IMPORTANT: If the message "[GPX] Interstitial ad already called" is displayed, the function is called multiple times before the ad is displayed. This needs to be fixed.

Reward Advertising

The Reward ad should be used when you want to reward the player after watching an ad. The RewardAd method takes two arguments: success and fail callbacks. Success is called when the ad is watched to the end and fail is called in all other cases.

Example of using RewardAd:

private static Action onSuccess;
public void ShowRewardAd(Action success)
{
    onSuccess = success;
    Gpx.Ads.RewardAd(OnRewardAdSuccess, OnRewardAdFail);
}

private void OnRewardAdSuccess()
{
    Debug.Log("Reward received");
}

private void OnRewardAdFail()
{
    Debug.Log("Reward not available. Try again later.");
}

IMPORTANT: If the message "[GPX] Reward ad already called" is displayed, the function is called multiple times before the ad is displayed. This needs to be fixed.

Troubleshooting

Too large WebGL data file

Use for build:

• GamePix>Safe builds->Build and Run (Compressed textures\sounds)

All textures (except NPOT) and sounds will be lossy compressed. NPOT textures can be compressed after the scale to power-of-two option is selected in Unity Editor.

This will reduce quality, but may help build the game. However this is not recommended, because the quality of the game may be insufficient.

If nothing helps, you can ask GamePix support to help build your game.

Freeze

If game freezes in browser without any error in browser console, it likely run into infinite loop. You should check the code and avoid any infinite loops. Like this:

if (UseOnlineTime)
{
    WWW www = new WWW(OnlineTimeUrl);
    while (!www.isDone)  {  }
}

Best Practices

Take in account that our target environment is a default mobile browser (Safari, Android Webview, etc).

Do not expect that environment will support very recent desktop related technologies.

Most common environment will be WebGL 1 without any extension. Please try to use this basic stack only.

Another important thing - target environment is Single Threaded, do not run any long-running background task.

However, all this tips are optional you should follow them to create most optimized and minified version of game.

Assets and packages

Delete all unused assets and packages.

It is highly desirable that everything not used in the game be deleted from both Assets and Packages folders.

Packages

Do not use any additional packages.

Fonts

Do not use fonts and fonts assets or fonts packages.

Exceptions

Do not use. Using "try-catch" block slows down the game a lot. This is especially noticeable in JavaScript.