cturtle/events

include "cturtle/events";

Events let one part of a game tell the rest that something happened.

Each kind of event is an object type: declare an object whose fields hold the event's data, register it once with eventRegister, then subscribe to it and fire it by naming the type:

object ScoreChanged { int player; float score; }

eventRegister(typeof(ScoreChanged), eventFifo())?;
channel<ScoreChanged> scores = eventSubscribe(typeof(ScoreChanged), 16)?;
eventFire(ScoreChanged { player: 1, score: 10.0 })?;

The engine's own events, such as this package's UiInputEvent, are object types too. Subscribe to them the same way; they need no registering.

eventRegister, eventSubscribe and eventFire fail with: -450 when the type has not been registered as an event, -451 when an event of that name is already registered with different fields, -452 when scripts may not fire, or may not subscribe to, that event, -453 when the type cannot be an event (it is not an object, or a field is not bool, int, float, string or Entity), and -454 when delivery could not be set up.

Types

EventDelivery

Object

How an event reaches each subscriber; see eventFifo and eventConflate.

ResolvedCollisionHit

Object

Field	Type	Writable	Description
source	Entity	yes
target	Entity	yes
proxy	Entity	yes
provider	int	yes
payload	int	yes
layer	int	yes
mask	int	yes
tag	int	yes
t	float	yes
exitT	float	yes
x	float	yes
y	float	yes
z	float	yes
normalX	float	yes
normalY	float	yes

UiInputEvent

Object

Field	Type	Writable	Description
kind	int	yes
surface	int	yes
hitToken	int	yes
button	int	yes
x	float	yes
y	float	yes
dx	float	yes
dy	float	yes
scrollX	float	yes
scrollY	float	yes
key	int	yes
modifiers	int	yes
codepoint	int	yes
text	string	yes

UiSurfaceResized

Object

Field	Type	Writable	Description
surface	int	yes
width	int	yes
height	int	yes

UiElementLayoutChanged

Object

Field	Type	Writable	Description
element	int	yes
x	float	yes
y	float	yes
width	float	yes
height	float	yes

UiTransitionFinished

Object

Field	Type	Writable	Description
element	int	yes
property	int	yes

UiBrowserLocationChanged

Object

Field	Type	Writable	Description
location	string	yes

GameSessionStateChanged

Object

Field	Type	Writable	Description
state	int	yes
status	int	yes
message	string	yes

FileDropped

Object

Field	Type	Writable	Description
path	string	yes
index	int	yes
count	int	yes

WindowCloseRequested

Object

Field	Type	Writable	Description
request	int	yes

StudioDocumentSnapshotRequested

Object

Field	Type	Writable	Description
request	int	yes
plugin	int	yes
generation	int	yes
uri	string	yes

StudioDocumentReplaceRequested

Object

Field	Type	Writable	Description
request	int	yes
plugin	int	yes
generation	int	yes
uri	string	yes
revision	int	yes
source	string	yes

StudioDocumentEditsRequested

Object

Field	Type	Writable	Description
request	int	yes
plugin	int	yes
generation	int	yes
uri	string	yes
revision	int	yes
label	string	yes

StudioDocumentSaveRequested

Object

Field	Type	Writable	Description
request	int	yes
plugin	int	yes
generation	int	yes
uri	string	yes
revision	int	yes

StudioSourceRevealRequested

Object

Field	Type	Writable	Description
request	int	yes
plugin	int	yes
generation	int	yes
uri	string	yes
line	int	yes
column	int	yes

StudioPluginFailed

Object

Field	Type	Writable	Description
plugin	int	yes
message	string	yes

StudioGameRunRequested

Object

Field	Type	Writable	Description
request	int	yes
plugin	int	yes
generation	int	yes
uri	string	yes

ConsoleStateChanged

Object

Field	Type	Writable	Description
revision	int	yes
open	bool	yes

ConsoleLineAdded

Object

Field	Type	Writable	Description
line	string	yes

ConsoleStreamRequested

Object

Field	Type	Writable	Description
maxLines	int	yes

ConsoleCommandSubmitted

Object

Field	Type	Writable	Description
command	string	yes

ConsoleDismissed

Object

Field	Type	Writable	Description
byEscape	bool	yes

ResolvedCollisionBatch

Object

Field	Type	Writable	Description
sequence	int	yes
part	int	yes
last	bool	yes
startX	float	yes
startY	float	yes
endX	float	yes
endY	float	yes
radius	float	yes
hits	array<ResolvedCollisionHit>	yes

Functions

eventRegister

fn eventRegister(type<$T> payload, EventDelivery delivery)

Makes the object type T an event that scripts can subscribe to and fire. Its fields must be bool, int, float, string or Entity. Registering the same type again succeeds; a type of the same name with different fields fails with -451.

eventSubscribe

fn eventSubscribe(type<$T> payload, int capacity) -> channel<$T>

A new channel receiving every T event fired from now on. capacity is how many events the channel holds; with eventFifo delivery, further events wait in a queue instead of being dropped.

eventFire

fn eventFire($T event)

Sends event to the engine and to every channel subscribed to its type.

eventFifo ^infallible

infallible fn eventFifo() -> EventDelivery

Every event, in order. Events sent to a full channel wait in a queue instead of being dropped.

eventConflate ^infallible

infallible fn eventConflate() -> EventDelivery

Only the newest event each subscriber has not yet received. The last event fired always arrives.