more sphinx (mostly concepts)

Author: malytomas

sphinx/Makefile

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+sphinx-autobuild source build

sphinx/live.sh

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

sphinx/make.bat

@@ -1,2 +1,15 @@
-ECS
-===
+Entities (ECS)
+==============
+
+.. epigraph::
+
+	.. image:: /_static/ecs.svg
+		:alt: ECS Diagram from Wikipedia
+		:height: 100pt
+		:align: right
+
+	"Entity–component–system (ECS) is a software architectural pattern mostly used in video game development for the representation of game world objects. An ECS comprises entities composed from components of data, with systems which operate on the components.
+
+	ECS follows the principle of composition over inheritance, meaning that every entity is defined not by a type hierarchy, but by the components that are associated with it. Systems act globally over all entities which have the required components. "
+
+	— `Wikipedia - Entity Component System <https://en.wikipedia.org/wiki/Entity_component_system>`_

sphinx/requirements.txt

@@ -3,7 +3,6 @@ General Concepts
 Glossary and explanation of concepts used throughout this documentation and in the game.
 
 .. toctree::
-	tiles
-	clusters
+	map
 	prototypes
 	ecs

sphinx/source/_static/ecs.svg

@@ -0,0 +1,40 @@
+Map
+===
+Map is uniquely identified by its GUID.
+It will differ even for each version of the same map.
+
+Tiles
+-----
+The map uses discrete tiles representation (similar to chess), as opposed to continuous space.
+
+Tiles are indexed `0 .. N-1`.
+
+Data available for each tile:
+
+- Position - 3D coordinates
+- Up - 3D vector - direction opposite of local gravity
+- Neighbors - array of indices of neighboring tiles
+- Cluster - index of the cluster this tile belongs to
+- Terrain - index of the terrain at this tile
+
+Clusters
+--------
+Clusters are aggregations of tiles into smaller connected groups.
+It is intended primarily for performance optimizations.
+All tiles in one cluster have the same terrain.
+
+Clusters are indexed `0 .. M-1`.
+
+Data available for each cluster:
+
+- Neighbors - array of indices of neighboring clusters
+- Tile - index of the center-most tile in this cluster
+
+Overview
+--------
+Automatically updated ids of entities present on each tile.
+This is used for performance optimization.
+
+Entities with larger radius will be present in all tiles that they cover, not just the center.
+
+Additionally, bit-flags are available for each tile, with different bits denoting different types of entities present on the tile.

sphinx/source/concepts/clusters.rst

@@ -1,2 +1,55 @@
 Prototypes
 ==========
+Prototypes are data definitions used for everything in the game.
+They are loaded with the map, and are immutable.
+
+Each prototype is identified by its id, which is a hash of its name (the full path in the source files).
+
+Resource Prototype
+------------------
+Defines properties of a resource - aka a crate/pallet/barrel that would exist in the world.
+
+Recipe Prototype
+----------------
+Defines a transformation of resources, units, and upgrades.
+It contains amounts and ids of inputs and outputs.
+Also defines the duration of the recipe.
+Recipes are processed in buildings/units.
+
+Some recipes have a *place-over* requirement, which is an id of a unit, that the building must be placed on, in order for the recipe to be available.
+
+Construction Prototype
+----------------------
+Constructions are similar to recipes, but are manually placed into the world by the player.
+It contains amounts of input resources, and has exactly one output unit/building.
+
+Unit Prototype
+--------------
+Both buildings and units are treated as units in the game.
+Some neutral objects, such as trees, rocks, ore deposits, etc. are all also units.
+
+The prototype contains combat related properties, movement (speeds), 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.
+
+Upgrade Prototype
+-----------------
+Upgrades improve combat or economy of specified units/buildings of the same player.
+The upgrade itself defines the improvements that it will apply, and units have a list of upgrades that may be applied to them.
+
+The upgrades are temporary, and will disappear after specified duration.
+Multiple same upgrades stack together, up to a specified limit.
+
+Race Prototype
+--------------
+Each player selects one race that they play as.
+The race defines their starting resources and units, and a list of available constructions.
+
+Note that neither resources, recipes, units, or upgrades are inherently associated with any particular race.
+There are no restrictions on units that the player may control, if they get hold of them.
+
+Tags
+----
+All prototypes may have associated some tags with them.
+Tags are short strings (mapped to unique ids), that are provided by the game/map/mods to help programs understand the nuances of that particular prototype.
+Tags are *not* used by the game, except by the built-in AI/bot, which uses tags to alter behavior of some units.
+Tags may be used by both Bots and Scripts.