Toribash Learning Environment. Extra "L" to make words more memorable for Finns ("Torille" = "To the marketplace").
ToriLLE provides learning agents an interface to video-game Toribash, a humanoid fighting game. Toribash provides environment for MuJoCo-like humanoid control, specifically aimed for competitive gameplay. This makes ToriLLE suitable for e.g. self-play experiments.
ToriLLE comes with a Python interface and pre-made OpenAI Gym environment with various tasks. Following white-paper includes baseline experiments and benchmarks conducted using ToriLLE: https://arxiv.org/abs/1807.10110
Tested to work on Windows 10, Ubuntu 16.04 and MacOS 10.13. Tested on Python versions 3.5 and 3.6, and will likely not work on 2.7.
- Numpy (Python)
- FileLock (Python)
- Wine (For Linux/MacOS. Requires modern version. Tested on 3.0.3)
Remember to install Wine if you are on Linux or MacOS. Make sure wine
command is defined.
Following will download ToriLLE with stripped down version of Toribash:
pip install git+https://github.com/miffyli/torille
Random agent:
from torille import ToribashControl
from torille.utils import create_random_actions
# Show gameplay
toribash = ToribashControl(draw_game=True)
toribash.init()
# Random agent
while 1:
state, t = toribash.get_state()
if t: break
toribash.make_actions(create_random_actions())
toribash.close()
OpenAI Gym environment:
import gym
import torille.envs
env = gym.make("Toribash-DestroyUke-v0")
# Show gameplay
env.set_draw_game(True)
initial_state = env.reset()
t = False
# Random agent
while not t:
s, r, t, _ = env.step(env.action_space.sample())
env.close()
You can install ToriLLE without PyPI/pip with the following:
- Install Toribash (note: Only Steam version may be up to date)
- Copy contents of
toribash-codes
to Toribash installation directory. Overwrite files- Note: This will prevent using that specific installation as a regular game. Remove/rename
profile.tbs
file to revert most of the changes and use game normally again. - Note2: Starting with Toribash 5.4 / Steam version of Toribash, settings file is stored in under user's directory at
Saved Games/Toribash/custom.cfg
. Toribash loads this file by default if it finds it, which may cause ToriLLE to run in wrong settings.
- Note: This will prevent using that specific installation as a regular game. Remove/rename
- Provide path the installed
toribash.exe
when creatingToribashControl
objects (if you use provided Python library)
Want to try your agents against human players in multiplayer? Check how manual remote control works.
Examples in examples
provide quickstart to how to use ToriLLE, and also show how to apply settings or
record replays.
For references see:
For troubleshooting, see the FAQ.
If you wish to modify ToriLLE or use other language to control Toribash instance, see hacking and documentation on protocol.
./torille/
: Python codes for the learning environment (inc. Gym environment)./torille/toribash
: This includes stripped version of the Toribash game when installed from PyPi
./toribash-codes/
: Files required for Toribash to make this learning environment work./examples/
: Python examples on how to use this library./docs/
: Detailed documentation of the inner workings./experiments/
: Codes used to run experiments in the white paper./images/
: Contains GIFs used here
- Options/chat rules: http://forum.toribash.com/showthread.php?t=317900
- Lua functions: https://github.com/trittimo/ToriScriptAPI/blob/master/docs/toribash_docs.txt
- Bodypart list: http://forum.toribash.com/showthread.php?t=9391
- Previous experiments at machine learning with Toribash:
- http://forum.toribash.com/showthread.php?t=170100
- http://forum.toribash.com/showthread.php?t=167355
- http://forum.toribash.com/showthread.php?t=25263
- https://www.researchgate.net/profile/Jonathan_Byrne/publication/228848637_Optimising_offensive_moves_in_toribash_using_a_genetic_algorithm/links/0046351420d5001396000000.pdf
We wouldn't mind a citation if you find ToriLLE useful in your work. It also helps us to see what people have been up to!
@inproceedings{kanervisto2019torille,
title={ToriLLE: Learning Environment for Hand-to-Hand Combat},
author={Kanervisto, Anssi and Hautam{\"a}ki, Ville},
booktitle={2019 IEEE Conference on Games (CoG)},
year={2019},
}
- hampa and Dranix for invaluable help with configuring Toribash and lua scripts (also for developing the game in the first place!)
- Siim Põder (user "windo" on GitHub) for original toribash-evolver code
- box (Toribash user) for comments during inception of this project
Code original to ToriLLE is licensed under GNU GPL 3.0. Toribash is property of Nabistudios. Toribash binary in this package is shared with the permission of main developer "hampa".