API overview

Once you imported and integrated a being into your Unity project, you can now access the VirtualBeingsTech API in order to interact with the beings and their ecosystem (control the lifecycle of beings, their interaction with your world, decide how to create more AI content for beings, …).

Container

The VIRTUAL BEINGS ecosystem exists inside a Container object that is initialized by BeingInstaller.cs. This is a singleton that can be accessed by adding

Container Container => Container.Instance;

in your scripts.

The Container comprises multiple managers and important entities used during the being lifecycle:

  • BeingManager

  • PlayerManager

  • InteractionDB

  • WorldEvents

Events

To interact with VirtualBeingsTech, you will use WorldEvents from the Container. You can subscribe anywhere in your code to any type of events that are called by VirtualBeingsTech on specific moment. Some important events are:

  • WorldEvent_OnBeingSpawn

  • WorldEvent_InteractableRegistration

  • WorldEvent_MotiveSatisfied

You can Register/Unregister from any type of event, and even Raise() a type of event, that will call all callbacks subscribed to this specific event.

Being

Access BeingManager through the Container, and call the InitializeAndStartBeing() method with an instance of the being prefab (you control how you instantiate it), and settings accessed via the Container:

_beingManager.InitializeAndStartBeing(
  being, 
  _beingManager.BeingManagerSettings.BeingData,
  _beingManager.BeingManagerSettings.BeingSettings
);

Interactables

Every gameObject that the being should be aware of, even if the being doesn't directly interact with it, should have the InteractableController.cs script attached to it.

In KuteEngine™, the majority of objects are interactables (including player, XR-hands, beings, interactable objects).

Player

A player is represented by the main camera. Since VirtualBeingsTech was created with multiplayer in mind, you can access all the players inside the Container.PlayerManager.

NavigableTerrain.cs defines an area where a Being can move and how the navigation system from KuteEngine calculate path.

  • NavigableCollider defines the collider from which the navigable area's limits will be induced. To avoid reducing too much the accuracy of the navigation, it might be preferable to avoid too big areas (but we are speaking in kilometers here, you have quite the margin). In the screenshot above, it is defined by a sphere that you can see in light green. Not all Unity colliders are handled, here is what you can feed the navigable terrain with:

  • NavigationIsInLocalSpace defines whether the navigable collider is defined relative to its containing game object, and should move with it. This is supposed to be used for moving navigable areas, such as a moving platform. This should not be used in the general case.

  • MaxSizedefines the maximum size of the navigation area for this terrain. It cannot exceed 1000m at the moment. This value should be set in the order of magnitude of the area the NavigableTerrain will leave in (e.g. if it's in a room, it should be set to something like 10 to 20m, if you are working at millimeters scale, you should put it to something like 1m, etc). Please choose this value wisely (by keeping it above the maximum size your NavigationCollider can grow but still minimize it) as it cannot be changed at runtime. This value must be strictly positive.

  • SpawningPoints defines the possible spawning positions of the beings. It is optional and can be used or not to define fixed spawn position. Use NavigableTerrain.GetSpawningPositions() to retrieve them.

Note on colliders: Please keep in mind when feeding a navigable terrain with a collider that, what is being used in the end to define the navigable area is the convex hull of the 2D projection of your input.

Dynamic navigable terrains

Navigable terrains can be constructed and configured at edit time. They also can be spawned and removed dynamically at runtime.

There are different ways one can construct them, either using a prefab that gets instantiated at runtime, constructing a GameObject and adding the NavigableTerrain component, or using the NavigableTerrain.CreateNavigableTerrain() helper function.

If the case you add the NavigableTerrain manually, make sure you call the SetCollider() function on it to specify the collider to be used. The navigable terrain won't get registered by KuteEngine until you call this method.

Updating the navigation collider

After you have set your NavigationCollider once, it is possible to update it at runtime by calling the UpdateCollider method, with the new navigation collider to use.

Debugging navigable terrains

To help debug the navigable terrains, one can toggle on the EnableDebugView option. This will activate the debug visualization of the navmesh within the editor view. It is also possible to enable the visualization in game view (e.g. to debug on device) by creating aLineSegmentVisualizer that implements the ILineSegmentVisualizer interface to render the provided lines.

Last updated