Datasetpublic

strakammm/generals_io_replays

⚔️ Generals.io High-Rank Replay Dataset 🌟 Overview This dataset contains a curated collection of 1v1 game replays from the online strategy game generals.io, specifically designed for training high-level reinforcement learning agents 🤖. 🏆 High-Quality Matches: Includes games where at least one participant had a star rating of 70 or higher 📈, ensuring a baseline of quality and strategic depth. ✅ Clean Data: Carefully filtered to remove outliers, games with AFK… See the full description on the dataset page: https://huggingface.co/datasets/strakammm/generals_io_replays.

sourceHugging Faceapache-2.0updated 1y agoView on Hugging Face

5likes55downloads

Dataset Card

⚔️ Generals.io High-Rank Replay Dataset 🌟

Overview

This dataset contains a curated collection of 1v1 game replays from the online strategy game generals.io, specifically designed for training high-level reinforcement learning agents 🤖.

—🏆 High-Quality Matches: Includes games where at least one participant had a star rating of 70 or higher 📈, ensuring a baseline of quality and strategic depth.
—✅ Clean Data: Carefully filtered to remove outliers, games with AFK players, and trolls, providing a clean and focused dataset for agent training.
—🚀 Proven Effectiveness: An agent trained exclusively on this dataset has been shown to be capable of reaching a 60-star rating, demonstrating the sufficiency and quality of the provided replays.

Game Version

All replays were recorded on the game patch featuring an alternating priority turn system. However, extensive testing has shown that agents trained on this data generalize effectively to the newer priority system without requiring further training.

Dataset Structure & Documentation

The dataset is composed of individual JSON files, where each file represents a single game replay. For a detailed technical description of the replay format, please refer to the official (archived) documentation:

➡️ [http://dev.generals.io/replays (via Archive.org)](https://web.archive.org/web/20190917202205/http://dev.generals.io/replays)

The structure of each JSON object is as follows:

Field	Type	Description
`version`	`Integer`	The version number of the replay format.
`id`	`String`	A unique identifier for the replay.
`mapWidth`	`Integer`	The width of the game map in tiles.
`mapHeight`	`Integer`	The height of the game map in tiles.
`usernames`	`List[String]`	A list of the usernames for the players in the game. The index corresponds to the player's turn order.
`stars`	`List[Integer]`	The star rating of each player at the time the game was played.
`cities`	`List[Integer]`	A list of tile indices representing the locations of all neutral cities at the start of the game.
`cityArmies`	`List[Integer]`	The initial army count for each corresponding city in the `cities` list.
`generals`	`List[Integer]`	The starting tile indices for each player's general (home base).
`mountains`	`List[Integer]`	A list of tile indices for all impassable mountain tiles on the map.
`moves`	`List[List[Integer]]`	The core sequence of game actions. Each inner list is a move tuple, typically representing `[player_index, start_tile, end_tile, is_50%_move, turn_number]`.
`afks`	`List[]`	A list that would contain information on AFK players. This has been filtered and will always be empty.

Usage Example

This dataset is hosted on the Hugging Face Hub and can be loaded directly using the datasets library. Here is a showcase of how to load the dataset and inspect its contents.

python

from datasets import load_dataset

# 1. Load the dataset directly from the Hugging Face Hub
#    You may need to log in first: huggingface-cli login
print("Loading dataset...")
dataset = load_dataset("strakammm/generals_io_replays")

# The dataset is loaded into a DatasetDict, we'll use the 'train' split
train_dataset = dataset['train']

# 2. Print the total number of replays in the dataset
print(f"\nTotal number of replays: {len(train_dataset)}")

# 3. Iterate over the first few replays to showcase the data
print("\n--- Showcasing first 5 replays ---")
for i in range(5):
    replay = train_dataset[i]
    
    # Get the players and the number of moves
    players = replay['usernames']
    num_moves = len(replay['moves'])
    
    print(f"\nReplay {i+1}:")
    print(f"  Players: {players[0]} vs {players[1]}")
    print(f"  Total moves: {num_moves}")

print("\n------------------------------------")

Citation

If you use this dataset in your research, please cite the following paper:

bibtex

@misc{generals_rl,
      author    = {Matej Straka, Martin Schmid},
      title     = {Artificial Generals Intelligence: Mastering Generals.io with Reinforcement Learning},
      year      = {2025},
      eprint    = {2507.06825},
      archivePrefix = {arXiv},
      primaryClass = {cs.LG},
}