Module ark_api::behavior_controller

Expand description

📤 Behavior Controller API

This API provides functionality to indirectly communicate with external behavior modules.

Through this API, a user can retrieve reflection info of all loaded behavior modules, create new behavior instances of a particular type, and send messages to behavior instances.

Message passing

Messages are the protocols through which behaviors communicate. At the lowest level they are serializable Rust structures.

The entire message passing flow between this API and behavior modules goes as follows:

A user creates IncomingMessages and batch sends them to Ark through BehaviorController::instances_handle_messages
Ark owns the actual behavior modules and will, in order, send the IncomingMessages to the correct behavior instances inside external behavior modules
A behavior instance will then process the just received message
During the processing of a message, a behavior instance can create new OutgoingMessages that will be returned to the user, which then decides what to do with it

Aspects are used to associate data with actors, and share it between behaviors. Aspects are just data and don’t implement any logic. Through BehaviorController::aspect_upsert, users can sync their aspect data with Ark. Internally, Ark stores aspects in so called “aspect stores”, keyed by aspect guid first to be able to iterate on all actors that have a given aspect blazingly fast.

Why aspects?

As each behavior module is a separate Wasm module, behavior instances from separate behavior modules can’t access each others memory, meaning there is no direct sharing of state. While state could be asynchronously queried via message passing, aspects allow for a more optimal route for sharing state.