From 76fa6065c27537f6e3f212cacf93a24ad2705967 Mon Sep 17 00:00:00 2001
From: Louis Moureaux <m_louis30@yahoo.com>
Date: Sat, 2 Nov 2024 23:10:31 +0100
Subject: [PATCH] Document unit bribe cost

Requested by Corbeau on Discord.
---
 docs/Manuals/Server/index.rst |  1 +
 docs/Manuals/Server/maths.rst | 46 +++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 docs/Manuals/Server/maths.rst

diff --git a/docs/Manuals/Server/index.rst b/docs/Manuals/Server/index.rst
index 644136800b..889f196a71 100644
--- a/docs/Manuals/Server/index.rst
+++ b/docs/Manuals/Server/index.rst
@@ -24,6 +24,7 @@ place to start is the ``#questions-and-answers`` or ``#technicalities`` channels
   command-line.rst
   commands.rst
   options.rst
+  maths.rst
   settings-file.rst
   fcdb.rst
   :maxdepth: 2
diff --git a/docs/Manuals/Server/maths.rst b/docs/Manuals/Server/maths.rst
new file mode 100644
index 0000000000..530214e04d
--- /dev/null
+++ b/docs/Manuals/Server/maths.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+.. SPDX-FileCopyrightText: Freeciv21 and Freeciv Contributors
+
+Formulas
+********
+
+This page describes how Freeciv21 computes what happens in the game. It is
+intended as a reference for ruleset authors and players who want to heavily
+optimize their actions. Developers may occasionally find it useful, too.
+
+Unit Bribe Cost
+===============
+
+The amount of gold needed to bribe a unit is primarily governed by who much the
+unit costs, the ``base_bribe_cost`` ruleset setting, and how far the unit is
+from the nearest capital city (capped to 32 tiles). The amount of gold the
+opposing player has also plays a role. The base cost is computed as follows:
+
+.. math::
+  \text{base cost} =
+    \frac{\text{owner gold} + \texttt{base\_bribe\_cost}}{2 + \text{distance}}
+    \times \frac{\text{unit cost in shields}}{10}
+
+Several multiplicative factors are applied on top of the base cost:
+
+* Rulesets can modify this cost through the ``Unit_Bribe_Cost_Pct`` effect
+
+  .. math::
+    f_\text{effects} = 1 + \frac{\texttt{Unit\_Bribe\_Cost\_Pct}}{100}
+
+* Veteran units are more expensive. The cost is increased by two factors, the
+  combat power factor :math:`f_\text{power}` and the relative speed of the unit
+  compared to a green one, :math:`f_\text{MP}`.
+* Finally, a discount is given if the unit is short on HP, reducing the cost by
+  up to 50% if the unit has no HP. This is computed as follows:
+
+  .. math::
+    f_\text{HP} =
+      \frac{1}{2} \left( 1 + \frac{\text{unit HP}}{\text{base HP}} \right)
+
+The total bribe cost is then computed as:
+
+.. math::
+  \text{final cost} = \text{base cost}
+                        \times f_\text{effects} \times f_\text{power}
+                        \times f_\text{MP} \times f_\text{HP}