The event loop
The life-cycle of events in Indigo is very strict so that we can support referential transparency.
Key features of events:
- Events are immutable.
- Events are ordered (First-In-First-Out).
- Events that are present at the start of a frame, are all of the events.
- Events generated during the frame will only become available in the next frame.
- Events only last for a single frame, whether acted on or not, before being disposed of.
The events list received by the frame is never empty, it always contains one
Frametick event, and it is always last.
Indigo processes events as follows:
- The current frame emits events via
Outcomes. These events are not available to the current frame.
- Most events are sent to a queue, but some system specific events will be processed and actioned immediately, specifically:
- Audio events
- Network events
- Storage events
- Asset load events
- When the next frame starts, all the messages that went to the queue are retrieved in order, and the
- The events are then used to construct the
InputStatewhich is included as part of the
- The events are then consumed as follows (note that each stage could create new events to be processed on the next frame):
- The events are sent to the model update function in order.
- The events are sent to the view model update function in order.
- The events are sent to the subsystem update functions in order.
- The events are passed to scene elements to process entity events.
- All events are then discarded.
All events must be tagged with the
GlobalEvent trait in order for Indigo to process them.
You can create your own events by simply extending
FrameTick- the last event on a frame, used to update anything that must be updated every frame.
ViewportResize(viewport)- emitted when the game is resized so that your game layout can adapt.
ToggleFullScreen- Attempt to enter or exit full screen mode
EnterFullScreen- Attempt to enter full screen mode
ExitFullScreen- Attempt to exit full screen mode
FullScreenEntered- The game entered full screen mode
FullScreenEnterError- A problem occurred trying to enter full screen
FullScreenExited- The game exited full screen mode
FullScreenExitError- A problem occurred trying to exit full screen
ApplicationGainedFocus- The application is in focus
ApplicationLostFocus- The application has lost focus
CanvasGainedFocus- The game canvas is in focus
CanvasLostFocus- The game canvas has lost focus
CanvasLostFocus are very similar to their
counterparts. The main difference is that the game canvas can lose focus independently
of the application if the game is being run from inside a web application (such as
a Tyrian App or game site). In this scenario the
Canvas* events will fire whenever
the canvas loses or gains focus from the user clicking around the external parts
of the site, and will also fire when the application loses or gains focus.
InputEvents can be a bit tricky in some situations, so Indigo includes
Keyboard classes that can be accessed from the frame context, providing a rich interface to gather more complex information from those input devices.
What did the mouse do and at what location?
A Mouse event consists of the following properties:
position- The location of the mouse
buttons- The buttons that were down at the time of the event
isAltKeyDown- Whether the
altkey is held down
isCtrlKeyDown- Whether the
ctrlkey is held down
isMetaKeyDown- Whether the
cmdkey was held down
isShiftKeyDown- Whether the
shiftkey was held down
movementPosition- The difference between the position of this event, and the last mouse event
For events (such as
Click) where a button is pressed, an additional
button property is provided.
Up to five mouse buttons are supported, including the most common left, middle and right buttons.
The following events are available:
Click(position, buttons, isAltKeyDown, isCtrlKeyDown, isMetaKeyDown, isShiftKeyDown, movementPosition, button)
MouseUp(position, buttons, isAltKeyDown, isCtrlKeyDown, isMetaKeyDown, isShiftKeyDown, movementPosition, button)
MouseDown(position, buttons, isAltKeyDown, isCtrlKeyDown, isMetaKeyDown, isShiftKeyDown, movementPosition, button)
Move(position, buttons, isAltKeyDown, isCtrlKeyDown, isMetaKeyDown, isShiftKeyDown, movementPosition)
Wheel(position, buttons, isAltKeyDown, isCtrlKeyDown, isMetaKeyDown, isShiftKeyDown, movementPosition, amount)
There is only one audio event used to play one off sound effects, since background music is described on the
It's important to be aware that a network is considered online if there is access to the local network only. As such, an online network is not a guarantee that the internet or indeed a single resource on the internet is available.
Web socket events
GET(url, params, headers)
POST(url, params, headers, body)
PUT(url, params, headers, body)
DELETE(url, params, headers, body)
HttpError- Unspecified error
HttpResponse(status, headers, body)
Used to load and save data from local storage.
Save(key, data)- Request the serialized data is stored against the given key.
Load(key)- Load the data stored with the given key
Delete(key)- Delete the data stored against the given key
DeleteAll- Delete all stored data
Loaded(key, data)- Response event when data has been loaded
Should any of the above fail one of the following
StorageEventError types will
be raised as a separate event.
QuotaExceeded(key, actionType)- There is not enough room on the device
InvalidPermissions(key, actionType)- There were not enough permissions granted to access storage
FeatureNotAvailable(key, actionType)- The storage feature is not available
Unspecified(key, actionType, message)- An unknown error
These are the low level events used to load additional assets at runtime. If you want a slightly more sophisticated loading experience, please look at the asset bundle loader sub system.
Note that the
LoadAsset event is a convenience event, and in fact loads a bundle containing one element, which is why there is no corresponding "
AssetLoadError" event, just the bundle version.
The load events also have a
makeAvailableflag, which if set to false, loads the asset to the browsers cache but doesn't add it to the engine, this means you can add it to the engine quickly later. The
availableflag on the response indicates whether the asset has been made available or not.
LoadAsset(assetType, optional key, makeAvailable)- Load a single asset
LoadAssetBatch(set of assetType, optional key, makeAvailable)- Load a batch of assets
AssetBatchLoaded(optional key, available)- The response event to
AssetBatchLoadError(optional key)- If an error occurs during load, the game will be sent this event
Next- Instructs Indigo to advance one scene when emitted.
Previous- Instructs Indigo to go back by one scene when emitted.
JumpTo(sceneName)- Instructs Indigo to switch to the specified scene when emitted.
SceneChange(from, to, at)- Indigo emits this event when it changes scene. It is a useful hook that allows you to take action at the point of change. Example: Scene running time can be calculated as
context.running - atif you need an animation to play from the beginning of a scene.
Spawn(key, position, lifeSpan, payload)
KillAll- Remove them all immediately.
Cull- Remove automatons who have reached the end of their time, you don't have to call this manually.
RendererDetails(renderingTechnology, clearColor, magnification)- "renderingTechnology" tells you if Indigo is using WebGL 1.0 or WebGL 2.0.