Extended API

Intrinsics

sparkref

[var name] = sparkref(“[spark instance name]”)

Returns: ValMap in the “Spark” format

MEMORY HEAVY

Used for cases where a Spark Instance needs to be modified many times within the same script. This could be multiple traits on the same instance or the same traits modified multiple times (as in the case of a for or while loop).

spark = sparkref("Spark 1")

spark.traits.altitude = 3

spark.traits.position.value = "(0,1)"

color = spark.traits.color.value

color = "(0,0,0,1)"

spark.traits.color = color

mod

mod(“[spark instance name]”, “[trait display name]”, [value])

Used for cases where sparkref is overkill. It uses next to no memory and is “on-demand,” meaning it is slower than sparkref but only at scale. The performance hit should be minimal if you are not doing more than ten or more of these in a row.

mod("Spark 1", "Color", "(1,1,1,1)")

invokeOutput

invokeOutput([1 for success, 0 for failure])

Used for invoking one of the two outputs of the given Ember node. It should be treated like a return and be after the rest of the logic in the script.

Note: InvokeOutput must be triggered from the Behavior tree to invoke outputs properly.

invokeSuccess

invokeSuccess()

Used as a shortcut to invokeOutput(1).

invokeFailure

invokeFailure()

Used as a shortcut to invokeOutput(0).

ValMap Formats

Spark

Returned from the sparkRef intrinsic

Keys:

• “traitNames”

• • Immutable ValList of ValString

  • A list of strings with each of the names of the traits available.

  • These names (and those in the below traits key) are in camelCase.

• “traits”

• • ValList of ValMap

  • A list of ValMaps in the Trait format for each trait available to the spark.

Trait

Returned from the “traits” key in “Spark” valmaps.

Keys:

• “guid"

• • Immutable ValString

  • The guid for this trait

• "label"

• • Immutable ValString

  • The label for this trait.

  • This property in camelCase is used in the Spark ValMap to modify this trait.

• "type"

• • Immutable ValString

  • The fully qualified name of the type of this trait

• "isVisible"

• • ValNumber with a value of 0 (false) or 1 (true)

  • Is this trait visible in the Inspector?

• “value”

• • A representation of the value of this trait.

  • Note: Not available if the trait is of an unsupported type.

Examples:

button = sparkref("Button")

button.traits.isVisible = 0 //Booleans are denoted by either 0 (false) or 1 (true)

button.traits.labelText = "Press Me"

//Setting a value with either the name or the .value is allowed

//However, be sure to use .value to retrieve the value.

button.traits.sortOrder.value = 1

button.traits.isVisible = 1

mod("Spark 1", "Altitude", 0.5)

invokeOutput(1)

more to come…