Base class for native C++ gameplay behaviors. More...

#include <behavior.h>

Inheritance diagram for Vkm::Engine::Behavior:

Public Member Functions
virtual void	onStart ()
	Called on the first simulation tick this instance runs in play mode.
virtual void	onUpdate (float dt)
	Called every variable-step frame on which simulation time advanced.
virtual void	onRealtimeUpdate (float dt)
	Called every frame on real time, paused or not.
virtual void	onFixedUpdate (float dt)
	Called on each fixed-step tick; fed from simulation time, so pause and time-scale apply.
virtual void	onCollisionEnter (const Collision &hit)
	Called on the first tick this entity touches another, in a resolved (non-trigger) contact.
virtual void	onCollisionStay (const Collision &hit)
	Called on each later tick the contact lasts.
virtual void	onCollisionExit (const Collision &hit)
	Called on the first tick the contact is over.
virtual void	onTriggerEnter (EntityId other)
	Called on the first tick `other` overlaps this entity's trigger.
virtual void	onTriggerStay (EntityId other)
	Called on each later tick `other` is still inside, on onCollisionStay's terms.
virtual void	onTriggerExit (EntityId other)
	Called on the first tick `other` no longer overlaps, on onCollisionExit's terms.
virtual void	onDestroy ()
	Called on entity removal, and when the session ends (see BehaviorSystem::endSession).
virtual const char *	typeName () const =0
	Stable type name, identical to this type's BehaviorRegistry key; serialization uses it.
virtual void	visitFields (BehaviorFieldVisitor &visitor)
	Visit the behavior's reflected authoring fields; ReflectedBehavior generates it.
virtual std::unique_ptr< Behavior >	clone () const =0
	Deep copy for entity duplication; authored fields only, the context is rebound.

Protected Member Functions
EntityId	entity () const
	The entity this behavior is attached to.
template<typename T>
T *	tryGet ()
	This entity's T, or null when it has none.
template<typename T>
const T *	tryGet () const
	This entity's T, or null when it has none.
template<typename T>
T &	get ()
	This entity's T, which it must have.
template<typename T>
const T &	get () const
	This entity's T, which it must have.
template<typename T>
bool	has () const
	Whether this entity carries a T.
template<typename T>
auto &	add (T &&component)
	Give this entity a T.
template<typename T>
T *	findBehavior ()
	This entity's behavior of type T, or null when it has none.
template<typename T>
T *	findBehavior (EntityId other)
	`other's` behavior of type T, or null when it has none.
Scene &	scene ()
	The scene this behavior's entity lives in.
ResourceManager &	resources ()
	The assets this session holds, to look one up or add one.
EventSender	events ()
	The event bus's sending half, to emit or enqueue on.
RenderSettings &	render ()
	The quality settings the frame is drawn at; a write lands on the next frame.
InputMap &	input ()
	Named input actions, for the frame queries and to define bindings.
NetSession &	net ()
	The wire, or an offline session that answers as though local.
Clock &	clock ()
	Real and simulation time, and the play state behind them.
WindowManager *	window ()
	The window, or null on a host that draws nothing, such as a dedicated server.
bool	isSimulated () const
	Whether this end decides what happens to this entity.
bool	isMine () const
	Whether this entity belongs to the player at this end.
bool	isReplaying () const
	Whether this tick already happened and is being run again.
const InputCommand &	command () const
	The input driving this entity on the tick now running.
EntityId	spawn ()
	Create a new, empty entity; add components to it through scene().
EntityId	spawn (const char *name)
	Create an entity carrying `name`.
EntityId	spawn (const char *name, EntityId parent)
	Create an entity carrying `name`, parented under `parent`.
void	destroy (EntityId target)
	Destroy `entity` and its subtree, firing onDestroy.
void	destroy ()
	Destroy this behavior's own entity and its subtree, deferred likewise.
void	loadScene (const std::string &scenePath)
	Load `scenePath`, replacing everything currently in the scene.
template<typename EventT = void, typename Fn>
void	subscribe (Fn &&callback)
	Listen for an event until the behavior is destroyed or the session ends.

Static Protected Member Functions
template<typename T>
static T *	findBehavior (Scene &world, EntityId entity)
	The free findBehavior, which the member overloads would otherwise hide.
template<typename T>
static const T *	findBehavior (const Scene &world, EntityId entity)
	The free findBehavior, which the member overloads would otherwise hide.

Detailed Description

Base class for native C++ gameplay behaviors.

Attached through a ScriptComponent. The context is bound before onStart(), so no accessor works in a constructor; being session-stable, they are safe from a subscribe() callback and not worth caching.

Member Function Documentation

◆ onStart()

virtual void Vkm::Engine::Behavior::onStart ( )

inlinevirtual

Called on the first simulation tick this instance runs in play mode.

Never from onRealtimeUpdate, so one spawned while paused waits for time to flow.

◆ onUpdate()

virtual void Vkm::Engine::Behavior::onUpdate ( float dt )

inlinevirtual

Called every variable-step frame on which simulation time advanced.

Skipped entirely while paused (and in editor Edit mode), never run with a zero delta; work that must continue goes in onRealtimeUpdate.

Parameters

dt	Elapsed simulation time this frame, in seconds; always > 0.

◆ onRealtimeUpdate()

virtual void Vkm::Engine::Behavior::onRealtimeUpdate ( float dt )

inlinevirtual

Called every frame on real time, paused or not.

Only for started behaviors, so build a pause menu in onStart and toggle UIElement::visible rather than spawning it on pause.

Parameters

dt	Real frame delta in seconds, untouched by setTimeScale(); always > 0.

◆ onFixedUpdate()

virtual void Vkm::Engine::Behavior::onFixedUpdate ( float dt )

inlinevirtual

Called on each fixed-step tick; fed from simulation time, so pause and time-scale apply.

Parameters

dt	Fixed timestep (Clock::getFixedStep()), in seconds.

◆ onCollisionEnter()

virtual void Vkm::Engine::Behavior::onCollisionEnter ( const Collision & hit )

inlinevirtual

Called on the first tick this entity touches another, in a resolved (non-trigger) contact.

void Crate::onCollisionEnter(const Collision& hit) {
    if (hit.normal.y > 0.7f) LOG_INFO("landed on %u", hit.other.slot());
}

Parameters

hit	Who, where, and the normal from them into this entity.

◆ onCollisionStay()

virtual void Vkm::Engine::Behavior::onCollisionStay ( const Collision & hit )

inlinevirtual

Called on each later tick the contact lasts.

Not while both bodies rest (asleep or static); waking does not enter again.

Parameters

hit	The contact this tick.

◆ onCollisionExit()

virtual void Vkm::Engine::Behavior::onCollisionExit ( const Collision & hit )

inlinevirtual

Called on the first tick the contact is over.

Including when the other was destroyed or disabled, so it may be dead. An entity destroyed while touching hears nothing.

Parameters

hit	Who it stopped touching; its point and normal are zero.

◆ onTriggerEnter()

virtual void Vkm::Engine::Behavior::onTriggerEnter ( EntityId other )

inlinevirtual

Called on the first tick other overlaps this entity's trigger.

Parameters

other The entity that entered.

◆ onTriggerStay()

virtual void Vkm::Engine::Behavior::onTriggerStay ( EntityId other )

inlinevirtual

Called on each later tick other is still inside, on onCollisionStay's terms.

Parameters

other The entity still inside.

◆ onTriggerExit()

virtual void Vkm::Engine::Behavior::onTriggerExit ( EntityId other )

inlinevirtual

Called on the first tick other no longer overlaps, on onCollisionExit's terms.

Parameters

other The entity that left; it may no longer be alive.

◆ typeName()

virtual const char * Vkm::Engine::Behavior::typeName ( ) const

pure virtual

Stable type name, identical to this type's BehaviorRegistry key; serialization uses it.

Returns: The type's registered name.

Implemented in Vkm::Engine::ReflectedBehavior< Derived >.

◆ visitFields()

virtual void Vkm::Engine::Behavior::visitFields ( BehaviorFieldVisitor & visitor )

inlinevirtual

Visit the behavior's reflected authoring fields; ReflectedBehavior generates it.

Parameters

visitor Visited once per reflected field, in markup order.

Reimplemented in Vkm::Engine::ReflectedBehavior< Derived >.

◆ clone()

virtual std::unique_ptr< Behavior > Vkm::Engine::Behavior::clone ( ) const

pure virtual

Deep copy for entity duplication; authored fields only, the context is rebound.

Returns: A new instance of the same type carrying the authored fields.

Implemented in Vkm::Engine::ReflectedBehavior< Derived >.

◆ entity()

EntityId Vkm::Engine::Behavior::entity ( ) const

inlineprotected

The entity this behavior is attached to.

Returns: The owning entity; null until bound, just before onStart.

◆ tryGet() [1/2]

template<typename T>

T * Vkm::Engine::Behavior::tryGet ( )

inlineprotected

This entity's T, or null when it has none.

if (Transform* body = tryGet<Transform>()) body->position += step;

Vkm::Engine::Behavior::tryGet

T * tryGet()

This entity's T, or null when it has none.

Definition behavior.h:288

Vkm::Engine::Transform

Local position, rotation and scale of an entity.

Definition transform.h:17

Template Parameters

T	Component type.

Returns: Pointer to this entity's T, or nullptr.

◆ tryGet() [2/2]

template<typename T>

const T * Vkm::Engine::Behavior::tryGet ( ) const

inlineprotected

This entity's T, or null when it has none.

if (Transform* body = tryGet<Transform>()) body->position += step;

Template Parameters

T	Component type.

Returns: Pointer to this entity's T, or nullptr.

◆ get() [1/2]

template<typename T>

T & Vkm::Engine::Behavior::get ( )

inlineprotected

This entity's T, which it must have.

Template Parameters

T	Component type; the entity must carry one.

Returns: Reference to this entity's T.

◆ get() [2/2]

template<typename T>

const T & Vkm::Engine::Behavior::get ( ) const

inlineprotected

This entity's T, which it must have.

Template Parameters

T	Component type; the entity must carry one.

Returns: Reference to this entity's T.

◆ has()

template<typename T>

bool Vkm::Engine::Behavior::has ( ) const

inlineprotected

Whether this entity carries a T.

Template Parameters

T	Component type.

Returns: True when this entity has one.

◆ add()

template<typename T>

auto & Vkm::Engine::Behavior::add ( T && component )

inlineprotected

Give this entity a T.

Template Parameters

T	Component type; the entity must not already have one.

Parameters

component Component to store.

Returns: Reference to it in the scene's storage.

◆ findBehavior() [1/4]

template<typename T>

T * Vkm::Engine::Behavior::findBehavior ( )

inlineprotected

This entity's behavior of type T, or null when it has none.

Template Parameters

T	Behavior subclass with a VKM_REFLECT block.

Returns: The first T attached to this entity, or nullptr.

◆ findBehavior() [2/4]

template<typename T>

T * Vkm::Engine::Behavior::findBehavior ( EntityId other )

inlineprotected

other's behavior of type T, or null when it has none.

if (Health* health = findBehavior<Health>(hit.other)) health->damage(10.0f);

Vkm::Engine::Behavior::findBehavior

T * findBehavior()

This entity's behavior of type T, or null when it has none.

Definition behavior.h:335

Not worth caching: the entity may die and its slot be reused between hooks.

Template Parameters

T	Behavior subclass with a VKM_REFLECT block.

Parameters

other Entity to look on; a dead one has none.

Returns: The first T attached to other, or nullptr.

◆ findBehavior() [3/4]

template<typename T>

T * Vkm::Engine::Behavior::findBehavior	(	Scene &	world,
		EntityId	entity )

inlinestaticprotected

The free findBehavior, which the member overloads would otherwise hide.

Template Parameters

T	Behavior subclass with a VKM_REFLECT block.

Parameters

world	Scene holding the entity.
entity	Entity to look on; a dead one has none.

Returns: The first T attached to entity, or nullptr.

◆ findBehavior() [4/4]

template<typename T>

const T * Vkm::Engine::Behavior::findBehavior	(	const Scene &	world,
		EntityId	entity )

inlinestaticprotected

The free findBehavior, which the member overloads would otherwise hide.

Template Parameters

T	Behavior subclass with a VKM_REFLECT block.

Parameters

world	Scene holding the entity.
entity	Entity to look on; a dead one has none.

Returns: The first T attached to entity, or nullptr.

◆ scene()

Scene & Vkm::Engine::Behavior::scene ( )

inlineprotected

The scene this behavior's entity lives in.

Returns: The session's scene.

◆ resources()

ResourceManager & Vkm::Engine::Behavior::resources ( )

inlineprotected

The assets this session holds, to look one up or add one.

Returns: The session's resource manager.

◆ events()

EventSender Vkm::Engine::Behavior::events ( )

inlineprotected

The event bus's sending half, to emit or enqueue on.

Not the bus: a listener on it would outlive this instance; use subscribe().

Returns: A sender over the session's bus.

◆ render()

RenderSettings & Vkm::Engine::Behavior::render ( )

inlineprotected

The quality settings the frame is drawn at; a write lands on the next frame.

Returns: The session's render settings.

◆ input()

InputMap & Vkm::Engine::Behavior::input ( )

inlineprotected

Named input actions, for the frame queries and to define bindings.

A fixed update reads command() instead: input().pressed(command(), "Jump").

Returns: The session's input map.

◆ net()

NetSession & Vkm::Engine::Behavior::net ( )

inlineprotected

The wire, or an offline session that answers as though local.

Returns: The session's network session.

◆ clock()

Clock & Vkm::Engine::Behavior::clock ( )

inlineprotected

Real and simulation time, and the play state behind them.

A game may pause and resume through this. Never call beginFrame() or consumeFixedStep(): they belong to the main loop.

Returns: The session's clock.

◆ window()

WindowManager * Vkm::Engine::Behavior::window ( )

inlineprotected

The window, or null on a host that draws nothing, such as a dedicated server.

Returns: The window, or nullptr.

◆ isSimulated()

bool Vkm::Engine::Behavior::isSimulated ( ) const

inlineprotected

Whether this end decides what happens to this entity.

True offline and on a server; on a client only for what it owns. Ask before writing a Transform or velocity, never before drawing or playing a sound, or a remote player goes silent and invisible.

Returns: True when this end simulates the entity.

◆ isMine()

bool Vkm::Engine::Behavior::isMine ( ) const

inlineprotected

Whether this entity belongs to the player at this end.

Ask before touching the camera, mouse or HUD. Not isSimulated(): a server simulates every player and owns none.

Returns: True when the local player owns the entity.

◆ isReplaying()

bool Vkm::Engine::Behavior::isReplaying ( ) const

inlineprotected

Whether this tick already happened and is being run again.

A mispredicting client replays ticks. Computation must re-run, but nothing presented (an animation, a sound) may. False offline and on a server.

Returns: True during a replayed tick.

◆ command()

const InputCommand & Vkm::Engine::Behavior::command ( ) const

inlineprotected

The input driving this entity on the tick now running.

Offline, the local player's, whatever the entity; online, its driving player's, or nothing held. Read this, not the device, which misses taps between ticks, repeats presses on slow frames and cannot be replayed.

Returns: The command for this entity on this tick.

◆ spawn() [1/3]

EntityId Vkm::Engine::Behavior::spawn ( )

inlineprotected

Create a new, empty entity; add components to it through scene().

Safe from a hook; a behavior added during a pass starts on the next. Local to this end, so a client warns once; use NetSession::spawn on the server instead.

Returns: The new entity.

◆ spawn() [2/3]

EntityId Vkm::Engine::Behavior::spawn ( const char * name )

inlineprotected

Create an entity carrying name.

Parameters

name	Human-readable name; truncated into Name's fixed buffer.

Returns: The new entity.

◆ spawn() [3/3]

EntityId Vkm::Engine::Behavior::spawn	(	const char *	name,
		EntityId	parent )

inlineprotected

Create an entity carrying name, parented under parent.

Parenting is HierarchyOperations::setParent.

Parameters

name	Human-readable name; truncated into Name's fixed buffer.
parent	Entity to attach it under; must be alive.

Returns: The new entity.

◆ destroy()

void Vkm::Engine::Behavior::destroy ( EntityId target )

inlineprotected

Destroy entity and its subtree, firing onDestroy.

Deferred past the hook pass, so destroying your own entity is safe; drained on paused frames too.

Parameters

target Root of the subtree to destroy.

◆ loadScene()

void Vkm::Engine::Behavior::loadScene ( const std::string & scenePath )

inlineprotected

Load scenePath, replacing everything currently in the scene.

Deferred to the end of the hook pass, since it destroys the caller; the last request wins. Works while paused, but the new scene starts only once time flows, so a paused caller must resume the clock itself.

Parameters

scenePath Scene file, relative to the project root.

◆ subscribe()

template<typename EventT = void, typename Fn>

void Vkm::Engine::Behavior::subscribe ( Fn && callback )

inlineprotected

Listen for an event until the behavior is destroyed or the session ends.

subscribe([this](const UIClickEvent& click) { onClick(click); });

Vkm::Engine::Behavior::subscribe

void subscribe(Fn &&callback)

Listen for an event until the behavior is destroyed or the session ends.

Definition behavior.h:564

Vkm::Engine::UIClickEvent

Fired when a UIButton is clicked (a press released over the same button).

Definition ui_events.h:19

Name the type (subscribe<UIClickEvent>(...)) only for a generic lambda.

Template Parameters

EventT	Event type to listen for; deduced when left out.
Fn	Callable taking const EventT&.

Parameters

callback Called with each event; a throw is reported but does not disable.

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

system/script/behavior.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Function Documentation

◆ onStart()

◆ onUpdate()

◆ onRealtimeUpdate()

◆ onFixedUpdate()

◆ onCollisionEnter()

◆ onCollisionStay()

◆ onCollisionExit()

◆ onTriggerEnter()

◆ onTriggerStay()

◆ onTriggerExit()

◆ typeName()

◆ visitFields()

◆ clone()

◆ entity()

◆ tryGet() [1/2]

◆ tryGet() [2/2]

◆ get() [1/2]

◆ get() [2/2]

◆ has()

◆ add()

◆ findBehavior() [1/4]

◆ findBehavior() [2/4]

◆ findBehavior() [3/4]

◆ findBehavior() [4/4]

◆ scene()

◆ resources()

◆ events()

◆ render()

◆ input()

◆ net()

◆ clock()

◆ window()

◆ isSimulated()

◆ isMine()

◆ isReplaying()

◆ command()

◆ spawn() [1/3]

◆ spawn() [2/3]

◆ spawn() [3/3]

◆ destroy()

◆ loadScene()

◆ subscribe()