More documentation (#115): move as much as possible into module READMEs

README.md

@@ -1,6 +1,6 @@
 # GRAD Civilians
 
-<img src="docs/gradcivs_logo.svg" width="400" />
+<img alt="logo: Gruppe Adler eagle being both posh and dorky" src="docs/gradcivs_logo.svg" width="400" />
 
 Spawn ambient civilians on the map.
 
@@ -39,7 +39,7 @@ Civilians on separate islands can run into pathing problems. Avoid by creating e
 
 ## Detailed documentation
 
-should be found for the distinct modules: 
+All modules have their own READMEs that describe features, settings & APIs: 
 
 * [activities](addons/activities/README.md)
 * [cars](addons/cars/README.md)
@@ -58,53 +58,6 @@ should be found for the distinct modules:
 * [voyage](addons/voyage/README.md)
 * [zeus](addons/zeus/README.md)
 
-## Config
-
-Settings can be found as CBA Addon settings.
-
-![settings](docs/grad_civs-cba_settings.png)
-
-Attribute                | Default Value | Explanation
--------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
-animalTransportChance    | 0.4           | Probability that a suitable vehicle will carry some animals as cargo.
-automaticVehicleGroupSize| 1             | Allow vehicles to be filled according to capacity, ignoring *initialGroupSize* (0,1).
-backpackProbability      | 0.5            | Probability that a civilian will wear a backpack
-backpacks                | []            | All classnames of backpacks that civilians may wear.
-civClasses               | ["C_Man_1"]   | Unit classes to use for spawning civilians
-clothes                  | []            | All classnames of clothes that civilians may wear.
-debugFps                 | 0             | Toggles fps monitoring mode (0/1).
-enabled                  | false         | if grad_civs is enabled (false,true)
-faces                    | []            | All classnames of faces that civilians may have.
-goggles                  | []            | All classnames of goggles that civilians may wear.
-headgear                 | []            | All classnames of headgear that civilians may wear.
-initialGroupSize         | 3             | Initial group size for civilians, between 1..N . Value may be any valid parameter to the `random` command.
-maxCivsInVehicles        | 10            | Maximum number of civs in vehicles.
-maxCivsOnFoot            | 30            | Maximum number of civs on foot.
-maxCivsResidents         | 20            | Maximum number of civs that are residents, mostly doing their thing at home.
-minCivUpdateTime         | 2             | Spawn new civilians only if their beheviour states get updated at least every N seconds. NOTE: each frame only one civ gets updated. Example: With 40fps and minCivUpdateTime=2, not more than 80 civs will be alive at any given time. This setting is meant to prevent civs from becoming too unresponsive.
-minFps                   | 40            | Spawn new civilians only if fps are at or above N . *NOTE*: the fps are taken from the machine that spawns the civs, which may be a HC.
-panicCooldown            | [15,120,240]  | Time it takes until a civilian relaxes after panicking (trivariate: [lowest, median, highest])
-spawnDistancesInVehicles | [1500,6000]   | Minimum and maximum distance to players that civilians in vehicles can spawn in.
-spawnDistancesOnFoot     | [1000,4500]   | Minimum and maximum distance to players that civilians on foot can spawn in.
-spawnDistancesResidents  | [500, 1000]   | Minimum and maximum distance to players that civilians living in houses spawn in.
-vehicles                 | ["C_Van_01_fuel_F", "C_Hatchback_01_F", "C_Offroad_02_unarmed_F", "C_Truck_02_fuel_F", "C_Truck_02_covered_F", "C_Offroad_01_F", "C_SUV_01_F", "C_Van_01_transport_F", "C_Van_01_box_F"]            | All classnames of vehicles that civilians may drive.
-
-## API
-
-see the various module READMEs 
-
-### EVENTS
-
-#### global
-
-common events:
-
-    ["grad_civs_civKilled", { params ["_deathPos", "_killer", "_civilian"]; }] call CBA_fnc_addEventHandler;
-
-
-    ["grad_civs_vehicleTheft", { params ["_vehicle", "_thief"]; }] call CBA_fnc_addEventHandler;
-
-
 ## Development
 
 * we're using the CBA state machine implementation, see `addons/*/functions/fn_sm_*/`
@@ -118,4 +71,4 @@ This is the current structure:
 
 ![activities state machine](docs/states.png)
 
-see `addons/*/fnc_sm*.sqf` for all the places where state machines are defined/added to.
+see `addons/*/fnc_sm*.sqf` for all the places where state machines are defined/added to.

addons/activities/README.md

@@ -4,6 +4,13 @@
 
 Manages basic life states. Emotions, special activities, 
 
+## Settings
+
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+panicCooldown            | [15,120,240]  | Time it takes until a civilian relaxes after panicking (trivariate: [lowest, median, highest])
+
 ## API
 
 ### grad_civs_activities_fnc_doCustomActivity

addons/cars/README.md

@@ -4,13 +4,26 @@ Basic handling of civs driving cars.
 
 As a user, see transit and voyage modules to actually get civs driving on the streets.
 
+## Config settings
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+animalTransportChance    | 0.4           | Probability that a suitable vehicle will carry some animals as cargo.
+automaticVehicleGroupSize| 1             | Allow vehicles to be filled according to capacity, ignoring *initialGroupSize* (0,1).
+vehicles                 | ["C_Van_01_fuel_F", "C_Hatchback_01_F", "C_Offroad_02_unarmed_F", "C_Truck_02_fuel_F", "C_Truck_02_covered_F", "C_Offroad_01_F", "C_SUV_01_F", "C_Van_01_transport_F", "C_Van_01_box_F"]            | All classnames of vehicles that civilians may drive.
+
 ## API
 
 ### grad_civs_cars_fnc_setVehicles
+
 Sets all vehicles that civilians may drive. Overwrites value from CBA settings. Execute globally
 
-#### Syntax
-`[vehicles] call grad_civs_cars_fnc_setVehicles`
+#### Example
+
+```sqf
+private _vehicles = ["C_Van_01_Fuel_F"];
+[_vehicles] call grad_civs_cars_fnc_setVehicles
+```
 
 Parameter | Explanation
 ----------|-------------------------------------------------------------

addons/cars/functions/fnc_initConfig.sqf

@@ -7,7 +7,7 @@ private _settingsGroup = ["GRAD Civs", "7) cars - basic settings for civilian dr
 [
     QGVAR(animalTransportChance),
     "SLIDER",
-    "Suitable vehicles that will have animals as cargo",
+    "Ratio of suitable vehicles that will have animals as cargo",
     _settingsGroup,
     [0, 1, 0.4, 0, true],
     true,

addons/diagnostics/README.md

@@ -1,3 +1,14 @@
 # grad\_civs\_diagnostics
 
-Debugging GUI stuff
+Debugging GUI stuff
+
+## Settings
+
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+showFps                  | false         | Show server & HC fps
+showOnMap                | false         | Show civs on map
+showInfoLine             | false         | Show detailed info line on civilian
+showPinkArrows           | false         | Create 3D arrows over civ heads
+showMisc                 | false         | Miscellaneous stuff

addons/gta/README.md

@@ -28,3 +28,11 @@ Serves to create events around civilian-owned vehicles getting stolen by players
                 * THEN LATER no event will have been triggered
                 * AND the player switches seats with the driver
                     * THEN ONCE a global event will be triggered: `"grad_civs_vehicleTheft", [_vehicle, player]`
+
+## API
+
+### Events
+
+```sqf
+["grad_civs_vehicleTheft", { params ["_vehicle", "_thief"]; }] call CBA_fnc_addEventHandler; 
+```

addons/lifecycle/README.md

@@ -2,6 +2,18 @@
 
 Controls all spawning & despawning of civilians, as well as incapacitation & death.
 
+## Settings
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+civClasses               | ["C_Man_1"]   | Unit classes to use for spawning civilians
+cleanupCorpses           | true          | If `corpseManagerMode` should be supported by adding dead units using `addToRemainsCollector`.
+minCivOwnerFps           | 30            | Spawn new civilians only on machines that have at least `N` fps.
+minCivUpdateTime         | 2             | Spawn new civilians only if their beheviour states get updated at least every N seconds. NOTE: each frame only one civ gets updated. Example: With 40fps and minCivUpdateTime=2, not more than 80 civs will be alive at any given time. This setting is meant to prevent civs from becoming too unresponsive.
+minServerFps             | 40            | Spawn new civilians only if server fps are at or above `N`.
+smMultiplicator          | 1             | Speed multiplicator for state machines on HC. Will reduce both civ update times and fps on the respective HC.  
+spawnOnlyWithPlayers     | true          | Spawn civilians only if players are connected.
+
 ## API
 
 ### Events 
@@ -12,3 +24,13 @@ Controls all spawning & despawning of civilians, as well as incapacitation & dea
 
 If civilians come under the control of grad-civs or are removed from grad-civs control, respectively.
 Argument is an *array of* civilians (i.e. units)
+
+```sqf
+["grad_civs_lifecycle_civ_added", { systemChat format ["new civs: %1", _this]}] call CBA_fnc_addEventHandler; 
+```
+
+#### `grad_civs_civKilled`
+
+```sqf 
+["grad_civs_civKilled", { params ["_deathPos", "_killer", "_civilian"]; }] call CBA_fnc_addEventHandler;
+```

addons/loadout/README.md

@@ -2,6 +2,18 @@
 
 Determine clothing etc for civilians
 
+## Settings
+
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+backpackProbability      | 0.5            | Probability that a civilian will wear a backpack
+backpacks                | []            | All classnames of backpacks that civilians may wear.
+clothes                  | []            | All classnames of clothes that civilians may wear.
+faces                    | []            | All classnames of faces that civilians may have.
+goggles                  | []            | All classnames of goggles that civilians may wear.
+headgear                 | []            | All classnames of headgear that civilians may wear.
+
 ## API
 
 

addons/main/README.md

@@ -0,0 +1,9 @@
+# grad\_civs\_main
+
+Contains the main switch & meta information.
+
+## Settings
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+enabled                  | false         | if grad_civs is enabled (false,true)

addons/patrol/README.md

@@ -1,3 +1,12 @@
 # grad\_civs\_patrol
 
 Civilians who patrol the neighborhood, alone or in groups.
+
+## Settings
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+initialGroupSize         | 3             | Initial group size for civilians, between 1..N . Value may be any valid parameter to the `random` command.
+maxCivsOnFoot            | 30            | Maximum number of civs on foot.
+spawnDistancesOnFoot     | [1000,4500]   | Minimum and maximum distance to players that civilians on foot can spawn in.
+

addons/residents/README.md

@@ -1,3 +1,13 @@
 # grad\_civs\_residents
 
-Civilians who live in their homes and leave them only for a short chat with the neighbors.
+Civilians who live in their homes and leave them only for a short chat with the neighbors.
+
+## Settings
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+chatTime                 | 20            | How long civilian chats can last, in seconds
+maxCivsResidents         | 20            | Maximum number of civs that are residents, mostly doing their thing at home.
+meetNeighborCooldown     | 150           | Time between visiting neighbors
+spawnDistancesResidents  | [500, 1000]   | Minimum and maximum distance to players that civilians living in houses spawn in.
+

addons/voyage/README.md

@@ -1,3 +1,11 @@
 # grad\_civs\_voyage
 
-Voyagers are civilians who randomly drive around in cars.
+Voyagers are civilians who randomly drive around in cars.
+
+## Settings
+
+Attribute                | Default Value | Explanation
+-------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------
+maxCivsInVehicles        | 10            | Maximum number of civs in vehicles.
+maxTravelRadius          | -             | Max travel radius around spawn; defaults to a bit more than max spawnDistance   
+spawnDistancesInVehicles | [1500,6000]   | Minimum and maximum distance to players that civilians in vehicles can spawn in.