Since an array of script paths is used, if you have a lot of DOM code, you can split it across different files. Don't forget to add these files to the file list in addon.json.
For documentation on the DOM messaging APIs, refer to DOMElementHandler (used in domSide.js), SDKDOMPluginBase (used in plugin.js), and SDKDOMInstanceBase (used in instance.js).
For an example demonstrating how to get started, see the domElementPlugin template in the C3 plugin SDK download. This demonstrates using the above APIs to create a simple <button> element in the DOM with a custom button text, and firing an On clicked trigger, with support for running in a Web Worker.
Supporting the debugger
Plugins and behaviors can display custom properties in the debugger by overriding the GetDebuggerProperties() method of the instance class. It should return an array of property sections of the form { title, properties }, where title is a string of the section title and properties is an array of property objects. Each property object is of the form { name, value } with an optional onedit callback. The name must be a string, and the value can be a string, number or boolean.
Editing properties
If an onedit callback is omitted, the debugger displays the property as read-only. If it is provided, the debugger allows the property to be edited. If it is changed, the callback is run with the new value as a parameter.
In many cases, editing a property does the equivalent of an action. To conveniently manage your code, you can implement actions as methods on your instance class, and call the same method from both the action and the debugger edit handler. These methods can then also be re-used for other interfaces, such as the scripting inferface, or an API for other addons to call.
Translation
By default, property section titles and property names are interpreted as language string keys. This allows them to be translated by looking them up in your addon's language file. Note property values do not have any special treatment. You can bypass the language file lookup by prefixing the string with a dollar character $, e.g. the property name "plugins.sprite.debugger.foo" will look up a string in the language file, but "$foo" will simply display the string foo.
The debugger runs in a separate context to the editor, and as such not all language strings are available. The language keys available in the debugger are:
- The addon name
- All property names
- All combo property items
- Everything under the "debugger" key
In general, if you need a language string for the debugger, simply place it under the "debugger" key, e.g. at "plugins.sprite.debugger.foo".
Sample code
The following code is used by the Sprite plugin to display its animation-related debugger properties. Notice how it uses language keys and calls actions to update properties.
GetDebuggerProperties()
{
const prefix = "plugins.sprite.debugger.animation-properties";
return [{
title: prefix + ".title",
properties: [
{name: prefix + ".current-animation", value: this._currentAnimation.GetName(), onedit: v => this._SetAnimation(v)},
{name: prefix + ".current-frame", value: this._currentFrameIndex, onedit: v => this._SetAnimationFrame(v)},
{name: prefix + ".is-playing", value: this._isAnimationPlaying, onedit: v => this._SetAnimationPlaying(v)},
{name: prefix + ".speed", value: this._currentAnimationSpeed, onedit: v => this._SetAnimationSpeed(v)},
{name: prefix + ".repeats", value: this._animationRepeats, onedit: v => this._SetAnimationRepeats(v)}
]
}];
}