Threads ‐ JSON Declaration Syntax

Summary

Entity threads are supported by a number of constructs throughout the engine.

Most notably, this includes features like archetypes and states.

This article covers the standard behavior that glare engine uses to parse and process thread definitions in these circumstances.

Thread List Syntax

For supported constructs, a threads field is commonly used to declare or define what threads are available.

This field can be either an array, string, or object.

If the threads field is an object, each element's key will be used as the thread's name, whereas the element's value will be used as its content:

"threads":
{
	"my_thread":
	[
		"print(\"Hello from my_thread\")"
	],
	
	"my_other_thread": "path/to/my_other_thread"
}

If the threads field is an array, each element is enumerated and processed as an anonymous thread, meaning that the thread's name is not explicitly set in the declaration phase, but could be later defined in the thread's contents, using a name instruction:

"threads":
[
	[
		"print(\"Hello from an anonymous thread\")"
	],
	
	"path/to/my_other_anonymous_thread",
	
	[
		"name(\"named_thread\")",
		"print(\"Hello from named_thread\")"
	]
]

If the threads field is a string, the value is used directly as the content of the thread, meaning a single thread will be loaded from the path specified:

"threads": "path/to/some_thread"

When a string/path is used to load a thread, that thread's filename (excluding its extension) is adopted as its name.

Thread Content

A thread's content may be supplied as either an array, string, or object.

Array Syntax:

If the thread's content is an array, each element will be treated as an instruction. In most cases, these will be string values presenting lines of Entity Script source code, although both nested array and object syntax is also supported.

Example of string elements:

[
	"print(\"Waiting 10 seconds...\")",
	"sleep(10)",
	"print(\"10 seconds are up.\")"
]

If a nested array is used, each element of the array is treated as an instruction to be bundled into a multi-instruction block, allowing for multiple actions to take place on one update tick.

Example of array elements:

[
	[
		"print(\"First operation, executed on first tick, along with Second and Third\")",
		"print(\"Second operation, executed on first tick, along with First and Third\")",
		"print(\"Third operation, executed on first tick, along with First and Second\")"
	],
	
	"print(\"Fourth operation, executed on second tick\")",
	"print(\"Fifth operation, executed on third tick\")",
]

^{Sub-instructions in a multi-instruction block are always executed in-order, on the same thread update tick.}

If a nested object is used, the result is a manual update instruction. These instructions can be useful, as they provide a natural way of updating one or more components' members in a similar manor to a state, or archetype:

[
	{
		"NameComponent": "Some Name"
	}
]

Manual update instructions also have an optional target field, which allows for specification of a different entity to be updated than the context entity. This can be performed using Entity Reference Syntax:

[
	{
		"target": "child(my_child)",
		
		"NameComponent": "Some Name for my_child",
	}	
]

These manual update instructions behave similarly to any other instruction, in that they execute in their entirety once reached. This means that multiple components may be updated in a single update tick.

String Syntax

Direct usage of a string value (i.e. un-nested) allows for specification of a file path to an Entity Script detailing the thread's contents.

This syntax allows for a thread's content to be stored remotely, allowing for a more intuitive development experience:

"path/to/my_script"

Paths are relative to the owning construct's working directory. This in turn allows for better encapsulation for things like states or archetypes as script files can be contained in designated sub-directories.

Object Syntax

Object syntax allows for the entirety of a thread's contents to be a manual update instruction. For more details, please view the nested object segment of the Array Syntax section above.

Example using object syntax:

{
	"target": "parent",
	
	"+camera": { "fov": 120.0 }
}