Construct 3 icon

Construct 3

Documentation

Runtime script interface

Ashley's avatar
Medal
Construct Team Founder
Published 28 May, 2019
953 words
~4-6 mins

The IRuntime script interface provides a way for JavaScript code in Construct to interact with the engine.

Runtime events

The following events can be listened for using the addEventListener method.

"tick"

Fires every tick, just before running the layout's event sheet. Use the runtime.dt property to access delta-time and step the game's logic by that amount of time.

"beforeprojectstart"

"afterprojectstart"

Fired once only when the first layout in the project starts. "beforeprojectstart" fires before "beforelayoutstart" on the first layout, which in turn is before On start of layout triggers. "afterprojectstart" fires after "afterlayoutstart" on the first layout, which in turn is after On start of layout triggers. In both events, all instances on the first layout are created and available to modify.

"keydown"

"keyup"

Fired when keys are pressed and release on the keyboard. These pass copies of a KeyboardEvent.

"mousedown"

"mousemove"

"mouseup"

"dblclick"

Fired when mouse input is received. These pass copies of a MouseEvent.

"wheel"

Fired when mouse wheel input is received. This passes a copy of a WheelEvent.

"pointerdown"

"pointermove"

"pointerup"

"pointercancel"

Fired when pointer input is received. This covers mouse, pen and touch input. These pass copies of a PointerEvent. Construct also adds a lastButtons property for "mouse" type pointers with the previous buttons state, which makes it easier to detect if different mouse buttons have been pressed or released in this event.

Runtime APIs

addEventListener(eventName, callback)

removeEventListener(eventName, callback)

Add or remove a callback function for an event. See Runtime events above for the available events.

dt

Return the value of delta-time, i.e. the time since the last frame, in seconds.

gameTime

Return the in-game time in seconds, which is affected by the time scale. This is equivalent to the time system expression.

objects

An object with a property for each object class in the project. For example if the project has an object named Sprite, then runtime.objects.Sprite will refer to the IObjectClass interface for Sprite.

globalVars

An object with a property for each global variable on an event sheet in the project. For example if the project has a global variable on an event sheet named Score, then runtime.globalVars.Score provides access to the global variable from script.

mouse

A shorthand reference to the Mouse script interface. This is only set if the Mouse plugin is added to the project.

keyboard

A shorthand reference to the Keyboard script interface. This is only set if the Keyboard plugin is added to the project.

layout

An ILayout interface representing the current layout.

getLayout(layoutNameOrIndex)

Get an ILayout interface for a layout in the project, by a case-insensitive string of its name or its zero-based index in the project.

getAllLayouts()

Return an array of ILayout interfaces representing all the layouts in the project, in the sequence they appear in the Project Bar.

goToLayout(layoutNameOrIndex)

End the current layout and switch to a new layout given by a case-insensitive string of its name, or its zero-based index in the project (which is the order layouts appear in the Project Bar with all folders expanded). Note the layout switch does not take place until the end of the current tick.

assets

An IAssetManager interface providing access to project assets like sound and music files or other project files, as well as audio decoding utilities.

storage

An IStorage interface providing access to storage from scripts. Storage is shared with the Local Storage plugin.

callFunction(name, ...params)

Call a function in an event sheet, by a case-insensitive string of its name. Each parameter added after the name is passed to the function. There must be at least as many parameters provided as the function uses, although any additional parameters will be ignored. If the function has a return value, it will be returned from this method, else it returns null.

setReturnValue(value)

This can only be called from a script in an event sheet function with a return type other than None. It is essentially equivalent to the Set return value action. However the fact this method can be called from script can make it easier to return a value from script from an event sheet function. For example an event sheet function could contain a single script action with the code runtime.setReturnValue(getMyValue()), which means anywhere the event sheet function is called it returns the value of calling getMyValue() in JavaScript.

projectName

A string of the project name, as specified in Project Properties.

projectVersion

A string of the project version, as specified in Project Properties.

random()

Return a random number in the range [0, 1). This is similar to Math.random(), but can produce a deterministic sequence of values if the Advanced Random object overrides the system random.

wallTime

Return the in-game wall-clock time in seconds, which is not affected by the time scale. This is equivalent to the wallclocktime system expression.