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
- Vectorized
-
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.
-
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.
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
Cmake Presets
UsingWe 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
Cmake Presets
UsingWe 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
- Install cmake
- Install Visual Studio Build Tools
MacOS
- Install xcode CLI tools
xcode-select --install
- Install Brew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
- Install cmake
brew install cmake