Mod scripting guide update (#356)

* added bool to number function expression * added group attribute to cell entities * added neighbors attribute to group entities * updated modding guide a bit more * more modding guide updates * Update entities_guide.md * more guide updates * more guide updates * more modding guide updates * final modding guide update
Zematus · Sep 25, 2022 · ae3f8a3 · ae3f8a3
1 parent 532d8bb
commit ae3f8a3
Show file tree

Hide file tree

Showing 36 changed files with 905 additions and 843 deletions.
diff --git a/Assets/Scripts/WorldEngine/Modding/Entities/CellEntity.cs b/Assets/Scripts/WorldEngine/Modding/Entities/CellEntity.cs
@@ -8,6 +8,7 @@ public class CellEntity : DelayedSetEntity<TerrainCell>
     public const string BiomeTraitPresenceAttributeId = "biome_trait_presence";
     public const string BiomeTypePresenceAttributeId = "biome_type_presence";
     public const string NeighborsAttributeId = "neighbors";
+    public const string GroupAttributeId = "group";
     public const string ArabilityAttributeId = "arability";
     public const string AccessibilityAttributeId = "accessibility";
     public const string HillinessAttributeId = "hilliness";
@@ -26,6 +27,7 @@ public virtual TerrainCell Cell
     private ValueGetterEntityAttribute<float> _hillinessAttribute;
     private ValueGetterEntityAttribute<float> _flowingWaterAttribute;
 
+    private GroupEntity _groupEntity = null;
     private CellCollectionEntity _neighborsEntity = null;
 
     private class BiomeTraitPresenceAttribute : ValueEntityAttribute<float>
@@ -115,10 +117,25 @@ public EntityAttribute GetNeighborsAttribute()
         return _neighborsEntity.GetThisEntityAttribute();
     }
 
+    public EntityAttribute GetGroupAttribute()
+    {
+        _groupEntity =
+            _groupEntity ?? new GroupEntity(
+                GetGroup,
+                Context,
+                BuildAttributeId(GroupAttributeId),
+                this);
+
+        return _groupEntity.GetThisEntityAttribute();
+    }
+
     public override EntityAttribute GetAttribute(string attributeId, IExpression[] arguments = null)
     {
         switch (attributeId)
         {
+            case GroupAttributeId:
+                return GetGroupAttribute();
+
             case BiomeTraitPresenceAttributeId:
                 return new BiomeTraitPresenceAttribute(this, arguments);
 
@@ -180,6 +197,9 @@ protected override void ResetInternal()
 
         if (_isReset) return;
 
+        _groupEntity?.Reset();
         _neighborsEntity?.Reset();
     }
+
+    private CellGroup GetGroup() => Cell.Group;
 }
diff --git a/Assets/Scripts/WorldEngine/Modding/Entities/GroupEntity.cs b/Assets/Scripts/WorldEngine/Modding/Entities/GroupEntity.cs
@@ -16,6 +16,7 @@ public class GroupEntity : CulturalEntity<CellGroup>
     public const string AccessibilityModifierAttributeId = "accessibility_modifier";
     public const string PropertiesAttributeId = "properties";
     public const string PopulationAttributeId = "population";
+    public const string NeighborsAttributeId = "neighbors";
 
     public virtual CellGroup Group
     {
@@ -33,6 +34,7 @@ public virtual CellGroup Group
     private PolityCollectionEntity _presentPolitiesEntity = null;
     private FactionCollectionEntity _closestFactionsEntity = null;
     private ModifiableGroupPropertyContainerEntity _propertiesEntity = null;
+    private GroupCollectionEntity _neighborsEntity = null;
 
     protected override object _reference => Group;
 
@@ -162,10 +164,27 @@ private void UpdateAccessibilityModifier(float value)
         Group.SetToUpdate(warnIfUnexpected: false);
     }
 
+    public ICollection<CellGroup> GetNeighbors() => Group.Neighbors.Values;
+
+    public EntityAttribute GetNeighborsAttribute()
+    {
+        _neighborsEntity =
+            _neighborsEntity ?? new GroupCollectionEntity(
+            GetNeighbors,
+            Context,
+            BuildAttributeId(NeighborsAttributeId),
+            this);
+
+        return _neighborsEntity.GetThisEntityAttribute();
+    }
+
     public override EntityAttribute GetAttribute(string attributeId, IExpression[] arguments = null)
     {
         switch (attributeId)
         {
+            case NeighborsAttributeId:
+                return GetNeighborsAttribute();
+
             case CellAttributeId:
                 return GetCellAttribute();
 
@@ -242,6 +261,7 @@ protected override void ResetInternal()
         _presentPolitiesEntity?.Reset();
         _closestFactionsEntity?.Reset();
         _propertiesEntity?.Reset();
+        _neighborsEntity?.Reset();
 
         base.ResetInternal();
     }

diff --git a/Assets/Scripts/WorldEngine/Modding/Expressions/ExpressionBuilder.cs b/Assets/Scripts/WorldEngine/Modding/Expressions/ExpressionBuilder.cs
@@ -321,6 +321,8 @@ private static IExpression BuildIdentifierExpression(
                 return new ClampFunctionExpression(context, argExpressions);
             case GetProbabilityAdjectiveFunctionExpression.FunctionId:
                 return new GetProbabilityAdjectiveFunctionExpression(context, argExpressions);
+            case NumberFunctionExpression.FunctionId:
+                return new NumberFunctionExpression(context, argExpressions);
         }
 
         if (string.IsNullOrWhiteSpace(arguments))

diff --git a/...ts/Scripts/WorldEngine/Modding/Expressions/NumericExpressions/NumberFunctionExpression.cs b/...ts/Scripts/WorldEngine/Modding/Expressions/NumericExpressions/NumberFunctionExpression.cs
@@ -0,0 +1,19 @@
+using UnityEngine;
+using System.Collections;
+using System.Collections.Generic;
+using System.Text.RegularExpressions;
+
+public class NumberFunctionExpression : FunctionExpressionWithOutput<float>
+{
+    public const string FunctionId = "number";
+
+    private readonly IValueExpression<bool> _arg;
+
+    public NumberFunctionExpression(Context c, IExpression[] arguments) :
+        base(c, FunctionId, 1, arguments)
+    {
+        _arg = ValueExpressionBuilder.ValidateValueExpression<bool>(arguments[0]);
+    }
+
+    public override float Value => _arg.Value ? 1 : 0;
+}
diff --git a/...ripts/WorldEngine/Modding/Expressions/NumericExpressions/NumberFunctionExpression.cs.meta b/...ripts/WorldEngine/Modding/Expressions/NumericExpressions/NumberFunctionExpression.cs.meta
diff --git a/Modding Guide/Guides/action_modding_guide.md b/Modding Guide/Guides/action_modding_guide.md
@@ -1,9 +1,10 @@
 # Action Modding Guide
 
-**Action** mod files are located within the *Actions* folder.
+**Action** scripting 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
+Note: *.json* files do not support comments. Remove texts enclosed within double dashes `--`
 
 ```
 {
@@ -30,7 +31,7 @@ To be valid, mod files must have the .json extension and have the following file
                                        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
+                                       menu. Please read expressions_guide.md for more
                                        details on how to define valid boolean
                                        expressions.
 
@@ -46,9 +47,17 @@ To be valid, mod files must have the .json extension and have the following file
       "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
+                                       related entity. Please read expressions_guide.md
                                        for more details on how to define valid effect
                                        expressions.
+
+      "enableDebugLog":             -- (optional) Can only have 'true' or 'false'
+                                       as value (default: 'false'). This an option
+                                       to assist in mod development. If this is
+                                       'true', and 'Debug Mode' is enabled within
+                                       the game, then debug information specific
+                                       to this action will be logged during the
+                                       game execution.
     },
     ...                             -- additional actions --
   ]
@@ -66,12 +75,12 @@ if an action is available for execution, They also define the tooltips to be dis
     {
       "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
+                                       time. Please read expressions_guide.md 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 be displayed. See string_values_guide.md
                                        to find more about how to define valid dynamic
                                        text values.
     }

diff --git a/Modding Guide/Guides/adjective_modding_guide.md b/Modding Guide/Guides/adjective_modding_guide.md
@@ -23,4 +23,4 @@
 
 ## 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.
+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.md* for more details on how to define and use region constraints.
diff --git a/Modding Guide/Guides/attribute_flags.txt b/Modding Guide/Guides/attribute_flags.txt
diff --git a/Modding Guide/Guides/conditions_guide.txt b/Modding Guide/Guides/conditions_guide.txt
diff --git a/Modding Guide/Guides/cultural_preferences_modding_guide.md b/Modding Guide/Guides/cultural_preferences_modding_guide.md
@@ -1,9 +1,9 @@
 # Cultural Preferences Modding Guide
 
-Cultural Preferences modding files are located within the **Preferences** folder. To be valid, mod files must have the **.json** extension and have the following file structure:
+Cultural Preferences scripting mod files are located within the **Preferences** folder. To be valid, mod files must have the **.json** extension and have the following file structure:
 
 #### File Structure
-Note: .json files do not support comments. Remove texts enclosed within double dashes '--'
+Note: *.json* files do not support comments. Remove texts enclosed within double dashes `--`
 
 ```
 {