Package: pystk2-gymnasium
PySuperTuxKart gymnasium wrapperRead theChangelogInstallThe PySuperKart2 gymnasium wrapper is a Python package, so installing is fairly easypip install pystk2-gymnasiumNote that during the first run, SuperTuxKart assets are downloaded in the cache directory.AgentSpecEach controlled kart is parametrized bypystk2_gymnasium.AgentSpec:namedefines name of the player (displayed on top of the kart)rank_startdefines the starting position (None for random, which is the default)use_aiflag (False by default) to ignore actions (when callingstep, and use a SuperTuxKart bot)camera_modecan be set toAUTO(camera on for non STK bots),ON(camera on) orOFF(no camera).EnvironmentsWarningonly one SuperTuxKart environment can be created for now. Moreover, no graphics information
is available for now.After importingpystk2_gymnasium, the following environments are available:supertuxkart/full-v0is 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_spaceandenv.action_space. The following options can be used to modify the environment:agentis anAgentSpec (see above)render_modecan be None orhumantrackdefines the SuperTuxKart track to use (None for random). The full list can be found inSTKRaceEnv.TRACKSafter initialization withinitialize.initialize(with_graphics: bool)has been called.num_kartdefines the number of karts on the track (3 by default)max_pathsthe maximum number of the (nearest) paths (a track is made of paths) to consider in the observation statelapsis the number of laps (1 by default)difficultyis the difficulty of the AI bots (lowest 0 to highest 2, default to 2)supertuxkart/simple-v0is 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-v0has observation and action spaces simplified at the maximum (onlydiscreteandcontinuouskeys)supertuxkart/flattened_continuous_actions-v0removes discrete actions (default to 0) so this is steer/acceleration only in the continuous domainsupertuxkart/flattened_multidiscrete-v0is like the previous one, but with fully multi-discrete actions.acceleration_stepsandsteer_steps(default to 5) control the number of discrete values for acceleration and steering respectively.supertuxkart/flattened_discrete-v0is like the previous one, but with fully discretized actionsThe 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.Multi-agent environmentsupertuxkart/multi-full-v0can be used to control multiple karts. It takes anagentsparameter that is a list ofAgentSpec. Observations and actions are a dictionary of single-kart ones wherestringkeys that range from0ton-1withnthe number of karts.To use different gymnasium wrappers, one can use aMonoAgentWrapperAdapter.Action and observation spaceAll the 3D vectors are within the kart referential (zfront,xleft,yup):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_anglethe max angle of the steering (given the current speed)distance_center_path: distance to the center of the pathpaths_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 spowerupshield_timeskeed_factorvelocity: velocity vectorExampleimportgymnasiumasgymfrompystk2_gymnasiumimportAgentSpec# 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 observationsenv=gym.make("supertuxkart/flattened-v0",render_mode="human",agent=AgentSpec(use_ai=False))ix=0done=Falsestate,*_=env.reset()whilenotdone:ix+=1action=env.action_space.sample()state,reward,terminated,truncated,_=env.step(action)done=truncatedorterminated