Skip to content

Utilities API

Helper functions and utilities for EldenGym.

Configuration Parsing

parse_config_file 

parse_config_file(config_filepath)

Parse a TOML config file and extract process configuration and attributes.

This function mirrors the ParseConfigFile function from the C++ client, reading process information and memory attributes from a TOML configuration file.

Parameters:

Name Type Description Default
config_filepath

str or Path, path to the TOML configuration file

 required

Returns:

Name Type Description
tuple

(process_name, process_window_name, attributes) - process_name: str, name of the process (e.g., "eldenring.exe") - process_window_name: str, window name of the process (e.g., "ELDEN RING") - attributes: list of dicts, each containing: - name: str, attribute name - pattern: str, memory pattern to search for - offsets: list of int, memory offsets - type: str, data type (e.g., "int", "float", "array") - length: int, length for array types (default: 0) - method: str, method for reading (default: "")

Raises:

Type Description
FileNotFoundError

If the config file doesn't exist
ValueError

If the config file is malformed or missing required fields
Example

process_name, window_name, attrs = parse_config_file("config.toml") print(f"Process: {process_name}, Window: {window_name}") print(f"Attributes: {len(attrs)}")

Source code in eldengym/utils.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def parse_config_file(config_filepath):
    """
    Parse a TOML config file and extract process configuration and attributes.

    This function mirrors the ParseConfigFile function from the C++ client,
    reading process information and memory attributes from a TOML configuration file.

    Args:
        config_filepath: str or Path, path to the TOML configuration file

    Returns:
        tuple: (process_name, process_window_name, attributes)
            - process_name: str, name of the process (e.g., "eldenring.exe")
            - process_window_name: str, window name of the process (e.g., "ELDEN RING")
            - attributes: list of dicts, each containing:
                - name: str, attribute name
                - pattern: str, memory pattern to search for
                - offsets: list of int, memory offsets
                - type: str, data type (e.g., "int", "float", "array")
                - length: int, length for array types (default: 0)
                - method: str, method for reading (default: "")

    Raises:
        FileNotFoundError: If the config file doesn't exist
        ValueError: If the config file is malformed or missing required fields

    Example:
        >>> process_name, window_name, attrs = parse_config_file("config.toml")
        >>> print(f"Process: {process_name}, Window: {window_name}")
        >>> print(f"Attributes: {len(attrs)}")
    """
    config_path = Path(config_filepath)

    if not config_path.exists():
        raise FileNotFoundError(f"Config file not found: {config_filepath}")

    # Read and parse TOML file
    with open(config_path, "rb") as f:
        config = tomllib.load(f)

    # Extract process info
    if "process_info" not in config:
        raise ValueError("Missing [process_info] section in config file")

    process_info = config["process_info"]
    process_name = process_info.get("name", "")
    process_window_name = process_info.get("window_name", "")

    if not process_name:
        raise ValueError("Missing 'name' field in [process_info] section")

    # Extract attributes
    if "attributes" not in config:
        raise ValueError("Missing [attributes] section in config file")

    attributes = []
    attributes_section = config["attributes"]

    for attr_name, attr_data in attributes_section.items():
        if not isinstance(attr_data, dict):
            continue

        attribute = {
            "name": attr_name,
            "pattern": attr_data.get("pattern", ""),
            "offsets": attr_data.get("offsets", []),
            "type": attr_data.get("type", ""),
            "length": attr_data.get("length", 0),
            "method": attr_data.get("method", ""),
        }

        attributes.append(attribute)

    return process_name, process_window_name, attributes

Example

from eldengym.utils import parse_config_file

# Parse a TOML config file
process_name, window_name, attributes = parse_config_file(
    "eldengym/files/configs/ER_1_16_1.toml"
)

print(f"Process: {process_name}")
print(f"Window: {window_name}")
print(f"Attributes: {len(attributes)}")

# Inspect an attribute
attr = attributes[0]
print(f"Name: {attr['name']}")
print(f"Type: {attr['type']}")
print(f"Pattern: {attr['pattern']}")
print(f"Offsets: {attr['offsets']}")

Config File Format

TOML configuration files define the game process and memory attributes:

[process_info]
name = "eldenring.exe"
window_name = "ELDEN RING"

[attributes.HeroHp]
pattern = "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 0F 48 39 88"
offsets = [0x10EF8, 0x0, 0x190, 0x0, 0x138]
type = "int"

[attributes.HeroMaxHp]
pattern = "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 0F 48 39 88"
offsets = [0x10EF8, 0x0, 0x190, 0x0, 0x13C]
type = "int"

[attributes.HeroPosX]
pattern = "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 0F 48 39 88"
offsets = [0x10EF8, 0x0, 0x190, 0x68]
type = "float"

[attributes.CustomArray]
pattern = "some pattern"
offsets = [0x1000, 0x20]
type = "array"
length = 16  # For array types
method = ""   # Optional method

Attribute Fields

Field Type Description
name str Attribute identifier
pattern str Memory scan pattern (AOB)
offsets list[int] Pointer chain offsets
type str Data type: "int", "float", "array"
length int Length for array types (optional)
method str Access method (optional)

Pattern Syntax

Memory patterns use IDA/x64dbg style with ?? for wildcards:

48 8B 05 ?? ?? ?? ?? 48 85 C0 74 0F
  • Fixed bytes: 48, 8B, 05
  • Wildcards: ?? (matches any byte)

Return Values

parse_config_file()

Returns: - process_name (str): Name of the target process - process_window_name (str): Window title of the process - attributes (list[dict]): List of memory attributes

Each attribute dict contains: 

{
    'name': str,
    'pattern': str,
    'offsets': list[int],
    'type': str,
    'length': int,
    'method': str,
}

Error Handling

from eldengym.utils import parse_config_file

try:
    process_name, window_name, attributes = parse_config_file("config.toml")
except FileNotFoundError:
    print("Config file not found!")
except ValueError as e:
    print(f"Invalid config format: {e}")

Possible errors: - FileNotFoundError: Config file doesn't exist - ValueError: Missing required sections or malformed TOML