Arma 3 Scripting

Arma 3: Civilian Presence

  • Also known as Arma 3 Civilian Presence

Topic · Markdown · JSON · original wiki page

Arma 3 v1.78 Civilian Presence (CP) is a supplementary system introduced with the Arma 3 Tac-Ops Mission Pack. Its goal is it to enrich combat experience in urban areas without hindering overall game performance.

It was designed and scripted with performance in mind, and because of that, the behavior of civilian units created by CP is simple:

General notes about CP

The CP system consists of three types of modules, described in the following sections.

Civilian Presence Module

This is the core module that provides global definition of system behavior in a given area.
Settings for the 'Civilian Presence' module

Module settings

Each of the module settings has its own brief in-game description in the tooltip.

Code On Unit Created / Deleted: These two attributes allow for the definition of custom code that gets called when unit is spawned / despawned by the CP system.

Example: Apply random loadouts from the CUP Units mod to civilians:

_this setUnitLoadout selectRandom [
    "CUP_C_TK_Man_05_Waist",
    "CUP_C_TK_Man_06_Waist",
    "CUP_C_TK_Man_01_Coat",
    "CUP_C_TK_Man_08_Waist",
    "CUP_C_TK_Man_03_Coat",
    "CUP_C_TK_Man_01_Jack",
    "CUP_C_TK_Man_06_Jack",
    "CUP_C_TK_Man_03_Jack"
];

Apply random identity:

[_this, selectRandom ["TO_C03_Pilot", "TO_C03_Medic", "TO_C03_Collins", "RC_B_HQ"]] remoteExec ["setIdentity", 0, _this];

Civilian Count: Defines how many civilian units should be created and handled by the CP in the area. If there are more units, the extra units get continuously despawned until the unit count reaches the value and vice versa.

Use Panic Action: Allows for use of panic action on the handled civilian units. Because panic state animations do not always working well, this is an optional setting. Try what works best for your scenario and use case.

Use Agents: Controls if agents (units with limited simulation) should be used instead of standard units. Agents are less performance demanding, but not all of the unit related script commands works with them. If you experience such issues, turn this option OFF.

Debug: Turn on visual in-game debug. If this option is ON, you will see overlay debug indicators on CP units and waypoints / cover points while running the scenario. The overlay contains information about each unit position, destination and threat level (how afraid unit currently is) and each waypoint placement and it is capacity.

Unit Types: This parameter controls what kind of units are created on map. By default, module will try to automatically pick terrain appropriate civilians. It is also possible to override that automatic selection and pick unit types manually.

Module setup

Expanding module

Module can be expanded via mods which can add different unit types or define their default type of

Adding support for new terrains

Community made maps can define what kind of units are spawned by Civilian Presence Module by default. To do so, a new array has to be added to UnitTypes. Name of that parameter should match terrain class name from CfgWorlds.

Below is example code adding Livonian units to Chernarus:

class CfgVehicles
{
    class Module_F;
    class ModuleCivilianPresence_F : Module_F
    {
        class UnitTypes
        {
            chernarus[] = {"C_Man_1_enoch_F", "C_Man_2_enoch_F", "C_Man_3_enoch_F", "C_Man_4_enoch_F", "C_Man_5_enoch_F", "C_Man_6_enoch_F", "C_Farmer_01_enoch_F"};
        };
    };
};

Adding new unit types

Adding new units to Civilian Presence Module requires creating new class in CfgVehicles which have custom fsmDanger. Module expects CivilianPresence_ prefix on those classes.

The macro below can be used to quickly create those new classes:

class CfgVehicles
{
    // special agent variants used by the Civilian Presence system
    #define CREATE_AGENT(type)\
    class CivilianPresence_##type##:type\
    {\
        scope = 1;\
        scopeCurator = 0;\
        fsmDanger = "A3\Modules_F_Tacops\Ambient\CivilianPresence\FSM\danger.fsm";\
        fsmFormation = "";\
    };
    CREATE_AGENT(C_Man_1_enoch_F);
    CREATE_AGENT(C_Man_2_enoch_F);
    CREATE_AGENT(C_Man_3_enoch_F);
    CREATE_AGENT(C_Man_4_enoch_F);
    CREATE_AGENT(C_Man_5_enoch_F);
    CREATE_AGENT(C_Man_6_enoch_F);
    CREATE_AGENT(C_Farmer_01_enoch_F);
};

Once those new classes are created, they can be added to CivilianPresence_Presets class located in core config:

class CivilianPresence_Presets
{
    class Civ_Livionian
    {
        name = "Men (Livionian)";
        picture = "\a3\Data_f_enoch\flags\flag_Enoch_CO.paa";
        value = "Civ_Livionian";
        defaultValue = "Civ_Livionian";
        class UnitTypes
        {
            bis_units[]    = { "C_Man_1_enoch_F", "C_Man_2_enoch_F", "C_Man_3_enoch_F", "C_Man_4_enoch_F", "C_Man_5_enoch_F", "C_Man_6_enoch_F", "C_Farmer_01_enoch_F" };
        };
    };
};

Civilian Presence Spawnpoint Module

This module determines the positions where civilian units can spawn. Each time CP system is activated, one civilian unit is automatically create on each of the Civilian Presence Spawnpoint module in the area.

Module settings

None.

Module setup

Civilian Presence Position Module

Module provides a waypoint / cover point for CP units. Its settings and especially placement is crucial for CP system to achieve a good effect.
Settings for 'Civilian Presence Position' module

Module settings

Each of the module settings has its own brief in-game description in the tooltip.

Type

Controls type of the position module.

Capacity: Maximum number of civilian units that can fit in. If the max. capacity is reached, remaining civilians will pick another position.

Use Closest Building: Setting controls if civilian units should use the module position or rather the position of a nearby building instead. If you want a building to serve as the position, use this option. The maximum distance for the building to get paired with the module is 50 m.

Is Terminal: Controls if a unit should be despawned when the position is reached. Use this option if you want to achieve an effect, where units will be fleeing from the area. Standard despawning rules apply (distance & line of sight).

Module setup