Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

Update June 2019:

VGDL 2.0 is a new and extended version of this project, developed and maintained independently by Ruben Vereecken, and recommended for anyone looking to start using VGDL today (this repository is effectively dormant).

The other actively developed extension is java-vgdl, which is used for the GVG-AI competition.

(original read-me below)


PyVGDL is a high-level video game description language (VGDL) built on top of pygame.

The aim is to decompose game descriptions into two parts: 1) a very high-level description, close to human language, to specify the dynamics, which builds on 2) an ontology of preprogrammed concepts for dynamics, interactions, control. Programmers extend the possibilities of (1) by writing modules in (2), and game designers can very quickly compose new games from those components without programming.


The original idea was discussed in the 2012 Dagstuhl seminar, with a full description presented at the IEEE CIG conference 2013 (this is also the reference paper to cite if you use PyVGDL for academic work).

Installation and Dependencies


  • Get the pygame package

  • (Alternative Method) Using Homebrew and virtualenv on Mac OSX

          brew install sdl sdl_image sdl_mixer sdl_ttf portmidi
          pip install mercurial
          pip install hg+
  • For all reinforcement learning usage, also get the PyBrain machine learning library

  • For the upload to youtube functionality, you will need the gdata library


using pip on linux

sudo pip install git+git://

using pip on windows or Max OSX

pip install git+git://

otherwise you can download it and install it using

git clone git://
python install
  • Try examples

       python -m examples.gridphysics.aliens
       python -m examples.gridphysics.frogs
       python -m examples.gridphysics.zelda


  • Language
  • A simple programming language of 2D video game design
  • A parser for the language
  • A parser for textual level descriptions
  • An ontology with numerous high-level building blocks for games
    • grid-based physics engine
    • continuous physics engine, including gravity, friction, etc.
    • stochastic events
  • Classic examples (simplified versions)
  • Space invaders
  • Frogger
  • Lunar lander
  • Zelda
  • Super Mario
  • Portal
  • Sokoban
  • PTSP
  • Pong
  • Tank wars
  • Dig-dug
  • Pacman
  • ...
  • Human play
  • Interactive play, either from bird-eye viewpoint, or from first-person viewpoint
  • Create animated GIFs from replayed action sequences
  • Bot play
  • Interface for artificial players (bots)
  • Conversion of game dynamics into the transition matrices of a Markov Decision Process (MDP)
  • Automatically generated local/subjective observation features
  • Reinforcement learning
    • Easy interface to RL algorithms from PyBrain
    • Classic grid world benchmarks


A video game description language (VGDL) built on top pf pygame.







No packages published

Contributors 4