Github Pages
Further documentation can be found at github pages.
Special Thanks
We would like to thank Prof. Nir Lipovetzky, an instructor in COMP90054 “AI Planning for Autonomy” course of the University of Melbourne. The course staff have organized a contest for autonomous agents for the game Splendor, developed by the students. We've contancted associate Prof. Nir Lipovetzky (Github, mail ) of Melbourne University and he provided us with their implementation of the game engine. From there we've started tweeking the game engine a bit for our needs (like adding the generatePredecessor method to SplendorGameRule ).
NOTE
Some of the features here will require python 3.11
or higher.
There are 2 possible ways to install the requirements of splendor.
- using
conda
. - using
pip
.
Execute the following (in the repo's top directory):
conda env create -f environment.yaml
conda activate splendor
pip install .
Execute the following (in the repo's top directory):
pip install -r requirements.txt
pip install .
Execute the following command for help message (location is no longer relevant):
splendor --help
splendor --interactive
There are a few option for specifying agents:
- The specified agent is part of
splendor
. - The specified agent is not part of
splendor
, however he is installed as a part of a different package. - The specified agent is not part of
splendor
and he is not installed as a part of a different package.
We'll now address each case.
Whenever you wish to invoke/use a specific agent (from splendor
) you need to specify the absolute import path.
The absolute import path must be specified regardless of the working directory.
splendor -a splendor.agents.generic.random,splendor.agents.generic.first_move --agent_names=random,first_move
Let's assume we've installed a package called external
and there is an agent called best
whithin external.agents
and we want to flesh out this agent againt the random agent we would execute the following command:
splendor -a splendor.agents.generic.random,external.agents.best --agent_names=random,external
Let's assume we want to use an agent called agent_in_my_cwd which isn't part of splendor
nor installed via another package.
We would utilize the fact that the game adds the current working directory to the module search path when loading agents.
So we would act as follows:
cd <path to the directory containing the agent>
splendor -a agent_in_my_cwd,another_agent_in_my_cwd --agent_names=external_1,external_2
By default the game adds the current working directory to the module search path when loading agents.
This can be disabled by providing the flag --absolute-imports
however this would deny the usage of agents which aren't part of splendor
without installing them as part of other package.
- the
-a
flag is used to specify which agents to load, this must be comma seperated values, where each value must be an import path of the agent to be loaded. Moreover each of those agent must inherit fromsplendor.template.Agent
and must call their agent (or a factory) by the following name -myAgent
. - the
--agent_names=
is another comma seperated argument which specifies the names given to each agent. The number of agents to be loaded is determined by the amount of names given, when there are more names listed than agents listed the game will automatically load random agents to fill the void.
just add the -t
option, for example:
splendor -a splendor.agents.generic.random,splendor.agents.generic.first_move --agent_names=random,first_move -t
Interactively play against the trained genetic algorithm agent:
splendor -a splendor.agents.our_agents.genetic_algorithm.genetic_algorithm_agent --agent_names=genetic,human --interactive
Interactively play against the trained PPO agent:
splendor -a splendor.agents.our_agents.ppo.ppo_agent --agent_names=ppo,human --interactive
Let the genetic algorithm agent play against minimax (with alpha-beta pruning) agent:
splendor -a splendor.agents.our_agents.genetic_algorithm.genetic_algorithm_agent,splendor.agents.our_agents.minmax --agent_names=genetic,minimax
Let the genetic algorithm agent play against minimax (with alpha-beta pruning) agent for 10 consecutive games (only text display):
splendor -a splendor.agents.our_agents.genetic_algorithm.genetic_algorithm_agent,splendor.agents.our_agents.minmax --agent_names=genetic,minimax -t -m 10
Let the PPO agent play against minimax (with alpha-beta pruning) agent for 10 consecutive games (only text display):
splendor -a splendor.agents.our_agents.ppo.ppo_agent,splendor.agents.our_agents.minmax --agent_names=ppo,minimax -t -m 10
In order for the game to properly load your agent one must install the agent, there are several ways to do so:
- create a new agent within
src/splendor/agents
and when installing splendor your agent will be installed as well. (i.e. when invokingpip install .
) - create a new package and develop your agent there and then install it.
- create a new agent within
src/splendor/agents
and ONLY DURING DEVELOPMENT install splendor by usingpip install -e .
(instead of thepip install .
) which allowes you to edit and adjust your agent as you please without the necessity to re-install the package.
In order to train the genetic algorithm agent with the following hyper-parameters:
- Specify the population size in each generation to be 24 (should be a multiple of 12).
- Train for 20 generations.
- Fix the mutation rate chance to be 0.1(%).
- Use a fixed random seed. Use the following command:
evolve --population-size 24 --generations 20 --mutation-rate 0.1 --seed 1234
In order to train the PPO agent you should run the following command:
ppo
This command will train the PPO agent with the default training hyper-parameters.
We've made a custom gym.Env
and registered it as one of gym
environments. This would come in handy when training agent such as DQN or PPO.
- import
gymnasium
-import gymnasium as gym
. - registering
SplendorEnv
togym
-import splendor.Splendor.gym
- define the opponents:
When creating an instance of SplendorEnv
you should tell it which agents will
be used as opponents to you (the one who uses the env.).
For the following example we'll use a single random agent as an opponent.
from splendor.agents.generic.random import myAgent
opponents = [myAgent(0)]
- creating the environment:
env = gym.make("splendor-v1", agents=opponents)
- every call to
env.step(action)
simulate (by usingSplendorGameRule
) the turns of all the opponents. - when calling
env.reset()
SplendorEnv
will return the feature vector of the initial state AND the turn of our agent via the second variable (thedict
) which will have a key calledmy_turn
. SplendorEnv
have several custom properties:state
- the actualSplendorState
- not the feature vector.my_turn
- the turn of the agent, same as the value returned byenv.reset()
.
SplendorEnv
have several custom methods:get_legal_actions_mask
- a method for getting a mask vector which masks all the illegal action ofsplendor.Splendor.gym.envs.actions.ALL_ACTIONS
.
You can access those like this:
env.unwrapped.my_turn