Runtime

Addon SDK v1 retirement

The Runtime class controls execution of a project. It is the equivalent of an IProject at runtime.

Events

The following events are fired on the runtime dispatcher, which is accessed using runtime.Dispatcher(). For example to add an "instancedestroy" event, use runtime.Dispatcher().addEventListener("instancedestroy", callback).

"instancedestroy"

Fired when any instance is destroyed. The callback receives an event object with an instance property referring to the Instance that was destroyed. Use this event to ensure all references to destroyed instances are dropped.

"afterload"

Fired after the LoadFromJson call after the rest of the runtime has finished loading. This means all objects are available and can be looked up by their UID. For example to save a reference to an instance, save its UID to JSON, load its UID and store it in LoadFromJson(), and then look it up with GetInstanceByUID() in the "afterload" event.

"beforefirstlayoutstart"

"beforelayoutstart"

"afterlayoutstart"

"afterfirstlayoutstart"

Fired when starting a layout. The events fire in the order shown, with the On start of layout trigger firing in between "beforelayoutstart" and "afterlayoutstart". The "beforefirstlayoutstart" and "afterfirstlayoutstart" events only trigger for the first layout in the project, so can be used to determine when the project starts running. In all cases, all instances on the layout are already created and available to modify.

Methods

Dispatcher()

Return the runtime event dispatcher. This is where runtime events are fired. For example use runtime.Dispatcher().addEventListener(...) to listen for a runtime event.

GetAssetManager()

Return the project's AssetManager, which is used to load sub-resources.

AddLoadPromise(promise)

Only valid while the project is still loading. Add a promise that the runtime will wait to resolve before starting the first layout. This is useful if you want to make sure your addon loads a dynamic resource before the game starts.

IsInWorker()

Return true if the runtime is hosted in a worker. The DOM will be unavailable.

IsPreview()

Returns true if running in Construct 3's preview mode.

GetAllObjectClasses()

Return a read-only array of all ObjectClass in the project. Note this includes families.

GetObjectClassByName(name)

Look up an ObjectClass by a case-insensitive string of its name. Note this can return a family.

GetObjectClassBySID(sid)

Look up an ObjectClass by a SID (Serialization ID), which is a unique number assigned to every ObjectClass. Note this can return a family.

GetSingleGlobalObjectClassByCtor(ctor)

Look up a single-global plugin's ObjectClass by its plugin constructor function, e.g. C3.Plugins.Facebook. Returns null if the plugin is not added to the project.

CreateInstance(objectClass, layer, x, y)

Create and return a new Instance of an ObjectClass on the given Layer at a position.

DestroyInstance(inst)

Destroy an Instance.

GetObjectCount()

Get the total number of instances created.

GetInstanceByUID(uid)

Look up an Instance by its UID. If none exists with the given UID, returns null.

GetEventSheetManager()

Return the EventSheetManager that handles the event system.

GetEventStack()

Return the EventStack. This is a shorthand for GetEventSheetManager().GetEventStack().

GetCurrentEventStackFrame()

Return the current EventStackFrame. This is a shorthand for GetEventSheetManager().GetCurrentEventStackFrame().

GetCurrentEvent()

Return the current EventBlock. This is a shorthand for GetEventSheetManager().GetCurrentEvent().

GetCanvasClientX()

GetCanvasClientY()

Return the offset of the canvas in the document in CSS pixels.

GetCanvasCssWidth()

GetCanvasCssHeight()

Return the size of the canvas in the document in CSS pixels.

GetSampling()

Return one of "nearest", "bilinear" or "trilinear", reflecting the project Sampling property.

UpdateRender()

Call to indicate that something visible has changed. Most runtime code calls this automatically. However by default if this is not called during a tick, the runtime will skip drawing a frame on the assumption nothing visible has changed.

GetWebGLRenderer()

Return the WebGLRenderer for the runtime, which is responsible for rendering graphics.

GetMainRunningLayout()

Return the main Layout that is currently running.

SetTimeScale(t)

GetTimeScale()

Set and get the timescale as a multiplier.

GetDt(inst)

Get the current delta-time (time the last frame took) in seconds. You can optionally pass an Instance to get delta-time using the object's own timescale.

GetStartTime()

Get the timestamp in milliseconds at the time the runtime started up.

GetGameTime()

Get the in-game time in seconds, which can be affected by time scaling.

GetWallTime()

Get the in-game time in seconds without taking in to account time scaling (aka the "wall clock" time).

GetTickCount()

Get the number of ticks that have elapsed so far.

GetProjectName()

GetProjectVersion()

Return a string of the name and version of the project.

GetProjectUniqueId()

Return a string representing a unique identifier for this project.

SetPixelRoundingEnabled(e)

IsPixelRoundingEnabled()

Set and get a boolean indicating whether pixel rounding is enabled.

InvokeDownload(url, filename)

Invoke a download of the given URL and use the provided filename. The URL can be a blob URL.

Random()

Generate a random number in the range [0,1), which is the same range as Math.random(). Use this method to allow the runtime control over the random number generator, e.g. setting a fixed seed to reproduce the same random sequence.

SetSuspended(suspend)

Pass true to suspend the runtime or false to resume it if paused. When suspended, the entire runtime halts and stops processing events or drawing the screen. This is done by default when the window or app goes in to the background.