Video Game Description Language (VGDL) & General Video Game Playing Framework (GVG-AI)

This post is a presentation I did couple of weeks ago at Game Innovation Lab (GIL). It supposes to help people at the lab to understand VGDL and GVG-AI framework. I think that if we want VGDL to evolve, more people should know about it and use it. This evolution won’t happen without showing to people the power of GVG-AI Framework and VGDL. There is lots of development happening to improve the framework and language and making it more accessible to people (creating an Interactive Visual Editor with computer assist). The following paragraphs are my slides with a description for each slide.



General Video Game Playing (GVGP) is creating an AI agent that can play different video games (not a certain game) efficiently. The hard constrain on these agents that they need to have a response time in about 40 msec.


Video Game Description Language (VGDL) was invented to help to prototype different games quickly for the GVGP and have a common framework to work with. VGDL was initially written in python but now ported for java (to be faster). The language is tree structured like xml files. It supports grid physics like old arcade games (PcMan, Space Invaders, …etc). It is human readable and easy to prototype lots of different games using it (PcMan, Frogs, Space Invaders, Sokoban, …etc)


The current drawbacks of the VGDL: It hasn’t a visual editor, It hasn’t a good online documentation for the language, It has limited physics (no continuous physics to prototype games like Cut the Rope), and It has limited events (all game events are restricted with collision events between objects). Right now people are working to improve these drawbacks and make the VGDL more accessible to more people. Check the current draft of documentation and may be you could help improve the writing and improve it (link).


In order to write a game using VGDL, you need to provide two files (Game Description File and Level Description File). The Game Description File describes the whole game (What are the game sprites? What’s the termination condition? How do sprites interact? …etc). The Level Description File describes the level layout (Sprite arrangement).


Let’s take an example. This game is called WaterGame. It’s super simple game where you have to move the avatar towards the exit. The problem is the path is always blocked by water. If avatar touches water, it will die. In order to pass the water, the avatar should push boxes over it (Box destroys the water, you can think it floats).


That’s the Game Description File for that game. It is divided into 4 sections (SpriteSet, TerminationSet, InteractionSet, and LevelMapping).

  • SpriteSet: explains all the game sprites (their type, their rendered image). For example “avatar” is defined as of type “MovingAvatar” which means it can move in all 4 directions and it has an image called “avatar” (All images must be in sprites folder).
  • TerminationSet: explains how should the game ends? For example “SpriteCounter stype=avatar limit=0 win=False” means if the number of “avatar” sprites are equal to zero, you lose the game.
  • InteractionSet: explains the result of collision between sprites. For example the first collision says if “avatar” collides with “wall”, the “avatar” should “stepBack” which means undo its last movement.
  • LevelMapping: just helps the VGDL engine to parse the Level Description File. The VGDL engine just replace each character with the corresponding sprites.


The Level Description File is a 2D matrix of characters described in the LevelMapping section. The VGDL engine just replace each character with the correct sprites and voila the level appears.


Let’s now talk about the different types of sprites we can define. There is several amount of sprites but I just categorize it into the following:

  • Portal & Spawn Points: Like doors, teleports, portals that spawn objects, and …etc
  • NPC: there is chasing npc (follows a certain sprite), fleeing npc (runs away from certain sprite), random npc (moves randomly), and …etc
  • Resource: objects that can be collected and change certain defined variable value. This value can be anything like score, health, ammo, …etc
  • Avatar: It is controlled by the player (using keyboard or an agent). It can be moving avatar (moves everywhere), shooting avatar (which moves and can shoot), …etc
  • Movable: It is an object that is affected with physics like missiles.
  • Static: It is not affected with any physics even its applied on it like walls.


There is only three different types of termination condition:

  • SpriteCounter: It terminates the game when the number of certain sprite is larger than or equal to certain value.
  • MultiSpriteCounter: It terminates the game when the summation of two different sprites equal to certain value.
  • TimeOut: It terminates the game when the game time is larger than or equal to certain value.


There is lots of different interactions that can be used on collision between different sprites. The following are categorization for them:

  • Kill Sprite
  • Spawn Sprite
  • Undo Movement
  • Change Orientation
  • Change Position
  • Collect Resource


The following slides will focus on the GVG-AI framework and what does it offer? For more details check GVG-AI website documentation (link).


You can integrate an AI Agent that plays VGDL games just by extending AbstractPlayer class and providing a constructor and an act function which returns the avatar action every single game step.


The framework also supports a StateObservation class that wraps the current game status (winning, score, and time), avatar status (speed, position, and orientation), grid observation for all the game (also it supports arrays for different sprite types), and Event History for all collisions happened due to the avatar or a sprites spawned by it.


The StateObservation class provides forward model that can predict the future but not exactly as most games are some how stochastic.


Last thing the framework comes with couple of sample agents to help you understand how to write your AI agent. For example: Random Agent, One Look Ahead, Genetic Algorithm, and Monte Carlo Tree Search.


That’s the whole presentation. I hope it encourages you to use VGDL to prototype your games or even participate in the next GVG-AI competition (link). The Game Innovation Lab is trying to improve all the drawbacks of the VGDL language and even start a PCG competition track (link).

Bye Bye

2 thoughts on “Video Game Description Language (VGDL) & General Video Game Playing Framework (GVG-AI)

  1. Nice introduction.

    VGDL looks promising. Maybe if there is a tool that converts already made games to VGDL, that would make it more popular.

    Best of Luck.

    • It’s a little bit hard to be done as most of games doesn’t have an easy API to access them and make an agent play them to have sense of rules and translate to VGDL but it’s a neat idea 🙂 btw we will have a simple visual editor for the language which might not be as powerful as the language itself (as I don’t know it’s full capabilities of the editor) but will help people to make quick arcade games prototypes

Leave a Reply

Your email address will not be published. Required fields are marked *