Service Framework

The Service Framework package by the Reality Collective. This package is an extensible service framework to build highly performant components for your Unity projects.

Overview

The Service framework provides a service repository for enabling background services to run efficiently in a Unity project, it features capabilities such as:

Platform specific operation - choose which platforms your service runs on.
Zero Latency from Unity operations - services are fully c# based with no Unity overhead.
Ability to host several sub-services (service modules) as part of a service, automatically maintained by a parent service and also platform aware.
Fully configurable with Scriptable profiles - Each service can host a configuration profile to change the behaviour of your service without changing code.

Requirements

Installation

Make sure to always use the same source for all toolkit modules. Avoid using different installation sources within the same project. We provide the following ways to install Reality Toolkit modules:

Method 1: Using Package Manager for git users

Open the Package Manager using the Window menu -> Package Manager
Inside the Package Manager, click on the "+" button on the top left and select "Add package from git URL..."
Input the following URL: https://github.com/realitycollective/com.realitycollective.service-framework.git and click "Add".

Method 2: OpenUPM

    openupm add com.realitycollective.service-framework

Method 3: Unity Asset Store

This option will be available soon.

Use cases

The service framework has been the foundation behind such toolkit's as Microsoft's MRTK and open source projects like the XRTK and newly formed Reality Toolkit. These utilise the framework to enable such use cases as:

A platform independent input system - A single service able to route input data from multiple controllers on various platforms, each controller only activates on the platform it was designed for.
An Authentication service - Able to integrate with multiple authentication providers as needed through a single interface.
A networking service - Utilising multiple endpoints for Lobbys, communication routes and data sharing.

The possibilities are almost endless.

Tip Check out Joost van Schaik blog for some excellent tips using the Service Framework!

Getting Started

1. Creating a service

A fully featured "Service Generator" is included with the Service Framework to get you quickly started, by simply giving a service a name and a namespace with which to run from, the generator will quickly create:

An interface to identify your service to the Service Framework (all services are identified by their parent interface)
A configuration profile - to customise to the needs of your service (optional, delete if not required)
The Service Implementation - You service to do with as you wish.

Additionally, the generator can also create additional data providers (sub services) for your service to maintain, these require you to specify the parent services interface when generating to ensure they are appropriately bound in creation. Data Providers are automatically started with a parent service provided their platforms match the current operating environment.

2. Configuring your service

With your service created, it will need to be registered with an active "Service Manager" in a scene, this can either use the provided "Service Manager Instance" component on a GameObject, or uitilised as a private property on a class of your own.

Note, at this time, only a single Service Framework Manager can be active in the scene at a time.

Simply create an empty GameObject and add the ServiceManagerInstance component to it to begin. From there it is simply a matter of creating a Profile for the Service Manager and then adding your services to it.

3. Accessing your running services

Your services are available at any time from anywhere in your code by simply requesting the service from the Service Manager using its interface (Data Providers are also accessible directly, although we recommend working through your service), for example:

    var myService = ServiceManager.Instance.GetService<MyServiceInterface>();

Alternatively, there are also TryGet versions of the Service endpoints which return a bool to denote the service retrieval was successful and an out parameter to output the service instance, for example:

    IService myServiceInstance;
    if(!ServiceManager.Instance.TryGetService<MyServiceInterface>(out myServiceInstance))
    {
        // Do something if your service was not found.
    }

Feedback

Please feel free to provide feedback via the Reality Toolkit dev channel here, all feedback. suggestions and fixes are welcome.

Raise an Information Request

If there is anything not mentioned in this document or you simply want to know more, raise an RFI (Request for Information) request here.

Or simply join us on Discord and come chat about your questions, we would love to hear from you

realitycollective / com.realitycollective.service-framework

readme