Variables

You may have noticed that some properties claiming they support "variables". Without getting too far into the complexities of it, variables are a way to declare, compute, and propagate values through the model's inheritance tree.

There are two ways to use variables: Either you're declaring them to be used in other parts of a model and by its descendants, or you're redeclaring and using variables declared in a parent for your own model.

< back to Root Model Definition

Declaring Variables

Variables can only be declared in a small number of places:

1. In a root model definition
2. In a slotted model definition

In both cases variables declared made visible from any property that supports variables in that file by using the variable reference syntax (below), and to any real or virtual file that uses this file as their parent.

To declare variables, you simply have to create a locals object in the root of your model, and name the values for each one. Every property in the locals object becomes a variable you can reference from other places.

// quadruped.json

        "parent": "mson:my_parent"
	"locals": {
		"leg_length": 0,
		"leg_rotation_z": -5,
		"leg_rotation_x": 3
	}

As you can see, the above block defines 4 variables: leg_length, leg_rotation_x, leg_rotation_z. Each variable has a numeric value associated with it (all variables are exclusively numbers*) that will take that variable's place when building the model.

Redeclaring Variables

Variables are not exclusive to your model, though. They can be referenced re-declared by anyone that uses our model as their parent.

// cow.json

	"parent": "mson:quadruped",
	"locals": {
		"leg_length": 12
	},

Here this model has changed the leg_length variable to 12meaning that anywhere this variable is referenced, the value 12 will be used instead of 0. The same is true for usages in the parent! Declarations bubble up, which means any time leg_length is referenced in the context of this model, whether from itself or its parent, the value from the most recent declaration will be used.

Variables used like this are essentially properties in their own right, and when used correctly allow for mod/api makers to expose customisations to their children by way of changing these variables.

Variable Algebra

Declarations aren't restricted to simple constants, though. More complicated relations can be constructed by referencing other variables within your declaration.

All the basic algebraic functions are supported (+, -, *, /, ^) and are arranged in arrays with their operands as you would expect.

	"locals": {
		"leg_length": 0,
		"leg_rotation_z": -5,
		"leg_rotation_z_neg": 7,
		"leg_rotation_x": 3,
		"leg_rotation_x_neg": [0, "-", "#leg_rotation_x"],
		"leg_rotation_y": [24, "-", "#leg_length"],
		"head_rotation_y": [18, "-", "#leg_length"],
		"body_rotation_y": [17, "-", "#leg_length"]
	},

Referencing Variables

Referencing variable is pretty straight forward.

imply replace the normal value you would use with a text value containing the variable's name in the format: #variable_name