A heavily optimized and flexible grid-world game engine for Game AI research.

Some Environments

Check out the full list of pre-built environments here

Some features

• Design and build game mechanics using a simple YAML-based language: GDY

• Fast execution speed environments can run up to 70k FPS on a single thread.

• Don't worry about complex efficient rendering code, just define the images for each game object and Griddly passes this to the GPU.

• Supports Single Agent, Multi Agent and RTS environment interfaces.

• Multiple observervation modes:

  • Vectorized
  • Configurable one-hot encodings for each x,y coordinate
  • Rendered
  • Isometric, sprites and simple shapes
  • We also let you use custom shaders to render however you want!
  • State Maps
  • Description of the entire environment including objects, locations and variables.
  • Event History
  • Descriptions of actions that have happened in each step.
  • Configurable partial observability

• Copyable Forward Models

  • Game state can be cloned at any point in time. This is super useful for many Algorithms. For example Mont-Carlo Tree Search.

• Procedural Content Generation Interfaces

• Reinforcement Learning with RLLib

  • Integration with Wandb

Community

Join the Discord community for help and to talk about what you are doing with Griddly!

Documentation

Full documentation can be found here: griddly.readthedocs.org

Tutorials

The most awesome part of Griddly is the ability to easily customize and build your own research environments. To make this extra easy we've written lots of tutorials:

Making A Simple Game (Sokoban)

• This tutorial takes you through how to create a simple game environment using GDY.

Game Mechanics

• Proximity Triggers
  • Configure interactions between objects based on their distance.
• Projectiles
  • Objects that move under their own power.
• Level Design
  • How to design levels for single and multi-agent environments.
• Stochasticity
  • How to make environments with stochastic mechanics.
• A* Search
  • Use A* pathfinding for mobs in Griddly

Custom Shaders

• Customize rendering for environments using SPIR-V shaders.

  Global Lighting

  

  Health Bars

  

  Per-Object Lighting

  

Installing

Building locally

Firstly you will need to configure the repo for the build.

You can do this using the configure.sh script in the root directory.

Web Assembly Binaries

Build a debug version of the web-assembly binaries.

Manually

You can run all the build commands manually

# Download the build requirements
conan install deps/wasm/conanfile_wasm.txt --profile:host deps/wasm/emscripten.profile --profile:build default -s build_type=Debug --build missing -if build_wasm

# Configure the cmake build
cmake . -B build_wasm -GNinja -DWASM=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake

# Run the build
cmake --build build_wasm --config Debug

Using [Cmake Presets]()

We provide two presets for CMake to use to develop locally using your IDE (provided it supports CMakePresets)

# Download the build requirements
./configure.sh -p=WASM -b=Debug

# Configure build with preset
cmake --preset="Debug WASM"

# Build with preset
cmake --build build_wasm --config Debug

Native Binaries

Manually

Build native griddly binaries:

# Download the build requirements
conan install deps/conanfile.txt --profile default --profile deps/build.profile -s build_type=Debug --build missing -if build

# Configure the cmake build
cmake . -B build -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake

# Run the build
cmake --build build --config Debug

Using [Cmake Presets]()

We provide two presets for CMake to use to develop locally using your IDE (provided it supports CMakePresets)

# Download the build requirements
./configure.sh -b=Debug

# Configure build with preset
cmake --preset="Debug Native"

# Build with preset
cmake --build build --config Debug

Tests

Test can be run with:

ctest .

Python Installer

To install the built libraries with python you need to do one of the following (depending if your built the binaries with Debug or Release)

The installer should copy the following files into the python/griddly directory:

• resources/* -> python/griddly/resources
• {Release|Debug}/python_griddly.cpython* -> python/griddly/libs

Debug

cd python
python setup.py develop

OR

cd python
pip install -e .

Release

cd python
python setup.py install

Prerequisites

We use Conan to install all build dependencies and libraries used to compile Griddly.

You will need to set up a python environment of your choice and then install conan using:

pip install conan

Debug Layers for Vulkan

When compiling using Debug, you will need the install vulkan validation layers which are part of the vulkan sdk. Otherwise you will run into errors like:

[2023-01-04 15:21:54.412] [warning] Required vulkan layer unavailable: VK_LAYER_KHRONOS_validation
[2023-01-04 15:21:54.412] [error] Missing vulkan extensions in driver. Please upgrade your vulkan drivers.

Ubuntu

1. Install [cmake](https://cmake.org/download/)

Windows

1. Install cmake
2. Install Visual Studio Build Tools

MacOS

1. Install xcode CLI tools

   xcode-select --install

2. Install Brew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

3. Install cmake

   brew install cmake