最后同步日期：2026-04-15 | Godot 官方原文 — randi

randi

定义

randi() 用于生成一个随机的整数，范围是 0 到 4294967295（即 0 到 2^32 - 1，约 42 亿）。

想象你有一个超级大的骰子，上面有 42 亿个面，每个面写着不同的数字。你掷一次骰子，得到的数字就是 randi() 的结果。由于数字范围太大，实际使用时通常会配合取余运算（%）来缩小到你需要的范围。

函数签名

C#

// C# 中使用 GD.Randi
uint value = GD.Randi();

GDScript

func randi() -> int

参数说明

无参数。调用时不需要传入任何值。

返回值

int（GDScript）/ uint（C#）—— 一个随机的非负整数，范围 0 到 4294967295（即 0 到 2^32 - 1）。

代码示例

基础用法：生成随机整数

C#

using Godot;

public partial class RandiExample : Node
{
    public override void _Ready()
    {
        // 生成一个随机整数（0 到约 42 亿）
        uint value = GD.Randi();
        GD.Print($"随机整数: {value}");
        // 运行结果: 随机整数: 2847193652

        // 用取余限制范围：0 到 9
        uint zeroToNine = GD.Randi() % 10;
        GD.Print($"0~9: {zeroToNine}");
        // 运行结果: 0~9: 3

        // 用取余限制范围：1 到 6（模拟骰子）
        uint dice = (GD.Randi() % 6) + 1;
        GD.Print($"骰子: {dice}");
        // 运行结果: 骰子: 5
    }
}

GDScript

extends Node

func _ready():
    # 生成一个随机整数（0 到约 42 亿）
    var value = randi()
    print("随机整数: ", value)
    # 运行结果: 随机整数: 2847193652

    # 用取余限制范围：0 到 9
    var zero_to_nine = randi() % 10
    print("0~9: ", zero_to_nine)
    # 运行结果: 0~9: 3

    # 用取余限制范围：1 到 6（模拟骰子）
    var dice = (randi() % 6) + 1
    print("骰子: ", dice)
    # 运行结果: 骰子: 5

实际场景：随机选择和抽签

C#

using Godot;
using System.Collections.Generic;

public partial class CardDeck : Node
{
    private readonly List<string> _cards = new()
    {
        "黑桃A", "黑桃K", "黑桃Q", "黑桃J",
        "红心A", "红心K", "红心Q", "红心J",
        "梅花A", "梅花K", "梅花Q", "梅花J",
        "方块A", "方块K", "方块Q", "方块J"
    };

    public string DrawRandom()
    {
        int index = (int)(GD.Randi() % (uint)_cards.Count);
        return _cards[index];
    }

    public override void _Ready()
    {
        GD.Print($"抽到: {DrawRandom()}");
        GD.Print($"抽到: {DrawRandom()}");
        GD.Print($"抽到: {DrawRandom()}");
        // 运行结果（每次不同）:
        // 抽到: 红心K
        // 抽到: 梅花A
        // 抽到: 黑桃Q
    }
}

GDScript

extends Node

var _cards: Array = [
    "黑桃A", "黑桃K", "黑桃Q", "黑桃J",
    "红心A", "红心K", "红心Q", "红心J",
    "梅花A", "梅花K", "梅花Q", "梅花J",
    "方块A", "方块K", "方块Q", "方块J"
]

func draw_random() -> String:
    var index = randi() % _cards.size()
    return _cards[index]

func _ready():
    print("抽到: ", draw_random())
    print("抽到: ", draw_random())
    print("抽到: ", draw_random())
    # 运行结果（每次不同）:
    # 抽到: 红心K
    # 抽到: 梅花A
    # 抽到: 黑桃Q

进阶用法：随机方向和颜色生成

C#

using Godot;

public partial class RandomGenerator : Node
{
    public override void _Ready()
    {
        // 随机选一个方向（上下左右）
        string[] directions = { "上", "下", "左", "右" };
        int dirIndex = (int)(GD.Randi() % 4);
        GD.Print($"随机方向: {directions[dirIndex]}");

        // 随机生成颜色
        float r = (float)(GD.Randi() % 256) / 255f;
        float g = (float)(GD.Randi() % 256) / 255f;
        float b = (float)(GD.Randi() % 256) / 255f;
        var color = new Color(r, g, b);
        GD.Print($"随机颜色: RGB({(int)(r * 255)}, {(int)(g * 255)}, {(int)(b * 255)})");

        // 随机布尔值（50% 概率）
        bool coinFlip = GD.Randi() % 2 == 0;
        GD.Print($"掷硬币: {(coinFlip ? "正面" : "反面")}");
    }
}

GDScript

extends Node

func _ready():
    # 随机选一个方向（上下左右）
    var directions = ["上", "下", "左", "右"]
    var dir_index = randi() % directions.size()
    print("随机方向: ", directions[dir_index])

    # 随机生成颜色
    var r = float(randi() % 256) / 255.0
    var g = float(randi() % 256) / 255.0
    var b = float(randi() % 256) / 255.0
    var color = Color(r, g, b)
    print("随机颜色: RGB(%d, %d, %d)" % [int(r * 255), int(g * 255), int(b * 255)])

    # 随机布尔值（50% 概率）
    var coin_flip = randi() % 2 == 0
    print("掷硬币: ", "正面" if coin_flip else "反面")

注意事项

1. 推荐使用 randi_range() 代替取余：虽然 randi() % n 可以把范围缩小到 0 到 n-1，但推荐使用 randi_range(0, n - 1) 来获得更均匀的分布。randi_range() 内部使用了更好的算法来避免取余带来的分布偏差。

2. 范围非常大：randi() 返回 0 到约 42 亿的整数。在大多数情况下，你需要配合取余或 randi_range() 来获得更实用的范围。

3. C# 返回 uint：C# 中 GD.Randi() 返回 uint 类型，如果需要 int 类型，需要显式转换：(int)GD.Randi()。