GVG Framework

GVG Framework is an java framework that can parse and decode Video Game Description Language (VGDL). It can be easily used to play any VGDL game. Beside that, it can be used as an AI benchmark to test General Intelligent agents. The framework has been used in General Video Game Playing (GVGP) competition for multiple years. Recently we added an interface to help people to design level and rule generators for any game, including parameterizing existing games.

The following pages describe the whole framework. It describes in details the VGDL so people can understand the language either for creating games or to used for General level generation. It also describes the whole framework and how the code is organized. We also support some tutorials and sample controllers/generators to help everyone starts working on his agent/generator.

The following section is written by Benlot which will help everyone to setup the framework with Eclipse IDE:

Install Java Development Kit (JDK):

As we want to compile Java source code into its byte-code format, we need a JDK on your computer. Don't confuse it with the Java Runtime Environment (JRE) which is most surely already on your system. A JRE is for running Java byte-code (the executable so to say), and a JDK is to compile the human-readable Java source code into the executable byte-code format. A JDK usually contains a JRE, so you do not need to have installed both. So let's go!

• We need Java 7 as required by the GVG-AI framework, and it is recommended to get the one from Oracle in the GVG-AI specs. So go to the Oracle Downloads website and download the JDK for your OS.
• The installation is very OS specific, but for Mac and Windows it is nothing but a double click, for your linux distribution, if you do not know how to install a JDK, just google " install JDK". Here are Instructions for Ubuntu and Linux Mint, which is most probably the distro you have if you do not know how to install a JDK in linux.

You installed a JDK on your system, very good!

Install the Eclipse IDE

The Eclipse IDE itself is written in Java and is therefore a cross-platform IDE. We will add the version control extension to it that will be used to get the pre-configured GVG-AI project from github.com. Let's go!

• Go to the Eclipse Downloads page and download "Eclipse IDE for Java Developers" for your OS. You will get a .zip or .tar.gz compressed data file.
• Open the file and put the eclipse folder inside the file somewhere suitable for you (your user's home folder i.e. Users/ or /home/ etc.).
• Go into the eclipse folder and you should see an executable called eclipse or eclipse.exe (depending on OS again).
• Make a shortcut to your desktop of this executable.
• Open the Eclipse IDE. You should get a small loading window saying Eclipse Luna and then it asks you where you want to create your workspace (that is where your projects will reside).
• We will now check whether the version control extensions are already there. Go to Help->Eclipse Marketplace...
• If you want to use subversion for version control (recommended for beginners), then search for Subversive and install it if it is not yet installed. Just click continue if it can not find all resources. You will have to restart after the installation finishes.
• If you want to use git for version control (recommended for advanced users), then search for egit and install it if it is not yet installed. If it is already installed, then do not update egit, I had some incompatibilities with the newest version of it, so only update if you could fix it if it if the update does not work.

Success! You installed eclipse on your system and installed the appropriate version control extension.

Get the GVG-AI project from our github.com repository

• If you installed subversive, then continue here:
  • Then go to File->Import...->SVN->Project from SVN and enter the repository URL https://github.com/GAIGResearch/GVGAI to the form, together with your github.com account name and password. Don't worry about your credentials, they go directly to the github.com server to get the repository content. However if would recommend you to save the credentials in eclipse too, because otherwise you have to enter your credentials every time you commit changes to the repository. To do that, check the 'Save authentication' box right below the password field. Click Next. (It might be that you are asked to install a connector, install the newest version of SVNKit.)
  • Click Finish on the next view called 'Select resource'.
  • You will be asked how you want to checkout the project: Select 'Find projects in the children of the selected resource' and click 'Finish'.
  • It will find the project 'gvgai', click finish to put the project into your workspace.
• If you installed egit, then continue here:
  • Then go to File->Import...->Git->Project from Git, select clone from URI and enter the repository URL https://github.com/GAIGResearch/GVGAI.git to the form, together with your github.com account name and password. Don't worry about your credentials, they go directly to the github.com server to get the repository content. However if would recommend you to save the credentials in eclipse too, because otherwise you have to enter your credentials every time you commit changes to the repository. To do that, check the 'Store in Secure Store' box right below the password field. Click Next.
  • Click Next on the next view called 'branch selection'. You will get the master branch which is the main branch we will be working on.
  • Click Next on the next view called 'Local destination'. This will store the project in your home folder in 'git/gvgai'.
  • You will be asked how you want to checkout the project: Select 'Import existing projects' and click 'Next'.
  • It will find the project 'gvgai', click finish to put the project into your workspace.

(Optional, but handy): Add the Java source and Javadoc to the dependency (gvgai.jar)

• In your Eclipse 'Package Explorer' view (usually located left in the window, or find it through Window->Show View->Other...->Java->Package Explorer), select the file gvgai.jar with the right mouse button and choose Properties.
• Go to 'Java Source Attachment', choose the option 'External location' and hit the button 'External File...'. We provided the decompiled source as jar file in the root of the git repository. Navigate to local repository location, select gvgai-src.jar and hit 'Open'.
• Next, go to 'Javadoc Location', choose the option 'Javadoc URL' and hit the button 'Browse...'. The source is provided in the 'doc' folder located in the root of the git repository. Navigate to local repository location, select the 'doc/javadoc/' directory and hit 'Open'. Validate that this is a Javadoc location by hitting 'Validate...'. It should put out some message like 'Location is likely valid. [...]'.

You made it! The project GVG-AI is imported to your eclipse IDE!

Run the Controller Test Runner

• In eclipse in the left panel called 'Package Explorer' (or find it through Window->Show View->Other...->Java->Package Explorer), select the 'gvgai' project which is the project we just imported. Click on Run->Run as...->Java Application (you can also do that with the little down arrow aside the Green button with the right arrow in the toolbar above). It will ask you what you want to run, where you should click on 'Runner - main'. This will start the GVG-AI framework with the the Random Movement Controller and test it against multiple games and levels.
• In case it does not run but says something about a wrong class version instead, your eclipse IDE chose the wrong default JDK to compile and run the Java code. We fix this as follows:
  • Go to Eclipse->Preferences (Mac) or Window->Preferences
  • Then you go to Java->Installed JREs
  • There you will probably have a Java-6, JDK-1.6 etc. selected (what matters is the 6 or lower). That means it selected the wrong JDK to run it. Click on Search....
  • New JDKs should appear in the panel, hopefully one called Java-7, JDK 1.7 (what matters is the 6 or higher). From those appearing, select a version 7 or 1.7 or 8 or 1.8. They all will run
  • Click OK.
  • Repeat the "Run Controller Test Runner", this time you only have to click Run->Run or the Green button with the right arrow in the toolbar above. It should run fine now.

Congratulations! Your setup is working!

Using Ant

• Download latest version of Ant from http://ant.apache.org/bindownload.cgi.
• Install and set Ant up (there are detailed instructions here, depending on your OS: http://ant.apache.org/manual/index.html). In short:
  • Uncompress the ant package to a folder (i.e: in Win: C:\ant, or $~/ant/ in Unix)
  • Set the environment variables:
    • ANT_HOME: C:\ant\ or ~/ant/
    • Add to the PATH variable: C:\ant\bin or ~/ant/bin/
    • JAVA_HOME: To your JDK directory (something like C:\Program Files (x86)\Java\jdk1.7.0_30, or /usr/lib/jvm/jdk1.7.0/bin/java)
• A build.xml file is included in the distribution. In the directory that contains the build.xml file, type in a shell/command prompt:
  • ant clean: Deletes the compiled files.
  • ant compile or just ant: compiles the framework and sample controllers.
  • ant run: Executes the Test class.
  • ant: Cleans, compiles and creates a jar distribution file.