Package: oog
Object-Oriented GamesDescriptionProject WebsiteSummaryThisObject-Oriented Games (OOG)
libraryis a general-purpose
python-based platform for interactive games. It aims to satisfy the following
criteria:Highly customizable. Environment physics, reward structure, agent interface,
and more are customizable.Easy to rapidly prototype tasks. Tasks can be composed in a single short
file.Usable for both reinforment learning and psychology, withDeepMind
dm_envandOpenAI
Gyminterfaces for RL agents and anMWorksinterface for psychology and
neurophysiology.Light-weight and efficient. Most tasks run quickly, almost always faster than
100 frames per second on CPU and often much faster than that.Facilitates procedural generation for randomizing task conditions every trial.Seeoog_demosfor a variety of example tasks.Intended UsersOOG may be useful for the following kinds of researchers:Machine learning researchers studying reinforcement learning in
2.5-dimensional physical environments who want to quickly implement tasks
without having to wrangle with more complicated game engines that aren't
designed for RL.Psychology researchers who want more flexibility than existing psychology
platforms afford.Neurophysiology researchers who want to study interactive games yet still need
to precisely control stimulus timing.Machine learning researchers studying unsupervised learning, particularly in
the video domain. OOG can be used to procedurally generate video datasets with
controlled statistics.IntroductionThe core philosophy of OOG is"one task, one file."Namely, each task can be
implemented with a single configuration file. This configuration file should be
a short "recipe" for the task, containing as little substantive code as
possible, and should define a set of components to pass to the OOG environment.
Seethe OOG READMEfor more details.We also include an exampleMWorksinterface for
running psychophysics experiments, as well as apython demo
scriptfor testing task prototypes.Features Compared to Existing PlatformsCompared to professional game engines (Unity, Unreal, etc.) and existing visual
reinforcement learning platforms (DM-Lab, Mujoco, VizDoom, etc.):Python. OOG tasks are written purely in python, so users who are most
comfortable with python will find OOG easy to use.Procedural Generation. OOG facilitates procedural generation, with alibrary of compositional
distributionsto randomize
conditions across trials.Online Simulation. OOG supports online model-based RL, with aground truth
simulatorfor tree search.Psychophysics. OOG can be run with MWorks, a psychophysics platform.Speed. OOG is fast on CPU. While the speed depends on the task and
rendering resolution, OOG typically runs at ~200fps with 512x512 resolution on
a CPU, which is faster than one would get with DM-Lab or Mujoco and at least
as fast as Unity and Unreal.Compared to existing python game platforms (PyBullet, Pymunk, etc.):Customization. Custom forces and game rules can be easily implemented in
OOG.Psychophysics, Procedural Generation, and Online Simulation, as described
above.RL Interface. A task implemented in OOG can be used out-of-the-box to
train RL agents, since OOG is python-based and has DeepMind dm_env and OpenAI
Gym interfaces.Compared to existing psychophysics platforms (PsychoPy, PsychToolbox, MWorks):Flexibility. OOG offers a large scope of interactive tasks. Existing psychophysics platforms are not easily customized for
game-like tasks, action interfaces, and arbitrary object shapes.Physics. Existing psychophysics platforms do not have built-in physics,
such as forces, collisions, etc.RL Interface, as described above.OOG caninterface with MWorks, allowing users to leverage the OOG task
framework while also allowing for precise timing control and interfaces with
eye-trackers, joysticks, and electrophysiology software.LimitationsNot 3D. OOG environments are 2.5-dimensional, meaning that they render in
2-dimensions with z-ordering for occlusion. OOG does not support 3D sprites.Very simple graphics. OOG sprites are monochromatic polygons. There are no
textures, shadows, or other visual effects. Composite sprites can be
implemented by creating multiple overlapping sprites, but still the graphics
complexity is very limited. This has the benefit of a small and easily
parameterizable set of factors of variation of the sprites, but does make OOG
environments visually unrealistic.Imperfect physics. OOG's physics engine is simple. It uses Newton's method
to effect action-at-a-distance forces. OOG does include a collision module
that implements rotational mechanics, but it is not as robust as more
professional physics engines and can have instabilities (particularly if
multiple objects collide simultaneously). Seeoog_demos/example_configs/falling_balls.pyfor an extreme example of unstable physics.Getting StartedSee theproject websitefor
API documentation about every file and function in OOG.InstallationIf you would like to install this library as a package, you can install using
pip:pipinstalloogThis will installoogandoog_demospackages. Be sure to use python 3.7 or
later.Running The DemoTasks can be played by running therun_demoscript, in which the--configflag indicates the task config to demo. For example, to demo thepongtask, you would run:python3-moog_demos.run_demo--config='oog_demos.example_configs.pong'When this command is run, the demo will produce an interactive display. At the
top of the display is the rendered environment state, in the middle of the
display is a histogram of recent rewards, and at the bottom of the display is a
top-down view of a cartoon joystick. You can click and drag the joystick around
to control the agent avatar. The demo can be terminated by pressingescape.The pong task looks like this:You can change the config flag to point to any of theexample
configs. They will all run except forcleanup,
which is multi-agent so cannot be played by a single-agent demo, (though seemulti_agent_examplefor more about that).Implementing TasksBefore implementing your own tasks, please readthe OOG README.To begin implementing your own task, we recommend first looking at all the
example configs inoog_demosand copying one with some
similarities to your task into a working directory. Then modify it incrementally
to your specification.To demo your config, copyrun_demo.pyinto your
working directory and run it with$python3run_demo.py--config='path.to.your.config'--level=$your_config_levelContact and SupportPlease seeCONTRIBUTING.mdfor information about support.
Please email Nick Watters atnwatters@mit.eduwith questions and feedback.ReferenceSome parts of this codebase are derived fromSpriteworld. See the Spriteworld
license inLICENSE-spriteworld.