Procedural Worlds Blog

Articles, Tips and Tricks, Industry News
World Manager API

World Manager API and Unity Timeline

What is World Manager API?

World Manager API (WAPI) is a light weight command and control system for Unity 3D that manages all your environmental assets via one simple API.

It bridges the gap between your game and the assets it uses so that systems that support it can be quickly and easily configured to work together – without coding!

Why would I use it ? Give me an example scenario!

Let’s use Timeline to control Game Time and Weather and get it all running in 5 minutes!

  1. Make your scene.
  2. Plug in CTS and Enviro and switch on WAPI integration.
  3. From Enviro we get dynamic lighting, time of day, clouds, weather, fog, scattering, rain, snow and from CTS we get terrain that responds to rain and snow.
  4. Then create a new Timeline, add a Game Time Track, and add the various Weather tracks, blend them together and stick it on repeat.

Time to set this up – 5 minutes. Check the videos further down this page for an example of what can be done, and how to do it.

Timeline Sample

The alternative… read the Enviro documentation, read the CTS documentation, create your own time and weather management system and then get busy coding doing the integration…. weeks later lets see how you are travelling…

What does it do?

  • Provides a common way to describe your scene
  • Provides a common way to describe and control game time
  • Provides a common way to describe and control weather

Control Approaches:

At its heart WAPI is a set of useful global variables with a subscription based messaging system bolted on, and because of this, control can be mixed and matched to suit your game.

  • Your Game -> WAPI -> Environment
  • Timeline -> WAPI -> Your Game, Environment
  • Timeline, Your Game -> WAPI -> Environment
  • Environment -> WAPI -> Your Game, Other Environment Parts

Benefits For Game Developers:

  • FREE, Open Source!
  • One simple and generic API
  • Add or remove compatible 3rd party assets easily and have them ‘just work’
  • Or alternatively, provide a common way to integrate them into your game
  • Control everything script free via Timeline
  • Saves time and reduce complexity!

Benefits For Publishers:

  • FREE, Open Source!
  • One simple and generic API
  • Extend your audience reach
  • Lower your support burden
  • Simple integration – check the sample code here!

But my system is different!?

No problem. You can still configure your assets individually to your own taste to do your own thing, the only thing that WAPI does is ensure that command and control is centralized through one API and in a generic way.

Assets which implement API support can choose which parts they implement and regardless of how much they support, you will get value from this system because of the way it coordinates their behavior.

API Categories Covered:

  • IsActive
  • Game Time
  • Player Location
  • Scene Attributes, Sea Level, Latitude & Longitude
  • Temperature and humidity
  • Wind
  • Fog
  • Rain
  • Hail
  • Snow
  • Thunder
  • Clouds
  • Moon
  • Season
  • Sound Levels
  • Extensions
  • Serialization

Timeline Support:

WAPI is integrated with Unity Timeline, via the Playable’s API.

In the video sample below, Timeline controls WAPI for game time, fog, rain and snow, and Cinemachine for the shots and Post FX – it was done from end to end with Zero Coding!

 

This next video provides a high level introduction to WAPI and shows an overview of how the first video was constructed and which assets were used.

 

The assets used here are:

Shader Support:

WAPI introduces and manages a global set of shader variables. Any shader that conforms to the WAPI standard will be updated automatically when settings change without needing the the message subscription system.

Open Source & Source Code:

WAPI is Open Source under the MIT licence, under active development, and will be released on the asset store as well soon for convenience.  To get your own copy of WAPI go to the WAPI Github page and download it.

When you grab the source code – take a look at the demo scene and the sample integration. It is very easy to implement.

API Usage Pattern:

To enable or disable World Manager (and all events and update / lateupdate):

  • WorldManager.Instance.WorldAPIActive = true/false;

To generate events, and get and set values use the following generic format:

  • WorldManager.Instance.APICall()
  • WorldManager.Instance.Property = value;
  • value = WorldManager.Instance.Property

To receive events when values are changed implement your own listener via the IWorldApiChangeHandler interface and then choose which events you want to listen to:

WAPI SAMPLE CODE

public class WorldController : MonoBehaviour, IWorldApiChangeHandler
{
    .. your stuff..

    void Start()
    {
        ConnectToWorldAPI();
    }

    //Let world manager API know you want to handle events
    void ConnectToWorldAPI()
    {
        WorldManager.Instance.AddListener(this);
    }

    //Let world manager API know that you are no longer interested
    void DisconnectFromWorldAPI()
    {
        WorldManager.Instance.RemoveListener(this);
    }

    //If this object has been added as a listener then it will be called whenever an event is fired,
    //use the changeArgs.HasChanged method to filter for the events you are interested in
    public void OnWorldChanged(WorldChangeArgs changeArgs)
    {
        if (changeArgs.HasChanged(WorldConstants.WorldChangeEvents.GameTimeChanged))
        {
            //Grab game time
            m_timeNow = (float)changeArgs.manager.GetTimeDecimal();

            //Do whatever logic you want
            m_timeNow += 0.25f;

            //Set it back into world manager -> NOTE you would never do THIS SPECIFIC THING
            //as this will cause another OnWorldChanged event to be generated, which would in turn
            //cause this to be executed again in one nasty loop
            WorldManager.Instance.SetDecimalTime(m_timeNow);
        }
    }
}

 

Supported By:

Enviro – Sky and Weather (coming soon)

TENKOKU Dynamic Sky (coming soon)

CTS – Complete Terrain Shader (coming soon)

Stay in the loop!

If you would like to be kept up to date about how WAPI is evolving, and and get access to my free monthly tips, tricks, news reviews and freebies newsletter then please sign up on my home page.

Leave a Reply