From 95f1a304c981aa642b88a76077a245db1d6e9927 Mon Sep 17 00:00:00 2001 From: DBotThePony Date: Wed, 5 Mar 2025 09:41:53 +0700 Subject: [PATCH] Provide docs for random number generators --- .../ru/dbotthepony/mc/otm/core/util/CMWCRandom.kt | 3 +++ .../ru/dbotthepony/mc/otm/core/util/LCG64Random.kt | 14 +++++++++++--- .../mc/otm/core/util/Xoshiro256SSRandom.kt | 3 +++ 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/CMWCRandom.kt b/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/CMWCRandom.kt index 767637340..16d885b7e 100644 --- a/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/CMWCRandom.kt +++ b/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/CMWCRandom.kt @@ -8,6 +8,9 @@ import net.minecraft.world.level.levelgen.RandomSupport import java.lang.StringBuilder import java.util.random.RandomGenerator +/** + * Random number generator with insane period of at least 2^511 + */ class CMWCRandom(seed: Long = RandomSupport.generateUniqueSeed()) : RandomGenerator, RandomSource { private val state = IntArray(CMWC_STATE_SIZE) private var carry = 0 diff --git a/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/LCG64Random.kt b/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/LCG64Random.kt index 7cac69c0d..d6edf5afc 100644 --- a/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/LCG64Random.kt +++ b/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/LCG64Random.kt @@ -2,15 +2,23 @@ package ru.dbotthepony.mc.otm.core.util import net.minecraft.util.Mth import net.minecraft.util.RandomSource +import net.minecraft.world.level.levelgen.LegacyRandomSource import net.minecraft.world.level.levelgen.MarsagliaPolarGaussian import net.minecraft.world.level.levelgen.PositionalRandomFactory import net.minecraft.world.level.levelgen.RandomSupport import java.lang.StringBuilder import java.util.random.RandomGenerator -// different from LegacyRandomSource minecraft uses in meaning that this class use different constants -// and always use upper 32 bits instead of implementing BitRandomSource -// AND it uses all bits from provided seed +/** + * Simple and insanely fast random number generator, which can be used for seeding (initializing internal state) of other number generators. + * + * While can be used on its own, it probably shouldn't. + * + * Differs from [LegacyRandomSource] (also LCG, created by [RandomSource.create]) Minecraft uses in: + * * Different constants (with supposedly/expected better statistical properties) + * * Always use upper 32 bits instead of implementing BitRandomSource and sampling some upper bits + * * Uses all bits from provided seed + */ class LCG64Random(private var seed: Long = RandomSupport.generateUniqueSeed()) : RandomGenerator, RandomSource { private val gaussian = MarsagliaPolarGaussian(this) diff --git a/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/Xoshiro256SSRandom.kt b/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/Xoshiro256SSRandom.kt index 492db9761..99438ed72 100644 --- a/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/Xoshiro256SSRandom.kt +++ b/src/main/kotlin/ru/dbotthepony/mc/otm/core/util/Xoshiro256SSRandom.kt @@ -9,6 +9,9 @@ import net.minecraft.world.level.levelgen.RandomSupport import java.lang.StringBuilder import java.util.random.RandomGenerator +/** + * Excellent number generator with guaranteed period of 2^255 + */ class Xoshiro256SSRandom private constructor( private var s0: Long, private var s1: Long,