{"id":28753230,"url":"https://github.com/google-deepmind/spriteworld","last_synced_at":"2025-07-05T02:35:25.806Z","repository":{"id":57470344,"uuid":"202149353","full_name":"google-deepmind/spriteworld","owner":"google-deepmind","description":"Spriteworld: a flexible, configurable python-based reinforcement learning environment","archived":false,"fork":false,"pushed_at":"2020-06-01T15:09:16.000Z","size":457,"stargazers_count":371,"open_issues_count":0,"forks_count":55,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-06-17T00:48:07.008Z","etag":null,"topics":["deepmind","environment","generative","procedural","rl","sprites"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-deepmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-13T13:21:12.000Z","updated_at":"2025-06-10T03:09:33.000Z","dependencies_parsed_at":"2022-09-19T15:00:44.392Z","dependency_job_id":null,"html_url":"https://github.com/google-deepmind/spriteworld","commit_stats":null,"previous_names":["google-deepmind/spriteworld","deepmind/spriteworld"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/google-deepmind/spriteworld","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fspriteworld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fspriteworld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fspriteworld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fspriteworld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-deepmind","download_url":"https://codeload.github.com/google-deepmind/spriteworld/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fspriteworld/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263671820,"owners_count":23494045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deepmind","environment","generative","procedural","rl","sprites"],"created_at":"2025-06-17T00:39:14.553Z","updated_at":"2025-07-05T02:35:25.783Z","avatar_url":"https://github.com/google-deepmind.png","language":"Python","readme":"# Spriteworld: A Flexible, Configurable Reinforcement Learning Environment\n\n## Description\n\nSpriteworld is a python-based RL environment that consists of a 2-dimensional\narena with simple shapes that can be moved freely. This environment was\ndeveloped for the COBRA agent introduced in the paper [\"COBRA: Data-Efficient\nModel-Based RL through Unsupervised Object Discovery and Curiosity-Driven\nExploration\" (Watters et al., 2019)](https://arxiv.org/abs/1905.09275). The\nmotivation for the environment was to provide as much flexibility for\nprocedurally generating multi-object scenes while retaining as simple an\ninterface as possible.\n\nSpriteworld sprites come in a variety of shapes and can vary continuously in\nposition, size, color, angle, and velocity. The environment has occlusion but no\nphysics, so by default sprites pass beneath each other but do not collide or\ninteract in any way. Interactions may be introduced through the action space,\nwhich can update all sprites each timestep. For example, the DiscreteEmbodied\naction space (see `spriteworld/action_spaces.py`) implements a rudimentary form\nof physics in which an agent's body sprite can adhere to and carry sprites\nunderneath it.\n\nThere are a variety of action spaces, some of which are continuous (like a\ntouch-screen) and others of which are discrete (like an embodied agent that\ntakes discrete steps).\n\n## Example Tasks\n\nBelow are three of the tasks used in the\n[COBRA paper](https://arxiv.org/abs/1905.09275).\n\nGoal-finding task. The agent must bring the target sprites (squares) to the\ncenter of the arena.\n\n![goal_finding_video](./gifs/goal_finding_video.gif)\n\nClustering task. The agent must arrange the sprites into clusters according to\ntheir color.\n\n![clustering_video](./gifs/clustering_video.gif)\n\nSorting task. The agent must sort the sprites into goal locations according\nto their color (each color is associated with a different goal location).\n\n![sorting_video](./gifs/sorting_video.gif)\n\n## Installation\n\nSpriteworld can be installed using `pip`:\n\n```bash\npip install spriteworld\n```\n\nOr through Github:\n\n```bash\npip install git+https://github.com/deepmind/spriteworld.git\n```\n\nor alternatively by checking out a local copy of our repository and running:\n\n```bash\ngit clone https://github.com/deepmind/spriteworld.git\npip install spriteworld/\n```\n\nThis last option additionally downloads tests, the demo UI and an example run loop.\n\n## Getting Started\n\n#### Prerequisites\n\nSpriteworld depends on `numpy`, `six`, `absl`, `PIL`, `matplotlib`, `sklearn`,\nand `dm_env`.\n\n#### Running The Demo\n\nOnce installed, you may familiarize yourself with Spriteworld through\n`run_demo.py`:\n\n```bash\npython /path/to/local/spriteworld/run_demo.py\n```\n\nThis will run a cluster-by-color task with a drag-and-drop action space. There\nare a number of tasks specified in the `spriteworld/configs` directory, each of\nwhich can be run with the demo by modifying the `--config` flag. Note that some\ntasks (namely `spriteworld.configs.examples.goal_finding_embodied`) use an\nembodied agent instead of the drag-and-drop action space.\n\n#### Creating Your Own Task\n\nIn `spriteworld/tasks.py` are three tasks: `FindGoalPosition`, `Clustering`, and\n`MetaAggregated`. These can be configured and combined in numerous ways to\ncreate a wide variety of tasks, including all of those used in the\n[COBRA paper](https://arxiv.org/abs/1905.09275). In particular, see\n`spriteworld/configs/cobra/sorting.py` for a non-trivial combination of\ngoal-finding tasks.\n\nYou may create new tasks be re-using these building blocks, or creating entirely\nnew types of tasks (just be sure to inherit from\n`spriteworld/tasks.AbstractTask`).\n\n#### Running An Agent\n\nSee `example_run_loop.py` for an example of how to run a random agent on a\nSpriteworld task. See `spriteworld/gym_wrapper.py` if you prefer the OpenAI Gym\nenvironment interface.\n\n## Additional Use-Cases\n\nSpriteworld can be used for purposes other than reinforcement learning. For\nexample, it was used to generate the image datasets with controlled factor\ndistributions presented in the paper [\"Spatial Broadcast Decoder: A Simple\nArchitecture for Learning Disentangled Representations in VAEs\" (Watters et al.,\n2019)](https://arxiv.org/abs/1901.07017). It can also be easily extended to\ngenerate datasets of objects interacting with simple physical forces (e.g.\nspring, gravity, etc.), which are useful for research in unsupervised learning\nof visual dynamics.\n\n## Reference\n\nIf you use this library in your work, please cite it as follows:\n\n```\n@misc{spriteworld19,\nauthor = {Nicholas Watters and Loic Matthey and Sebastian Borgeaud and Rishabh Kabra and Alexander Lerchner},\ntitle = {Spriteworld: A Flexible, Configurable Reinforcement Learning Environment},\nhowpublished = {https://github.com/deepmind/spriteworld/},\nurl = {https://github.com/deepmind/spriteworld/},\nyear = \"2019\",\n}\n```\n\n## Disclaimers\n\nThis is not an officially supported Google product.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fspriteworld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-deepmind%2Fspriteworld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fspriteworld/lists"}