https://github.com/facebookresearch/nle Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code + Explore + All features + Documentation + GitHub Skills + Blog * Solutions + By Plan + Enterprise + Teams + Compare all + By Solution + CI/CD & Automation + DevOps + DevSecOps + Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles + Repositories + Topics + Trending + Collections * Pricing [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} facebookresearch / nle Public * Notifications * Fork 90 * Star 776 The NetHack Learning Environment License View license 776 stars 90 forks Star Notifications * Code * Issues 9 * Pull requests 8 * Actions * Projects 1 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights facebookresearch/nle This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 31 branches 14 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/f] Use Git or checkout with SVN using the web URL. [gh repo clone facebo] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP * Codespaces is rolling out You don't have access just yet, but in the meantime, you can learn about Codespaces Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @condnsdmatters condnsdmatters Change the name of the altorg test files for Windows, to fix issue #341... ... 68b9362 Nov 2, 2022 Change the name of the altorg test files for Windows, to fix issue # 341... ... (#343) 68b9362 Git stats * 9,727 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .circleci Make sure we follow the latest speech guidelines. (#247) Sep 15, 2021 .github Change clang-format workflow. Dec 1, 2021 DEVEL typo fix Dec 10, 2018 dat Updates to cmake (#310) Feb 2, 2022 doc Make sure we follow the latest speech guidelines. (#247) Sep 15, 2021 docker Suggest --gpus all flag when running our Dockerfiles. Oct 8, 2021 include Add the filepath of the ttyrec if it exists to the xlogfile. May 16, 2022 nle Change the name of the altorg test files for Windows, to fix issue # 341... Nov 2, 2022 src Test and fix for issue 333. (#334) Aug 5, 2022 sys Fail if libnethack is resident before dlopening. (#311) Feb 4, 2022 third_party Set the terminal emulator to by default not wrap extra long lines, (# 330 Jun 16, 2022 util For the GNU Makefile generator, creating NLE_SRC_GEN first is required. Dec 1, 2021 win Ensure that if no ttyrec is found, you wipe the ttyrecname before May 16, 2022 .clang-format Add clang-formatting file. May 25, 2015 .flake8 Add isort to pre-commit and lint_python.yml workflow, apply isort. (# 227 Jul 26, 2021 .gitattributes update Files attributes with priorities and %s substitution Jun 1, 2018 .gitignore Add pycharm project configs to .gitignore. Sep 23, 2020 .gitmodules Commit of libtmt into source. Apr 28, 2022 .pre-commit-config.yaml Bump up pre-commit config for Black. Aug 5, 2022 .travis.yml clear travis boolean prerelease flag as well Mar 7, 2020 CITATION.cff Add CITATION.cff file. (#295) Dec 16, 2021 CMakeLists.txt Make converter statically linked, instead of dynamically. Apr 28, 2022 CODE_OF_CONDUCT.md Add NLE public version 0.1 May 4, 2020 CONTRIBUTING.md Make sure we follow the latest speech guidelines. (#247) Sep 15, 2021 DATASET.md Add NLD to the README.md and create instructions and tutorial for NLD. ( Nov 1, 2022 Files Add NLE public version 0.1 May 4, 2020 Files.nh Add NLE public version 0.1 May 4, 2020 Files.nle Remove run-clang-format script. Dec 1, 2021 LICENSE Add NLE public version 0.1 May 4, 2020 MANIFEST.in Remove run-clang-format script. Dec 1, 2021 Porting add missing copyright info Apr 25, 2018 README.md Add NLD to the README.md and create instructions and tutorial for NLD. ( Nov 1, 2022 README.nh Add NLE public version 0.1 May 4, 2020 pyproject.toml Add isort to pre-commit and lint_python.yml workflow, apply isort. (# 227 Jul 26, 2021 setup.py Pin gym to 0.23.0 temporarily. Jun 9, 2022 version.txt Bump version. Dec 16, 2021 View code [ ] NLE Language Wrapper NetHack Learning Dataset Papers using the NetHack Learning Environment Getting started Installation Docker Trying it out Contributing Architecture Related Environments Interview about the environment with Weights&Biases Citation README.md NetHack Learning Environment (NLE) --------------------------------------------------------------------- [6874747073] [badge] [6874747073] [6874747073] Twitter The NetHack Learning Environment (NLE) is a Reinforcement Learning environment presented at NeurIPS 2020. NLE is based on NetHack 3.6.6 and designed to provide a standard RL interface to the game, and comes with tasks that function as a first step to evaluate agents on this new environment. NetHack is one of the oldest and arguably most impactful videogames in history, as well as being one of the hardest roguelikes currently being played by humans. It is procedurally generated, rich in entities and dynamics, and overall an extremely challenging environment for current state-of-the-art RL agents, while being much cheaper to run compared to other challenging testbeds. Through NLE, we wish to establish NetHack as one of the next challenges for research in decision making and machine learning. You can read more about NLE in the NeurIPS 2020 paper, and about NetHack in its original README, at nethack.org, and on the NetHack wiki. Example of an agent running on NLE NLE Language Wrapper We thank ngoodger for implementing the NLE Language Wrapper that translates the non-language observations from NetHack tasks into similar language representations. Actions can also be optionally provided in text form which are converted to the Discrete actions of the NLE. NetHack Learning Dataset The NetHack Learning Dataset (NLD) code now ships with NLE, allowing users to the load large-scale datasets featured in Dungeons and Data: A Large-Scale NetHack Dataset, while also generating and loading their own datasets. import nle.dataset as nld if not nld.db.exists(): nld.db.create() # NB: Different methods are used for data based on NLE and data from NAO. nld.add_nledata_directory("/path/to/nld-aa", "nld-aa-v0") nld.add_altorg_directory("/path/to/nld-nao", "nld-nao-v0") dataset = nld.TtyrecDataset("nld-aa-v0", batch_size=128, ...) for i, mb in enumerate(dataset): foo(mb) # etc... For information on how to download NLD-AA and NLD-NAO, see the dataset doc here. Otherwise checkout the tutorial Colab notebook here. Papers using the NetHack Learning Environment * Izumiya and Simo-Serra Inventory Management with Attention-Based Meta Actions (Waseda University, CoG 2021). * Samvelyan et al. MiniHack the Planet: A Sandbox for Open-Ended Reinforcement Learning Research (FAIR, UCL, Oxford, NeurIPS 2021). * Zhang et al. BeBold: Exploration Beyond the Boundary of Explored Regions (Berkley, FAIR, Dec 2020). * Kuttler et al. The NetHack Learning Environment (FAIR, Oxford, NYU, Imperial, UCL, NeurIPS 2020). Open a pull request to add papers. Getting started Starting with NLE environments is extremely simple, provided one is familiar with other gym / RL environments. Installation NLE requires python>=3.5, cmake>=3.15 to be installed and available both when building the package, and at runtime. On MacOS, one can use Homebrew as follows: $ brew install cmake On a plain Ubuntu 18.04 distribution, cmake and other dependencies can be installed by doing: # Python and most build deps $ sudo apt-get install -y build-essential autoconf libtool pkg-config \ python3-dev python3-pip python3-numpy git flex bison libbz2-dev # recent cmake version $ wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add - $ sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main' $ sudo apt-get update && apt-get --allow-unauthenticated install -y \ cmake \ kitware-archive-keyring Afterwards it's a matter of setting up your environment. We advise using a conda environment for this: $ conda create -y -n nle python=3.8 $ conda activate nle $ pip install nle NOTE: If you want to extend / develop NLE, please install the package as follows: $ git clone https://github.com/facebookresearch/nle --recursive $ pip install -e ".[dev]" $ pre-commit install Docker We have provided some docker images. Please see the relevant README. Trying it out After installation, one can try out any of the provided tasks as follows: >>> import gym >>> import nle >>> env = gym.make("NetHackScore-v0") >>> env.reset() # each reset generates a new dungeon >>> env.step(1) # move agent '@' north >>> env.render() NLE also comes with a few scripts that allow to get some environment rollouts, and play with the action space: # Play NetHackStaircase-v0 as a human $ python -m nle.scripts.play # Use a random agent $ python -m nle.scripts.play --mode random # Play the full game using directly the NetHack internal interface # (Useful for debugging outside of the gym environment) $ python -m nle.scripts.play --env NetHackScore-v0 # works with random agent too # See all the options $ python -m nle.scripts.play --help Note that nle.scripts.play can also be run with nle-play, if the package has been properly installed. Additionally, a TorchBeast agent is bundled in nle.agent together with a simple model to provide a starting point for experiments: $ pip install "nle[agent]" $ python -m nle.agent.agent --num_actors 80 --batch_size 32 --unroll_length 80 --learning_rate 0.0001 --entropy_cost 0.0001 --use_lstm --total_steps 1000000000 Plot the mean return over the last 100 episodes: $ python -m nle.scripts.plot averaged episode return 140 +---------------------------------------------------------------------+ | + + ++-+ ++++++++++++++++++++++++| | : : ++++++++|||||||||||||||||||||||| 120 |-+...........:.............:...+-+.++++||||||||||||||||||||||||||||||| | : +++++++++++++++||||||||||AAAAAAAAAAAAAAAAAAAAAA| | +++++++++++++||||||||||||||AAAAAAAAAAAA||||||||||||||||||| 100 |-+......+++++|+|||||||||||||||||||||||AA|||||||||||||||||||||||||||||| | +++|||||||||||||||AAAAAAAAAAAAAA|||||||||||+++++++++++++++++++| | ++++|||||AAAAAAAAAAAAAA||||||||||||++++++++++++++-+: | 80 |-++++|||||AAAAAA|||||||||||||||||||||+++++-+...........:...........+-| | ++|||||AAA|||||||||||||||++++++++++++-+ : : | 60 |++||AAAAA|||||+++++++++++++-+............:.............:...........+-| |++|AA||||++++++-|-+ : : : | |+|AA|||+++-+ : : : : | 40 |+|A+++++-+...:.............:.............:.............:...........+-| |+AA+-+ : : : : | |AA-+ : : : : | 20 |AA-+.........:.............:.............:.............:...........+-| |++-+ : : : : | |+-+ : : : : | 0 |-+...........:.............:.............:.............:...........+-| |+ : : : : | |+ + + + + | -20 +---------------------------------------------------------------------+ 0 2e+08 4e+08 6e+08 8e+08 1e+09 steps Contributing We welcome contributions to NLE. If you are interested in contributing please see this document. Architecture NLE is direct fork of NetHack and therefore contains code that operates on many different levels of abstraction. This ranges from low-level game logic, to the higher-level administration of repeated nethack games, and finally to binding of these games to Python gym environment. If you want to learn more about the architecture of nle and how it works under the hood, checkout the architecture document. This may be a useful starting point for anyone looking to contribute to the lower level elements of NLE. Related Environments * gym_nethack * rogueinabox * rogue-gym * MiniGrid * CoinRun * MineRL * Project Malmo * OpenAI Procgen Benchmark * Obstacle Tower Interview about the environment with Weights&Biases Facebook AI Research's Tim & Heiner on democratizing reinforcement learning research. Interview with Weigths&Biases Citation If you use NLE in any of your work, please cite: @inproceedings{kuettler2020nethack, author = {Heinrich K{\"{u}}ttler and Nantas Nardelli and Alexander H. Miller and Roberta Raileanu and Marco Selvatici and Edward Grefenstette and Tim Rockt{\"{a}}schel}, title = {{The NetHack Learning Environment}}, booktitle = {Proceedings of the Conference on Neural Information Processing Systems (NeurIPS)}, year = {2020}, } If you use NLD or the datasets in any of your work, please cite: @inproceedings{hambro2022dungeonsanddata, author = {Eric Hambro and Roberta Raileanu and Danielle Rothermel and Vegard Mella and Tim Rockt{\"{a}}schel and Heinrich K{\"{u}}ttler and Naila Murray}, title = {{Dungeons and Data: A Large-Scale NetHack Dataset}}, booktitle = {Thirty-sixth Conference on Neural Information Processing Systems Datasets and Benchmarks Track}, year = {2022}, url = {https://openreview.net/forum?id=zHNNSzo10xN} } About The NetHack Learning Environment Resources Readme License View license Code of conduct Code of conduct Security policy Security policy Stars 776 stars Watchers 29 watching Forks 90 forks Releases 14 v0.8.1 Latest Dec 16, 2021 + 13 releases Packages 0 No packages published Contributors 39 * @nhmall * @paxed * @heiner * @barthouse * @edran * @condnsdmatters * @nhkeni * @remirol * @yobibyte * @alkom * @rockt + 28 contributors Languages * C 90.9% * C++ 4.2% * Python 1.9% * Yacc 0.7% * Perl 0.5% * Makefile 0.3% * Other 1.5% Footer (c) 2022 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.