docs: economy and orders

Author: malytomas

sphinx/source/concepts/economy.rst

@@ -0,0 +1,81 @@
+Economy
+=======
+
+Resources are mined from deposits, or processed from other resources.
+Producing units or researching upgrades works the same way as recipes.
+
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # find closest viable position for miner:
+          p = uw_world.find_construction_placement(DRILL_CONSTRUCTION_ID, home_position, METAL_RECIPE_ID) # recipe id is optional
+          if p == INVALID:
+            return
+
+          # place construction:
+          uw_commands.place_construction(DRILL_CONSTRUCTION_ID, p, 0, METAL_RECIPE_ID, UwPriorityEnum.Normal) # yaw, recipe, and priority are optional
+          
+          # recipe and priority can be changed later:
+          uw_commands.set_recipe(own_id, ANOTHER_RECIPE_ID)
+          uw_commands.set_priority(own_id, UwPriorityEnum.High)
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // find closest viable position for miner:
+          uint p = World.FindConstructionPlacement(DRILL_CONSTRUCTION_ID, homePosition, METAL_RECIPE_ID); // recipe id is optional
+          if (p == Entity.Invalid):
+            return;
+
+          // place construction:
+          Commands.PlaceConstruction(DRILL_CONSTRUCTION_ID, p, 0, METAL_RECIPE_ID, Interop.UwPriorityEnum.Normal); // yaw, recipe, and priority are optional
+          
+          // recipe and priority can be changed later:
+          Commands.SetRecipe(own_id, ANOTHER_RECIPE_ID)
+          Commands.SetPriority(own_id, Interop.UwPriorityEnum.High)
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
+Logistics
+---------
+
+Resources are automatically transported by trucks.
+They will fulfill tasks by their priority, and on first-come-first-serve basis.
+
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # percentage of trucks that are idle:
+          100.0 * uw_world.my_force_statistics().logisticsUnitsIdle / uw_world.my_force_statistics().logisticsUnitsTotal
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // percentage of trucks that are idle:
+          100.0 * World.MyForceStatistics().logisticsUnitsIdle / World.MyForceStatistics().logisticsUnitsTotal
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // nothing

sphinx/source/concepts/entities.rst

@@ -1,5 +1,5 @@
-Entities & Components
-=====================
+Entities
+========
 
 .. epigraph::
 
@@ -103,7 +103,7 @@ It is forbidden to change eg. from unit to resource.
           x.Proto.Value.proto // assumes that the entity actually has Proto component
 
           // access a value from the prototype:
-          x.ProtoUnit.dps // assumes that the entity is a unit
+          x.ProtoUnit?.dps // assumes that the entity is a unit
 
    .. tab-item:: C++
       :sync: cpp
@@ -220,7 +220,7 @@ Contains additional state for a unit (or building).
       .. code-block:: csharp
 
           // check if unit is Processing:
-          (x.Unit.Value.state & UwUnitStateFlags::Processing) != 0
+          (x.Unit.Value.state & UwUnitStateFlags.Processing) != 0
 
    .. tab-item:: C++
       :sync: cpp

sphinx/source/concepts/index.rst

@@ -7,7 +7,7 @@ Glossary and explanation of concepts used throughout this documentation and in t
    map
    prototypes
    entities
-   resources
-   combat
+   economy
+   military
    programState
    callbacks

sphinx/source/concepts/map.rst

@@ -80,6 +80,32 @@ There are multiple functions for finding tiles within some distance.
 
          **Area Extended**
 
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # find all connected tiles around home position:
+          uw_map.area_connected(home_position, 300)
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // find all connected tiles around home position:
+          Map.AreaConnected(homePosition, 300)
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
 Pathfinding
 -----------
 Finds fastest path for a specified type of unit from tile A to tile B.

sphinx/source/concepts/combat.rst renamed to sphinx/source/concepts/military.rst

@@ -1,9 +1,61 @@
-Combat & Upgrades
-=================
+Military
+========
+
+Orders
+------
+
+.. note::
+   Orders are usable by clients only. Server-side scripts do not have the concept of orders.
+
+You can have multiple orders queued for each unit.
+
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # get list of orders of own unit:
+          os = uw_commands.orders(own_id)
+          
+          # order own unit to attack enemy unit (cancels all previous orders):
+          uw_commands.order(own_id, uw_commands.fight_to_entity(enemy_id))
+          
+          # alternatively, enqueue attack order:
+          o = uw_commands.fight_to_entity(enemy_id)
+          o.priority = o.priority | UwOrderPriorityFlags.Enqueue
+          uw_commands.order(own_id, o)
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // get list of orders of own unit:
+          var os = Commands.Orders(own_id);
+          
+          // order own unit to attack enemy unit (cancels all previous orders):
+          Commands.Order(own_id, Commands.FightToEntity(enemy_id));
+          
+          // alternatively, enqueue attack order:
+          Order o = Commands.FightToEntity(enemy_id);
+          o.priority |= Interop.UwOrderPriorityFlags.Enqueue;
+          Commands.Order(own_id, o);
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // nothing
 
 Shooting
 --------
 
+Units will automatically target appropriate enemies in their vicinity.
+
 Requirements for shooting:
 
 - the target is withing shooting range.

sphinx/source/concepts/prototypes.rst

@@ -59,6 +59,8 @@ Tags may be used by both Bots and Scripts.
 - ``ambush`` - walks over additional terrain types.
 - ``artillery`` - longer range than most.
 - ``assault`` - good for front-line combat.
+- ``decoration`` - just a decoration.
+- ``deposit`` - contains ore; build a miner over this unit to gather resources.
 - ``harassment`` - good for hit-and-run attacks, especially targeting workers.
 - ``home`` - the center of your base. dont let it die.
 - ``miner`` - generates resources, usually from ore deposits.