Skip to content

Observations

Choose an observation mode with the observation argument to make_env():

from mudgym import make_env

env = make_env(observation="parsed")
observation, info = env.reset()
env.close()

Every built-in observation mode includes text and points, the persona's current score.

text

Contains the common text and points observations only.

from mudgym import make_env

env = make_env(observation="text")
observation, info = env.reset()
env.close()

print(observation["text"])

Road opposite cottage.
You are standing on a badly paved road with a cemetery to the north and the home of a grave-digger to the south. An inscription on the cemetery gates reads, "RESTING PLACE OF LOST SOULS".

parsed

Adds keyed data parsed from game output.

Key Value
room_name dally lane
room_name_index 121
here David the protector, road
features road
mobiles empty
players empty
points 200
vitals [52, 52, 65, 65, 63, 63, 0, 52]
flags [0, 0, 0, 0]
reset_minutes 105
weather fair
weather_index 1
available_exits [1, 1, 1, 1, 0, 0, 1, 0, 1, 0, 0, 1, 0, 1]
available_exit_names north, east, south, west, southwest, up, out, swampward
portables empty
inventory empty
Dally Lane. You are standing on a dusty road with rising ground both to the north and south. Though dilapidated and disused, the route north of where you stand, with a building at the far end, looks as if it once formed a grand driveway. To the south, the road twists up the hill where, at the summit, an ancient walled monastery dominates the scene. Open fields lie to the west, and east is a flat area of lawn.

available_exit_names is the available subset of DIRECTIONS, in the same game-native order as the set bits in available_exits. over and swampward are MudGym's public names for the game's internal jump and swamp directions.

vitals is [stamina, max_stamina, effective_strength, strength, effective_dexterity, dexterity, magic, max_magic]; flags is [blind, deaf, crippled, dumb].

cheats

Adds hidden state output from the mgcheats command, some of which wouldn't typically be known to a player. Most notably room_id.

Key Value
points 200
vitals [69, 69, 51, 51, 60, 60, 0, 69]
flags [0, 0, 0, 0]
reset_minutes 105
weather fair
weather_index 1
available_exits [1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 0, 1]
available_exit_names north, east, south, west, northeast, southeast, southwest, northwest, out, swampward
room_id mtrack2
room_id_index 696
room_name beaten track
room_name_index 37
fighting 0
dark 0
glowing 0
asleep 0
gifted 0
here road
portables empty
inventory empty
Beaten track. You're on a rough east-west track with a dense forest to the north and pasture to the south.

bytes

Adds raw_bytes, a fixed-size uint8 NumPy array zero-padded to 16,384 bytes by default. The unpadded bytes value is available as info["raw_bytes"].

raw = observation["raw_bytes"][: len(info["raw_bytes"])].tobytes()

Shown as a bytes literal here for readability:

b'fes,move north\r\n\x1b[32mRoad opposite cottage\x1b[37m.\r\n\x1b[0;32;40mYou are standing on a badly paved road with a cemetery to the north and the home of a grave-digger to the south. An inscription on the cemetery gates reads, "RESTING PLACE OF LOST SOULS". \x1b[1;37;40m\r\n\x1b[0;34;40m\x1b[1;34;40m*\x1b[0;34;40m\x1b[1;37;40mfes\r\n\x1b[0;37;40m\x1b[1;'
...
Road opposite cottage. You are standing on a badly paved road with a cemetery to the north and the home of a grave-digger to the south. An inscription on the cemetery gates reads, "RESTING PLACE OF LOST SOULS".

Creating your own keys

Custom observations are defined by selecting fields and the keys each field contributes:

from mudgym import make_env
from mudgym.envs.fields import FEScoreField, SuperQuickLookField

env = make_env(
    field_parsers=(
        SuperQuickLookField(include_keys=("room_name", "here")),
        FEScoreField(include_keys=("points",)),
    )
)
env.close()

You can add your own field parsers in the same way by creating an ObservationField subclass. Take a look at the fields in mudgym/envs/fields/ to use as a reference.

Observation commands

Observation fields can declare commands for output to consume. MudGym sends those commands on a separate line after the player's action, and the final one also acts as an end of step marker, so we know when the response is complete.