From eeddf894b327762c8c9f9d14539e42aabadf1fbf Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Tue, 16 Sep 2025 20:27:35 +0300
Subject: [PATCH] add 'random' library docs

---
 doc/en/scripting.md                    |  1 +
 doc/en/scripting/builtins/librandom.md | 38 ++++++++++++++++++++++++++
 doc/ru/scripting.md                    |  1 +
 doc/ru/scripting/builtins/librandom.md | 38 ++++++++++++++++++++++++++
 4 files changed, 78 insertions(+)
 create mode 100644 doc/en/scripting/builtins/librandom.md
 create mode 100644 doc/ru/scripting/builtins/librandom.md

diff --git a/doc/en/scripting.md b/doc/en/scripting.md
index c68d6b0c..9b2a0297 100644
--- a/doc/en/scripting.md
+++ b/doc/en/scripting.md
@@ -35,6 +35,7 @@ Subsections:
     - [pathfinding](scripting/builtins/libpathfinding.md)
     - [player](scripting/builtins/libplayer.md)
     - [quat](scripting/builtins/libquat.md)
+    - [random](scripting/builtins/librandom.md)
     - [rules](scripting/builtins/librules.md)
     - [time](scripting/builtins/libtime.md)
     - [utf8](scripting/builtins/libutf8.md)
diff --git a/doc/en/scripting/builtins/librandom.md b/doc/en/scripting/builtins/librandom.md
new file mode 100644
index 00000000..0ae52155
--- /dev/null
+++ b/doc/en/scripting/builtins/librandom.md
@@ -0,0 +1,38 @@
+# *random* library
+
+A library of functions for generating random numbers.
+
+## Non-deterministic numbers
+
+```lua
+-- Generates a random number in the range [0..1)
+random.random() --> number
+
+-- Generates a random integer in the range [0..n]
+random.random(n) --> number
+
+-- Generates a random integer in the range [a..b]
+random.random(a, b) --> number
+
+-- Generates a random byte array of length n
+random.bytes(n: number) -> Bytearray
+
+-- Generates a UUID version 4
+random.uuid() -> str
+```
+
+## Pseudorandom numbers
+
+The library provides the Random class - a generator with its own isolated state.
+
+```lua
+local rng = random.Random()
+
+-- Used similarly to math.random
+local a = rng:random() --> [0..1)
+local b = rng:random(10) --> [0..10]
+local c = rng:random(5, 20) --> [5..20]
+
+-- Sets the generator state to generate a reproducible sequence of random numbers
+rng:seed(42)
+```
diff --git a/doc/ru/scripting.md b/doc/ru/scripting.md
index 40cac325..d8f1b3be 100644
--- a/doc/ru/scripting.md
+++ b/doc/ru/scripting.md
@@ -35,6 +35,7 @@
     - [pathfinding](scripting/builtins/libpathfinding.md)
     - [player](scripting/builtins/libplayer.md)
     - [quat](scripting/builtins/libquat.md)
+    - [random](scripting/builtins/librandom.md)
     - [rules](scripting/builtins/librules.md)
     - [time](scripting/builtins/libtime.md)
     - [utf8](scripting/builtins/libutf8.md)
diff --git a/doc/ru/scripting/builtins/librandom.md b/doc/ru/scripting/builtins/librandom.md
new file mode 100644
index 00000000..8aa58592
--- /dev/null
+++ b/doc/ru/scripting/builtins/librandom.md
@@ -0,0 +1,38 @@
+# Библиотека *random*
+
+Библиотека функций для генерации случайный чисел.
+
+## Недетерминированные числа
+
+```lua
+-- Генерирует случайное число в диапазоне [0..1)
+random.random() --> number
+
+-- Генерирует случайное целое число в диапазоне [0..n]
+random.random(n) --> number
+
+-- Генерирует случайное целое число в диапазоне [a..b]
+random.random(a, b) --> number
+
+-- Генерирует случайный массив байт длиной n
+random.bytes(n: number) -> Bytearray
+
+-- Генерирует UUID версии 4
+random.uuid() -> str
+```
+
+## Псевдослучайные числа
+
+Библиотека предоставляет класс Random - генератор с собственным изолированным состоянием.
+
+```lua
+local rng = random.Random()
+
+-- Используется аналогично math.random
+local a = rng:random() --> [0..1)
+local b = rng:random(10) --> [0..10]
+local c = rng:random(5, 20) --> [5..20]
+
+-- Устанавливает состояние генератора для генерации воспроизводимой последовательности случайных чисел
+rng:seed(42)
+```