Getting Started

Supported Target

• Windows x64

Required Artifacts

• grimoire_pcg.dll runtime binary
• grimoire_pcg.lib import library for linker input
• C headers under grimoire-pcg/
• NASM import declarations in grimoire_pcg.inc (if consuming from asm)

Export Package Layout

Expected package layout:

• grimoire_pcg/bin/grimoire_pcg.dll
• grimoire_pcg/bin/grimoire_pcg.lib
• grimoire_pcg/inc/grimoire_pcg.inc
• grimoire_pcg/include/grimoire-pcg/common.h
• grimoire_pcg/include/grimoire-pcg/random.h
• grimoire_pcg/include/grimoire-pcg/noise.h

C/C++ Integration

1. Add grimoire_pcg/include to include paths.
2. Link grimoire_pcg/bin/grimoire_pcg.lib.
3. Ensure grimoire_pcg.dll is in your runtime search path.
4. Include headers with <grimoire-pcg/...>.

Minimal C Example

#include <stdint.h>
#include <grimoire-pcg/random.h>

int main(void)
{
    GrimoireRandom rng = GrimoireRandom_CreateSeed(1337);
    if (!rng) {
        return 1;
    }

    int32_t roll = GrimoireRandom_NextRange(rng, 1, 7);
    (void)roll;

    GrimoireRandom_Destroy(rng);
    return 0;
}

Minimal Noise Example

#include <grimoire-pcg/noise.h>

float sample(float x, float y)
{
    return Grimoire_Perlin2D(x, y, 0.0f, 2026);
}

NASM Integration

1. Add grimoire_pcg/inc to your NASM include paths.
2. Link against grimoire_pcg/bin/grimoire_pcg.lib.
3. Keep grimoire_pcg.dll available at runtime.
4. Include grimoire_pcg.inc in modules that call Grimoire exports.

Minimal NASM Example

bits 64

%include "grimoire_pcg.inc"

section .data
    seed    dd 1337

section .text
global example_entry

example_entry:
    sub rsp, 40

    mov ecx, [rel seed]
    call GrimoireRandom_CreateSeed

    test rax, rax
    jz .done

    mov rbx, rax

    mov rcx, rax
    mov edx, 1
    mov r8d, 6
    call GrimoireRandom_NextRange

    mov rcx, rbx
    call GrimoireRandom_Destroy

.done:
    add rsp, 40
    ret

Build-Side Macros

• Define _GRIMOIRE_BUILD only when building the DLL itself.
• Do not define _GRIMOIRE_BUILD in consumer projects.
• Define GRIMOIRE_STATIC only when building/consuming as static linkage.

Determinism Checklist

1. Use explicit seeds with GrimoireRandom_CreateSeed.
2. Keep call order stable between runs.
3. Use the same function family (ValueSmooth vs Perlin, etc.).
4. Persist and restore RNG state when exact continuation is required.

Troubleshooting

Linker cannot resolve symbols

• Verify you linked the import library for the same build.
• Confirm target architecture is x64.
• For NASM projects, confirm the .obj output is linked with grimoire_pcg.lib.

Runtime DLL not found

• Put the DLL next to the executable or on an expected DLL search path.

NASM include cannot be resolved

• Verify the assembler include path contains grimoire_pcg/inc.
• Confirm the source uses %include "grimoire_pcg.inc".

Non-reproducible outputs

• Ensure fixed seed usage.
• Ensure identical function call order.
• Avoid replacing deterministic create calls with non-deterministic create calls.

Security Reminder

GrimoireRandom is not cryptographically secure. Do not use it for cryptographic keys, secure tokens, or security boundaries.