Revision as of 13:04, 17 April 2020 by Admin (talk | contribs)

Unity plugin documentation

From GURaaS Developer Community

This page describes how to set up and use the GURaaS logging plugin for unity.


installing the plugin

  1. Download the plugin unity asset TODO: download link.
  2. Import the plugin into unity (Assets -> Import Package -> Custom Package...).
  3. Your project should now have the following additional assets:
  4. Select the GLogConfig asset and set the Game Unique Id to the Id assigned to the game on the GURaaS portal.
  5. The plugin is now set up and ready to use!


Your first log

Logging something in GLog is as easy as this:

using GLogUnity;

GLog.StartSession();
GLog.Log(VerboseLevel.DEBUG, "tag1", "tag2", "data");

Sessions

The first thing we are doing here is starting a new session. A session is a group of logs that belong together. Determining what defines a session is left up to the developer but the general guideline is to have a session be a single level. Sessions can be manually closed by calling:

GLog.CloseSession();

Sessions will also automatically be closed if the game is closed, but it is important to note that no logging can be done when there is no session active. While a session can be opened without parameters, a player Id or context string can also be passed to make grouping results easier:

public static void StartSession(string playerId = null, string context = null)

Logs

A log has the following properties:

  • A verbose level that indicates the log's type and determines what channels will handle it.
  • Up to 3 string tags that can be used to identify or filter the log.
  • 1 string of data (which can of course be a representation of multiple objects)

Below are a number of different ways to log data:

GLog.Log(VerboseLevel.DEBUG, "tag1", "tag2", "data");
GLog.Log(VerboseLevel.INFO, "data");
GLog.Debug("tag1", "tag2", "tag3", "data");
GLog.Info("data");
GLog.Performance("data");
GLog.Subsystem("data");
GLog.Warning("data");
GLog.Info("data");
GLog.Error("data");
GLog.Player("data");
GLog.Event("data");


Plugin structure

The plugin consists of three important components:

GLog

The GLog file is a ScriptableObject that contains the settings for your game and functions as a central point for any interaction with the plugin.

When using the plugin your asset folder should have a single GLog asset (called GLogConfig) in a Resources folder. When unpacking the plugin a GLog asset is placed in the Resources folder.

GLogChannel

A channel is a ScriptableObject that listens to the logs passed to GLog and passes any logs that match its verbosity mask to an output. The plugin comes with 3 different types of channels, but more can be added by extending the GLogChannel class. The default channels are:

  • File channel: outputs received logs to the file location specified.
  • Console channel: outputs received logs to the Unity console.
  • GURaaS channel (or remote channel): sends received logs to the GURaaS server.
    GURaaS channel.png

A game can have multiple channels, but only channels that are referenced in the GLogConfig will be used.

The plugin includes one existing channel asset for each of the default types, these can be found in the Resources folder.

GLogMonitor

Because GLog and GLogChannel are both ScriptableObjects they are not part of the scenes and don't receive updates. This is why the first call GLog creates a GLogMonitor in the scene and adds it to DontDestroyOnLoad. The GLogMonitor passes updates to the other components and handles any networking.

Users should never need to access the GLogMonitor directly, but it is good to know its function.