Improved warp-in formulas on the Useful Formulae page

docs/guides/useful-formulae.md

@@ -1,30 +1,50 @@
 # Useful Formulae
 
-## Ordinary Objects
+## Warp-in points
+
+### Ordinary Objects
 An ordinary object is any object that does not fall withing any of the other categories described below.
 
 Let the 3D vectors $p_d$ and $p_s$ represent the object’s position and the warp’s origin, respectively; and $\vec{v}$ the directional vector from $p_s$ to $p_d$. Let $r$ be the object’s radius.
 
 The object’s warp-in point is the vector $p_s + \vec{v} - r\hat{v}$.
 
-## Large Objects
-A large object is any celestial body whose radius exceeds 90 kilometres (180 kilometres in diameter), except planets.
+In other words, the warping ship arrives at a point between the starting position and the targets' position, at the edge of the targets' radius.
+
+### Large Objects
+A large object is any Celestial (type category 2) with a radius of at least 90 kilometres (180 kilometres in diameter), except wrecks, planets, and suns.
 
 Let $x$, $y$, and $z$ represent the object’s coordinates. Let $r$ be the object’s radius.
 
 The object’s warp-in point is the vector $\left(x + (r + 5000000)\cos{r} \\, y + 1.3r - 7500 \\, z - (r + 5000000)\sin{r} \\ \right).$
 
-## Planets
+<h3>Example</h3>
+
+--8<-- "snippets/formulae/large-object-warp-in.md"
+
+### Suns
+
+The warp-in point of a sun is determined by its radius.
+
+Let $r$ be the sun's radius.
+
+The sun’s warp-in point is the vector $\left((r + 100000)\cos{r} \\, 0.2r \\, -(r + 100000)\sin{r} \\ \right).$
+
+<h3>Example</h3>
+
+--8<-- "snippets/formulae/sun-warp-in.md"
+
+### Planets
 
 The warp-in point of a planet is determined by the planet's ID, its location, and radius.
 
-Let $x$, $y$, and $z$ represent the planet's coordinates. Let $r$ be the planet's radius.
+Let $x$, $y$, and $z$ represent the planet's coordinates. Let $r$ be the planet's radius, and $p$ be the planet's ID.
 
 The planet's warp-in point is the vector $\left(x + d \sin{\theta}, y + \frac{1}{2} r \sin{j}, z - d \cos{\theta}\right)$
 where:
 
 $$
-d = r(s + 1) + 1000000
+d = r(s + 1) + 10^6
 $$
 
 $$
@@ -35,11 +55,20 @@ $$
 s|_{0.5 \leq s \leq 10.5} = 20\left(\frac{1}{40}\left(10\log_{10}\left(\frac{r}{10^6}\right) - 39\right)\right)^{20} + \frac{1}{2}
 $$
 
-Now, $j$ is a special snowflake. Its value is the Python equivalent of `(random.Random(planetID).random() - 1.0) / 3.0`.
+$$
+j = \frac{mt(p) - 1}{3}
+$$
+
+The function $mt(p)$ represents the first floating point number in range $[0,1)$ generated by a
+[Mersenne Twister](https://en.wikipedia.org/wiki/Mersenne_Twister) PRNG seeded with the planet's ID.
+
+In Python, this is equivalent to `random.Random(p).random()`. Implementations of Mersenne Twisters are widely available
+for popular languages, but you need to be careful to match Python's, as not all implementations use the provided seed in
+the same way.
 
 <h3>Example</h3>
 
---8<-- "snippets/formulae/warp-in.md"
+--8<-- "snippets/formulae/planet-warp-in.md"
 
 ## Skillpoints needed per level
 

scripts/generate-snippets.py

@@ -12,13 +12,15 @@
 EXTENSION_MAPPING = {
     ".py": "Python",
     ".cs": "C#",
+    ".kt": "Kotlin",
 }
 
 # The mapping of file extensions to syntax highlighting names. The key is the file
 # extension (including the dot), and the value is the syntax highlighting name.
 SYNTAX_MAPPING = {
     ".py": "python",
     ".cs": "csharp",
+    ".kt": "kotlin",
 }
 
 # The file extension for the combined markdown file.

snippets/formulae/large-object-warp-in.kt

@@ -0,0 +1,8 @@
+import kotlin.math.*
+
+fun getLargeObjectWarpInPoint(x: Double, y: Double, z: Double, radius: Double): Triple<Double, Double, Double> {
+    val x = (radius + 5000000) * cos(radius)
+    val y = 1.3 * radius - 7500
+    val z = -(radius + 5000000) * sin(radius)
+    return Triple(x, y, z)
+}

snippets/formulae/planet-warp-in.kt

@@ -0,0 +1,10 @@
+import org.apache.commons.math3.random.MersenneTwister
+import kotlin.math.*
+
+fun getPlanetWarpInPoint(planetId: Int, x: Double, y: Double, z: Double, radius: Double): Triple<Double, Double, Double> {
+    val j = (MersenneTwister(intArrayOf(planetId)).nextDouble() - 1) / 3
+    val theta = asin((x / abs(x)) * (z / (sqrt(x.pow(2) + z.pow(2))))) + j
+    val s = (20 * ((10 * log10(radius / 1000000) - 39) / 40).pow(20) + 0.5).coerceIn(0.5, 10.5)
+    val d = radius * (s + 1) + 1000000
+    return Triple(x + sin(theta) * d, y + radius * sin(j) / 2, z - cos(theta) * d)
+}

snippets/formulae/sun-warp-in.kt

@@ -0,0 +1,8 @@
+import kotlin.math.*
+
+fun getSunWarpInPoint(radius: Double): Triple<Double, Double, Double> {
+    val x = (radius + 100000) * cos(radius)
+    val y = 0.2 * radius
+    val z = -(radius + 100000) * sin(radius)
+    return Triple(x, y, z)
+}