From 9e05a9bdd5f7e5ddc8a2170c031a47d669432832 Mon Sep 17 00:00:00 2001
From: Ilion Beyst <ilion.beyst@gmail.com>
Date: Mon, 19 Sep 2022 22:28:27 +0200
Subject: update docs

- divide rules doc in sections
- clarify turn order
- document logging to stderr
- bump turn limit to 500
---
 web/pw-server/src/routes/docs/local-development.md |  2 +
 web/pw-server/src/routes/docs/rules.md             | 49 +++++++++++++++++-----
 2 files changed, 40 insertions(+), 11 deletions(-)

(limited to 'web/pw-server/src/routes/docs')

diff --git a/web/pw-server/src/routes/docs/local-development.md b/web/pw-server/src/routes/docs/local-development.md
index 02913dc..218ae22 100644
--- a/web/pw-server/src/routes/docs/local-development.md
+++ b/web/pw-server/src/routes/docs/local-development.md
@@ -72,9 +72,11 @@ CMD python simplebot.py
 Refer to https://docs.docker.com for guides on how to write your own dockerfile.
 
 In the directory that contains your `Dockerfile`, run the following command:
+
 ```bash
 docker build -t my-bot-name .
 ```
+
 If all went well, your docker daemon now holds a container tagged as `my-bot-name`.
 
 ### Publishing the bot
diff --git a/web/pw-server/src/routes/docs/rules.md b/web/pw-server/src/routes/docs/rules.md
index ff803e7..4d37729 100644
--- a/web/pw-server/src/routes/docs/rules.md
+++ b/web/pw-server/src/routes/docs/rules.md
@@ -1,4 +1,6 @@
-## How to play
+# How to play
+
+## Protocol
 
 In every game turn, your bot will receive a json-encoded line on stdin, describing the current
 state of the game. Each state will hold a set of planets, and a set of spaceship fleets
@@ -46,7 +48,6 @@ Example game state:
 
 The `owner` field holds a player number when the planet is held by a player, and is
 `null` otherwise. Your bot is always referred to as player 1.  
-Each turn, every player-owned planet will gain one additional ship.  
 Planets will never move during the game.
 
 Every turn, you may send out expeditions to conquer other planets. You can do this by writing
@@ -64,24 +65,50 @@ Example command:
     }
   ]
 }
+
+You can dispatch as many expeditions as you like.
 ```
 
-All players send out their commands simultaneously, so there is no turn order. You may send as
-many commands as you please.
+## Rules
+
+All players send out their commands simultaneously, so there is no player order.
 
 The amount of turns an expedition will travel is equal to the ceiled euclidean distance
 between its origin and destination planet.
 
+Each turn, one additional ship will be constructed on each player-owned planet.
+Neutral planets do not construct ships.
+
 Ships will only battle on planets. Combat resolution is simple: every ship destroys one enemy
-ship, last man standing gets to keep the planet.
+ship, last man standing gets to keep the planet. When no player has ships remaining, the planet will turn neutral.
+
+A turn progresses as follows:
+
+1. Construct ships
+2. Dispatch expeditions
+3. Arrivals & combat resolution
+
+It is not allowed for players to abandon a planet - at least one ship should remain at all times.
+Note that you are still allowed to dispatch the full ship count you observe in the game state,
+as an additional ship will be constructed before the ships depart.
 
 The game will end when no enemy player ships remain (neutral ships may survive), or when the
-turn limit is reached. The default limit is 100 turns.
+turn limit is reached. When the turn limit is hit, the game will end it a tie.
+Currently, the limit is set at 500 turns.
+
+## Writing your bot
+
+You can code a bot in python 3.10 using the [web editor](/editor). A working example bot is provided.
+If you'd like to use a different programming language, or prefer coding on your own editor,
+you can try [local development](/docs/local-development).
 
-You can code your bot in python 3.10. You have the entire stdlib at your disposal.  
-If you'd like additional libraries or a different programming language, feel free to nag the administrator.
+As logging to stdout will be interpreted as commands by the game server, we suggest you log to stderr.  
+In python, you can do this using
+
+```python
+print("hello world", file=sys.stderr)
+```
 
-### TL;DR
+Output written to stderr will be displayed alongside the match replay.
 
-Head over to the editor view to get started - a working example is provided.  
-Feel free to just hit the play button to see how it works!
+Feel free to launch some test matches to get the hang of it!
-- 
cgit v1.2.3