# PySuperTuxKart gymnasium wrapper
[](https://badge.fury.io/py/pystk2-gymnasium)
Read the [Changelog](./CHANGELOG.md)
## 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.
## AgentSpec
Each controlled kart is parametrized by `pystk2_gymnasium.AgentSpec`:
- `name` defines name of the player (displayed on top of the kart)
- `rank_start` defines the starting position (None for random, which is the default)
- `use_ai` flag (False by default) to ignore actions (when calling `step`, and use a SuperTuxKart bot)
- `camera_mode` can be set to `AUTO` (camera on for non STK bots), `ON` (camera on) or `OFF` (no camera).
## 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/full-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 using `env.observation_space` and `env.action_space`. The following options can be used to modify the environment:
- `agent` is an `AgentSpec (see above)`
- `render_mode` can be None or `human`
- `track` defines the SuperTuxKart track to use (None for random). The full list can be found in `STKRaceEnv.TRACKS` after initialization with `initialize.initialize(with_graphics: bool)` has been called.
- `num_kart` defines the number of karts on the track (3 by default)
- `max_paths` the maximum number of the (nearest) paths (a track is made of paths) to consider in the observation state
- `laps` 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 by `state_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 (only `discrete` and `continuous` keys)
- `supertuxkart/flattened_continuous_actions-v0` removes discrete actions (default to 0) so this is steer/acceleration only in the continuous domain
- `supertuxkart/flattened_multidiscrete-v0` is like the previous one, but with fully multi-discrete actions. `acceleration_steps` and `steer_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.
## Multi-agent environment
`supertuxkart/multi-full-v0` can be used to control multiple karts. It takes an
`agents` parameter that is a list of `AgentSpec`. Observations and actions are a dictionary of single-kart ones where **string** keys that range from `0` to `n-1` with `n` the number of karts.
To use different gymnasium wrappers, one can use a `MonoAgentWrapperAdapter`.
## 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 start
- `energy`: remaining collected energy
- `front`: 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 kept
- `items_type`: type of the item
- `jumping`: is the kart jumping
- `karts_position`: position of other karts, beginning with the ones in front
- `max_steer_angle` the max angle of the steering (given the current speed)
- `distance_center_path`: distance to the center of the path
- `paths_distance`: the distance of the paths
- `paths_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 s
- `powerup`
- `shield_time`
- `skeed_factor`
- `velocity`: velocity vector
## Example
```py3
import gymnasium as gym
from pystk2_gymnasium import AgentSpec
# 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", agent=AgentSpec(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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/bpiwowar/pystk2-gymnasium",
"name": "pystk2-gymnasium",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Benjamin Piwowarski",
"author_email": "benjamin@piwowarski.fr",
"download_url": "https://files.pythonhosted.org/packages/c0/0d/0f019b1ccd82b0cbd3f669f4979db5d54ba3cdf6bde94a37c7015bdc3b20/pystk2_gymnasium-0.4.3.tar.gz",
"platform": null,
"description": "# PySuperTuxKart gymnasium wrapper\n\n[](https://badge.fury.io/py/pystk2-gymnasium)\n\nRead the [Changelog](./CHANGELOG.md)\n\n## Install\n\nThe PySuperKart2 gymnasium wrapper is a Python package, so installing is fairly easy\n\n`pip install pystk2-gymnasium`\n\nNote that during the first run, SuperTuxKart assets are downloaded in the cache directory.\n\n## AgentSpec\n\nEach controlled kart is parametrized by `pystk2_gymnasium.AgentSpec`:\n\n- `name` defines name of the player (displayed on top of the kart)\n- `rank_start` defines the starting position (None for random, which is the default)\n- `use_ai` flag (False by default) to ignore actions (when calling `step`, and use a SuperTuxKart bot)\n- `camera_mode` can be set to `AUTO` (camera on for non STK bots), `ON` (camera on) or `OFF` (no camera).\n\n\n## Environments\n\n\n*Warning* only one SuperTuxKart environment can be created for now. Moreover, no graphics information\nis available for now.\n\nAfter importing `pystk2_gymnasium`, the following environments are available:\n\n- `supertuxkart/full-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 using `env.observation_space` and `env.action_space`. The following options can be used to modify the environment:\n - `agent` is an `AgentSpec (see above)`\n - `render_mode` can be None or `human`\n - `track` defines the SuperTuxKart track to use (None for random). The full list can be found in `STKRaceEnv.TRACKS` after initialization with `initialize.initialize(with_graphics: bool)` has been called.\n - `num_kart` defines the number of karts on the track (3 by default)\n - `max_paths` the maximum number of the (nearest) paths (a track is made of paths) to consider in the observation state\n - `laps` is the number of laps (1 by default)\n - `difficulty` is the difficulty of the AI bots (lowest 0 to highest 2, default to 2)\n- `supertuxkart/simple-v0` is a simplified environment with a fixed number of observations for paths (controlled by `state_paths`, default 5), items (`state_items`, default 5), karts (`state_karts`, default 5)\n- `supertuxkart/flattened-v0` has observation and action spaces simplified at the maximum (only `discrete` and `continuous` keys)\n- `supertuxkart/flattened_continuous_actions-v0` removes discrete actions (default to 0) so this is steer/acceleration only in the continuous domain\n- `supertuxkart/flattened_multidiscrete-v0` is like the previous one, but with fully multi-discrete actions. `acceleration_steps` and `steer_steps` (default to 5) control the number of discrete values for acceleration and steering respectively.\n- `supertuxkart/flattened_discrete-v0` is like the previous one, but with fully discretized actions\n\nThe reward $r_t$ at time $t$ is given by\n\n$$ 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 $$\n\nwhere $d_t$ is the\noverall 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.\n\n## Multi-agent environment\n\n`supertuxkart/multi-full-v0` can be used to control multiple karts. It takes an\n`agents` parameter that is a list of `AgentSpec`. Observations and actions are a dictionary of single-kart ones where **string** keys that range from `0` to `n-1` with `n` the number of karts.\n\nTo use different gymnasium wrappers, one can use a `MonoAgentWrapperAdapter`.\n\n## Action and observation space\n\nAll the 3D vectors are within the kart referential (`z` front, `x` left, `y` up):\n\n- `distance_down_track`: The distance from the start\n- `energy`: remaining collected energy\n- `front`: front of the kart (3D vector)\n- `items_position`: position of the items (3D vectors)\n- `attachment`: the item attached to the kart (bonus box, banana, nitro/big, nitro/small, bubble gum, easter egg)\n- `attachment_time_left`: how much time the attachment will be kept\n- `items_type`: type of the item\n- `jumping`: is the kart jumping\n- `karts_position`: position of other karts, beginning with the ones in front\n- `max_steer_angle` the max angle of the steering (given the current speed)\n- `distance_center_path`: distance to the center of the path\n- `paths_distance`: the distance of the paths\n- `paths_start`, `paths_end`, `paths_width`: 3D vector to the paths start and end, with their widths (sccalar)\n- `paths_start`: 3D vectors to the the path s\n- `powerup`\n- `shield_time`\n- `skeed_factor`\n- `velocity`: velocity vector\n\n## Example\n\n```py3\nimport gymnasium as gym\nfrom pystk2_gymnasium import AgentSpec\n\n# Use a a flattened version of the observation and action spaces\n# In both case, this corresponds to a dictionary with two keys:\n# - `continuous` is a vector corresponding to the continuous observations\n# - `discrete` is a vector (of integers) corresponding to discrete observations\nenv = gym.make(\"supertuxkart/flattened-v0\", render_mode=\"human\", agent=AgentSpec(use_ai=False))\n\nix = 0\ndone = False\nstate, *_ = env.reset()\n\nwhile not done:\n ix += 1\n action = env.action_space.sample()\n state, reward, terminated, truncated, _ = env.step(action)\n done = truncated or terminated\n```\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Gymnasium wrapper for PySTK2",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/bpiwowar/pystk2-gymnasium",
"Repository": "https://github.com/bpiwowar/pystk2-gymnasium"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5371f082bdf37adf9e09f6fd3db1d268639eb5932f4c261451bee45c8ad6586b",
"md5": "4bd5af436e653567df7ab5b1c1181020",
"sha256": "08bd6be7662f0e9b545564ab0a95db7913bf9ccc46d010c39336c7929a9105de"
},
"downloads": -1,
"filename": "pystk2_gymnasium-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bd5af436e653567df7ab5b1c1181020",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 28217,
"upload_time": "2023-11-20T14:39:23",
"upload_time_iso_8601": "2023-11-20T14:39:23.610325Z",
"url": "https://files.pythonhosted.org/packages/53/71/f082bdf37adf9e09f6fd3db1d268639eb5932f4c261451bee45c8ad6586b/pystk2_gymnasium-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c00d0f019b1ccd82b0cbd3f669f4979db5d54ba3cdf6bde94a37c7015bdc3b20",
"md5": "5db6e5f0d702b0f636541436d35ba91b",
"sha256": "7e0c8d323d99880742dedc1c75343199cf33848aa8e4b4e0dfcd33b743bb2c2b"
},
"downloads": -1,
"filename": "pystk2_gymnasium-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "5db6e5f0d702b0f636541436d35ba91b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 27258,
"upload_time": "2023-11-20T14:39:24",
"upload_time_iso_8601": "2023-11-20T14:39:24.925089Z",
"url": "https://files.pythonhosted.org/packages/c0/0d/0f019b1ccd82b0cbd3f669f4979db5d54ba3cdf6bde94a37c7015bdc3b20/pystk2_gymnasium-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-20 14:39:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bpiwowar",
"github_project": "pystk2-gymnasium",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pystk2-gymnasium"
}
JSON
