module Lapis::Docs::E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::A_OBJECTDB_AND_MONOTONIC_IDS

Overview

Godot ObjectDB & Monotonic Instance IDs

Technical analysis of Godot's ObjectDB internal architecture, monotonic 64-bit instance IDs, and how Lapis prevents heap address aliasing across recycled C++ allocations.

Executive Summary & Key Topics

Topic Method / Anchor Description
ObjectDB Invariants .topic_00_core_concepts Monotonic 64-bit IDs, instance lookup, and pointer validity.
The Recycled Pointer Hazard .topic_01_pointer_aliasing_hazard Why storing raw C++ pointers causes silent memory corruption.

Related Guides & Source References

Defined in:

libgodot/docs/e_memory_safety_and_engine_internals/a_objectdb_and_monotonic_ids.cr

Class Method Summary

Class Method Detail

def self.topic_00_core_concepts : Nil #

ObjectDB Invariants: Monotonic 64-bit IDs, instance lookup, and pointer validity.

Key Topics & Information

  • Every Godot Object is assigned a strictly increasing 64-bit integer ID
  • Instance IDs never collide across deleted and newly allocated objects
  • Native address validation via gd_util_is_instance_id_valid

def self.topic_01_pointer_aliasing_hazard : Nil #

The Recycled Pointer Hazard: Why storing raw C++ pointers causes silent memory corruption.

In native C and C++, the operating system allocator frequently reuses freed memory addresses:

  1. Node A is allocated at pointer address 0x1000.
  2. Node A is freed (queue_free).
  3. A new Node B is allocated and assigned the recycled address 0x1000.
  4. If a Crystal wrapper only tracks 0x1000, calling a method on A inadvertently mutates B!

Lapis Solution:

Every Godot::Object stores its monotonic @instance_id (e.g. 9223372041468510447). When A is freed, its instance ID is permanently retired by Godot. Querying ObjectDB.get_instance(@instance_id) safely returns null!