Skip to content

Anatomy of an IdleKit Scene

This guide is intended to show the essential parts of the the scene in a project made with IdleKit. The guide will use the scene from IdleKit Showcase as an example. Be aware that for your own project we advise that you inherit from the classes mentioned in this article.

You can read more about how to retrieve and setup the IdleKit Showcase project here: Showcase Setup

What You Need to Run Your Game

An IdleKit scene requires the following parts to operate:

  • IdleKit specific MonoBehaviour scripts on a GameObject in the scene
  • Your GameObject containing your UI system

Our IdleKit Showcase scene only has 3 GameObjects in it at the root level to keep things simple.

  • The Main Camera - the camera, which renders everything in the game
  • ShowcaseCanvas - our showcase UI object, which is referenced by components mentioned in this article
  • StorySequenceUI - the player for the Story Sequence system which is enabled automatically when a Story Sequence needs to be played

showcase_scene_hierarchy

IdleKit - Required MonoBehaviour Scripts

For your IdleKit project to run correctly the scene will require a GameObject with the following IdleKit Scripts (these examples are taken from the IdleKit Showcase project):

  • A Startup script
  • An Installer script
  • A Context script
  • A class that will initialize your UI which must inherit from IUiLoadPhaseProvider and IIKComponentBinder

Please note that most of these components cross reference each other in their inspector fields, as well as reference UI and Story Sequence related objects in our Showcase scene. If after adding these components to your GameObject in your scene you are getting Null Reference Exceptions in the console, make sure to compare your scene to how our IdleKit Showcase scene is setup and check for any missing references in the inspector.

idlekit_monobehaviours

Below are expanations for what each of the scripts does.

Startup

This is the entry point of an IdleKit project. This scripts's Start method kicks off the startup flow of your IdleKit game. If you're looking to trace all the steps IdleKit takes to initialize all of its systems and set up all its dependencies - look no further than an IStartup.

In our Showcase project we use the RemoteStartup implementation which is a class that we recommend that you inherit from when making your own Startup script. This script will work with your Context script as well as your Installer script to resolve all the dependencies within the game, and set the framework's systems and its server connection up for a successful run when you start the game.

/// <summary>
/// A version of the <see cref="IStartup"/> thad loads the <see cref="IData"/> from a remote endpoint utilizing
/// the <see cref="IKManifest"/>s.
/// </summary>
public class RemoteStartup : Startup
{
    ...
}

Installer and Context

While a traditional Unity project might use inspector references or GetComponent calls to get references to all required components within a class, IdleKit uses a custom Dependency Injection framework to resolve all of its dependencies. The Installer (IInstaller) class defines which classes will be available during IdleKit's runtime by adding ("binding") these classes in a dictionary (a "container") inside of the the Context (IContext) script.

In our Showcase we use the RemoteInstaller and MonoContext implementation of the above mentioned interfaces, and these 2 classes should be used as the basis for your own versions if you want to bind any extra objects for use in your game.

 /// <summary>
/// This installer links IdleKit up with Beamable.
/// </summary>
public class RemoteInstaller : IKMonoInstaller
{
    ...
}

Initialize UI Component

You can initialize your UI objects as part of IdleKit's already existing startup flow which is defined by LoadPhases inside of the RemoteStartup class. In the Showcase project all our UI is initialized through the InitializeUIIKComponent components which is located on the main camera gameobject.

The IdleKit uses the InitializeUIIKComponent to retrieve the custom LoadPhases written to initialize the UI components of the IdleKit Showcase project. For your own project, you will need to create your own class which implements the IUiLoadPhaseProvider and IIKComponentBinder interfaces, as well as your own LoadPhases which will set up your UI objects in the game.

/// <summary>
/// A component used to provide UI-related <see cref="ILoadPhase"/>s to the IdleKit startup flow.
/// </summary>
public class InitializeUiIKComponent : MonoBehaviour, IUiLoadPhaseProvider, IIKComponentBinder
{
    ...
}

A Note About UI

Just like the rest of classes in IdleKit MonoBehaviour based UI classes can access any of the IdleKit services by getting Injected and using a resolver. This process is already setup as part of the default Startup class, all you need to do is make sure your UI MonoBehaviour class implements the IInjectable interface, and then you can "pull out" anything IdleKit related from the IResolver that is passed into the Inject method that interface requires.

Unity Event Listener

As you might've noticed there is one more custom component on the main camera in the IdleKit Showcase scene - the UnityEventListener. This component converts the usual Unity engine calls like Update, FixedUpdate, LateUpdate as well as calls like OnApplicationQuit and Pause into IdleKit specific Actions. In IdleKit we use Unity's Update calls to keep track of game time in the TimerService class for example, so this is a required component as well. Make sure to add it to the same GameObject along with the rest of the components mentioned in this article.

/// <summary>
/// An Unity MonoBehaviour implementation of the <see cref="IUnityEventListener"/>
/// </summary>
public class UnityEventListener: MonoBehaviour, IUnityEventListener, IInjectable
{
    ...
}

Story Sequence Database

If your game is going to use narrative you will probably be making Story Sequences. In order for your Story Sequences to be available in your game, you need to attach a StorySequenceDatabase to your Startup component same as we do it in our IdleKit Showcase project. Our tutorial on the Story Sequence Tool setup explains how to setup the tool for use in the scene and access your sequences in the game.

story_sequence_database

Further Setup

After setting up the aforementioned components, make sure you have your Beamable project setup using these guides: Beamable Sheets Setup and Beamable Setup. These articles will teach you how to setup your data on the server in order for IdleKit to be able to download it when you launch the project.