Gymnasium wrapper for PySTK2
Project description
PySuperTuxKart gymnasium wrapper
warning: pystk2-gymnasium is in alpha stage - the environments might change abruptly!
Install
The PySuperKart2 gymnasium wrapper is a Python package, so installing is fairly easy
pip install pystk2-gymnasium
Note that during the first run, SuperTuxKart assets are downloaded in the cache directory.
Environments
Warning only one SuperTuxKart environment can be created for now. Moreover, no graphics information is available for now.
After importing pystk2_gymnasium
, the following environments are available:
supertuxkart-v0
is the main environment containing complete observations. The observation and action spaces are both dictionaries with continuous or discrete variables (see below). The exact structure can be found usingenv.observation_space
andenv.action_space
. The following options can be used to modify the environment:render_mode
can be None orhuman
track
defines the SuperTuxKart track to use (None for random). The full list can be found inSTKRaceEnv.TRACKS
after initialization withinitialize.initialize(with_graphics: bool)
has been called.num_kart
defines the number of karts on the track (3 by default)rank_start
defines the starting position (None for random, which is the default)use_ai
flag (False by default) to ignore actions (when callingstep
, and use a SuperTuxKart bot)max_paths
the maximum number of the (nearest) paths (a track is made of paths) to consider in the observation statelaps
is the number of laps (1 by default)difficulty
is the difficulty of the AI bots (lowest 0 to highest 2, default to 2)
supertuxkart-simple-v0
is a simplified environment with a fixed number of observations for paths (controlled bystate_paths
, default 5), items (state_items
, default 5), karts (state_karts
, default 5)supertuxkart-flattened-v0
has observation and action spaces simplified at the maximum (onlydiscrete
andcontinuous
keys)supertuxkart-flattened-continuous-actions-v0
removes discrete actions (default to 0) so this is steer/acceleration only in the continuous domainsupertuxkart-flattened-multidiscrete-v0
is like the previous one, but with fully multi-discrete actions.acceleration_steps
andsteer_steps
(default to 5) control the number of discrete values for acceleration and steering respectively.supertuxkart-flattened-discrete-v0
is like the previous one, but with fully discretized actions
The reward $r_t$ at time $t$ is given by
$$ r_{t} = \frac{1}{10}(d_{t} - d_{t-1}) + (1 - \frac{\mathrm{pos}_t}{K}) \times (3 + 7 f_t) - 0.1 + 10 * f_t $$
where $d_t$ is the overall track distance at time $t$, $\mathrm{pos}_t$ the position among the $K$ karts at time $t$, and $f_t$ is $1$ when the kart finishes the race.
Action and observation space
All the 3D vectors are within the kart referential (z
front, x
left, y
up):
distance_down_track
: The distance from the startenergy
: remaining collected energyfront
: front of the kart (3D vector)items_position
: position of the items (3D vectors)attachment
: the item attached to the kart (bonus box, banana, nitro/big, nitro/small, bubble gum, easter egg)attachment_time_left
: how much time the attachment will be keptitems_type
: type of the itemjumping
: is the kart jumpingkarts_position
: position of other karts, beginning with the ones in frontmax_steer_angle
the max angle of the steering (given the current speed)paths_distance
: the distance of the pathspaths_start
,paths_end
,paths_width
: 3D vector to the paths start and end, with their widths (sccalar)paths_start
: 3D vectors to the the path spowerup
shield_time
skeed_factor
velocity
: velocity vector
Example
import gymnasium as gym
import pystk2_gymnasium
# Use a a flattened version of the observation and action spaces
# In both case, this corresponds to a dictionary with two keys:
# - `continuous` is a vector corresponding to the continuous observations
# - `discrete` is a vector (of integers) corresponding to discrete observations
env = gym.make("supertuxkart-flattened-v0", render_mode="human", use_ai=False)
ix = 0
done = False
state, *_ = env.reset()
while not done:
ix += 1
action = env.action_space.sample()
state, reward, terminated, truncated, _ = env.step(action)
done = truncated or terminated
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pystk2_gymnasium-0.3.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a0ad147ab7272caddc3982e506326e741fed994c5b32b5500b5617455483df8e |
|
MD5 | 05d2109ac98c7aef7636462529827329 |
|
BLAKE2b-256 | e583619c77cbacd59f85b0a19a8bc95322b9f6b4ed15c9e0e25d99b853091c4b |