OakEmu-RL v0.1.0

Appearance

OakEmuMultiEnv ​

python
OakEmuMultiEnv(number_of_environments: int, number_of_runners: int, game_configuration: GameConfiguration, model_configuration: ModelConfiguration, training_configuration: TrainingConfiguration | None, observation_shape_order: Literal['hwf', 'fhw'], training_mode: TrainingMode = TrainingMode.TRAINING, dump_directory: str | PathLike | None = None) -> None

Manages multiple OakEmu environments running in parallel.

Initialize the OakEmuMultiEnv.

Parameters:

  • number_of_environments (int) – Total number of parallel environments.
  • number_of_runners (int) – Number of threads used to update the environments.
  • game_configuration (GameConfiguration) – The game configuration.
  • model_configuration (ModelConfiguration) – The model configuration.
  • training_configuration (TrainingConfiguration | None) – The training configuration.
  • observation_shape_order (Literal['hwf', 'fhw']) – Dimension order for observations.
  • training_mode (TrainingMode) – The training mode.
  • dump_directory (str | PathLike | None) – Optional directory for environment dumps.

Source

Properties ​

action_shape ​

python
action_shape: int

Get the action shape.

Returns:

  • int – The size of the discrete action space.

Source

action_space ​

python
action_space: Discrete

Get the action space.

Returns:

  • Discrete – The Discrete action space.

Source

number_of_environments ​

python
number_of_environments: int

Get the number of environments.

Returns:

  • int – The total number of parallel environments.

Source

number_of_runners ​

python
number_of_runners: int

Get the number of runners.

Returns:

  • int – The number of runner threads.

Source

observation_shape ​

python
observation_shape: tuple[int, int, int]

Get the observation shape.

Returns:

  • tuple[int, int, int] – The shape of the observations.

Source

observation_space ​

python
observation_space: Box

Get the observation space.

Returns:

  • Box – The Box observation space.

Source

result_queue_depth ​

python
result_queue_depth: int

Get the current number of results waiting to be dequeued.

Returns:

  • int – The current result queue depth.

Source

training_mode ​

python
training_mode: TrainingMode

Get the training mode.

Returns:

  • TrainingMode – The training mode.

Source

Methods ​

dispose ​

python
dispose() -> None

Release the underlying C# environment's native resources (it is IDisposable).

Source

run ​

python
run() -> MultiEnvRun

Returns a context manager that starts the environment and stops it when exiting the context.

Returns:

  • MultiEnvRun – A MultiEnvRun instance.

Source

start ​

python
start() -> None

Start all parallel environments.

Source

stop ​

python
stop() -> None

Stop all parallel environments.

Source

unsafe_dequeue_results ​

python
unsafe_dequeue_results(max_results: int) -> list[MultiEnvResult]

Dequeue up to max_results available results without blocking, via a single pointer-based interop call.

No pythonnet objects are marshalled per result: OakEmu writes scalars, observation pointers and any trajectory block bytes into one reused buffer and returns its address, and everything is parsed in Python with ctypes/struct/numpy. Observations and trajectories are copied out eagerly, so the returned results remain valid after the environments move on. Trajectories are returned as mrkwatkins.oakemu_rl.gymnasium.TrajectoryData.TrajectoryData, numeric StepResult.Data entries cross inline (falling back to trajectory end values for completed episodes), and failed results raise RuntimeError carrying the environment exception text.

Parameters:

  • max_results (int) – The maximum number of results to dequeue.

Returns:

  • list[MultiEnvResult] – The parsed results; empty if no results were queued.

Source

unsafe_dequeue_results_blocking ​

python
unsafe_dequeue_results_blocking(max_results: int, timeout_milliseconds: int) -> list[MultiEnvResult]

As unsafe_dequeue_results, but block until at least one result is queued, the channel completes, or timeout_milliseconds elapses, before draining ; a consumer can wait on the next result without spinning. OakEmu releases the GIL while waiting, so other Python threads run. The wait triggers on any result, so a slow replay/random environment never holds the batch up behind faster single steps. Returns an empty list when the timeout elapses with nothing queued.

Parameters:

  • max_results (int) – The maximum number of results to dequeue.
  • timeout_milliseconds (int) – The maximum time to wait for the first result before returning empty.

Returns:

  • list[MultiEnvResult] – The parsed results; empty if none arrived before the timeout.

Source

unsafe_enqueue_random ​

python
unsafe_enqueue_random(environment_id: int, *, action_indices: Sequence[int | np.integer] | bytes | bytearray | None = None, initial_state: bytes | None = None, reset_parameters: dict[str, int] | None = None) -> None

Enqueue one full random exploration episode via the pointer-based interop call.

Parameters:

  • environment_id (int) – The target environment ID.
  • action_indices (Sequence[int | integer] | bytes | bytearray | None) – Optional subset of action indices to sample from.
  • initial_state (bytes | None) – Optional serialised emulator state.
  • reset_parameters (dict[str, int] | None) – Optional reset-parameter overrides (for example {"start_cavern": 1}), applied on the fast path. Requires an OakEmu build that exposes ResetParameterNames.

Source

unsafe_enqueue_replay ​

python
unsafe_enqueue_replay(environment_id: int, *, initial_state: bytes, action_indices: Sequence[int | np.integer] | bytes | bytearray, trajectory_recording_mode: ReplayTrajectoryRecordingMode = ReplayTrajectoryRecordingMode.FULL) -> None

Enqueue one full replay execution via the pointer-based interop call.

The initial state and action indices cross to OakEmu as pointers and are copied there, avoiding per-element pythonnet marshalling.

Parameters:

  • environment_id (int) – The target environment ID.
  • initial_state (bytes) – Serialised emulator state to replay from.
  • action_indices (Sequence[int | integer] | bytes | bytearray) – Action indices to replay.
  • trajectory_recording_mode (ReplayTrajectoryRecordingMode) – Whether OakEmu should keep replay trajectory recording enabled.

Source

unsafe_enqueue_reset ​

python
unsafe_enqueue_reset(environment_id: int, initial_state: bytes | None = None, reset_parameters: dict[str, int] | None = None, initial_frames: bytes | None = None) -> None

Enqueue a reset action via the pointer-based interop call.

Parameters:

  • environment_id (int) – The target environment ID.
  • initial_state (bytes | None) – Optional serialised emulator state to reset from.
  • reset_parameters (dict[str, int] | None) – Optional reset-parameter overrides (for example {"start_cavern": 1}), applied on the fast path. Requires an OakEmu build that exposes ResetParameterNames.
  • initial_frames (bytes | None) – Optional seed for the observation frame stack, as the raw stacked-observation bytes in the configured layout. A snapshot is an emulator state, not a rendered-frame history, so without this the environment fills the stack by repeating the restored frame -- which at a midpoint restart shows the policy a world where nothing is moving. Only meaningful alongside initial_state.

Source

unsafe_enqueue_reset_all ​

python
unsafe_enqueue_reset_all() -> None

Enqueue a reset action for every environment in one pointer-based interop call.

Source

unsafe_enqueue_steps ​

python
unsafe_enqueue_steps(steps: Sequence[tuple[int, int]]) -> None

Enqueue step actions for several environments in one pointer-based interop call.

No pythonnet action objects are created or marshalled: the actions are packed into one buffer that OakEmu reads directly.

Parameters:

  • steps (Sequence[tuple[int, int]]) – (environment_id, action_index) pairs.

Source

Values ​

metadata ​

python
metadata = {'observation_shape_orders': ['hwf', 'fhw']}

Source