documentation: callbacks, network

malytomas · malytomas · commit 95b109706533 · 2025-06-11T00:16:20.000+02:00
diff --git a/sphinx/source/bots/programOverview.rst b/sphinx/source/bots/programOverview.rst
@@ -2,15 +2,6 @@ Program Overview
 ================
 High-level look at basic bot program.
 
-Environment Variables
----------------------
-Some variables that may alter the behavior of your bot program.
-
-- ``UNNATURAL_ROOT`` - path to the ``bin`` folder that contains the shared library.
-- ``UNNATURAL_CONNECT_LOBBY`` - id of Steam lobby to connect to.
-- ``UNNATURAL_CONNECT_ADDR`` - IP address or domain name to connect to.
-- ``UNNATURAL_CONNECT_PORT`` - port of the game server to connect to.
-
 Program Lifecycle
 -----------------
 At start, you are in full control of the program.
@@ -24,7 +15,7 @@ Initialization
 .. warning::
 	Do *not* change current working directory once configured.
 
-- Next you load the shared library.
+- Next, you load the shared library.
 
 .. tab-set::
    :sync-group: language
@@ -45,7 +36,7 @@ Initialization
 
 Connect
 ^^^^^^^
-There are multiple ways to connect to a server.
+There are multiple ways to connect to a game server.
 The usual approach is to first try reconnecting, in case the game has crashed previously.
 Second, you connect to an existing server using the parameters provided in the environment variables, if any.
 Third, you spin up your own server.
@@ -54,7 +45,7 @@ Alternatively, you may implement your own logic to determine how to connect to a
 
 No matter the method, the game will now take control over the program.
 Your program is blocked until the network connection closes.
-All your further actions will happen inside callbacks only.
+*All your further actions will happen inside callbacks only.*
 
 Game Loop
 ^^^^^^^^^
@@ -63,7 +54,7 @@ Notably, the ``Update`` callback is periodically called, no matter the game stat
 This is where you keep track of the state of the game, and perform any of your actions.
 
 .. warning::
-	The ``Update`` callback, and some other, may be called before the game has actually started (eg. in ``Session``), or when the map is not yet ``Loaded``.
+	The ``Update`` callback, and some others, may be called before the game has actually started (eg. in ``Session``), or when the map is not yet ``Loaded``.
 	Be mindful of what operations are valid in these circumstances.
 
 You may prematurely close the connection with the ``Disconnect`` function.
@@ -76,4 +67,36 @@ When the connection function returns, the network connection has already been cl
 You may do any cleanup operations, for example you may save some statistics from the game.
 Ultimately, you should unload the shared library, and exit the program.
 
-It may be tempting to just loop and connect again to next server, however this is strongly discouraged.
+It may be tempting to just loop over and connect to next server, however this is strongly discouraged.
+
+Network
+-------
+The game is designed for multiplayer, and always plays over network, even in single-player scenarios.
+
+Any actions that you do in your program are first send to the game server, then processed, and then the results are send back to your client.
+
+Example: you call a function to place a construction.
+After that you look through all the entities and the construction is not there, as expected.
+You will not know the id of the entity either.
+The construction will appear only after the game server has processed the request.
+It is recommended to wait several ticks between these kinds of actions, to avoid placing same construction multiple times in different places.
+
+.. note::
+	Test your program over a real network, not just localhost.
+
+Client-only State
+^^^^^^^^^^^^^^^^^
+Some state is stored on client only, notably:
+
+- Units orders
+- Pathfinding
+- Logistics planning
+
+Environment Variables
+---------------------
+Some variables that may alter the behavior of your bot program.
+
+- ``UNNATURAL_ROOT`` - path to the ``bin`` folder that contains the shared library.
+- ``UNNATURAL_CONNECT_LOBBY`` - id of Steam lobby to connect to.
+- ``UNNATURAL_CONNECT_ADDR`` - IP address or domain name to connect to.
+- ``UNNATURAL_CONNECT_PORT`` - port of the game server to connect to.
diff --git a/sphinx/source/bots/troubleshooting.rst b/sphinx/source/bots/troubleshooting.rst
@@ -1,7 +1,7 @@
 Troubleshooting
 ===============
 
-.. warning::
+.. important::
 	Do *not* use Flatpak for Steam on Linux.
 
 .. dropdown:: Unable to load DLL 'unnatural-uwapi-hard'
diff --git a/sphinx/source/concepts/callbacks.rst b/sphinx/source/concepts/callbacks.rst
@@ -0,0 +1,58 @@
+Callbacks
+=========
+
+Game/Map/Connection State Callback
+-------------------
+Viz :ref:`concepts/programState:Game State`, :ref:`concepts/programState:Map State`, and :ref:`concepts/programState:Connection State`.
+
+Update Callback
+---------------
+This callback is called every time the simulation time progresses (:ref:`tick <concepts/programState:Ticks>` changes).
+It is also called when game time is not progressing (eg. when paused, or in session), but real time elapses.
+The difference is indicated with the ``stepping`` parameter.
+
+This callback is the primary driving point for your program.
+
+.. note::
+	Some ticks may be skipped, eg. when the game is lagging.
+	Use ``>=`` when waiting for number of ticks to pass.
+
+Shooting Callback
+-----------------
+Shooting events are synchronized *asynchronously and unreliably*.
+This event is useful for measuring threat levels.
+
+.. warning::
+	The entity id may be expired.
+
+Explosions Callback
+-------------------
+Explosions events are synchronized *asynchronously and unreliably* - some events may be lost, or delivered much later.
+Do *not* depend on explosions events for important decisions.
+It is useful for measuring threat levels.
+
+.. warning::
+	The entity id may be expired.
+
+Task Completed Callback
+-----------------------
+Some functions, such as pathfinding and clusters distances, need more time to compute the results.
+The calculations happen on separate threads internally in the uwapi library.
+Finally, this callback is called, passing in the results, when it finishes.
+
+This callback may be called at any time, relative to other callbacks - there are no guarantees.
+
+.. warning::
+	Do *not* try to wait (blocking) for the tasks.
+	It will block the whole program indefinitely.
+
+.. warning::
+	Any entity id may have expired by the time the task completed.
+
+Force Eliminated Callback
+-------------------------
+This informs you that a player lost.
+
+Chat Callback
+-------------
+You have received a message.
diff --git a/sphinx/source/concepts/entities.rst b/sphinx/source/concepts/entities.rst
@@ -25,107 +25,107 @@ 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.
 
-Proto
------
+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.
 
-Owner
------
+Owner Component
+---------------
 Defines which force owns this entity.
 
 Immutable.
 
-Controller
-----------
+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.
 
-.. warning::
+.. note::
 	Controllers are not yet implemented.
 
-Position
---------
+Position Component
+------------------
 Index of the tile this entity is placed on.
 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 direction of 0 degrees yaw is different for each tile.
+The actual facing of 0 degrees yaw is different for each tile.
 
-Unit
-----
+Unit Component
+--------------
 Contains additional state for a unit (or building).
 
 - ``Shooting`` - waiting for the cannon to cool down.
 - ``Processing`` - the unit has processed a recipe and is waiting for it to complete.
 - ``Rebuilding`` - recipe for the unit has changed, and the unit is waiting for the changes to complete.
 - ``Stalling`` - the unit's recipe cannot be executed, usually because a limit for the outputs has been reached.
 
-Life
-----
+Life Component
+--------------
 Amount of life of the unit (or building).
 
-Move
-----
+Move Component
+--------------
 Contains information about current movement of the unit.
 Information is available for the next neighboring tile only.
 
-Aim
----
+Aim Component
+-------------
 Id of a target unit that this unit will automatically shoot at.
 
-Recipe
-------
+Recipe Component
+----------------
 Id of the prototype of the recipe that this unit will automatically process.
 
-UpdateTimestamp
----------------
+Update Timestamp Component
+--------------------------
 Contains a timestamp (tick) of when this construction started, or when this unit's recipe was last processed.
 It is used for planning logistics deliveries.
 
-RecipeStatistics
-----------------
+Recipe Statistics Component
+---------------------------
 Used for calculating this unit's processing efficiency.
 
 It is reset when the recipe changes.
 
-Priority
---------
+Priority Component
+------------------
 Contains the priority assigned by the player.
 The priority applies to both constructions and recipe processing.
 It is used by the logistics planning.
 
-Amount
-------
+Amount Component
+----------------
 Contains the count of the resource in this entity.
 
-Attachment
-----------
+Attachment Component
+--------------------
 Defines that this entity is attached to another entity.
 This entity is automatically moved to the position (and orientation) of the target.
 This is commonly used by a resource carried by a truck.
 
-Player
-------
+Player Component
+----------------
 This entity represents a client - a player or an observer.
 
-Force
------
+Force Component
+---------------
 This entity represents a force.
 The component contains public information about the force.
 
-ForceDetails
-------------
+Force Details Component
+-----------------------
 This component contains private information about the force.
 
-ForeignPolicy
--------------
+Foreign Policy Component
+------------------------
 This entity declares the policy between two forces.
 
-DiplomacyProposal
------------------
+Diplomacy Proposal Component
+----------------------------
 This entity contains a proposal of a policy to another force.
 
-.. warning::
+.. note::
 	Diplomacy is not yet implemented.
diff --git a/sphinx/source/concepts/index.rst b/sphinx/source/concepts/index.rst
@@ -10,3 +10,4 @@ Glossary and explanation of concepts used throughout this documentation and in t
 	resources
 	combat
 	programState
+	callbacks
diff --git a/sphinx/source/concepts/map.rst b/sphinx/source/concepts/map.rst
@@ -54,28 +54,28 @@ There are multiple functions for finding tiles within some distance.
          :img-bottom: /_static/area-query-range.svg
          :text-align: center
 
-         **AreaRange**
+         **Area Range**
 
    .. grid-item::
 
       .. card::
          :img-bottom: /_static/area-query-connected.svg
          :text-align: center
 
-         **AreaConnected**
+         **Area Connected**
 
    .. grid-item::
 
       .. card::
          :img-bottom: /_static/area-query-neighborhood.svg
          :text-align: center
 
-         **AreaNeighborhood**
+         **Area Neighborhood**
 
    .. grid-item::
 
       .. card::
          :img-bottom: /_static/area-query-extended.svg
          :text-align: center
 
-         **AreaExtended**
+         **Area Extended**
diff --git a/sphinx/source/concepts/players.rst b/sphinx/source/concepts/players.rst
@@ -27,7 +27,7 @@ In that case, these players share ownership of all the units associated with the
 Each unit remembers the last player that gave it any order, this player is called the controller.
 Any automated system in the game (eg. logistics controls for trucks) will not give any orders to units with different controller.
 
-.. warning::
+.. note::
 	Controllers are only partially implemented in the game for now.
 
 Neutral
@@ -47,7 +47,7 @@ The game has additional enumeration values for some edge cases.
 Diplomacy
 ^^^^^^^^^
 
-.. warning::
+.. note::
 	Diplomacy is not yet implemented.
 
 Teams
diff --git a/sphinx/source/concepts/programState.rst b/sphinx/source/concepts/programState.rst
@@ -34,3 +34,12 @@ Connection State
 - ``Connected`` - connection has been fully established. We are receiving data, and can send commands.
 - ``Error`` - connection has been closed or broken. Do *not* send any commands.
 
+Ticks
+-----
+Ticks are the measurement of time in the game simulation.
+
+When ticks are ticking, units are moving.
+When tick is the same, no units are moving, no one is shooting, etc.
+
+There is 20 ticks per second, by default.
+This is provided as a constant in the api.
diff --git a/sphinx/source/concepts/prototypes.rst b/sphinx/source/concepts/prototypes.rst
@@ -28,7 +28,7 @@ Unit Prototype
 Both buildings and units are treated as units in the game.
 
 .. note::
-	Some neutral objects, such as trees, rocks, ore deposits, etc. are all units too.
+	Some neutral objects, such as trees, rocks, ore deposits, etc. are units too.
 
 The prototype contains combat related properties, movement speeds or building radius, a list of available recipes, and a list of applicable upgrades.
 Additionally, there are several boolean properties, which modify behavior or requirements of the unit/building.
diff --git a/sphinx/source/conf.py b/sphinx/source/conf.py
@@ -24,8 +24,7 @@
 
 templates_path = ['_templates']
 exclude_patterns = []
-
-
+autosectionlabel_prefix_document = True
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
diff --git a/sphinx/source/index.rst b/sphinx/source/index.rst
diff --git a/sphinx/source/maps/index.rst b/sphinx/source/maps/index.rst
diff --git a/sphinx/source/mods/index.rst b/sphinx/source/mods/index.rst
