Merge pull request #63339 from cake-pie/jsonflags-docu

`JSON_FLAGS.md` cleanup

doc/JSON_FLAGS.md

@@ -8,8 +8,10 @@
     - [Ammo type](#ammo-type)
     - [Effects](#ammo-effects)
     - [Flags](#flags)
+  - [Traps](#traps)
   - [Armor](#armor)
     - [Covers](#covers)
+    - [Specifically Covers](#specifically-covers)
     - [Flags](#flags-1)
   - [Bionics](#bionics)
   - [Bodyparts](#bodyparts)
@@ -21,56 +23,63 @@
     - [Use action](#use-action)
     - [Flags](#flags-2)
   - [Effects](#effects)
-  - [Furniture and Terrain](#furniture-and-terrain)
     - [Flags](#flags-3)
+  - [Furniture and Terrain](#furniture-and-terrain)
+    - [Flags](#flags-4)
     - [Fungal Conversions Only](#fungal-conversions-only)
     - [Furniture Only](#furniture-only)
   - [Generic](#generic)
-    - [Flags](#flags-4)
+    - [Flags](#flags-5)
   - [Guns](#guns)
     - [Firing modes](#firing-modes)
   - [Magazines](#magazines)
-  - [MAP SPECIALS](#map-specials)
+  - [Mapgen](#mapgen)
+  - [Map Specials](#map-specials)
   - [Material Phases](#material-phases)
   - [Melee](#melee)
-    - [Flags](#flags-5)
+    - [Flags](#flags-6)
   - [Monster Groups](#monster-groups)
     - [Seasons](#seasons)
     - [Time of day](#time-of-day)
   - [Monsters](#monsters)
     - [Anger, Fear and Placation Triggers](#anger-fear-and-placation-triggers)
     - [Categories](#categories)
     - [Death Functions](#death-functions)
-    - [Flags](#flags-6)
+    - [Flags](#flags-7)
     - [Sizes](#sizes)
     - [Special attacks](#special-attacks)
   - [Mutations](#mutations)
-      - [Flags](#flags-7)
+      - [Flags](#flags-8)
     - [Categories](#categories-1)
   - [Overmap](#overmap)
     - [Overmap connections](#overmap-connections)
     - [Overmap specials](#overmap-specials)
-      - [Flags](#flags-8)
-    - [Overmap terrains](#overmap-terrains)
       - [Flags](#flags-9)
+    - [Overmap terrains](#overmap-terrains)
+      - [Flags](#flags-10)
   - [Recipes](#recipes)
-    - [Categories](#categories-2)
-    - [Flags](#flags-10)
+    - [Crafting recipes](#crafting-recipes)
+      - [Flags](#flags-11)
+    - [Camp building recipes](#camp-building-recipes)
+      - [Flags](#flags-12)
   - [Scenarios](#scenarios)
-    - [Flags](#flags-11)
+    - [Flags](#flags-13)
+      - [Profession Flags](#profession-flags)
+      - [Starting Location Flags](#starting-location-flags)
   - [Skills](#skills)
     - [Tags](#tags)
   - [Techniques](#techniques)
   - [Tools](#tools)
-    - [Flags](#flags-12)
+    - [Flags](#flags-14)
     - [Flags that apply to items](#flags-that-apply-to-items)
     - [Use actions](#use-actions)
   - [Vehicle Parts](#vehicle-parts)
-    - [Flags](#flags-13)
+    - [Flags](#flags-15)
+    - [Vehicle parts requiring other vehicle parts](#vehicle-parts-requiring-other-vehicle-parts)
     - [Fuel types](#fuel-types)
-  - [Faults](#faults)
-    - [Flags](#flags-14)
-    - [Parameters](#parameters)
+    - [Faults](#faults)
+      - [Flags](#flags-16)
+      - [Parameters](#parameters)
 
 ## Notes
 
@@ -411,6 +420,80 @@ Some armor flags, such as `WATCH` and `ALARMCLOCK` are compatible with other ite
 - ```INSPIRATIONAL``` Reading this book grants bonus morale to characters with the `SPIRITUAL` trait.
 - ```BINDER_ADD_RECIPE``` Add recipe to a book binder.
 
+
+## Character
+
+- ```BLEED_IMMUNE``` Immune to bleeding.
+- ```COLDBLOOD``` For heat dependent mutations.
+- ```COLDBLOOD2``` For very heat dependent mutations.
+- ```COLDBLOOD3``` For cold-blooded mutations.
+- ```ECTOTHERM``` For ectothermic mutations, like `COLDBLOOD4` and `DRAGONBLOOD3` (Black Dragon from Magiclysm).
+- ```HEAT_IMMUNE``` Immune to very hot temperatures.
+- ```NO_DISEASE``` This mutation grants immunity to diseases.
+- ```NO_THIRST``` Your thirst is not modified by food or drinks.
+- ```NO_RADIATION``` This mutation grants immunity to radiations.
+- ```NO_MINIMAL_HEALING``` This mutation disables the minimal healing of 1 hp a day.
+- ```INFECTION_IMMUNE``` This mutation grants immunity to infections, including infection from bites and tetanus.
+- ```SUPER_HEARING``` You can hear much better than a normal person.
+- ```IMMUNE_HEARING_DAMAGE``` Immune to hearing damage from loud sounds.
+- ```CANNIBAL``` Butcher humans, eat foods with the `CANNIBALISM` and `STRICT_HUMANITARIANISM` flags without a morale penalty
+- ```CLIMB_NO_LADDER``` Capable of climbing up single-level walls without support.
+- ```DEAF``` Makes you deaf.
+- ```BLIND``` Makes you blind.
+- ```EYE_MEMBRANE``` Lets you see underwater.
+- ```NO_SCENT``` You have no scent.
+- ```STOP_SLEEP_DEPRIVATION``` Stops Sleep Deprivation while awake and boosts it while sleeping.
+- ```GLARE_RESIST``` Protect your eyes from glare like sunglasses.
+- ```HYPEROPIC``` You are far-sighted - close combat is hampered and reading is impossible without glasses.
+- ```MYOPIC``` You are nearsighted - vision range is severely reduced without glasses.
+- ```MYOPIC_IN_LIGHT``` You are nearsighted in light, but can see normally in low-light conditions.
+- ```MEND_ALL``` You need no splint to heal broken bones.
+- ```NIGHT_VISION``` You can see in the dark.
+- ```INFRARED``` You can see infrared, aka heat vision.
+- ```SEESLEEP``` You can see while sleeping, and aren't bothered by light when trying to fall asleep.
+- ```ELECTRIC_IMMUNE``` You are immune to electric damage.
+- ```COLD_IMMUNE``` You are immune to cold damage.
+- ```BIO_IMMUNE``` You are immune to biological damage.
+- ```BASH_IMMUNE``` You are immune to bashing damage.
+- ```CUT_IMMUNE``` You are immune to cutting damage.
+- ```STAB_IMMUNE``` You are immune to stabbing damage.
+- ```ACID_IMMUNE``` You are immune to acid damage.
+- ```BULLET_IMMUNE``` You are immune to bullet damage.
+- ```WATCH``` You always know what time it is.
+- ```ALARMCLOCK``` You always can set alarms.
+- ```PARAIMMUNE``` You are immune to parasites.
+- ```IMMUNE_SPOIL``` You are immune to negative outcomes from spoiled food.
+- ```FEATHER_FALL``` You are immune to fall damage.
+- ```INVISIBLE``` You can't be seen.
+- ```DIMENSIONAL_ANCHOR``` You can't be teleported.
+- ```PORTAL_PROOF``` You are immune to personal portal storm effects.
+- ```CLIMATE_CONTROL``` You are resistant to extreme temperatures.
+- ```HEATSINK``` You are resistant to extreme heat.
+- ```THERMOMETER``` You always know what temperature it is.
+- ```CBQ_LEARN_BONUS``` You learn CBQ from the bionic bio_cqb faster.
+- ```GILLS``` You can breathe underwater.
+- ```HARDTOHIT``` Whenever something attacks you, RNG gets rolled twice, and you get the better result.
+- ```HUGE``` Changes your size to `creature_size::huge`.  Checked last of the size category flags, if no size flags are found your size defaults to `creature_size::medium`.
+- ```LARGE``` Changes your size to `creature_size::large`.  Checked third of the size category flags.
+- ```PSYCHOPATH``` Butcher humans without a morale penalty
+- ```PRED1``` Small morale bonus from foods with the `PREDATOR_FUN` flag.  Lower morale penalty from the guilt mondeath effect.
+- ```PRED2``` Learn combat skills with double catchup modifier.  Resist skill rust on combat skills. Small morale bonus from foods with the `PREDATOR_FUN` flag.  Lower morale penalty from the guilt mondeath effect.
+- ```PRED3``` Learn combat skills with double catchup modifier.  Resist skill rust on combat skills. Medium morale bonus from foods with the `PREDATOR_FUN` flag.  Immune to the guilt mondeath effect.
+- ```PRED4``` Learn combat skills with triple catchup modifier.  Learn combat skills without spending focus.  Resist skill rust on combat skills. Large morale bonus from foods with the `PREDATOR_FUN` flag.  Immune to the guilt mondeath effect.
+- ```SAPIOVORE``` Butcher humans without a morale penalty
+- ```SMALL``` Changes your size to `creature_size::small`.  Checked second of the size category flags.
+- ```STEADY``` Your speed can never go below base speed, bonuses from effects etc can still apply.
+- ```STRICT_HUMANITARIAN``` You can eat foodstuffs tagged with `STRICT_HUMANITARIANISM` without morale penalties.
+- ```TINY``` Changes your size to `creature_size::tiny`.  Checked first of the size category flags.
+- ```WEBBED_FEET``` You have webbings on your feet, supporting your swimming speed if not wearing footwear.
+- ```WEBBED_HANDS``` You have webbings on your hands, supporting your swimming speed.
+- ```WEB_RAPPEL``` You can rappel down staircases and sheer drops of any height.
+- ```WALL_CLING``` You can ascend/descend sheer cliffs as long as the tile above borders at least one wall. Chance to slip and fall each step.
+- ```WALL_CLING_FOURTH``` Same as `WALL_CLING`, but you need four instances of the flag for it to function (ex. four bodyparts with the flag).
+- ```WINGS_1``` You have 50% chance to ignore falling traps (including ledges).
+- ```WINGS_2``` You have 100% chance to ignore falling traps (including ledges).  Requires two flag instances.
+
+
 ## Comestibles
 
 ### Comestible type
@@ -776,7 +859,7 @@ These flags can be applied via JSON item definition to most items.  Not to be co
 - ```AVOID_CREATURES``` If a creature is present on terrain, furniture and traps won't be placed.
 
     
-## MAP SPECIALS
+## Map Specials
 
 - ```mx_bandits_block``` ...  Road block made by bandits from tree logs, caltrops, or nailboards.
 - ```mx_burned_ground``` ... Fire has ravaged this place.
@@ -1163,7 +1246,8 @@ These branches are also the valid entries for the categories of `dreams` in `dre
 
 ## Recipes
 
-### Categories
+### Crafting recipes
+These flags apply to crafting recipes, i.e. those that fall within the following categories:
 
 - ```CC_AMMO```
 - ```CC_ARMOR```
@@ -1174,7 +1258,7 @@ These branches are also the valid entries for the categories of `dreams` in `dre
 - ```CC_MISC```
 - ```CC_WEAPON```
 
-### Flags
+#### Flags
 
 - ```ALLOW_ROTTEN``` Explicitly allow rotten components when crafting non-perishables.
 - ```BLIND_EASY``` Easy to craft with little to no light.
@@ -1184,16 +1268,14 @@ These branches are also the valid entries for the categories of `dreams` in `dre
 - ```NEED_FULL_MAGAZINE``` If this recipe requires magazines, it needs one that is full.
 - ```FULL_MAGAZINE``` Crafted or deconstructed items from this recipe will have fully-charged magazines.
 
-### Categories
+### Camp building recipes
+These flags apply only to camp building recipes (hubs and expansions), i.e. those that have category `CC_BUILDING`.
 
-- ```CC_BUILDING```
-
-### Flags
-
-These flags apply only to camp building recipes (hubs and expansions). The purpose is to allow reuse of blueprints to create the "same"
-facility oriented differently. Mirroring takes place before rotation, and it is an error to try to apply mirroring multiple times with the
-same orientation, as well as to try to apply multiple rotations. It is permitted to apply different versions of the flags if they apply to
-different directions (and it is indeed the primary intended usage).
+#### Flags
+The purpose of these flags is to allow reuse of blueprints to create the "same" facility oriented differently. Mirroring takes place before
+rotation, and it is an error to try to apply mirroring multiple times with the same orientation, as well as to try to apply multiple
+rotations. It is permitted to apply different versions of the flags if they apply to different directions (and it is indeed the primary
+intended usage).
 
 - ```MAP_MIRROR_HORIZONTAL``` Causes the building recipe to mirror both the location and contents of the blueprint(s) used by the recipe.
 - ```MAP_MIRROR_VERTICAL``` Causes the building recipe to mirror both the location and contents of the blueprint(s) used by the recipe.
@@ -1580,74 +1662,3 @@ Gun fault flags:
 - ```turns_into``` Causes this fault to apply to the item just mended.
 - ```also_mends``` Causes this fault to be mended (in addition to fault selected) once that fault is mended.
 
-## Character
-
-- ```BLEED_IMMUNE``` Immune to bleeding.
-- ```COLDBLOOD``` For heat dependent mutations.
-- ```COLDBLOOD2``` For very heat dependent mutations.
-- ```COLDBLOOD3``` For cold-blooded mutations.
-- ```ECTOTHERM``` For ectothermic mutations, like `COLDBLOOD4` and `DRAGONBLOOD3` (Black Dragon from Magiclysm).
-- ```HEAT_IMMUNE``` Immune to very hot temperatures.
-- ```NO_DISEASE``` This mutation grants immunity to diseases.
-- ```NO_THIRST``` Your thirst is not modified by food or drinks.
-- ```NO_RADIATION``` This mutation grants immunity to radiations.
-- ```NO_MINIMAL_HEALING``` This mutation disables the minimal healing of 1 hp a day.
-- ```INFECTION_IMMUNE``` This mutation grants immunity to infections, including infection from bites and tetanus.
-- ```SUPER_HEARING``` You can hear much better than a normal person.
-- ```IMMUNE_HEARING_DAMAGE``` Immune to hearing damage from loud sounds.
-- ```CANNIBAL``` Butcher humans, eat foods with the `CANNIBALISM` and `STRICT_HUMANITARIANISM` flags without a morale penalty
-- ```CLIMB_NO_LADDER``` Capable of climbing up single-level walls without support.
-- ```DEAF``` Makes you deaf.
-- ```BLIND``` Makes you blind.
-- ```EYE_MEMBRANE``` Lets you see underwater.
-- ```NO_SCENT``` You have no scent.
-- ```STOP_SLEEP_DEPRIVATION``` Stops Sleep Deprivation while awake and boosts it while sleeping.
-- ```GLARE_RESIST``` Protect your eyes from glare like sunglasses.
-- ```HYPEROPIC``` You are far-sighted - close combat is hampered and reading is impossible without glasses.
-- ```MYOPIC``` You are nearsighted - vision range is severely reduced without glasses.
-- ```MYOPIC_IN_LIGHT``` You are nearsighted in light, but can see normally in low-light conditions.
-- ```MEND_ALL``` You need no splint to heal broken bones.
-- ```NIGHT_VISION``` You can see in the dark.
-- ```INFRARED``` You can see infrared, aka heat vision.
-- ```SEESLEEP``` You can see while sleeping, and aren't bothered by light when trying to fall asleep.
-- ```ELECTRIC_IMMUNE``` You are immune to electric damage.
-- ```COLD_IMMUNE``` You are immune to cold damage.
-- ```BIO_IMMUNE``` You are immune to biological damage.
-- ```BASH_IMMUNE``` You are immune to bashing damage.
-- ```CUT_IMMUNE``` You are immune to cutting damage.
-- ```STAB_IMMUNE``` You are immune to stabbing damage.
-- ```ACID_IMMUNE``` You are immune to acid damage.
-- ```BULLET_IMMUNE``` You are immune to bullet damage.
-- ```WATCH``` You always know what time it is.
-- ```ALARMCLOCK``` You always can set alarms.
-- ```PARAIMMUNE``` You are immune to parasites.
-- ```IMMUNE_SPOIL``` You are immune to negative outcomes from spoiled food.
-- ```FEATHER_FALL``` You are immune to fall damage.
-- ```INVISIBLE``` You can't be seen.
-- ```DIMENSIONAL_ANCHOR``` You can't be teleported.
-- ```PORTAL_PROOF``` You are immune to personal portal storm effects.
-- ```CLIMATE_CONTROL``` You are resistant to extreme temperatures.
-- ```HEATSINK``` You are resistant to extreme heat.
-- ```THERMOMETER``` You always know what temperature it is.
-- ```CBQ_LEARN_BONUS``` You learn CBQ from the bionic bio_cqb faster.
-- ```GILLS``` You can breathe underwater.
-- ```HARDTOHIT``` Whenever something attacks you, RNG gets rolled twice, and you get the better result.
-- ```HUGE``` Changes your size to `creature_size::huge`.  Checked last of the size category flags, if no size flags are found your size defaults to `creature_size::medium`.
-- ```LARGE``` Changes your size to `creature_size::large`.  Checked third of the size category flags.
-- ```PSYCHOPATH``` Butcher humans without a morale penalty
-- ```PRED1``` Small morale bonus from foods with the `PREDATOR_FUN` flag.  Lower morale penalty from the guilt mondeath effect.
-- ```PRED2``` Learn combat skills with double catchup modifier.  Resist skill rust on combat skills. Small morale bonus from foods with the `PREDATOR_FUN` flag.  Lower morale penalty from the guilt mondeath effect.
-- ```PRED3``` Learn combat skills with double catchup modifier.  Resist skill rust on combat skills. Medium morale bonus from foods with the `PREDATOR_FUN` flag.  Immune to the guilt mondeath effect.
-- ```PRED4``` Learn combat skills with triple catchup modifier.  Learn combat skills without spending focus.  Resist skill rust on combat skills. Large morale bonus from foods with the `PREDATOR_FUN` flag.  Immune to the guilt mondeath effect.
-- ```SAPIOVORE``` Butcher humans without a morale penalty
-- ```SMALL``` Changes your size to `creature_size::small`.  Checked second of the size category flags.
-- ```STEADY``` Your speed can never go below base speed, bonuses from effects etc can still apply.
-- ```STRICT_HUMANITARIAN``` You can eat foodstuffs tagged with `STRICT_HUMANITARIANISM` without morale penalties.
-- ```TINY``` Changes your size to `creature_size::tiny`.  Checked first of the size category flags.
-- ```WEBBED_FEET``` You have webbings on your feet, supporting your swimming speed if not wearing footwear.
-- ```WEBBED_HANDS``` You have webbings on your hands, supporting your swimming speed.
-- ```WEB_RAPPEL``` You can rappel down staircases and sheer drops of any height.
-- ```WALL_CLING``` You can ascend/descend sheer cliffs as long as the tile above borders at least one wall. Chance to slip and fall each step.
-- ```WALL_CLING_FOURTH``` Same as `WALL_CLING`, but you need four instances of the flag for it to function (ex. four bodyparts with the flag).
-- ```WINGS_1``` You have 50% chance to ignore falling traps (including ledges).
-- ```WINGS_2``` You have 100% chance to ignore falling traps (including ledges).  Requires two flag instances.