Scenario¶

The scenario mode can be accessed from the main menu via selecting Play and then the Scenario option. From this menu you can choose from a wide variety of scenarios to play. In this section, we will be looking at the structure of scenarios. Understanding how scenarios work will allow you to create scenarios of your own.

Overview¶

Scenarios are self contained experiences where the aim it so complete a specific task or set of tasks within the constrains given. For example, the task might be to successfully stop a vehicle in a specific parking spot within a fixed time limit. If you accomplish the task or tasks, then the scenario ends successfully. If you don’t, then it fails. Scenarios make use of a host of systems such as the waypoint, statistics……

Scenario JSON File¶

Each scenario is defined by using a JSON file. The scenario JSON file constains an array with a single object in it. The scenario object contains a list of fields with their respective values. These values define the behaviour of the scenario. Not every field is required. The supported fields for a scenario object are as follows -

Field Name Purpose Description
authors Required

The value of this field is any Array of strings. Each entry in the array is the name of a named location in the level. The named location can be specifed using Waypoints or triggers.

However, it is prefered if waypoints specifed in the scenario’s prefab are used, ensuring that the scenario is self contained.

blackListActions Optional

The value of this field is any Array of strings. Each entry in the array is the name of a named location in the level. The named location can be specifed using Waypoints or triggers.

However, it is prefered if waypoints specifed in the scenario’s prefab are used, ensuring that the scenario is self contained.

date Optional Allows you to speecify a custom default message for when the user completes the scenario successfully.
defaultWin Optional This allows you to specify the message to use when the user wins the scenario.
description Optional Though optional, it is a good idea to give nice descriptions so that the player knows what the scenario is about.
difficulty Optional

Specifies the difficulty level of the scenario. It is a number which ranges from 0 to 100. The ranges are as follows meaning

0 to 25 Easy

25 to 50 Medium

50 to 75 Hard

75 to 100 Very Hard

enableCheckpoints Optional This is a boolean field, which defaults to false. Setting it to true enables the Checkpoint system. You can read about the Checkpoint system here.
endCountDownTime Optional This field can be used to specify how long the countdown delay at the end of a scenario is in seconds. The default value is 3.
endUIDelayTime Optional This field can be used to specify how long the delay at the end of the scenario is before the scenario summary UI is displayed. It is a time value in seconds. The default value is 0.
extensions Optional

This field can be used to list extension modules that also need to be loaded when the scenario is loaded.

It is an array which can hold both string names for extension or object data per extension. The format is as follows

"extensions": ["demolitionDerby", { "name": "customExtension", "optional": false}]


If the entry is a simple name string, then it is taken to mean one of the extension that exist in the scenario folder and the loader will attempt to load it from that folder.

If it is an object, like the 2nd entry above in the array, then the fields are

“name” the name of the extension. This extension will be loaded from the same directory from which the scenario is being loaded.

“optional” this is a boolean field which can be either true or false. If it is true and the extension could not be found, nothing happens, the loading process continues. If it is false, then the extension has to be preset or else it will be flagged as missing and an error.

failureTriggerTime Optional This is a time limit, specified in seconds, which states how long the user can stay inactive before failing the scenario.
failedMessage Optional Allows you to speecify a custom fail message for when the user fails the scenario.
introType Optional This field specifies the type of introduction UI to use at the start of the scenario. Valid values are none, camOnly, htmlOnly and portrait
lapConfig Optional

This field specifies the points a long a single lap in the level. The value of this field is an array of strings. Each entry in the array is the name of a named location in the level.

The named location can be specifed using Waypoints or triggers.However, it is prefered if waypoints specifed in the scenario’s prefab are used, ensuring that the scenario is self contained.

lapCount Optional This is the number of laps the user would have to complete to finish the scenario. This works in conjunction with lapConfig which specifies the points along a single lap.
levelObjects Optional

This is an object field used to set the properties of object in the scene. It can contain anything that is to be configured. It contains Key-Value pairs.

It uses the Key to find the object in the scenetree and then uses the Value to changes the properties of the object found.

For example, it can be uses to configure the Time of Day, tod, object in a scene.

"levelObjects": {
"tod" : { "time" : 0.95, "dayLength" : 120, "play" : false}
}

maxTime Optional This field sets the maximum allowed duration for the scenario. Once the time gets to this value, the scenario will end.
name Required This is the name of the scenario.
passedMessage Optional This is a custom message to display if the user wins the scenario. This allows for more appropriate message which suites the setting of the scenario.
playersCountRange Optional

The value of this field is an object which specifies the minimum and maximum number of players for the scenario. The example below would declares that the minimum number of player for the scenario is 2 and the maximum 4

"playersCountRange": {"min" : 2, "max" : 4}

portraitImg Optional

Used when introType is set to portrait

The value for this field is an object with fields for images to display for different states of the scenario. The images can be of characters to use in the UI

"portraitImg": {
"start": "campaigns/bus_minichapter/directorportrait.png",
"success": "campaigns/bus_minichapter/directorportrait_face.png",
"fail": "campaigns/bus_minichapter/directorportrait_face.png",
}


The start field is used at the start of the scenario when introType is set to portrait. An example is shown in the first image.

The success field is used when the user wins the scenario. An exmaple is shown in the second image.

The last image, specified by fail field, is used when the player fails the scenario. An exmaple is shown in the third image.

portraitText Optional

Used when introType is set to portrait and with the start image specified in portraitImg

The value for this is the text that will be displayed in the UI with the immage specifed in the start field of portraitImg

prefabs Optional

This is an array of prefab file names to load when the scenario starts. Prefabs allow the scenario to use unique objects that are specific to its needs. Prefab files for the scenario have to exist in the same directory as the scenario being loaded

"prefabs" : ["example_filename_one","example_filename_two"]


In this example, the prefab files, example_filename_one.prefab and example_filename_two.prefab, will get loaded with the scenario.

previews Optional This can be used to specify a list of images to use in the scenario selection UI as preview images for the scenario. The value is an array of image file names.
restrictToCampaign Optional
reverseTime Optional
showCountdown Optional
statistics Optional The value for this field is an object. The data specified in this object is used to control the behaviour of the Statistcs System during the scenario. Refer to the statistics section for more information.
startHTML Optional
trackPlayerVehicle Optional
type Optional
uilayout Optional
vehicles Optional The value for this field is an object. This object specifies the properties of each vehicle used in the scenario. If a vehicle is referenced by name, the vehicle has to exist in the accompanying prefab for the scenario or be spawned at startup of the scenario.
whiteListActions Optional

Scenario Custom Lua¶

The scenario system provides a wide variety of prebuilt systems that would allow you to create standard scenarios. However, the need might arise to provide custom behaviour for a scenario by processing events that occur during a scenario. This can be achieved by using an accompanying custom LUA file.

This Lua file can be used to control how a scenario runs and what logic executes for the various events that can occur during the scenario. The Lua file for a scenario must have the same name as the scenario JSON file. When the scenario is loaded, if a LUA file with the same name as the scenario is present, it will get loaded as well.

The LUA file has a particular structure. It has to return an object which will handle the processing for the scenario.

local M = {}
<body of the lua file>
return M


The object can be of any name, here is it called M.

Any functionality that is going to interact with the rest of the systems, has to be made public by defining it on the object M. Functions and data can be made public. In the example below, we are exposing some_function_name to other parts of the game.

local M = {}
local function some_function_name()
<body of function>
end

M.some_function_name = some_function_name
return M


The custom lua file for a scenario can interact with other systems such as vehicle lua, which controls vehicles in the scene, statistics, scenario, waypoint.