Creating Scenarios

Each scenario is made up of a Scenario description .json file, and a number of assets.

The scenario description .json files can be found in the data/training_scenarios/ folder, and all the assets in the scenarios can be found in the models/ folder. All filepaths in the scenario description file assume the asset is in the models folder.

Modify the JSON file manually in your favourite text editor. It is recommended to use an editor that supports JSON syntax e.g. Visual Studio Code.

When you have made your changes and saved the JSON file, you can launch umajin.exe again to get the changes, or if you have it running, you can press F5 and it will instantly reload.

Table of Contents

Asset Pipeline

3D Models

Umajin supports a few different 3d model formats, such as .fbx, but the proprietary .um, and ,uma model formats are preferred. To convert your models, you can use the Umajin Model Converter.

Reallusion Characters

Characters exported from Reallusion’s Character Creator 3 can be added into your scenario and animations can even be played using the play_animation action.

More documentation about how to work with Reallusion characters will be added later.

Scenario JSON format

The scenario description file contains all the structure and behaviour for your scenario. At the top there are some global properties and meta data, but all the contents is contained within the scene property.

Find more detailed information about the object and actions APIs at the Scenario Objects and Scenario Actions pages.

Here is a minimal template to get you started:

{
	"format": "Umajin Scenario",
	"version": "1.0",
	"title": "My Scene",
	"base_path": "models",
	"show_triggers": true,
	"debug_points": false,
	"debug_rigids": false,
	"skydome" : "ibl/studio.tga",
	"radiance_map" : "ibl/studio_radiance.dds",
	"irradiance_map" : "ibl/studio_irradiance.dds",
	"ibl_scale" : 1,
	"scene_light": {
		"position": [-6, 20, 6],
		"fov": 45,
		"frustum_near": 10,
		"frustum_far": 30
	},
	"scene": [
		{
			"id": "street",
			"type": "model",
			"path": "street.obj",
			"position": [0, 0, 0],
			"rotation": [0, 0, 0],
			"scale": 1
		}
	]
}

Interaction

Currently there is only a limited set of ways the user can interact with the world. They can stand inside an area, put their hand within a volume, or use speech. We do have other interactions planned, but this base set already lets us create a wide range of scenarios.

Usually a scenario will start with a scene, and a few trigger areas/volumes. Walking into a trigger area might fire a play_animation action of a character model, then on complete of that action, maybe several other activate actions are fired on some more triggers. These triggers become active and have there own events with actions.

In the example below, a trigger volume is attached to a person who is walking on a loop. If you get close to them, they will stop and tell you to pick up one of two items. Those items then become active.

[
	{
		"id": "walking_woman",
		"type": "model_character",
		"path": "walking_woman",
		"position": [20, 0, 0],
		"on_activate": [
			{
				"type": "play_animation",
				"animation": "walk_01_relaxed_loop",
				"looping": true
			},
			{
				"type": "tween",
				"time": 30000,
				"looping": true,
				"properties": { "position": [-20, 0, 0] }
			}
		]
	},
	{
		"id": "trigger_walk_to_woman",
		"type": "trigger_volume_head",
		"radius": 2,
		"on_active": [
			{
				"type": "attach",
				"ref": "trigger_walk_to_woman",
				"target": "walking_woman"
			}
		],
		"on_enter": [
			{ "type": "deactivate_all_triggers" },
			{
				"type": "play_animation",
				"ref": "walking_woman",
				"animation": "stop_and_give_quest",
				"blend": 200,
				"looping": false,
				"on_complete": [
					{
						"type": "activate",
						"ref": ["trigger_item_1", "trigger_item_2"]
					},
				]
			}
		]
	},
	{
		"id": "item_1",
		"type": "model",
		"path": "item_1/model.um",
		"position": [-10, 0, 0]
	},
	{
		"active": false,
		"id": "trigger_item_1",
		"type": "trigger_volume_hand_right",
		"position": [0, 0, 0],
		"radius": 0.2,
		"on_activate": [
			{
				"type": "attach",
				"target": "item_1"
			}
		],
		"on_enter": [
			{ 
				"type": "deactivate",
				"ref": ["trigger_item_1", "trigger_item_2"]
			},
			{
				"type": "attach",
				"ref": "item_1",
				"target": "@player_right_hand"
			}
		]
	},
	{
		"id": "item_2",
		"type": "model",
		"path": "item_2/model.um",
		"position": [10, 0, 0]
	},
	{
		"active": false,
		"id": "trigger_item_2",
		"type": "trigger_volume_hand_right",
		"position": [0, 0, 0],
		"radius": 0.2,
		"on_activate": [
			{
				"type": "attach",
				"target": "item_2"
			}
		],
		"on_enter": [
			{
				"type": "deactivate",
				"ref": ["trigger_item_1", "trigger_item_2"]
			},
			{
				"type": "attach",
				"ref": "item_2",
				"target": "@player_right_hand"
			}
		]
	}
]