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 -
+—+—+—————————————————————+
| F | P | Description |
| i | u | |
| e | r | |
| l | p | |
| d | o | |
| N | s | |
| a | e | |
| m | | |
| e | | |
+===+===+===============================================================+
| * | R | The value of this field is any Array of strings. Each entry |
| * | e | in the array is the name of a named location in the level. |
| a | q | The named location can be specifed using Waypoints or |
| u | u | triggers. |
| t | i | |
| h | r | However, it is prefered if waypoints specifed in the |
| o | e | scenario's prefab are used, ensuring that the scenario is |
| r | d | self contained. |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | The value of this field is any Array of strings. Each entry |
| * | p | in the array is the name of a named location in the level. |
| b | t | The named location can be specifed using Waypoints or |
| l | i | triggers. |
| a | o | |
| c | n | However, it is prefered if waypoints specifed in the |
| k | a | scenario's prefab are used, ensuring that the scenario is |
| L | l | self contained. |
| i | | |
| s | | |
| t | | |
| A | | |
| c | | |
| t | | |
| i | | |
| o | | |
| n | | |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | Allows you to speecify a custom default message for when the |
| * | p | user completes the scenario successfully. |
| d | t | |
| a | i | |
| t | o | |
| e | n | |
| * | a | |
| * | l | |
+—+—+—————————————————————+
| * | O | This allows you to specify the message to use when the user |
| * | p | wins the scenario. |
| d | t | |
| e | i | |
| f | o | |
| a | n | |
| u | a | |
| l | l | |
| t | | |
| W | | |
| i | | |
| n | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | Though optional, it is a good idea to give nice descriptions |
| * | p | so that the player knows what the scenario is about. |
| d | t | |
| e | i | |
| s | o | |
| c | n | |
| r | a | |
| i | l | |
| p | | |
| t | | |
| i | | |
| o | | |
| n | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | Specifies the difficulty level of the scenario. It is a |
| * | p | number which ranges from 0 to 100. The ranges are as follows |
| d | t | meaning |
| i | i | |
| f | o | 0 to 25 Easy |
| f | n | |
| i | a | 25 to 50 Medium |
| c | l | |
| u | | 50 to 75 Hard |
| l | | |
| t | | 75 to 100 Very Hard |
| y | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This is a boolean field, which defaults to false. Setting it |
| * | p | to true enables the Checkpoint system. You can read about the |
| e | t | Checkpoint system here. |
| n | i | |
| a | o | |
| b | n | |
| l | a | |
| e | l | |
| C | | |
| h | | |
| e | | |
| c | | |
| k | | |
| p | | |
| o | | |
| i | | |
| n | | |
| t | | |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This field can be used to specify how long the countdown |
| * | p | delay at the end of a scenario is in seconds. The default |
| e | t | value is 3. |
| n | i | |
| d | o | |
| C | n | |
| o | a | |
| u | l | |
| n | | |
| t | | |
| D | | |
| o | | |
| w | | |
| n | | |
| T | | |
| i | | |
| m | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This field can be used to specify how long the delay at the |
| * | p | end of the scenario is before the scenario summary UI is |
| e | t | displayed. It is a time value in seconds. The default value |
| n | i | is 0. |
| d | o | |
| U | n | |
| I | a | |
| D | l | |
| e | | |
| l | | |
| a | | |
| y | | |
| T | | |
| i | | |
| m | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This field can be used to list extension modules that also |
| * | p | need to be loaded when the scenario is loaded. |
| e | t | |
| x | i | It is an array which can hold both string names for extension |
| t | o | or object data per extension. The format is as follows |
| e | n | |
| n | a | > {.json} | | s | l | > "extensions": ["demol | | i | | itionDerby", { "name": "customExtension", "optional": false}] | | o | | > |
| n | | |
| s | | 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. |
+—+—+—————————————————————+
| * | O | This is a time limit, specified in seconds, which states how |
| * | p | long the user can stay inactive before failing the scenario. |
| f | t | |
| a | i | |
| i | o | |
| l | n | |
| u | a | |
| r | l | |
| e | | |
| T | | |
| r | | |
| i | | |
| g | | |
| g | | |
| e | | |
| r | | |
| T | | |
| i | | |
| m | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | Allows you to speecify a custom fail message for when the |
| * | p | user fails the scenario. |
| f | t | |
| a | i | |
| i | o | |
| l | n | |
| e | a | |
| d | l | |
| M | | |
| e | | |
| s | | |
| s | | |
| a | | |
| g | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This field specifies the type of introduction UI to use at |
| * | p | the start of the scenario. Valid values are none, |
| i | t | camOnly, htmlOnly and portrait |
| n | i | |
| t | o | |
| r | n | |
| o | a | |
| T | l | |
| y | | |
| p | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This field specifies the points a long a single lap in the |
| * | p | level. The value of this field is an array of strings. Each |
| l | t | entry in the array is the name of a named location in the |
| a | i | level. |
| p | o | |
| C | n | The named location can be specifed using Waypoints or |
| o | a | triggers.However, it is prefered if waypoints specifed in the |
| n | l | scenario's prefab are used, ensuring that the scenario is |
| f | | self contained. |
| i | | |
| g | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This is the number of laps the user would have to complete to |
| * | p | finish the scenario. This works in conjunction with lapConfig |
| l | t | which specifies the points along a single lap. |
| a | i | |
| p | o | |
| C | n | |
| o | a | |
| u | l | |
| n | | |
| t | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This is an object field used to set the properties of object |
| * | p | in the scene. It can contain anything that is to be |
| l | t | configured. It contains Key-Value pairs. |
| e | i | |
| v | o | It uses the Key to find the object in the scenetree and then |
| e | n | uses the Value to changes the properties of the object found. |
| l | a | |
| O | l | For example, it can be uses to configure the Time of Day, |
| b | | tod, object in a scene. |
| j | | |
| e | | > {.json} | | c | | > "levelObjects": { | | t | | > | | s | | "tod" : { "time" : 0.95, "dayLength" : 120, "play" : false} | | * | | > } | | * | | > |
+—+—+—————————————————————+
| * | O | This field sets the maximum allowed duration for the |
| * | p | scenario. Once the time gets to this value, the scenario will |
| m | t | end. |
| a | i | |
| x | o | |
| T | n | |
| i | a | |
| m | l | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | R | This is the name of the scenario. |
| * | e | |
| n | q | |
| a | u | |
| m | i | |
| e | r | |
| * | e | |
| * | d | |
+—+—+—————————————————————+
| * | O | This is a custom message to display if the user wins the |
| * | p | scenario. This allows for more appropriate message which |
| p | t | suites the setting of the scenario. |
| a | i | |
| s | o | |
| s | n | |
| e | a | |
| d | l | |
| M | | |
| e | | |
| s | | |
| s | | |
| a | | |
| g | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | The value of this field is an object which specifies the |
| * | p | minimum and maximum number of players for the scenario. The |
| p | t | example below would declares that the minimum number of |
| l | i | player for the scenario is 2 and the maximum 4 |
| a | o | |
| y | n | > {.json} | | e | a | > "playersCountRange": {"min" : 2, "max" : 4} | | r | l | > |
| s | | |
| C | | |
| o | | |
| u | | |
| n | | |
| t | | |
| R | | |
| a | | |
| n | | |
| g | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | Used when introType is set to portrait |
| * | p | |
| p | t | The value for this field is an object with fields for images |
| o | i | to display for different states of the scenario. The images |
| r | o | can be of characters to use in the UI |
| t | n | |
| r | a | > {.json} | | a | l | > "portraitImg": { | | i | | > | | t | | "start": "campaigns/bus_minichapter/directorportrait.png", | | I | | > "suc | | m | | cess": "campaigns/bus_minichapter/directorportrait_face.png", | | g | | > " | | * | | 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. |
| | | |
| | | > ——– ——– ——– |
| | | > |
| | | > |
| | | > ——– ——– ——– |
+—+—+—————————————————————+
| * | O | Used when introType is set to portrait and with the |
| * | p | start image specified in portraitImg |
| p | t | |
| o | i | The value for this is the text that will be displayed in the |
| r | o | UI with the immage specifed in the start field of |
| t | n | portraitImg |
| r | a | |
| a | l | |
| i | | |
| t | | |
| T | | |
| e | | |
| x | | |
| t | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | This is an array of prefab file names to load when the |
| * | p | scenario starts. Prefabs allow the scenario to use unique |
| p | t | objects that are specific to its needs. Prefab files for the |
| r | i | scenario have to exist in the same directory as the scenario |
| e | o | being loaded |
| f | n | |
| a | a | > {.json} | | b | l | > "prefabs" : ["example_filename_one","example_filename_two"] | | s | | > |
| * | | > |
| * | | > In this example, the prefab files, |
| | | > example_filename_one.prefab and |
| | | > example_filename_two.prefab, will get loaded with the |
| | | > scenario. |
+—+—+—————————————————————+
| * | O | This can be used to specify a list of images to use in the |
| * | p | scenario selection UI as preview images for the scenario. The |
| p | t | value is an array of image file names. |
| r | i | |
| e | o | |
| v | n | |
| i | a | |
| e | l | |
| w | | |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| r | t | |
| a | i | |
| d | o | |
| i | n | |
| u | a | |
| s | l | |
| M | | |
| u | | |
| l | | |
| t | | |
| i | | |
| p | | |
| l | | |
| i | | |
| e | | |
| r | | |
| A | | |
| I | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| r | t | |
| e | i | |
| s | o | |
| t | n | |
| r | a | |
| i | l | |
| c | | |
| t | | |
| T | | |
| o | | |
| C | | |
| a | | |
| m | | |
| p | | |
| a | | |
| i | | |
| g | | |
| n | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| r | t | |
| e | i | |
| v | o | |
| e | n | |
| r | a | |
| s | l | |
| e | | |
| T | | |
| i | | |
| m | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| s | t | |
| h | i | |
| o | o | |
| w | n | |
| C | a | |
| o | l | |
| u | | |
| n | | |
| t | | |
| d | | |
| o | | |
| w | | |
| n | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | The value for this field is an object. The data specified in |
| * | p | this object is used to control the behaviour of the Statistcs |
| s | t | System during the scenario. Refer to the statistics section |
| t | i | for more information. |
| a | o | |
| t | n | |
| i | a | |
| s | l | |
| t | | |
| i | | |
| c | | |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| s | t | |
| t | i | |
| a | o | |
| r | n | |
| t | a | |
| H | l | |
| T | | |
| M | | |
| L | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| t | t | |
| r | i | |
| a | o | |
| c | n | |
| k | a | |
| P | l | |
| l | | |
| a | | |
| y | | |
| e | | |
| r | | |
| V | | |
| e | | |
| h | | |
| i | | |
| c | | |
| l | | |
| e | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| t | t | |
| y | i | |
| p | o | |
| e | n | |
| * | a | |
| * | l | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| u | t | |
| i | i | |
| l | o | |
| a | n | |
| y | a | |
| o | l | |
| u | | |
| t | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | The value for this field is an object. This object specifies |
| * | p | the properties of each vehicle used in the scenario. If a |
| v | t | vehicle is referenced by name, the vehicle has to exist in |
| e | i | the accompanying prefab for the scenario or be spawned at |
| h | o | startup of the scenario. |
| i | n | |
| c | a | |
| l | l | |
| e | | |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| * | O | |
| * | p | |
| w | t | |
| h | i | |
| i | o | |
| t | n | |
| e | a | |
| L | l | |
| i | | |
| s | | |
| t | | |
| A | | |
| c | | |
| t | | |
| i | | |
| o | | |
| n | | |
| s | | |
| * | | |
| * | | |
+—+—+—————————————————————+
| | | |
+—+—+—————————————————————+
| | | |
+—+—+—————————————————————+
| | | |
+—+—+—————————————————————+
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.
<ADD MORE HERE>
Scenario Events
During a scenario, the scenario system use extension hooks to communicate with the external world. The events that it broadcasts are as follows -
Hook Description Name
