program state and bots lifecycle overview

Author: malytomas

sphinx/requirements.txt

@@ -1,5 +1,4 @@
 sphinx-autobuild
 sphinx_design
 sphinx-copybutton
-sphinx-inline-tabs
 furo

sphinx/source/bots/index.rst

@@ -8,4 +8,5 @@ Specifically, bots cannot cheat - no more than a regular player could.
 
 .. toctree::
 	setup
+	programOverview
 	troubleshooting

sphinx/source/bots/programOverview.rst

@@ -0,0 +1,78 @@
+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.
+
+Initialization
+^^^^^^^^^^^^^^
+
+- You need to change current working directory to the ``bin`` directory in the game installation.
+  Without it, the game will be unable to load maps and assets, even if it might load the shared library.
+
+.. warning::
+	Do *not* change current working directory once configured.
+
+- Next you load the shared library.
+
+.. tab-set::
+
+   .. tab-item:: Python
+      :sync: python
+
+      TODO
+
+   .. tab-item:: C#
+      :sync: csharp
+
+      The library is automatically loaded when you first access the global ``Game`` object.
+      This happens inside the ``Bot`` constructor.
+
+- Setup all your callbacks now.
+  You may also set some parameters for the connection.
+
+Connect
+^^^^^^^
+There are multiple ways to connect to a 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.
+
+Alternatively, you may implement your own logic to determine how to connect to a server.
+
+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.
+
+Game Loop
+^^^^^^^^^
+All your registered callbacks are now called, when appropriate.
+Notably, the ``Update`` callback is periodically called, no matter the game state.
+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``.
+	Be mindful of what operations are valid in these circumstances.
+
+You may prematurely close the connection with the ``Disconnect`` function.
+This will do a graceful closing of the connection, that is, you will get some additional callbacks called.
+After that the connect function will return.
+
+Finalization
+^^^^^^^^^^^^
+When the connection function returns, the network connection has already been closed, and you take back control over the program.
+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.

sphinx/source/bots/setup.rst

@@ -1,10 +1,10 @@
 Setup
-====
+=====
 You can write your bot in any language, as long as it can load a dynamic/shared library (.dll/.so).
 The shared library is distributed together with the game.
 
 The uwapi repository contains c/c++ headers for all functions and structures provided by the library.
-Furthermore, it contains convenient wrappers for Python and for C# for quicker start.
+Furthermore, it contains convenient wrappers for Python and C# for easy start.
 
 .. important::
 	Copy ``steam_appid.txt`` into the ``bin`` folder.
@@ -17,6 +17,16 @@ You will find the ``steam_appid.txt`` in the uwapi repository.
 Copy it into the ``bin`` folder, next to the game executable.
 
 .. important::
-	If your Steam games are in non-default location, define environment variable ``UNNATURAL_ROOT`` to the directory containing the library.
+	If you installed Unnatural World in non-default location, define environment variable ``UNNATURAL_ROOT`` to the directory containing the library.
 
-The default path on Windows: ``C:\Program Files (x86)\Steam\steamapps\common\Unnatural Worlds\bin``, on linux: ``~/.steam/steam/steamapps/common/Unnatural Worlds/bin``.
+.. tab-set::
+
+   .. tab-item:: Windows
+      :sync: windows
+
+      Default path: ``C:\Program Files (x86)\Steam\steamapps\common\Unnatural Worlds\bin``
+
+   .. tab-item:: Linux
+      :sync: linux
+
+      Default path: ``~/.steam/steam/steamapps/common/Unnatural Worlds/bin``

sphinx/source/concepts/index.rst

@@ -6,3 +6,4 @@ Glossary and explanation of concepts used throughout this documentation and in t
 	map
 	prototypes
 	ecs
+	programState

sphinx/source/concepts/programState.rst

@@ -0,0 +1,36 @@
+Program State
+=============
+The program state is controlled by several independent variables.
+
+Game State
+----------
+
+- ``None`` - the game is initializing.
+- ``Session`` - players are connecting, and are negotiating the map and other settings. An admin will start the game.
+- ``Preparation`` - countdown before the game actually starts. This alerts players to get ready.
+- ``Game`` - game is in progress.
+- ``Finish`` - game is over. Winners and defeated have been declared.
+
+Map State
+---------
+
+- ``None`` - no map is set to load.
+- ``Downloading`` - the map is not available locally and is being downloaded.
+- ``Loading`` - the map is being loaded.
+- ``Loaded`` - map is fully available. This is the only state when you can access any of the functions that interact with the map.
+- ``Unloading`` - the map is being unloaded.
+- ``Error`` - loading a map has encountered an error. Loading is cancelled.
+
+.. warning::
+	Do *not* access any of the map-related functions unless the map is ``Loaded``.
+
+Accessing any of the map-related functions when the map is *not* ``Loaded`` will crash the game, since all data are loaded concurrently.
+
+Connection State
+----------------
+
+- ``None`` - there is no connection. Do *not* send any commands.
+- ``Connecting`` - connection is being attempted. You may send commands, they will be delivered once the connection is established.
+- ``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.
+

sphinx/source/conf.py

@@ -20,7 +20,6 @@
     'sphinx.ext.githubpages',
     'sphinx_design',
     'sphinx_copybutton',
-    "sphinx_inline_tabs",
 ]
 
 templates_path = ['_templates']