501st-Aux-Mod/addons/RD501_Main/functions/shield

Energy Shield

Getting Started

For it to function correctly, there are two things that must be added. A configuration entry for rd501_shield_isShield=1 to allow shield logic, and an init event handler which will initialise the shield logic and setup everything for you.

Configuration

class CfgVehicles {
    class Example_Vehicle {
        rd501_shield_isShield=1;
    };
};

If this is missing or invalid, the init handler will cause the following message to be logged to rpt.

[RD501][Shield] Shield is not activated (rd501_shield_isShield=1 is not specified on 'class name')

Init EventHandler

class Extended_Init_EventHandlers 
{
    //Example_Vehicle must match the vehicles class in CfgVehicles
    class Example_Vehicle {
        // You can name this whatever you want
        class rd501_init_shield {
            init = "[_this select 0] call rd501_fnc_shield_init";
        };
    }
};

If this is missing, nothing will be logged.

Configuration Properties

Enable Shield

Allows the specified object to be set as a shield.

rd501_shield_isShield=1;

You can expressly disable a given child class by declaring rd501_shield_isShield=0;

If this is not set to 1, it will log [RD501][Shield] Shield is not activated (rd501_shield_isShield=1 is not specified on 'class name') in the rpt for the object's owner (whoever created it) when you run rd501_fnc_shield_init on the object.

Default: 0

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
    };
};

Shield Health

The total shield health.

rd501_shield_health=number;

Negative values for number may cause undefined behaviour.

Default: 1000

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
        rd501_shield_health=1000;
    };
};

Low Health Percentage

Specify the % of maximum health under which to switch to the 'low health' texture.

rd501_shield_lowHealthPercentage=number;

Keep number within the range 1-99 inclusive.

Default: 20

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
        rd501_shield_lowHealthPercentage=10;
    };
};

Regen Rate

Specify the flat rate per second at which the shield regenerates.

rd501_shield_regenPerSecond=number;

If you make number negative, you will remove health per second instead.

Default: 10

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
        rd501_shield_regenPerSecond=100;
    };
};

Regen Delay

The number of seconds to wait after taking damage before beginning regeneration.

rd501_shield_regenDelay=number;

number < 0 is undefined behaviour, keep it positive.

rd501_shield_regenDelay=0 will instantly start regeneration.

Default: 5

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
        rd501_shield_regenDelay=10;
    };
};

Shield Texture Set

The texture set to use for a shield.

rd501_shield_type="text";

Valid Options:

• rd501_shield_type="REPUBLIC"
• rd501_shield_type="CIS"

If text is not handled in RD501_Main/functions/shield/fnc_shield_getTextureSet.sqf, it will default to REPUBLIC.

Default: "REPUBLIC"

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
        rd501_shield_type="CIS";
    };
};

Adding new texture sets

Open: RD501_Main/functions/shield/fnc_shield_getTextureSet.sqf

Define your paths as macros, using the convention provided, you will modify the prefix to describe the shield. Say I am adding a type called HUMAN_DIVSION. Modify the path in quotes to whatever path you require.

#define HUMAN_DIVISION_LOW_HEALTH_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_human_division_low.paa"
#define HUMAN_DIVISION_NORMAL_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_human_division_normal.paa"

You'd add them just below the other definitions in RD501_Main/functions/shield/fnc_shield_getTextureSet.sqf as below.

params["_type"];

#define REPUBLIC_LOW_HEALTH_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_rep_low.paa"
#define REPUBLIC_NORMAL_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_rep_normal.paa"
#define CIS_LOW_HEALTH_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_cis_low.paa"
#define CIS_NORMAL_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_cis_normal.paa"
// Human Divison
#define HUMAN_DIVISION_LOW_HEALTH_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_human_division_low.paa"
#define HUMAN_DIVISION_NORMAL_TEXTURE "\RD501_Vehicles\static\shields\shared\rd501_shield_human_division_normal.paa"

Then scroll further down in the file to the switch section.

switch (_type) do {
    case "REPUBLIC": {
        _lowHealthTexture = REPUBLIC_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = REPUBLIC_NORMAL_TEXTURE;
    };
    case "CIS": {
        _lowHealthTexture = CIS_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = CIS_NORMAL_TEXTURE;
    };
    default {
        diag_log format["[RD501][Shield] Invalid type '%1' specified, defaulting to 'REPUBLIC'", _type];
        _lowHealthTexture = REPUBLIC_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = REPUBLIC_NORMAL_TEXTURE;
    };
};

We're going to add human division by adding a new case above default. We also will use the macros we defined earlier for the paths here.

case "HUMAN_DIVISION": {
    _lowHealthTexture = HUMAN_DIVISION_LOW_HEALTH_TEXTURE;
    _normalHealthTexture = HUMAN_DIVISION_NORMAL_TEXTURE;
};

So to integrate this block of code in the switch we're going to copy it as follows:

switch (_type) do {
    case "REPUBLIC": {
        _lowHealthTexture = REPUBLIC_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = REPUBLIC_NORMAL_TEXTURE;
    };
    case "CIS": {
        _lowHealthTexture = CIS_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = CIS_NORMAL_TEXTURE;
    };
    // Where you copy it to, try to keep the indentation consistent
    case "HUMAN_DIVISION": {
        _lowHealthTexture = HUMAN_DIVISION_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = HUMAN_DIVISION_NORMAL_TEXTURE;
    };
    default {
        diag_log format["[RD501][Shield] Invalid type '%1' specified, defaulting to 'REPUBLIC'", _type];
        _lowHealthTexture = REPUBLIC_LOW_HEALTH_TEXTURE;
        _normalHealthTexture = REPUBLIC_NORMAL_TEXTURE;
    };
};

This can then be referenced in your config using:

class CfgVehicles {
    class Example {
        rd501_shield_isShield=1;
        // "HUMAN_DIVISION" matches the switch 'case' keyword we defined in the fnc_shield_getTextureSet.sqf
        rd501_shield_type="HUMAN_DIVISION"; 
    };
};

Additional Note

Say we wanted to instead have the low health texture be the CIS low health texture. We'd instead write:

case "HUMAN_DIVISION": {
    _lowHealthTexture = CIS_LOW_HEALTH_TEXTURE;
    _normalHealthTexture = HUMAN_DIVISION_NORMAL_TEXTURE;
};

It is also valid to write:

case "HUMAN_DIVISION": {
    _lowHealthTexture = "\RD501_Vehicles\static\shields\shared\rd501_shield_cis_low.paa";
    _normalHealthTexture = HUMAN_DIVISION_NORMAL_TEXTURE;
};

But I find it less readable since you can more easily pair them at the top of the file in the macro sets.