Scenario Framework Setup

From Bohemia Interactive Community
Jump to navigation Jump to search

The Scenario Framework is a framework that allows quick scenario creation with a variety of tasks, based on specified, adjustable conditions.


Principle

The game mode entity's component instanciates all the found areas of action and, depending on their settings, activate layers. The activated layers then live their life and can later activate other layers, depending on actions in the world.


Components

All Scenario Framework components can be found in Prefabs/ScenarioFramework.

Scenario Framework Game Mode Component

The SCR_GameModeSFManager game mode component is the scripted component that will manage all the areas.

The GameModeSF.et game mode prefab is already setup to work with the Scenario Framework.

Areas, layers, slots are Generic Entities with a scripted component where all the settings are. All of them have the following properties:

Children

Spawn Children is the children spawning mode and conditions:

  • ALL: Default option, all layers nested under the current one are spawned
  • RANDOM_ONE: Only one child is selected randomly
  • RANDOM_MULTIPLE: Multiple children are spawned, based on the Random Percent
  • RANDOM_BASED_ON_PLAYERS_COUNT: Children spawning is balanced based on players ratio (connected / max players), the maximum players in the game mode being defined by the mission header

Random Percent is the spawn chance; it is only used along the RANDOM_MULTIPLE Spawn Children setting.

Debug

Show Debug Shapes During Runtime Allows to display the debug sphere while playing for debug purpose.

Activation

Activation Type tells the framework when the component should be initiated:

  • ON_INIT: the component is initiated on the start of the game mode. Basically all the Area components in the world are initiated recursively; this means the Area and everything nested under it is checked for its Activation Type and initiated if the activation event is the same as the activation type defined in this attribute
  • ON_TASKS_INIT: used by Areas to let know Layers of type Task to initiate
  • ON_TRIGGER_ACTIVATION: the component is initiated by another component - usually another component or a logic initiates the component based on a condition; for example a player stepped into the trigger; this trigger initiates another component which will spawn an object
  • ON_AREA_TRIGGER_ACTIVATION: issued by the special type of the Area trigger
  • SAME_AS_PARENT: the activation type is the same as the parent of the component 
  • CUSTOM1-4: predefined for custom events, anyone can use it for its own purpose

Area

An area is the topmost container to any other framework component. It can contain layers as well as slots.

Only Areas and their content will be detected by the framework. Any layer/slot that is not contained in an area will be ignored.

Layer

A layer can be seen as a main task container. It can contain other layers as well as slots. It has the following properties:

Slot

A slot is a layer's information - it can be seen as a task's parameter. It has events that can perform actions. It has the following properties:

Asset

Object To Spawn points to an .et file to create the entity to be picked up (then delivered). It will be created upon slot's activation.

Ticking Use Existing World Asset will instead use an existing prefab by finding all entities of Object To Spawn type in a 2.5m range and registers it to the slot.  This is useful in cases the slot is used as a subject to task ( i.e. destroy the radar ) or if someone needs to assign a name to the existing asset without changing the original (see ID)

Faction sets the #Extraction Slot trigger's side detection - it is not used anywhere else for now.

ID is used to either target the existing world asset (if it does not have a prefab) or to name the spawned object.

Action

An action is an effect that happens on Slot update, whether it is created, failed, progressed, updated or finished.

Getter

A getter is a class used by actions to determine an action's target, depending on the chosen getter and its provided parameters.

Getter Description Parameter Return Value
CP_Get Not to be used - it is the parent class.
CP_GetCountEntitiesInTrigger Returns the number of objects in the given trigger Name of the trigger object int
CP_GetEntityByName Returns the ( pointer to ) object specified in the name Name of the object IEntity
CP_GetLastFinishedTaskEntity The SF game mode remembers the last finished task. This action returns the task entity of the last finished task   IEntity
CP_GetListEntitiesInTrigger Returns array of entities located in the trigger area. Name of the trigger object array<IEntity>
CP_GetPlayerEntity Returns the player IEntity
CP_GetTask Returns the task object specified by the name of the Layer Task Name of the task layer IEntity


Layer Types

LayerTask

OnTaskX

Trigger Actions On Finish is an array of actions to take when the task finishes.

LayerTaskClearArea

LayerTaskDeliver

See also LayerTask.

Task

Task Title Updated is the new task's title when the item is collected.

Task Description Updated is the new task's description when the item is collected.

LayerTaskDestroy

See also LayerTask.

LayerTaskMove

See also LayerTask.

This layer is a LayerTask with a TaskMove task prefab created.


Slot Types

SlotAI

Waypoints

There are several ways to assign a waypoint to the group:

  • By specifying the waypoint to spawn with WP To Spawn
  • By creating the Waypoint Set with Waypoint Group Names

If Waypoint Group Names is left empty, then WP To Spawn is used. If WP To Spawn is empty, the group will be provided a default patrol waypoint.

Waypoint Group Names is the list of wanted waypoints for the created group. If multiple Waypoint Sets are defined, a random one is used.

  • Name: Name of the single waypoint (slot with waypoint prefab) or name of the layer including the waypoints (slots nested under the layer). 
  • Use Random Order: if there are multiple waypoints in the layer this option will shuffle them. This way, the waypoint set can be used for more AIs not following the same pattern.
  • Cycle Waypoints: it creates an endless loop. Once the last waypoint is reached, the AI will repeat waypoints.

Spawn AI On WP Pos makes the AI spawned on the first waypoint's position instead of the original spawn position.

WP To Spawn defines the waypoint prefab to spawn on the slot's position. This waypoint is used if Waypoint Group Names is left empty.

Misc

Balance On Players Count will change the amount of spawned group units depending on the number of players.
The minimum possible amount is between 1 and 3 units, the maximum is the whole group.

SlotTask

Task

Task Title is the original task's title.

Task Description is the task's description in the task list (it overrides the one defined in the LayerTask); %1 in the text will be replaced by the display name of the object or by the text specified in the Override Object Display Name attribute.

OnTaskX

Actions On Finished is an array of actions to take when the task finishes.

Actions On Created is an array of actions to take when the task is created.

Actions On Failed is an array of actions to take when the task fails.

Actions On Progress is an array of actions to take when the task progresses - e.g an object is picked up

Actions On Updated is an array of actions to take when the task gets updated - e.g a picked-up object is dropped

SlotClearArea

See also SlotTask.

Plugins

Only the Area Radius attribute is usaed as all the other attributes are already defined in the trigger prefab (defined in Asset > Object To Spawn).

SlotDelivery

See also SlotTask.

SlotDestroy

See also SlotTask.

SlotExtraction

See also SlotTask.

SlotMoveTo

See also SlotTask.

This slot is a SlotTask with a TaskMove task prefab created.

SlotPick

See also SlotTask.

It is a slot that spawns or registers the entity to be delivered; said entity should have the inventory item component in order to be delivered using the character's or vehicle's inventory. It inherits from SlotTask.
It is part of the Deliver Task set.

Task

Task Title Updated 1 is the task's title when the item is picked up.

Task Description Updated 1 is the task's description when the item is picked up.

Task Title Updated 2 is the task's title when the item gets dropped.

Task Description Updated 2 is the task's description when the item gets dropped.

SlotTrigger

Create a trigger to be used by other slots.

🚧
TODO: Check


Action Types

ActionEndMission

This action simply ends the mission - no settings are available.

ActionExecuteFunction

This action allows a method to be executed on the object designated by the action's fields.

Example: CP_GetEntityByName → Entity Name (e.g "MyCar") → method to call + one parameter.

ActionIncrementCounter

This action increments the named counter by 1.

ActionPlaySound

This action plays a sound (with a 2 seconds delay).

ActionPlaySoundOnEntity

This action plays a sound on the provided entity (with a 2 seconds delay).

ActionResetCounter

This action resets the counter under which it is placed.

🚧
TODO: Check


ActionShowHint

This action shows a hint to every connected players.

ActionSpawnClosestObjectFromList

This action spawns the layer/slot that is the closest from the name list.

🚧
TODO: Check


ActionSpawnObjects

This action spawns the layers and slots that are defined in the Spawn Object by name.

Activation Type must be set to ON_TRIGGER_ACTIVATION.


Examples

An example scenario is available as two worlds:

Tasks

Move

A Move task setup requires an Area holding a Move task holding a MoveTo slot.

Destroy

A Destroy task setup requires an Area holding a Destroy task holding a Destroy slot.

  • The target entity can be spawned during the scenario or it can be already existing in the world.
  • The target entity must have the Destruction Component.

Clear Area

A Clear Area task setup requires an Area holding a ClearArea task holding both a ClearArea and an AI slots.

Deliver

A Deliver task setup requires an Area holding a Deliver task holding both a Pickup and a Delivery slots.

There can be multiple possible destinations but only one must exist at the same time - use spawn conditions to do so.


Tutorial

This tutorial explains how to be tasked to walk near a vehicle, get in it, bring it to a certain location, destroy it, then run to an extraction point.

World Setup

  • Start Arma Reforger Tools
  • Create a new Project - name it "Scenario Framework Tutorial"
  • Open SF-Tutorial-Empty.ent and use Ctrl + N to create a new sub-scene of the current world
  • Eventually, change the WeatherAndTime entity to modify the date and time of the scenario
  • Save with Ctrl + S in ScenarioFrameworkTutorial/world/ScenarioFramework (you will have to create these two directories) as SF-Tutorial-Example.ent
The US Spawn Point is where the player will (re)spawn.

Entity Setup

  • Create a new layer (Hierarchy tab > right-click on SF-Tutorial-Example > Create layer and name the layer Entities - a layer in which scenario-related entities will be placed
  • Place a UAZ469.et entity in the wanted location
    • press Ctrl + ↡ PgDown to place it according to the ground below it
    • in its Components, search "dam" to find the SCR_VehicleDamageManagerComponent
    • name the UAZ TargetUAZ
      • under Additional hit zones > Hull, set Incendiary multiplier to 5 - this in order for the fire to destroy and blow up the vehicle faster

No need for more; once all the systems are working, the mission will see decorations/AI/etc added to it - not before!

Framework Setup

🚧
TODO: To Be Continued…!