Memory Interaction¶

Warning

Please note that memory interaction is currently supported on Windows only. If you wish to contribute to adding MacOS memory interaction, feel free to open a pull request.

gd.py allows to interact with the memory of Geometry Dash.

Quick example of a program that will print a random message every time the player dies.

import random  # for fun

import gd

messages = ["Get good.", "RIP", "F", "bruh", "hm..."]  # some messages to pick from

# initialize memory object by acquiring process handle and base addresses
memory = gd.memory.get_memory()
do_print = True

while True:
    if memory.is_dead():  # if player is dead
        if do_print:
            print(f"{random.choice(messages)} ({memory.get_percent()}%)")
        do_print = False
    else:
        do_print = True

Types¶

There are several simple types gd.py support for reading/writing memory: Bool, Int32, Int64, Float32, Float64, String.

They can be accessed like so:

import gd

print(gd.memory.Int32)
# or
print(gd.memory.Type.Float64)

Enums¶

class gd.memory.Scene(value: Any, names: Union[str, Dict[str, U], List[str], Tuple[str, …]] = (), module: Optional[str] = None, qualname: Optional[str] = None, type: Optional[Type[T]] = None, start: Optional[T] = None, **members: Dict[str, U])[source]¶: An enumeration that represents ID of different scenes in the game.

Buffer¶

class gd.memory.Buffer(data: bytes, order: str = 'little')[source]¶

Type that allows to unwrap bytes that were read into different Python types.

data¶

Current data that buffer works with.

Type: bytes

order¶

Represents order that buffer should interpret bits in. Either little for little-endian or big for big-endian.

Type: str

with_order(order: str) → gd.memory.interface.Buffer[source]¶: Change order of the buffer to order and return self.

classmethod from_int(integer: int, size: int = 4, order: str = 'little', signed: bool = True) → gd.memory.interface.Buffer[source]¶: Create buffer from an integer with size and order.

as_int(signed: bool = True) → int [source]¶: Cast current bytes to an integer.

classmethod from_bool(value: bool, order: str = 'little') → gd.memory.interface.Buffer[source]¶: Create buffer from a boolean with order.

as_bool() → bool [source]¶: Cast current bytes to an integer and return bool indicating if integer is non-zero.

classmethod from_float(number: float, order: str = 'little') → gd.memory.interface.Buffer[source]¶: Create buffer from a float with order. float means 32-bit floating point number.

as_float() → float [source]¶: Cast current bytes to a 32-bit floating point number.

classmethod from_double(number: float, order: str = 'little') → gd.memory.interface.Buffer[source]¶: Create buffer from a float with order. double means 64-bit floating point number.

as_double() → float [source]¶: Cast current bytes to a 64-bit floating point number.

classmethod from_str(string: str, terminate: bool = True, order: str = 'little') → gd.memory.interface.Buffer[source]¶: Create buffer from a string with order. If terminate is True, a null byte is appended at the end.

as_str(encoding: str = 'utf-8', errors: str = 'strict') → str [source]¶: Interpret current bytes as a string with encoding, reading until null terminator.

classmethod from_format(format_str: str) → gd.memory.interface.Buffer[source]¶: Create buffer from byte-format string, like 6A 14 8B CB FF.

to_format() → str [source]¶: Convert current bytes to byte-format string, like 6A 14 8B CB FF.

classmethod from_byte_array(array: Sequence[int]) → gd.memory.interface.Buffer[source]¶: Create buffer from a sequence of 8-bit integers.

into_buffer() → Any[source]¶: Convert current bytes to ctypes string buffer in order to write process memory.

Memory API¶

class gd.memory.MemoryType[source]¶: Pure type for Memory objects to inherit from.

class gd.memory.Memory(*args, **kwargs)[source]¶: Simple wrapper with platform check.

class gd.memory.WindowsMemory(process_name: str, load: bool = False, ptr_type: gd.memory.interface.Type = Type<UInt32>(4))[source]¶

read_at(size: int = 0, address: int = 0) → gd.memory.interface.Buffer[source]¶: Read size bytes at address, returning Buffer object.

read(type: gd.memory.interface.Type, address: int = 0) → T[source]¶: Read type structure at address, returning Buffer object.

write_at(buffer: gd.memory.interface.Buffer, address: int = 0) → None [source]¶: Writter buffer at address.

write(type: gd.memory.interface.Type, value: T, address: int = 0) → None [source]¶: Write value converted to type at address.

read_bytes(size: int = 0, *offsets, module: Optional[str] = None) → gd.memory.interface.Buffer[source]¶: Read size bytes, resolving *offsets to the final address.

read_type(type: gd.memory.interface.Type, *offsets, module: Optional[str] = None) → T[source]¶: Read type, resolving *offsets to the final address.

write_bytes(buffer: gd.memory.interface.Buffer, *offsets, module: Optional[str] = None) → None [source]¶: Write buffer, resolving *offsets to the final address.

write_type(type: gd.memory.interface.Type, value: T, *offsets, module: Optional[str] = None) → None [source]¶: Write value converted to type, resolving *offsets to the final address.

read_string(*offsets) → str [source]¶: Read string resolving *offsets, handling its size and where it is allocated.

load() → None [source]¶: Load memory, fetching process process id, process handle and base address.

is_loaded() → bool [source]¶: Check if memory was previously loaded.

reload() → None [source]¶: Reload memory, fetching process process id, process handle and base address.

inject_dll(path: Union[str, pathlib.Path]) → bool [source]¶: Inject DLL from path and check if it was successfully injected.

redirect_memory(size: int, *offsets, address: int = 0) → None [source]¶: Allocate size bytes, resolve *offsets and write new address there.

get_scene_value() → int [source]¶: Get value of current scene enum, which can be converted to Scene.

scene_value¶: Get value of current scene enum, which can be converted to Scene.

get_scene() → gd.memory.enums.Scene[source]¶: Get value of current scene and convert it to Scene enum.

scene¶: Get value of current scene and convert it to Scene enum.

get_resolution_value() → int [source]¶: Get value of current resolution.

resolution_value¶: Get value of current resolution.

get_resolution() → Tuple[int, int][source]¶: Get value of current resolution and try to get (w, h) tuple, (0, 0) on fail.

resolution¶: Get value of current resolution and try to get (w, h) tuple, (0, 0) on fail.

get_level_id_fast() → int [source]¶: Quickly read level ID, which is not always accurate for example on official levels.

level_id_fast¶: Quickly read level ID, which is not always accurate for example on official levels.

is_in_editor() → bool [source]¶: Check if the user is currently in editor.

get_user_name() → str [source]¶: Get name of the user.

user_name¶: Get name of the user.

is_dead() → bool [source]¶: Check if the player is dead in the level.

get_level_length() → float [source]¶: Get length of the level in units.

level_length¶: Get length of the level in units.

get_object_count() → int [source]¶: Get level object count.

object_count¶: Get level object count.

get_percent(*, final: float = 100.0) → float [source]¶: Get current percentage in the level.

percent¶: Get current percentage in the level.

get_x_pos() → float [source]¶: Get X position of the player.

set_x_pos(pos: float) → None [source]¶: Set X position of the player.

x_pos¶: Get X position of the player.

get_y_pos() → float [source]¶: Get Y position of the player.

set_y_pos(pos: float) → None [source]¶: Set Y position of the player.

y_pos¶: Get Y position of the player.

get_speed_value() → float [source]¶: Get value of the speed enum, which can be converted to gd.api.SpeedConstant.

set_speed_value(value: float) → None [source]¶: Set value of the speed.

speed_value¶: Get value of the speed enum, which can be converted to gd.api.SpeedConstant.

get_speed() → gd.api.enums.SpeedConstant[source]¶: Get value of the speed and convert it to gd.api.SpeedConstant.

set_speed(speed: Union[float, str, gd.api.enums.SpeedConstant], reverse: bool = False) → None [source]¶: Set value of speed to speed. If reverse, negate given speed value.

speed¶: Get value of the speed and convert it to gd.api.SpeedConstant.

get_size() → float [source]¶: Get hitbox size of the player icon.

set_size(size: float) → None [source]¶: Set hitbox size of the player icon.

size¶: Get hitbox size of the player icon.

is_practice_mode() → bool [source]¶: Check whether player is in Practice Mode.

get_gravity() → float [source]¶: Get value of gravity in the level. Affects cube only.

set_gravity(gravity: float) → None [source]¶: Set value of gravity in the level. Affects cube only.

gravity¶: Get value of gravity in the level. Affects cube only.

get_level_id() → int [source]¶: Get accurate ID of the level.

level_id¶: Get accurate ID of the level.

get_level_name() → str [source]¶: Get name of the level.

level_name¶: Get name of the level.

get_level_creator() → str [source]¶: Get creator name of the level.

level_creator¶: Get creator name of the level.

get_editor_level_name() → str [source]¶: Get level name while in editor.

editor_level_name¶: Get level name while in editor.

get_level_stars() → int [source]¶: Get amount of stars of the level.

level_stars¶: Get amount of stars of the level.

get_level_score() → int [source]¶: Get featured score of the level.

level_score¶: Get featured score of the level.

is_level_featured() → bool [source]¶: Check whether the level is featured.

is_level_epic() → bool [source]¶: Check whether the level is epic.

is_level_demon() → bool [source]¶: Fetch whether the level is demon.

is_level_auto() → bool [source]¶: Fetch whether the level is auto.

get_level_difficulty_value() → int [source]¶: Get difficulty value of the level, e.g. 0, 10, etc.

level_difficulty_value¶: Get difficulty value of the level, e.g. 0, 10, etc.

get_level_demon_difficulty_value() → int [source]¶: Get demon difficulty value of the level, e.g. 0, 3, etc.

level_demon_difficulty_value¶: Get demon difficulty value of the level, e.g. 0, 3, etc.

get_level_difficulty() → Union[gd.utils.enums.LevelDifficulty, gd.utils.enums.DemonDifficulty][source]¶: Compute actual level difficulty and return the enum.

level_difficulty¶: Compute actual level difficulty and return the enum.

get_attempts() → int [source]¶: Get amount of total attempts spent on the level.

attempts¶: Get amount of total attempts spent on the level.

get_jumps() → int [source]¶: Get amount of total jumps spent on the level.

jumps¶: Get amount of total jumps spent on the level.

get_normal_percent() → int [source]¶: Get best record in normal mode.

normal_percent¶: Get best record in normal mode.

get_practice_percent() → int [source]¶: Get best record in practice mode.

practice_percent¶: Get best record in practice mode.

get_level_type_value() → int [source]¶: Get value of the level type, which can be converted to LevelType.

level_type_value¶: Get value of the level type, which can be converted to LevelType.

get_level_type() → gd.api.enums.LevelType[source]¶: Get value of the level type, and convert it to LevelType.

level_type¶: Get value of the level type, and convert it to LevelType.

is_in_level() → bool [source]¶: Check whether the user is currently playing a level.

get_song_id() → int [source]¶: Get ID of the song that is used.

song_id¶: Get ID of the song that is used.

get_attempt() → int [source]¶: Get current attempt number.

set_attempt(attempt: int) → None [source]¶: Set current attempt to attempt.

attempt¶: Get current attempt number.

player_freeze() → None [source]¶: Freeze the player.

player_unfreeze() → None [source]¶: Unfreeze the player.

player_lock_jump_rotation() → None [source]¶: Lock rotation of the cube on jump.

player_unlock_jump_rotation() → None [source]¶: Unlock rotation of the cube on jump.

player_kill_enable() → None [source]¶: Enable player kill loop.

player_kill_disable() → None [source]¶: Disable player kill loop.

player_kill() → None [source]¶: Enable player kill loop and disable it after 0.05 seconds.

enable_level_edit() → None [source]¶: Enable hack: Level Edit.

disable_level_edit() → None [source]¶: Disable hack: Level Edit.

enable_accurate_percent() → None [source]¶: Enable hack: Accurate Percentage.

disable_accurate_percent() → None [source]¶: Disable hack: Accurate Percentage.

enable_level_copy() → None [source]¶: Enable hack: Level Copy.

disable_level_copy() → None [source]¶: Disable hack: Level Copy.

enable_practice_song() → None [source]¶: Enable hack: Practice Song Bypass.

disable_practice_song() → None [source]¶: Disable hack: Practice Song Bypass.

enable_noclip() → None [source]¶: Enable hack: NoClip (safe).

disable_noclip() → None [source]¶: Disable hack: NoClip.

enable_inf_jump() → None [source]¶: Enable hack: Infinite Jump.

disable_inf_jump() → None [source]¶: Disable hack: Infinite Jump.

disable_custom_object_limit() → None [source]¶: Enable hack: Custom Object Limit Bypass.

enable_custom_object_limit() → None [source]¶: Disable hack: Custom Object Limit Bypass.

disable_object_limit() → None [source]¶: Enable hack: Object Limit Bypass.

enable_object_limit() → None [source]¶: Disable hack: Object Limit Bypass.

disable_anticheat() → None [source]¶: Disable all AntiCheats.

enable_anticheat() → None [source]¶: Enable all AntiCheats.

class gd.memory.MacOSMemory[source]¶

gd.memory.get_memory(name: Optional[str] = 'GeometryDash', load: bool = True) → gd.memory.interface.MemoryType[source]¶: Create Memory object with name, optionally loading it if load is True.