Choosing math and random APIs
gdzig.math and gdzig.random expose Godot utility functions through GDExtension. Zig builtins, std.math, and std.Random run locally. Choose an API based on whether the code needs Godot behavior or local computation.
| Need | Use | Why |
|---|---|---|
| Hot local scalar math | Zig builtins or std.math |
This avoids a GDExtension utility-function call. |
| Godot semantics, Variant behavior, or GDScript/API parity | gdzig.math |
It calls the Godot math utilities. |
| Random values that use Godot’s RNG state | gdzig.random |
It uses Godot’s random utility functions and their state. |
| Random values with independent local state | std.Random |
Your Zig code owns the generator state and does not depend on Godot’s RNG state. |
gdzig.math exposes Godot’s math utility functions. A call to one of these functions crosses the GDExtension utility-function interface.
For hot scalar calculations that stay inside Zig code, prefer Zig builtins or std.math. Use gdzig.math when you need Godot’s semantics, Variant behavior, or parity with the GDScript and Godot APIs.
Random numbers
Section titled “Random numbers”gdzig.random uses Godot’s RNG state. Use it when random values must follow the state controlled through Godot’s global random functions.
Use std.Random when your Zig code should own the generator and its state. This keeps local random-number generation independent of Godot’s RNG state.
Rule of thumb
Section titled “Rule of thumb”Start with Zig builtins, std.math, and std.Random for work owned by Zig code. Choose gdzig.math or gdzig.random when the result must follow Godot behavior or Godot-owned state.
For exact functions and signatures, use the API reference.