Command Reference

smart_batch is called in the same way as the regular batch command with two extensions. The first is that it takes a new environment parameter. The environment allows command parameters to have their values set from the environment rather than directly providing a simple form of templating. The second is that individual commands can write their responses back into the environment for use by subsequent commands. This allows many operations that previously would have required a round trip between client and server to be performed in one call.

Parameters

The command takes the following parameters:

Smart_batch_sub_command

Each command specified in commands is a Map containing the following:

Return value

The command returns an object containing the following:

Environment and parameter replacement

The environment is simply a map where the keys are the names of replaceable parameters. Environment values are referenced in command parameters using the ${NAME} syntax.

Example: Contrived example setting a camera transform via environment parameters.

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "camera_instance": "cam_inst",
            "xform": {
                "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                "wx": 2, "wy": -3, "wz": -10, "ww": 1
            }
        },
        "commands": [
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "${camera_instance}",
                    "transform": "${xform}"
                }
            }
        ]
    }
}

Notice that even though the transform parameter is the string "${xform}" it will be substituted with the matrix provided in the environment so the command receives the correct parameter type. All string values are considered for replacement and any Array or Map arguments are recursively traversed.

Substring replacement

The type replacement above only occurs when the replacement reference is the entire string. If the reference is a substring of the parameter then the substring is replaced with the String converted environment value. This is useful for creating names for related elements.

Example: Creating a camera with similar naming.

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "basename": "main"        
        },
        "commands": [
            {
                "name": "create_element",
                "params" : {
                    "element_name": "${basename}",
                    "element_type": "Instance"
                }
            },
            {
                "name": "create_element",
                "params" : {
                    "element_name": "${basename}_camera",
                    "element_type": "Camera"
                }
            },
            {
                "name": "instance_attach",
                "params" : {
                    "instance_name": "${basename}",
                    "item_name": "${basename}_camera"
                }
            }
        ]
    }
}

This will create an Instance called main, a Camera called main_camera and attach the camera element to the instance.

Dot notation

Environment lookup also supports dot notation to lookup properties within environment objects.

Example: Contrived dot notation example.

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "camera_data" : {
                "instance_name": "cam_inst",
                "xform": {
                    "xx": 1, "xy": 0, "xz": 0, "xw": 0,
                    "yx": 0, "yy": 1, "yz": 0, "yw": 0,
                    "zx": 0, "zy": 0, "zz": 1, "zw": 0,
                    "wx": 2, "wy": -3, "wz": -10, "ww": 1
                }
            }
        },
        "commands": [
            {
                "name": "instance_set_world_to_obj",
                "params" : {
                    "instance_name": "${camera_data.instance_name}",
                    "transform": "${camera_data.xform}"
                }
            }
        ]
    }
}

Environment updating

It is also possible to store the result of a command in the environment. This can then be referenced in later commands.

Example: Copies an argument from one MDL material to another.

{
    "method": "smart_batch",
    "params": {
        "environment": {
            "source_material" : "material1",
            "dest_material" : "material2",
            "argument": "diffuse_color"
        },
        "commands": [
            {
                "name": "mdl_get_argument",
                "params" : {
                    "element_name": "${source_material}",
                    "argument_name": "${argument}"
                },
                "id": "source_value"
            },
            {
                "name": "mdl_set_argument",
                "params" : {
                    "element_name": "${dest_material}",
                    "argument_name": "${argument}",
                    "value": "${source_value}"
                }
            }
        ]
    }
}

The above retrieves the diffuse_color argument from material1 and stores it in the environment as source_value. The second command then sets the same argument on material2 by reading it back from the environment.

The environment returned by the command will also contain source_value.