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

Literature Review of PCG in Puzzle Games

Long time since posting (the usual me) but This post will be short and long at same time.

“How is that?” That’s easy, the post itself will be very short (just few words) but it will have an attached document (around 16 pages) which is the third chapter in my Master’s Thesis. This chapter is the literature review chapter (the third biggest chapter in my thesis) which I think one of the most entertaining chapters (to read obviously not to write :D).

“Why do I think its entertaining?” That’s also easy to reply, I combined lots of previous work about level and rule generation (look at the references), and a friend of mine enjoyed reading it and thought its the most entertaining chapter.

“You just said its a short post.” Yes, sorry for that but I want also to improve my writing capabilities. Here is the link to the document:

Bye Bye

PCG in my Games

Hello everybody,
Long time with no posts or updates here. It seems like desert, sorry for that but I am sure people who follow me on twitter knows I was busy with my Master’s Thesis in Procedural Content Generation (PCG). I have always used PCG in my games as an excuse for being lazy and not designing levels (as I am not amazing level designer). In this post I will wrap up quickly some of the PCGs I used in my games. In the next post will talk about PCG in my Master’s Thesis.

As most of people noticed lots of my arcade games used PCG especially top down shooters (Clean’Em Up and Alone in the Park). All these games don’t have levels designed in advance, but instead they have enemy numbers and types to be generated. The system afterwards choose the most suitable location (away from the player position) and insert them. Pace Maker was a little different where the system generates the types and numbers based on the level of difficulty so as difficulty increase the number of enemies and variety of types increased.

Match a Number used PCG technique to generate the map. The idea is super easy

  • Insert random tiles (numbers and types) over the whole grid
  • Choose the solution length based on the player score (define the difficulty).
  • Generate a random path of the specified length without any loops.
  • Calculate the value of this path and consider it as player target

For the puzzle mode instead of generating paths, the whole playground is divided into sets according to the number of sets required at the beginning and then calculate the value of each set separately.

Atomic+ bullet pattern was generated based on a certain equation of difficult. The bullet generator is divided into the following features and by combining these features we can get a new shooter

  • Bullet Path (bp): how the bullet moves in the game (straight line, sin wave, spring, and circular path).
  • Number of Spawner (ns): how many places bullets should fire from the center (1, 2, 3, and 4).
  • Rate of Spawning (rs): how many milliseconds does the spawner need to spawn a bullet (800, 750, 700, 650, and 600).
  • Number of Burst bullets (nbb): how many bullets should the spawner generate at everyshot (1, 2, and 3).
  • Number of Bullets (nb): how many bullets the spwaner should shoot after each other (1, 2, and 3).
  • Spawner movement (sm): how the spawner update its position (no movement, circular movement, and ping pong circular movement)

Each of values for each feature has a specific difficulty score. This score is inserted in a difficulty equation and if the output difficulty is near the target difficulty then this generator is used else repick another random generator. The difficult equation is:

difficulty = sm * rs * bp * ns * nbb * nb

Last game I am going to talk about is DivCircle. The music and the rotation are both chosen by the computer. For the game music. The music is divided into several tracks overlayed over each other as the rotation speed increased each layer of the music got activated and as the rotation speed decrease the layers gets lower. Also as the player approach more towards the death, all layers volume decreased while sounds of talking people increases. That’s everything with the music and Ben Burnes did an amazing job in helping me to reach that. About the rotations, I divided the game into 14 sequence each one with its own difficulty score. These sequences are:

  • Speed Up
  • Speed Up Fast
  • Slow Down
  • Slow Down Fast
  • Reverse
  • Speed Reverse
  • Slow Reverse
  • Reverse, Reverse
  • Speed Up Fast, Speed Up Fast, Slow Down Fast
  • Slow Down Fast, Speed Up Fast
  • Speed Reverse, Slow Down Fast, Speed Reverse
  • Reverse, Speed Up Fast, Reverse, Slow Down, Reverse
  • Speed Up Fast, Speed Up Fast, Reverse
  • Speed Reverse, Slow Reverse, Speed Reverse

All actions are stored in a queue and every amount of time an action is activated and new action sequence is inserted in the list based on the current player score and current rotation speed and how old is the reverse. The amount of time for inserting and applying new action is decreased as the score increase.

This is everything for now, Hope its a little bit entertainment and useful. Stay tuned for the next post which is gonna be about General Level Generation for Puzzle Script (which is a part of my Master’s Thesis).

Bye Bye for now

Help is Needed

Hello everyone,


Sorry for being away for long time, but as you all know I am working on my master’s thesis in Procedural Content Generation (PCG) of puzzle games and levels for Puzzle Script engine by Stephan Lavelle. I generated lots of levels using different methods for 5 different games and I need some human feedback on everything.

If you have some free time to help me with it please consider playing a handcrafted game and then one of the techniques (playing handcrafted give you reference to the best designed games) (link). Do the assessment after finishing every level to remember it because after playing 16 levels you may forget some games.

Please try playing some of the game at the end of the list such DestroyGame, GemGame, BlockFaker. As most of assessment is done on Sokoban and slightly on LavaGame.

Thanks everyone, I will publish my thesis and my code and everything once its done to be open source with all the results and data. Hope my work in PCG helps game developers in understanding more about games and how to design it and may be use or improve on my techniques.

The link for the games and the assessments:

Bye Bye

DivCircle is out today for Free

Hello Everybody,
I don’t know if there is still some followers to my blog, but if there I wanna say DivCircle is now OUT on AppStore and on GooglePlay. Get your headphones and try that experimental game and experience how different people feels toward developed societies.

Here a trailer for the game

Now Go and Try it (AppStore) and (GooglePlay) and here is the (Website) too :) Spread the word and make everyone try it :) Hope the world become a better place for everyone :)

That’s everything for now :) I am so busy right now applying for PhD degree so Pray god I got accepted in a PhD degree so I can work on Procedural Generation and stuff I love and I can get out of my country at same time. Thanks for supporting me all this time.

Bye Bye

DivCircle is Next Month

Hello Everyone,
I know I have long time away but as usual busy working on games, master thesis and trying to apply for PhD for next fall so I can leave Egypt and work on stuff I love :) Let’s not talk about my akward feeling towards Egyptians (not Egypt btw) and let’s show you all the new trailer for the game and the website (

The game will be released in December for Free on Android and iOS :) and its about Diversity and supporting We heart Campaign ( :) That’s everything for now :)

Bye Bye

AmidosEngine: a FlashPunk inspired game engine based on Starling

Hello Everybody,
That’s a short quick post :) I have decided to release my game engine I have been using for all my mobile games lately and desktop games to the internet.

I designed that engine to be fast and quick way to make games based on concepts of FlashPunk but at same time used Starling so it can render very fast on mobile devices making use of the new Stage3D rendering.

I know there are lots of better engines out there but I didn’t find any engine that resemble FlashPunk very well that’s why I build my engine over Starling, I will continue updating it with each game I create whenever I find a need for something, I will create it.

I know the name is very narcissistic because I used my name in it, I know but I am bad at names so I named it after myself (Sorry for that) and Thanks for Chevy Ray and Starling for making it possible.

Hope someone can find it useful and help him to make better games, That’s everything for now :)

github Page:

Bye Bye

Atomic+ Android Version

Hello Everybody,
Happy Feast for all Muslims in entire world and celebrating that I released Atomic+ on Google Play Store. Hope people will love it.


So to keep it short just tell your friends and go buy the game :D YaaaaaY :D The game is on 50% discount for limited time so what are you waiting for :) Go Go Go :) (Link)

That’s everything for now :)

Bye Bye

The RoguePuzzleGame prototype is now online

Hello Everyone,
Past GameZanga (Arabian game jam happens twice a year) I created a game called Random RPG for it, it was completely disaster but I felt it had some potential.

So I gave it around 1 more week of work and here what I got The RoguePuzzleGame, it was picked to be viewed at the Saudi Gamer’s Day (a Game Expo happens in Saudi Arabia once a year) but I didn’t feel very confident about the game and I always think its a very bad game and I was going to threw it away and stop developing in it but I decided to release a prototype and get some feedback about it.


The prototype is online on my beloved three websites

That’s everything for now :) Please give me some good feedback about the game :)

Bye Bye

P.S: The game music is done by Brother Android (its fuckin amazing)

RPSwipe is out now

Hello everyone,
I don’t need to say anything in the article the header says everything :D yes its true its 8th of August the release date of RPSwipe. The game is now out on Android and iOS at same time thanks to starling Engine. Here the release trailer of the game

Hope everybody will enjoy the game :) and love it :) its now under 50% sale on iOS and Android so you can pick it up for 0.99$ till 22nd August and then for 1.99$ afterwards so what are you waiting for go get a copy (AppStore Link, GooglePlay Link)

That’s everything for now stay tuned for more information about DivCircle.

Bye Bye