SDKInstanceBase interface

Addon SDK v1 retirement

The SDKInstanceBase interface is used as the base class for runtime instances in the SDK. For "world" type plugins, instances instead derive from SDKWorldInstanceBase which itself derives from SDKInstanceBase.

SDKInstanceBase cannot be directly constructed; it should only be used as a base class.

Properties

this._inst

Reference to the Instance representing this instance in the runtime. This allows access to Construct's built-in runtime features for instances.

this._runtime

Reference to the associated Runtime that controls execution of the project.

this._objectClass

Reference to the ObjectClass representing the object type that this instance belongs to.

this._sdkType

Reference to your addon's SDK type class, which derives from SDKTypeBase.

Methods

Release()

Optional override for when an instance is released.

GetInstance()

Returns this._inst publicly.

GetRuntime()

Returns this._runtime publicly.

GetObjectClass()

Returns this._objectClass publicly.

GetSdkType()

Returns this._sdkType publicly.

GetPlugin()

Returns your addon's SDK plugin class, which derives from SDKPluginBase.

Trigger(method)

Fire a trigger condition. The condition must be declared as a trigger in aces.json. Pass a full reference to the condition method, e.g. this.Trigger(C3.Plugins.Sprite.Cnds.OnAnimFinished).

AddDOMMessageHandler(handler, callback)

AddDOMMessageHandlers(arr)

Add a callback to be run to handle a message posted from a DOM-side script. The handler is a string identifier. The callback receives the posted data as an argument. Note that if the caller in the DOM-side script originally used the PostToRuntimeAsync method, the callback may be an async function, and the return value is posted back to the DOM-side script. The AddDOMMessageHandlers variant accepts an array of [handler, callback] which is convenient when adding multiple handlers.

PostToDOM(handler, data)

PostToDOMAsync(handler, data)

Post a message to a DOM-side script. The handler is a string identifier. The data must be structurally clonable (since it is posted down a MessageChannel).
The async method returns a promise that resolves with the DOM-side callback's return value. The non-async method does not return a value and the DOM-side callback's return value is discarded (i.e. a "fire and forget" message).

_StartTicking()

_StartTicking2()

IsTicking()

IsTicking2()

_StopTicking()

_StopTicking2()

Utility methods to start or stop the runtime calling the Tick() or Tick2() methods of your instance every tick, and also to check whether ticking is active. It is recommended to stop ticking whenever the tick method is no longer needed to reduce the performance overhead of ticking. Redundant calls to start or stop ticking are ignored. The first call always takes effect (i.e. calls do not stack - if you make 3 calls to start ticking then 1 call to stop ticking, ticking is stopped).

Tick()

Optional override that is called every tick just before events are run after _StartTicking() has been called.

Tick2()

Optional override that is called every tick just after events are run after _StartTicking2() has been called.

GetDebuggerProperties()

Override to return properties to display in the debugger. For more information see runtime scripts.

SaveToJson()

Optional override to return a JSON object that represents the state of the instance for savegames.

LoadFromJson(o)

Optional override accepting a JSON object returned by a prior call to SaveToJson() that represents the state of an instance to load, for savegames.

CallAction(actMethod, ...args)

Convenience method to run an action method with the given parameters. For example: this.CallAction(C3.Plugins.MyAddon.Acts.MyAction, "foo", "bar")

CallExpression(expMethod, ...args)

Convenience method to run an expression method with the given parameters. Returns the value returned by the expression. For example: const value = this.CallExpression(C3.Plugins.MyAddon.Exps.MyExpression)

GetScriptInterfaceClass()

Return a custom class to instantiate for the script interface in Construct's scripting feature. See the SDK downloads for sample usage of a custom script interface.

GetScriptInterface()

Return the actual script interface used for this instance in Construct's scripting feature. This is an IInstance or derivative.

DispatchScriptEvent(name, cancelable, additionalProperties)

Fire an event on the script interface for the instance (as with dispatchEvent() on the script interface). name is a string of the event name. cancelable is a boolean indicating if the event can be stopped with preventDefault(). The event object will have the default properties as described in Instance event in the scripting reference. Additional properties can optionally be set by passing an object for additionalProperties whose properties will be added to the event object. For example: DispatchScriptEvent("myevent", false, { extraProperty: 5 })

Wrapper extension methods

These methods relate to the use of wrapper extensions. Refer to that manual section for more details; for completeness the relevant methods are also included here.

SetWrapperExtensionComponentId(componentId)

Set the component ID of the wrapper extension. This must match the component ID set by the wrapper extension and must be unique to all wrapper extensions in use. It must be called prior to using any other wrapper extension methods.

IsWrapperExtensionAvailable()

Returns a boolean indicating whether the corresponding wrapper extension was successfully loaded. If this returns false then no messages sent to the wrapper extension will be received, and async messages will return a promise that never resolves.

AddWrapperExtensionMessageHandler(messageId, callback)

AddWrapperMessageHandlers(list)

Add a callback to be run to handle a message posted from the corresponding wrapper extension. The callback receives the JSON data sent from the wrapper extension as an argument. The AddWrapperMessageHandlers variant accepts an array of [messageId, callback] which is convenient when adding multiple handlers.

SendWrapperExtensionMessage(messageId, params)

SendWrapperExtensionMessageAsync(messageId, params)

Send a message to the wrapper extension. The message ID is used to identify the kind of message. params is an optional array of parameters to provide. These may only be boolean, number or string type values. The async variant returns a Promise that resolves when the wrapper extension responds to the message. The promise resolves with the JSON data sent from the wrapper extension.