Merge pull request #190 from 501st-Aux-Mod-Team/add-shield-documentation

Add README documentation for Shields

addons - Copy/RD501_Main/functions/shield/README.md

@@ -0,0 +1,275 @@
+# 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
+
+
+```cpp
+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
+
+```cpp
+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
+
+```cpp
+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
+
+```cpp
+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
+
+```cpp
+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
+
+```cpp
+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
+
+```cpp
+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"`
+
+```cpp
+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.
+
+```cpp
+#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.
+
+```cpp
+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.
+
+```sqf
+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.
+
+```sqf
+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:
+
+```sqf
+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:
+
+```cpp
+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:
+
+```sqf
+case "HUMAN_DIVISION": {
+    _lowHealthTexture = CIS_LOW_HEALTH_TEXTURE;
+    _normalHealthTexture = HUMAN_DIVISION_NORMAL_TEXTURE;
+};
+```
+
+It is also valid to write:
+
+```sqf
+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.