MayaFlux::Nexus::Expanse Class Reference

A defined region of space with a containment test and crossing actions. More...

#include <Expanse.hpp>

Inheritance diagram for MayaFlux::Nexus::Expanse:

Collaboration diagram for MayaFlux::Nexus::Expanse:

Public Types
using	ContainsFn = std::function< bool(const glm::vec3 &)>
using	CrossingFn = std::function< void(uint32_t)>

Public Member Functions
template<typename T >
std::shared_ptr< Influence< T, CrossingContext > >	add_entry (typename Influence< T, CrossingContext >::Producer producer)
	Add an action of any type that runs when an entity enters.
template<typename T >
std::shared_ptr< Influence< T, CrossingContext > >	add_exit (typename Influence< T, CrossingContext >::Producer producer)
	Add an action of any type that runs when an entity leaves.
template<typename T >
std::shared_ptr< Influence< T, CrossingContext > >	add_inside (typename Influence< T, CrossingContext >::Producer producer)
	Add an action of any type that runs on every commit for each entity inside.
template<typename T >
std::shared_ptr< Perception< T > >	add_perception (typename Perception< T >::Source source)
	Add a perception of any type over the entities inside, with as many targets as are wanted.
const std::optional< Kinesis::AABB3D > &	bounds () const
	The box, if set.
void	clear_bounds ()
	Remove the box, leaving the predicate.
void	clear_crossings ()
	Stop every typed action.
void	clear_perceptions ()
	Stop every perception added with add_perception().
virtual bool	contains (const glm::vec3 &p) const
	Test whether a world position lies within the Expanse.
void	evaluate (uint32_t fabric_id, std::span< const std::pair< uint32_t, glm::vec3 > > snapshot)
	Evaluate a spatial snapshot from one Fabric against this Expanse.
void	evict (uint32_t fabric_id)
	Fire the exit actions for everything inside for fabric_id and forget it.
	Expanse (const Kinesis::AABB3D &bounds, CrossingFn on_enter={}, CrossingFn on_exit={})
	Construct as a box.
	Expanse (ContainsFn contains)
	Construct with a containment predicate only, for an Expanse whose behaviour comes from typed actions.
	Expanse (ContainsFn contains, CrossingFn on_enter, CrossingFn on_exit)
	Construct with a containment predicate and crossing actions.
	Expanse (std::string fn_name, ContainsFn contains, CrossingFn on_enter, CrossingFn on_exit)
	Construct with a named containment predicate and crossing actions.
	Expanse (std::string fn_name, std::string on_enter_fn_name, std::string on_exit_fn_name, ContainsFn contains, CrossingFn on_enter, CrossingFn on_exit)
	Construct with named containment predicate and named crossing actions.
const std::string &	fn_name () const
	Identifier assigned to the containment predicate, empty if anonymous.
uint32_t	id () const
	Id assigned at construction.
const std::unordered_set< uint32_t > *	occupants (uint32_t fabric_id) const
	Entity ids inside this Expanse for fabric_id, or nullptr if that fabric has no occupants.
std::vector< uint32_t >	occupied_fabrics () const
	All fabric ids that currently have at least one occupant inside this Expanse.
const std::string &	on_enter_fn_name () const
	Identifier assigned to the on_enter callable, empty if anonymous.
const std::string &	on_exit_fn_name () const
	Identifier assigned to the on_exit callable, empty if anonymous.
template<typename T >
void	remove_crossing (const std::shared_ptr< Influence< T, CrossingContext > > &action)
	Stop an action added with add_entry(), add_exit() or add_inside().
template<typename T >
void	remove_perception (const std::shared_ptr< Perception< T > > &perception)
	Stop a perception added with add_perception().
virtual void	set_bounds (const Kinesis::AABB3D &bounds)
	Set or replace the box.
void	set_fn_name (std::string name)
	Set or replace the predicate identifier.
void	set_on_enter_fn_name (std::string name)
	Set or replace the on_enter callable identifier.
void	set_on_exit_fn_name (std::string name)
	Set or replace the on_exit callable identifier.
virtual	~Expanse ()=default

Protected Member Functions
virtual void	begin_evaluate ()
	Called at the start of every evaluate(), before any position is tested.
virtual std::pair< glm::vec3, float >	reach () const
	Where the region is centred and how far it reaches, for perceptions.

Private Types
using	Action = std::function< void(const CrossingContext &)>
using	Actions = std::vector< std::pair< std::shared_ptr< void >, Action > >
using	PerceptionFn = std::function< void(const PerceptionContext &)>

Static Private Member Functions
template<typename T >
static std::shared_ptr< Influence< T, CrossingContext > >	add_action (Actions &list, typename Influence< T, CrossingContext >::Producer producer)
static uint32_t	allocate_id ()

Private Attributes
std::optional< Kinesis::AABB3D >	m_bounds
ContainsFn	m_contains
Actions	m_entries
Actions	m_exits
std::string	m_fn_name
uint32_t	m_id { allocate_id() }
Actions	m_insides
std::unordered_map< uint32_t, std::unordered_set< uint32_t > >	m_occupants_by_fabric
CrossingFn	m_on_enter
std::string	m_on_enter_fn_name
CrossingFn	m_on_exit
std::string	m_on_exit_fn_name
std::vector< std::pair< std::shared_ptr< void >, PerceptionFn > >	m_perceptions

Detailed Description

A defined region of space with a containment test and crossing actions.

An Expanse is an extent, not a point. It answers whether a world position lies within it, and fires actions when an entity crosses its edge: one on entry, one on exit, and optionally one on every commit while inside. The Fabric evaluates the Expanse against every indexed position on each commit and diffs membership against the previous commit. The Expanse does not query; the Fabric drives it, because only the Fabric sees consecutive snapshots.

The region is a box, a predicate, or both. A box is plain data: it moves or resizes with set_bounds, which any influence can drive through bind_bounds. A predicate is a function from position to bool that closes over whatever state shapes the region. With both, the box is a cheap first test and both must pass. Derived classes may replace contains().

Crossing actions are either a plain function of the entity id, or any number of typed actions added with add_entry, add_exit and add_inside. A typed action builds a value from the CrossingContext and hands it to its targets, so the targets in FieldTargets.hpp work here as they do for an Agent. What crossing means computationally is the action's decision.

An Expanse also perceives its own contents, as a Sensor perceives its neighbourhood. add_perception sources receive a PerceptionContext centred on the region, with the occupants as the spatial results, once per evaluate and before any crossing action. Typed actions and perceptions are runtime objects and are not part of encoded state.

The id is assigned at construction and is the same on every Fabric the Expanse is registered on.

Definition at line 55 of file Expanse.hpp.

---

The documentation for this class was generated from the following files:

• Expanse.hpp
• Expanse.cpp