Abaci
Statistics with Context

Introduction

Bundle is the core of Abaci, it actually stores the statistics and contexts but also has another important feature - parenting.

Bundles automatically share statistics with parent bundles. This is perfect for team games, statistics for each player automatically feed into the team's bundle of statistics. It's also ideal for statistics per level whilst having a parent bundle that stores the players statistics over the entire game.

bundle_example.png


Component

A Bundle is a Unity component (MonoBehaviour), and can be added to a Game Object using the component menu (or Add Component button on Game Objects).

bundle_add_component.png

And for convenience can be added as a GameObject direction using the GameObject menu (or right clicking in Hierachy window).

bundle_add_game_object.png

Unlike other Abaci components you can't have multiple Bundles per GameObject. This is so it's always possible to reference bundles uniquely by GameObject name.


Parenting

If you haven't already take a look at Bundles tutorial and Space Shooter Example to see Bundle Parenting in action. They'll show you how parent bundles inherit all the statistics from their children.

Typically you'll want a separate Bundle for each player, with parent bundles defined for lifetime statistics and possibly bundles for team statistics.

You can define Parent bundles in the editor by assigning bundles. This is the simpliest and safest way, however requires all bundles to be in a single scene which isn't always feasible.

bundle_parent.png

If the parent bundle isn't in the game scene you can list the bundle's game object name under Parent Bundles Game Object Names

bundle_parent_object_name.png

Then when the bundle is created at runtime, it'll automatically be added as a parent to your bundle as shown below.

bundle_parent_object_name_ingame.png

For completeness it's possible to add (and remove) parents in code using Abaci.Bundle.AddParent (and Abaci.Bundle.RemoveParent)

Abaci.Bundle lifetimeBundle = Abaci.Manager.GetInstance().FindBundle("AbaciLifetimeBundle");
m_bundle.AddParent(lifetimeBundle);


Debugging

The simpliest way to debug a bundle is to explore it's stats and contexts in the Unity Editor (this also allows you to set values at runtime).

As you can quickly store many statistics and contexts a filter option is provided which only displays matching statistcs.

bundle_debugging_filter.png

Also you can enter multiple words separated by spaces, and it will only display statistics that match all of those words

bundle_debugging_multifilter.png

If you're not in the editor, debugging a listener is easy way of getting a break point during the function call that's causing the issue.

The most common error is changing the case or spelling of statistics or contexts.


Hashing

To efficiently store and retrieve all the statistics and contexts their names are hashed (using Abaci.Hash), and while there are infinite possibly strings there is only 4,294,967,195 (32 bit) possibly hashes. If a collision does happen a System.Exception is thrown to inform you. Collisions become likely when you start using over ~30,000 different entries (for futher reading see Hash Collision Probabilities) so is unlikely to be a problem for games development.


API

The full API for the bundle is available Abaci.Bundle