docs: examples for accessing components

Author: malytomas

sphinx/source/bots/setup.rst

@@ -13,14 +13,15 @@ Steam Appid Txt
 ---------------
 
 .. important::
-   Copy ``steam_appid.txt`` into the ``bin`` folder.
+   Copy ``steam_appid.txt`` into ``Unnatural Worlds/bin`` folder.
 
-The file ``steam_appid.txt`` tells Steam that this is developer copy of the game.
+You will find the ``steam_appid.txt`` in the uwapi repository.
+Copy it into ``bin`` folder, next to the game executable.
+
+This file tells Steam that this is a developer copy of the game.
 It allows running multiple processes of the game simultaneously, and to start the programs directly from outside the Steam.
 This allows you to start and debug your bot program from inside your IDE.
 You may also start the game client, game server, built-in AI, or any other associated programs from your terminal.
-You will find the ``steam_appid.txt`` in the uwapi repository.
-Copy it into the ``bin`` folder, next to the game executable.
 
 It is recommended to remove the ``steam_appid.txt`` when you are done with your AI/bot program.
 Presence of the file may cause corruption of some files when the game is updated.
@@ -29,7 +30,7 @@ Game Install Path
 -----------------
 
 .. important::
-   If you installed Unnatural World in non-default location, define environment variable ``UNNATURAL_ROOT`` pointing to the ``bin`` directory containing the library.
+   If you have installed Unnatural World in non-default location, define environment variable ``UNNATURAL_ROOT`` pointing to the ``bin`` directory containing the library.
 
 .. tab-set::
    :sync-group: platform

sphinx/source/concepts/callbacks.rst

@@ -98,7 +98,6 @@ Make sure to carefully decode them, as shown in the example below.
           	}
           }
 
-
 Task Completed Callback
 -----------------------
 Some functions, such as pathfinding and clusters distances, need more time to compute the results.

sphinx/source/concepts/entities.rst

@@ -25,19 +25,133 @@ These ids are assigned by the server, and client cannot predict the values.
 .. note::
    Some entities and/or components are synchronized only with the owner of the entity.
 
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # get list of all entities:
+          uw_world.entities().values()
+
+          # find entity by id:
+          uw_world.entity(id) # raises KeyError if not found
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // get list of all entities:
+          World.Entities().Values
+
+          // find entity by id:
+          World.Entity(id) // throws KeyNotFoundException if not found
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
 Proto Component
 ---------------
 Defines the prototype of the entity.
 
 It is allowed to change from construction to unit, or from unit to another unit.
 It is forbidden to change eg. from unit to resource.
 
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          x = uw_world.entity(id)
+
+          # find type (unit, resource, construction, ...) of the entity:
+          x.type()
+
+          # check if entity has Proto component:
+          x.Proto is not None
+
+          # find id of the prototype of an entity:
+          x.Proto.proto # assumes that the entity actually has Proto component
+
+          # access a value from the prototype:
+          x.proto().data.get("dps", 0)
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          Entity x = World.Entity(id);
+
+          // find type (unit, resource, construction, ...) of the entity:
+          x.type
+
+          // check if entity has Proto component:
+          x.Proto.HasValue
+
+          // find id of the prototype of an entity:
+          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
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
 Owner Component
 ---------------
 Defines which force owns this entity.
 
 Immutable.
 
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # id of the force that owns this entity:
+          x.Owner.force
+
+          # check if entity is own or enemy:
+          x.own()
+          x.enemy()
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // id of the force that owns this entity:
+          x.Owner.Value.force
+
+          // check if entity is own or enemy:
+          x.Own()
+          x.Enemy()
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
 Controller Component
 --------------------
 In case that multiple players belong to the same force, the last player to give any orders to this entity will become the controller of the entity.
@@ -53,6 +167,32 @@ In case the entity has large radius, this component defines the center tile.
 The yaw defines the orientation (a rotation along the local vertical axis) of this entity on the tile.
 The actual facing of 0 degrees yaw is different for each tile.
 
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # shortcut to get tile index:
+          x.pos()
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // shortcut to get tile index:
+          x.Pos
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
 Unit Component
 --------------
 Contains additional state for a unit (or building).
@@ -63,6 +203,32 @@ Contains additional state for a unit (or building).
 - ``Stalling`` - the unit's recipe cannot be executed, usually because a limit for the outputs has been reached.
 - ``Damaged`` - the unit has less than half life.
 
+.. tab-set::
+   :sync-group: language
+
+   .. tab-item:: Python
+      :sync: python
+
+      .. code-block:: python
+
+          # check if unit is Processing:
+          (x.Unit.state & UwUnitStateFlags.Processing) != 0
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      .. code-block:: csharp
+
+          // check if unit is Processing:
+          (x.Unit.Value.state & UwUnitStateFlags::Processing) != 0
+
+   .. tab-item:: C++
+      :sync: cpp
+
+      .. code-block:: cpp
+
+          // todo
+
 Life Component
 --------------
 Amount of life of the unit (or building).