Gives mission makers an easy and performance-friendly method of caching groups of AI.
In this case “caching” means: enableSimulationGlobal false, and hideObjectGlobal true, on all relevant AI.
AI will only be “uncached” - enableSimulationGlobal true, and hideObjectGlobal false - when: 1) a specified variable goes from `false` to `true`;
or
2) players of a specified side (and optionally as/in a vehicle class that is/is a child of a specified class) enter the same region in which the AI were cached
Included is a sample mission showing a few different use cases and markers documenting them. The sample mission can be found in @CBB_Mods_A3\examples\cbb_simpleCache.VR
Below are the full documentation instructions also included in the cbb_simpleCache.sqf file.
AUTHOR
Iron
DESCRIPTION
Gives mission makers an easy and performance-friendly method of caching AI until needed during a mission. Requires a trigger placed in the mission editor. The trigger should be set to "PRESENT", "ONCE", and either "ANY" or just the side of the AI desired to be cached. The trigger SIDE setting determines what AI are detectable by cbb_simplecache. Setting the SIDE of this trigger is not required, but it will make the initial caching faster if only doing one side. It must be set to "ANY" if AI on multiple sides are to be cached. The trigger's condition should be left as this . The trigger's onActivation will call cbb_simpleCache, as described in the arguments and examples below. This system is only designed to cache AI once and then uncache them once. It is not capable of repeated cycles or recaching AI should players leave and return to an area; a different caching system is required for scenarios where players are expected/allowed to travel at random across a region and the AI be repeatedly uncached whenever the players are near.
ARGUMENTS
REQUIRED
0: thisTrigger - the trigger that cbb_simpleCache is called from. Always thisTrigger , never anything else.
---------- ---------- ---------- ----------
1: uncache parameter
(1a): "uncacheVariableName" (STRING), OR
(1b): [ side of players to uncache , optional class player's vehicle must inherit from to uncache] (ARRAY)
Examples:
(1a): "uncacheVariableName" (STRING)
This is probably the most performance-friendly way to use cbb_simpleCache. AI units cached in a zone configured for this variable will not uncache until this variable is true. Setting this variable to true can be done in any way the mission maker likes.
"uncacheVariableName" -
The name of a boolean variable to watch and use for determining when to uncache AI. The variable name must be in quotes. The variable does not need to be initialized elsewhere, but if the variable does already exist and is anything other than the boolean value false , cbb_simpleCache will abort.
OR
(1b): [ side of players to uncache , optional class player's vehicle must inherit from to uncache] (ARRAY)
This method will uncache AI when players matching the required properties enter the area covered by the original trigger placed in the editor. This method allows for a more automatic "decache AI when players are nearby" approach to AI zoning, but it is probably slightly more performance intensive.
It does allow for very detailed control by way of filtering for specific kinds of vehicles (remember, infantry are vehicles too) and only decaching when players who are/are in vehicles of that type are present. (For example, only decache when infantry are nearby, but not when aircraft fly through the trigger zone.)
side of players to uncache (SIDE)
This method requires one side of players to check for. A sides can be any of the following:
west east resistance independent civilian.
cbb_simpleCache will abort if given no side or multiple sides.
optional class player's vehicle must inherit from to uncache (STRING)
This is an optional class that the vehicle occupied by the players in the trigger zone must match or be children classes of this parent class, for the trigger zone to activate.
For example, to only allow infantry to trigger this uncache zone, the class "man" could be used. If a player is the infantry unit "B_Soldier_F", and is on foot inside the trigger zone, this trigger will activate. "B_Soldier_F" is a child class of "man". If the player is in the vehicle "B_MRAP_01_F", the blufor MRAP, this vehicle be the object compared against class "man", and the trigger will not activate, as "B_MRAP_01_F" is not a child class of "man".
Because this parameter is optional, when no class is provided, the class "land" will be used by default. This means only vehicles that inherit from "land" will be able to decache AI unless otherwise specified. This is done so that with minimal work required byt he mission maker, ground units of all kinds will be able to, but aircraft flying across the map will not.
If it is desired that any player vehicle decache AI, use the class "AllVehicles". ("All" includes non-player vehicles such as backpacks and buildings, and is allowed, but untested and not recommended. For example, "man" and "tank" are within "AllVehicles"; "B_FieldPack_blk", a black fieldback backpack, and "Land_Radar_F", a radar structure, are within "All" in cfgVehicles, but not "AllVehicles".)
When a vehicle is empty, the vehicle will never be a player, and so will never fire these trigger areas. As a side note, it will also always be side civilian when empty.
When a vehicle is occupied, its side will be determined by its DRIVER if it has one, or the GUNNER or COMMANDER if there is no driver, or a PASSENGER if none of the previous crew positions are occupied. This means if a vehicle is driven by a player on west , it will only uncache trigger zones configured to look for units on west , even if there are players on a different side in the vehicle. This is an intentional limitation of cbb_simpleCache in order for it to run quickly and efficiently, and situations where this might affect gameplay are considered exceptionally rare.
Note that using mode (1b), the parameter is still an array, and the side and optional classname are elements within the array. For ease of use, the order of the elements in the array does not matter.
Examples:
[ west ] - Uncache when players on west, in a vehicle of type "land" (remember the default "land" is used when none is given) enter the trigger area.
[ west , "man" ] - Uncache when players on west, in a vehicle of type "man" (meaning infantry only, not inside another vehicle), enter the trigger area.
[ "man" , west ] - This is identical to the previous example in function. It demonstrates that, for ease of use, the order of the two elements in the array does not matter.
[ west , "tank" ] - Uncache when players on west, in a vehicle of type "tank" enter the trigger area. Infantry and vehicles not of type "tank" will not decache AI.
[ west , "Air"] - Uncache when players on west, in a vehicle of type "air" enter the trigger area. Infantry and anything not of type "air" will not decache AI.
[ west , "AllVehicles" ] - Uncache when players on west enter the trigger area. This includes when aircraft fly through it, even if they are many thousand meters above the ground. This is *usually* not the intended outcome of the mission maker, and should not be used without consideration.
[ west , "All" ] - Uncache when players on west enter the trigger area. Also looks at classes not normally considered as occupied by players - backpacks, buildings, etc. - and is untested and not recommended. But, it's there, if you really want it.
OPTIONAL
2: [ side(s) of AI to cache , optional classname(s) AI vehicles must inherit from to cache] (ARRAY) This is optional and allows for selecting only a subset of the AI inside a trigger area to cache. They can be filtered according to side, classname/children of a classname, or both. Multiple sides and multiple classnames are supported. This allows for caching, for example: cache all of the infantry in a town, but leave the vehicles uncached so they can be spotted from a very long distance by the players cache all of the units on side east in a town, but leave civilians uncached, so players observing from a distance cannot immediate see or engage units on east until they near the town cache all of the infantry and cars on side east in a town, but leave civilian units and east anti-aircraft units uncached, so players observing from a distance cannot immediate see or engage units on east until they near the town, and players flying overhead are threatened by AA in the town cache all of the units on sides east and resistance in a region, allowing civilian traffic to drive along roads without being blocked by military units sitting in crossroads/roadblocks/etc If this parameter is not included, by default all units regardless of side and class type will be cached. This is the most typical use case for a mission maker and makes it easiest for them to use cbb_simpleCache. Note that this parameter is an array, and the side(s) and classname(s) are elements in that array. For ease of use, the order of the elements in the array does not matter. Examples: [ east ] - Cache all AI on east in the trigger area [ "man" ] - Cache AI that are children of class "man" in the trigger area. So: basically any infantry get cached. [ east , "landvehicle" ] - Cache AI on east that are children of class "landvehicle" in the trigger area. So: any ground unit on east. [ east , resistance , "man" , "tank" ] - Cache AI on east OR resistance, that are children of class "man" or "tank" in the trigger area. So: redfor and greenfor infantry and tanks get cached. [ "man" , resistance , "tank" , east ] - This is identical to the previous example in function. It demonstrates that, for ease of use, the order of the elements in the array does not matter. [ east , resistance , "Air"] - Cache AI on east and resistance, in a vehicle of type "air", in the trigger area. Anything not of type "air" will not be cached.
RETURNS
BOOLEAN - true if simpleCache setup completed successfully, false otherwise
EXAMPLE
The following examples are constructed of the various possibilities described in the ARGUMENTS section above. See the ARGUMENTS section for more examples for each of the uncache and cache parameters. Both of the following methods require a trigger placed in the mission editor. The trigger should be set to "PRESENT", "ONCE", and either "ANY" or just the side of the AI desired to be cached. The trigger's condition should be left as this . The trigger's onActivation will call cbb_simpleCache, and be constructed as described in the arguments above and full examples below.
Using a separate variable to decide when to uncache units. This is the highest performance method. The “” around the variable name are required. The named uncache variable must be uninitialized or be a boolean false, or cbb_simpleCache will abort.
0 = [ thisTrigger , "uncacheVariableName" ] call cbb_fnc_simpleCache; Will only be uncached when the variable uncacheVariableName is true. Caches all AI in the trigger area. This is probably the highest-performance, easiest-to-use, and most common implementation of cbb_simpleCache. 0 = [ thisTrigger , "uncacheVariableName" , [ east ] ] call cbb_fnc_simpleCache; Same uncache parameter as above. Caches all AI of side EAST in the trigger area. 0 = [ thisTrigger , "uncacheVariableName" , [ "man" ] ] call cbb_fnc_simpleCache; Same uncache parameter as above. Caches all AI of type "man" in the trigger area. 0 = [ thisTrigger , "uncacheVariableName" , [ east , "landvehicle" ] ] call cbb_fnc_simpleCache; Same uncache parameter as above. Caches all AI in the trigger area that are side EAST and type "landvehicle". 0 = [ thisTrigger , "uncacheVariableName" , [ east , resistance , "man" , "tank" ] ] call cbb_fnc_simpleCache; Same uncache parameter as above. Caches all AI in the trigger on side EAST or RESISTANCE, that are of type "man" or "tank". Cars and aircraft, for example, will not be cached. 0 = [ thisTrigger , "uncacheVariableName" , [ "man" , resistance , "tank" , east ] ] call cbb_fnc_simpleCache; Same uncache parameter as above. Same caching as the previous example. This demonstrates that for ease-of-use the order of elements in the sub-array does not matter. 0 = [ thisTrigger , "uncacheVariableName" , [ east , resistance , "Air"] ] call cbb_fnc_simpleCache; Same uncache parameter as above. Caches all AI in the trigger area that are on side EAST or RESISTANCE, and of vehicle type "air". Ground units will not be cached.
Using the trigger-area defined by the caching trigger in the map editor to decide when to uncache units. This will automatically uncache AI when players matching a required side and optionally in a vehicle inheriting from a given classname enter the trigger area. This method is not quite as high-performance, but it is very easy to configure.
The following examples will include versions of the above 2nd optional parameter as well. 0 = [ thisTrigger , [ west ] ] call cbb_fnc_simpleCache; Uncache when players on WEST, in a vehicle of type "land" (remember the default "land" is used when none is given, and that infantry are vehicles of type "land") enter the trigger area. Caches all AI in the trigger area. If using a trigger area instead of an uncache variable, this is probably the highest-performance, easiest-to-use, and most common implementation of cbb_simpleCache. 0 = [ thisTrigger , [ west , "man" ] , [ east ] ] call cbb_fnc_simpleCache; Uncache when players on WEST, in a vehicle of type "man" (meaning infantry only; players inside another vehicle will not count), enter the trigger area. Caches all AI of side EAST in the trigger area. 0 = [ thisTrigger , [ "man" , west ] , [ "man" ] ] call cbb_fnc_simpleCache; Same uncaching as the previous example, demonstrating that for ease-of-use the order of elements in the sub-array does not matter. Caches all AI of type "man" in the trigger area. Special cases for the uncache parameters that exist but should only be used with careful consideration. Note: the cache parameters here are merely a continution of the above examples, are perfectly fine to use, and not part of any special case. It is only the uncache parameters, the first array, that is noteworthy. 0 = [ thisTrigger , [ west , "AllVehicles" ] , [ east , "landvehicle" ] ] call cbb_fnc_simpleCache; Uncache when players on WEST enter the trigger area. This includes when aircraft fly through it, even if they are many thousand meters above the ground. This is *usually* not the intended outcome of the mission maker, and should not be used without consideration. Caches all AI in the trigger area that are side EAST and type "landvehicle". 0 = [ thisTrigger , [ west , "All" ] , [ east , resistance , "man" , "tank" ] ] call cbb_fnc_simpleCache; Uncache when players on WEST enter the trigger area. Also looks at classes not normally considered as occupied by players - backpacks, buildings, etc. - and is untested and not recommended. But, it's there, if you really want it. Caches all AI in the trigger on side EAST or RESISTANCE, that are of type "man" or "tank". Cars and aircraft, for example, will not be cached.