跳转至

GFSeedUtility

API Reference / Standard / 类索引

  • 路径：addons/gf/standard/utilities/random/gf_seed_utility.gd
  • 模块：Standard
  • 继承：GFUtility
  • API：public
  • 类别：运行时服务 (runtime_service)
  • 首次版本：3.17.0

全局随机数种子管理器。 内部维护一个主 RandomNumberGenerator，并支持基于字符串标签派生 出独立的子 RNG。子 RNG 的生成不推进主随机序列，可用于保证 回放系统的确定性。

成员概览

类型 名称 签名
方法 init func init() -> void:
方法 set_global_seed func set_global_seed(seed_hash: int) -> void:
方法 get_global_seed func get_global_seed() -> int:
方法 get_rng func get_rng() -> RandomNumberGenerator:
方法 get_state func get_state() -> int:
方法 set_state func set_state(state: int) -> void:
方法 get_full_state func get_full_state() -> Dictionary:
方法 set_full_state func set_full_state(state: Dictionary) -> void:
方法 get_branched_rng func get_branched_rng(string_seed: String) -> RandomNumberGenerator:

方法

init

  • API：public
func init() -> void:

第一阶段初始化：创建主 RNG 实例。

set_global_seed

  • API：public
func set_global_seed(seed_hash: int) -> void:

设置全局主种子，并同步应用到主 RNG。

参数：

名称 说明
seed_hash 用于驱动主随机数序列的整数种子。

get_global_seed

  • API：public
func get_global_seed() -> int:

获取当前全局主种子。

返回：当前全局主种子。

get_rng

  • API：public
func get_rng() -> RandomNumberGenerator:

获取主随机数生成器。 调用方可以直接使用该实例生成随机数；生成行为会推进主 RNG 状态。

返回：主随机数生成器实例。

get_state

  • API：public
func get_state() -> int:

获取当前主 RNG 的内部精确状态。

返回：当前的内部状态值。

set_state

  • API：public
func set_state(state: int) -> void:

恢复主 RNG 的内部精确状态。

参数：

名称 说明
state 要恢复的内部状态值。

get_full_state

  • API：public
func get_full_state() -> Dictionary:

获取包含主种子、主 RNG 状态与分支计数的完整随机状态。 返回的 64 位整数状态会以十进制字符串保存，确保默认 JSON 存储可精确往返。

返回：JSON 安全的完整随机状态。

结构：

  • return: Dictionary with state_schema_version: int, global_seed: String, rng_state: String, and branch_counters: Dictionary[String, String].

set_full_state

  • API：public
func set_full_state(state: Dictionary) -> void:

恢复完整随机状态。

参数：

名称 说明
state get_full_state() 产生的字典。

结构：

  • state: Dictionary produced by get_full_state().

get_branched_rng

  • API：public
func get_branched_rng(string_seed: String) -> RandomNumberGenerator:

基于主 RNG 当前状态与字符串标签，派生出一个独立的子 RNG。 每次调用只推进当前标签的分支计数，不推进主 RNG 的随机序列。 同一主状态、同一标签和同一调用序号会产生确定的子随机序列。

参数：

名称 说明
string_seed 用于标识子随机流用途的字符串（如 "loot_table"、"enemy_ai"）。

返回：一个已完成种子初始化的独立 RandomNumberGenerator 实例。