Difference between revisions of "Unity plugin documentation"

From GURaaS Developer Community
(Updated the links)
 
(12 intermediate revisions by the same user not shown)
Line 4: Line 4:


==installing the plugin==
==installing the plugin==
<br />


#Download the plugin unity asset TODO: download link.
#Download the [http://guraas.com/builds/GLogUnity.unitypackage plugin unity asset]: '''.'''
#Import the plugin into unity (Assets -> Import Package -> Custom Package...).
#Import the plugin into unity (Assets -> Import Package -> Custom Package...).
#Your project should now have the following additional assets: <br />[[File:Imported_plugin.png|alt=|border]]
#Your project should now have the following additional assets: <br />[[File:Imported_plugin.png|alt=|border]]
#Select the GLogConfig asset and set the Game Unique Id to the Id assigned to the game on the GURaaS portal.  <br />[[File:GLogConfig.png|alt=|frameless]]    [[File:Game_Id_on_the_portal.png|alt=|border|frameless|810x810px]]
#Select the GLogConfig asset and set the Game Unique Id to the Id assigned to the game on the [https://portal.guraas.com GURaaS portal].  <br />[[File:GLogConfig.png|alt=|frameless]]    [[File:Game_Id_on_the_portal.png|alt=|border|frameless|810x810px]]
#The plugin is now set up and ready to use!
#The plugin is now set up and ready to use!


Line 15: Line 14:


==Your first log==
==Your first log==
<br />
Logging something in GLog is as easy as this:
<syntaxhighlight lang="c#" line="1" start="1">
<syntaxhighlight lang="c#" line="1" start="1">
using GLogUnity;
using GLogUnity;
Line 21: Line 20:
GLog.StartSession();
GLog.StartSession();
GLog.Log(VerboseLevel.DEBUG, "tag1", "tag2", "data");
GLog.Log(VerboseLevel.DEBUG, "tag1", "tag2", "data");
GLog.Debug("Test");
</syntaxhighlight>
GLog.Info("Test");
 
===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:
<syntaxhighlight lang="c#" line="1" start="1">
GLog.CloseSession();
GLog.CloseSession();
</syntaxhighlight>
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:
<syntaxhighlight lang="c#" line="1" start="1">
public static void StartSession(string playerId = null, string context = null)
</syntaxhighlight>
===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:
<syntaxhighlight lang="c#" line="1" start="1">
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");
</syntaxhighlight>
</syntaxhighlight>


== Plugin structure ==
<br />
==Plugin structure==
The plugin consists of three important components:
The plugin consists of three important components:


=== GLog ===
===GLog===
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. The config is a ScriptableObject that contains the settings for your game and functions as a central point for any interaction with the plugin.
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 ===
===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:
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.
*File channel: outputs received logs to the file location specified.
* Console channel: outputs received logsto the Unity console.
*Console channel: outputs received logs to the Unity console.
* GURaaS channel (or remote channel): sends received logs to the GURaaS server.
*GURaaS channel (or remote channel): sends received logs to the GURaaS server. <br />[[File:GURaaS channel.png|border|frameless]]


A game can have multiple channels, but only channels that are referenced in the GLogConfig will be used.
A game can have multiple channels, but only channels that are referenced in the GLogConfig will be used.
Line 43: Line 76:
The plugin includes one existing channel asset for each of the default types, these can be found in the Resources folder.
The plugin includes one existing channel asset for each of the default types, these can be found in the Resources folder.


=== GLogMonitor ===
===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.

Latest revision as of 14:55, 21 April 2020

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


installing the plugin

  1. Download the plugin unity asset: .
  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.