Extending Genesis World#

A package built on top of Genesis World often has resources of its own to set up and tear down: GPU buffers, a renderer, a background service. Tie that lifecycle to Genesis itself. Register a pair of callbacks and Genesis runs your setup on gs.init() and your teardown on gs.destroy(), so your extension comes up and goes down in lockstep with the engine.

Registering a module#

gs.register_external_module(init_fun, destroy_fun) takes two no-argument callables:

import genesis as gs

def my_init():
    # allocate resources that depend on the active backend and device
    ...

def my_destroy():
    # release them
    ...

gs.register_external_module(my_init, my_destroy)

gs.init(backend=gs.gpu)  # my_init() runs here, after core initialization
# ... use Genesis and your extension ...
gs.destroy()             # my_destroy() runs here
  • init_fun runs once, immediately after Genesis finishes initializing. If Genesis is already initialized when you register, init_fun runs right away instead.

  • destroy_fun runs when gs.destroy() is called. Genesis also registers destroy() with atexit, so teardown happens on normal interpreter exit even if you do not call it yourself.

Register before gs.init() when you can, so setup happens as part of a single, ordered initialization.

Unregistering#

gs.unregister_external_module(init_fun, destroy_fun) removes the pair. The registry keys on the exact function objects you passed, so unregister with the same two callables you registered:

gs.unregister_external_module(my_init, my_destroy)

Note

Because the two callables identify the registration, pass named functions (or hold onto the references) rather than throwaway lambdas, otherwise you cannot unregister them later.

Writing a custom recorder#

The built-in file writers and plotters cover most needs; to capture data any other way, subclass genesis.recorders.Recorder and pass your options to scene.add_recorder. The scene drives a recorder through five methods, so you implement them and never call them yourself:

  1. __init__ configures the recorder from its options.

  2. build() initializes resources (called during scene.build()).

  3. process(data, cur_time) handles each sampled value during recording.

  4. cleanup() finalizes and releases resources (called when recording stops).

  5. reset(envs_idx=None) resets state for a new episode.

import genesis as gs
from genesis.recorders import Recorder

class MyRecorder(Recorder):
    def __init__(self, manager, options, data_func):
        super().__init__(manager, options, data_func)
        self.data_buffer = []

    def build(self):
        super().build()
        self.data_buffer = []

    def process(self, data, cur_time):
        self.data_buffer.append({"time": cur_time, "data": data})

    def cleanup(self):
        print(f"Recorded {len(self.data_buffer)} samples")
        self.data_buffer = []

    def reset(self, envs_idx=None):
        self.data_buffer = []

For the recording workflow and the built-in recorders, see Recording data.

See also#