modding guide update

Modding Guide/Guides/action_modding_guide.md

@@ -0,0 +1,107 @@
+# Action Modding Guide
+
+**Action** mod files are located within the *Actions* folder.
+To be valid, mod files must have the .json extension and have the following file structure:
+
+#### File Structure
+
+```
+{
+  "actions": [                    -- list of actions --
+    {
+      "id":                         -- (required) Unique action identifier (see note 2).
+
+      "name":                       -- (required) Name of action.
+
+      "category":                   -- (required) The category the action should
+                                       be sorted into (see the 'Categories' section down below)
+
+      "target":                     -- (required) Target entity type for the action.
+                                       For now, the only acceptable value is "faction".
+
+      "properties":                 -- (optional) List of PROPERTIES that are available
+                                       to the action definition. Properties are
+                                       predefined values and expressions that can be
+                                       reused in different places within the definition.
+                                       Please read properties_guide.md for more details
+                                       on how to define valid properties.
+
+      "accessConditions":           -- (optional) List of BOOLEAN EXPRESSIONS to be evaluated
+                                       to decide if action will be present on the list a available actions within the assigned category.
+                                       If any of the expressions evaluate to 'false', then
+                                       the action will not be present within the category
+                                       menu. Please read expressions_guide.txt for more
+                                       details on how to define valid boolean
+                                       expressions.
+
+      "executeConditions":          -- (optional) List of CONDITION objects which are
+                                       to be used to decide if an action can be executed
+                                       at any particular time. If the enclosed expression
+                                       evaluates to false, then the action will appear
+                                       disabled on the UI. The condition object also contains
+                                       instructions to display info tooltips over the
+                                       action. See the 'Execution Conditions' section down
+                                       below for more information.
+
+      "effects":                    -- (required) List of EFFECT EXPRESSIONS to
+                                       evaluate after an action has been executed.
+                                       These can introduce changes to the target or any
+                                       related entity. Please read expressions_guide.txt
+                                       for more details on how to define valid effect
+                                       expressions.
+    },
+    ...                             -- additional actions --
+  ]
+}
+```
+
+## Execute Conditions
+
+Execute Conditions are *json* sub-objects that are added to actions that are used to evaluate
+if an action is available for execution, They also define the tooltips to be displayed over the action to indicate the reason for their availability state. They have the following structure:
+
+#### Object Structure
+
+```
+    {
+      "condition":                  -- (required) BOOLEAN EXPRESSION to be evaluated
+                                       to decide if action can be executed at a particular
+                                       time. Please read expressions_guide.txt for more
+                                       details on how to define valid boolean
+                                       expressions.
+
+      "info":                       -- (required) Text to generate when a tooltip needs
+                                       to be displayed. See string_values_guide.txt
+                                       to find more about how to define valid dynamic
+                                       text values.
+    }
+```
+
+## Categories
+
+A folder called *Categories*, located within the *Actions* folder, should
+contain a file named **categories.json** with a list of categories on which to group
+the available actions, and a set of **PNG** image files to use as thumbnails for each
+of the categories.
+
+The file structure of **categories.json** is a follows:
+
+```
+{
+  "actionCategories": [
+    {
+      "id":                         -- (required) Unique category identifier (see note 2).
+      "name":                       -- (required) Category name.
+      "image":                      -- (required) thumbnail file name.
+    },
+    ...                             -- additional categories --
+  ]
+}
+```
+
+## Notes
+1. List of values must be enclosed within square brackets and separated by commas.
+   Remove any trailing commas on any list enclosed by square brackets, or you'll
+   get a **json** parsing error.
+2. Do not duplicate action or category ids unless you want to specifically replace
+another decision already loaded.

Modding Guide/Guides/adjective_modding_guide.txt → Modding Guide/Guides/adjective_modding_guide.md

@@ -1,9 +1,10 @@
----- Adjective Modding Guide ----
+# Adjective Modding Guide
 
-Adjective modding files are located within the 'Adjectives' folder. To be valid, mod files must have the .json extension and have the following file structure:
+**Adjective** mod files are located within the *Adjectives* folder. To be valid, mod files must have the **.json** extension and have the following file structure:
 
--- File Structure --
+#### File Structure
 
+```
 {
   "adjectives": [ -- list of adjectives --
     {
@@ -15,12 +16,11 @@ Adjective modding files are located within the 'Adjectives' folder. To be valid,
 
       "regionConstraints":   -- (optional) List of region constraints, separated by commas (see note #2)
     },
-    ... -- additional adjectives --
+    ...                      -- additional adjectives --
   ]
 }
+```
 
--- Notes --
-1. Remove any trailing commas or the file won't be parsed
-2. These are used to decide whether or not to associate the element with a particular region. If any of the constraints fails then the adjective won't be used when generating names of phrases within the region. Refer to region_constraints_guide.txt for more details on how to define and use region constraints
-
---
+## Notes
+1. Remove any trailing commas or the file won't be parsed.
+2. These are used to decide whether or not to associate the element with a particular **region**. If any of the constraints fails then the adjective won't be used when generating names of phrases within the region. Refer to *region_constraints_guide.txt* for more details on how to define and use region constraints.

Modding Guide/Guides/biome_modding_guide.txt → Modding Guide/Guides/biome_modding_guide.md

@@ -1,9 +1,10 @@
----- Biome Modding guide ----
+# Biome Modding guide
 
-Biome modding files are located within the 'Biomes' folder. To be valid, mod files must have the .json extension and have the following file structure:
+**Biome** mod files are located within the *Biomes* folder. To be valid, mod files must have the **.json** extension and have the following file structure:
 
--- File Structure --
+### File Structure
 
+```
 {
   "biomes": [ -- list of biomes --
     {
@@ -39,17 +40,18 @@ Biome modding files are located within the 'Biomes' folder. To be valid, mod fil
         }
       ]
     },
-    ... -- additional biomes --
+    ...                             -- additional biomes --
   ]
 }
+```
 
--- Notes --
+## Notes
 1. Remove any trailing commas or the file won't be parsed
-2. Optional 'min' attribute values (altitude/rainfall/temperature) not defined will be assigned the minimum attribute value of its category
-3. Optional 'max' attribute values (altitude/rainfall/temperature) not defined will be assigned the maximum attribute value of its category
-4. Only set a minValue if the biome is not supposed to be present at values less than minValue. Otherwise do not add this constraint property
-5. Only set a maxValue if the biome is not supposed to be present at values greater than maxValue. Otherwise do not add this constraint property
-6. A layer constraint's minValue or maxValue shouldn't be greater than the specific layer's maxPossibleValue
-7. Saturation represents how close is particular biome from filling a particular cell and it helps calculate the relative strength of a particular biome in regards to others within a single cell. The saturation slope indicates how quickly a particular biome reaches it's saturation point within a cell. A saturation slope of 0 indicates that the biome never increases it's saturation level above 0. A  slope of 1 indicates that the biome reaches it's maximum saturation at the exact midpoint between the minimum and maximum values of a particular property. A slope greater than 1 indicates the biome reaches it's maximum saturation faster. A slope less than 1 indicates the biome won't reach it's saturation point. When undefined, the default saturation slope is 1
+2. Optional **min** attribute values (altitude/rainfall/temperature) not defined will be assigned the minimum attribute value of its category
+3. Optional **max** attribute values (altitude/rainfall/temperature) not defined will be assigned the maximum attribute value of its category
+4. Only set a **minValue** if the biome is not supposed to be present at values less than minValue. Otherwise do not add this constraint property
+5. Only set a **maxValue** if the biome is not supposed to be present at values greater than maxValue. Otherwise do not add this constraint property
+6. A layer constraint's **minValue** or **maxValue** shouldn't be greater than the specific layer's **maxPossibleValue**
+7. **Saturation** represents how close is particular biome from filling a particular cell and it helps calculate the relative strength of a particular biome in regards to others within a single cell. The saturation slope indicates how quickly a particular biome reaches its saturation point within a cell. A saturation slope of **0** indicates that the biome never increases its saturation level above **0**. A  slope of **1** indicates that the biome reaches its maximum saturation at the exact midpoint between the minimum and maximum values of a particular property. A slope greater than **1** indicates the biome reaches its maximum saturation faster. A slope less than **1** indicates the biome won't reach its saturation point. When undefined, the default saturation slope is **1**
 
 --

Modding Guide/Guides/decision_modding_guide.txt

@@ -10,9 +10,9 @@ files must have the .json extension and have the following file structure:
     {
       "id":                         -- (required) Unique decision identifier (see note 2).
 
-      "name":                       -- (required) Name of event.
+      "name":                       -- (required) Name of decision.
 
-      "target":                     -- (required) Target entity type for the event.
+      "target":                     -- (required) Target entity type for the decision.
                                        For now, the only acceptable value is "faction".
 
       "parameters":                 -- (optional) List of parameters that are required
@@ -37,7 +37,7 @@ files must have the .json extension and have the following file structure:
                                        to the decision definition. Properties are
                                        predefined values and expressions that can be
                                        reused in different places within the definition.
-                                       Please read properties_guide.txt for more details
+                                       Please read properties_guide.md for more details
                                        on how to define valid properties.
 
       "description":                -- (required) List of DESCRIPTION objects. These

Modding Guide/Guides/descriptions_modding_guide.txt

@@ -15,7 +15,7 @@ that can generate texts to display within the game. They have the following stru
                                        to the description definition. Properties are
                                        predefined values and expressions that can be
                                        reused in different places within the definition.
-                                       Please read properties_guide.txt for more details
+                                       Please read properties_guide.md for more details
                                        on how to define valid properties.
 
       "text":                       -- (required) Text to generate when this description

Modding Guide/Guides/effects_modding_guide.txt

@@ -15,7 +15,7 @@ following structure:
                                        to the effect definition. Properties are predefined
                                        values and expressions that can be reused in
                                        different places within the definition. Please
-                                       read properties_guide.txt for more details
+                                       read properties_guide.md for more details
                                        on how to define valid properties.
 
       "text":                       -- (required) Text to generate when this effect

Modding Guide/Guides/event_modding_guide.txt

@@ -24,7 +24,7 @@ must have the .json extension and have the following file structure:
                                        to the event definition. Properties are predefined
                                        values and expressions that can be reused in
                                        different places within the definition. Please
-                                       read properties_guide.txt for more details on
+                                       read properties_guide.md for more details on
                                        how to define valid properties.
 
       "assignmentConditions":       -- (optional) List of BOOLEAN EXPRESSIONS to