Skip to main content

Adding customizable fields

Luna Playground supports in-browser customisation of playables. This is achieved by the use of Playground Fields. Playground Fields are values that are exposed in Playground Editor as separate controls that allow developers to change some variables without rebuilding the playable.

Please note that these steps are also detailed on our community github alongside 2 example folders containing ready-to-upload playables.

Adding Playground fields to a playable#

1. Open playground.json configuration file and locate "fields" key.#

2. Add as many fields as you like.#

Each field is defined as a simple JSON object residing under specific class name and field name. Let's take this by example: consider the below playground.json:

{
"title": "Basic Playable",
"icon": "", // Icon next to the playable in Luna Playground, takes a Data URL.
"fields": {
"MyClass": {
"MyField": {
"title": "Field Title",
"type": "string",
"defaultValue": "hello, there!",
"section": "",
"order": 0,
"localization": 0,
"options": {}
}
}
}
}

The name of the class (MyClass in the above example) and the field (MyField above) are arbitrary - feel free to use whatever makes sense in your setup. Multiple fields can share the same class name, but the pair class name + field name should be unique. Please keep in mind, however, that updating the playable (uploading a new archive in the place of the previously uploaded one) will take those in consideration trying to match the fields based on the combination of class and field name. For instance, if you keep names the same and do not change field type, it will be retained in all versions keeping the values previously set through the playground.

Let us summarize all available field types:

typeDescriptionAdditional notes
stringA string value, can be multi-line"defaultValue" should be a string, i.e. "not set"
int32An int32 value"defaultValue" should be an int32, i.e. 100
floatA floating-point value"defaultValue" can be any number, i.e. 100.12
boolA boolean value"defaultValue" can be 0 or 1
enumAn integer value with preset list of options"options" key is expected to contain allowed entries, i.e. { "0": "Level 0", "1": "Level 1" }
colorAn RGBA color value"defaultValue" should be an array of 4 values of RGBA components, in 0..1 range, i.e. [ 1, 0, 0, 1 ]
vector2A 2 component vector"defaultValue" should be an array of 2 values, i.e. [ 100, 200 ]
vector3A 3 component vector"defaultValue" should be an array of 3 values, i.e. [ 100, 200, 300 ]
vector4A 4 component vector"defaultValue" should be an array of 4 values, i.e. [ 100, 200, 300, 400 ]

Constraints#

You can add a constraints object to a field to set limits for its values, this will stop values entered in Playground going under/over the set min/max.

An example of adding a constraints object to a field can be seen below.

Setting int/float constraints

If you make use of both the value_min & value_max constraints, your field will appear as a range slider in Luna Playground.

value_step can also be added in order to control at what value the slider increments at, though it is not required in order for a slider to function. By default sliders in Luna Playground will increment by 1 if the slider is affecting an int value, and for float values the default is the difference between the minimum and maximum slider values divided by 100 (max - min)/100.

nameDescriptionAdditional notes
value_minint32/float valueSet a minimum value for an int or float field
value_maxint32/float valueSet a maximum value for an int or float field
value_stepint32/float valueSet the increment value for an int or float field

Example

"mySlider":{
"title": "mySlider",
"type": "int32",
"defaultValue": 10,
"constraints": {
"value_min":1,
"value_max":15,
"value_step":1
}
}

Setting array constraints

If you have an array of Vectors or Colors, you can set the minimum and/or maximum length of said array using the constraints below. Arrays can function in Playground without min or max lengths set, however they will not have limits on the amount of items allowed to be entered into them.

nameDescriptionAdditional notes
array_min_lengthint32/float valueSet a minimum value for an int or float field
array_max_lengthint32/float valueSet a maximum value for an int or float field

Example

"myVec3Array":{
"title": "myVec3Array",
"type": "vector3[]",
"defaultValue": [
[2,4,6], [1,3,5]
],
"constraints": {
"array_min_length":0,
"array_max_length":3
}
}

3. Add JavaScript code to use the values from your playable#

In order to grab the value of the Playground Field, please use Luna.Unity.Playground.get. Since you might want to test your playable locally, don't forget to check for Luna API presence before calling the API, i.e.

function startGame() {
// initialize your game as normal
// ...
// check if Luna is defined meaning Playground API is available
if ( 'Luna' in window ) {
const myValue = Luna.Unity.Playground.get( 'MyClass', 'MyField', 'fallback value' );
// do something with myValue
// ...
}
// continue to initialize your game as normal :)
// ...
}

The Luna.Unity.Playground.get will return a value of corresponding type: if the Playground Field is defined to be a string, a string will be returned; if it's vector, an array will be returned and so on. Color fields allow you to pass an additional, 4th argument to Luna.Unity.Playground.get with the value set to rgba which will make it return a CSS-compatible string corresponding to the color, i.e. #ff00ffff.

Ready-to-use example#

Feel free to check the example residing at https://github.com/LunaCommunity/Playable-Examples/tree/master/full for a minimal setup of a playable using Playground Fields.