EldenGym 🎮

A Gymnasium-compatible reinforcement learning environment for Elden Ring.

🚀 Quick Start

import gymnasium as gym
import eldengym

# Create environment
env = gym.make("EldenGym-v0", scenario_name="margit")

# Standard RL loop
obs, info = env.reset()
for _ in range(1000):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)

    if terminated or truncated:
        obs, info = env.reset()

env.close()

✨ Features

• 🎯 Gymnasium API - Standard RL interface
• 🎮 Multiple Action Spaces - Discrete, multi-binary, or continuous
• 📊 Flexible Observations - RGB frames, game state, or both
• ⚡ High Performance - gRPC-based C++ backend
• 🔧 Customizable - Easy reward functions and wrappers
• 🏆 Boss Scenarios - Pre-configured boss fights

📚 Documentation

Read the full documentation →

• Installation Guide
• Quick Start Tutorial
• API Reference
• Examples

🔧 Installation

From PyPI (Stable Release)

pip install eldengym

From Source (Development)

# Clone repository
git clone https://github.com/dhmnr/eldengym.git
cd eldengym

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

🎮 Usage Examples

With Stable-Baselines3

from stable_baselines3 import PPO
import gymnasium as gym

env = gym.make("EldenGym-v0", scenario_name="margit")
model = PPO("CnnPolicy", env, verbose=1)
model.learn(total_timesteps=100_000)

Custom Reward Function

def custom_reward(obs, info, terminated, truncated):
    reward = 0.0
    if 'target_hp_delta' in info:
        reward += info['target_hp_delta'] * 10.0
    return reward

env = gym.make("EldenGym-v0", reward_function=custom_reward)

📖 Examples

Check out the examples directory:

• random_policy.ipynb - Random agent baseline
• llm_agent.ipynb - LLM-based agent

🛠️ Development

# Install dev dependencies
uv sync --group dev --group test --group docs

# Run tests
uv run pytest

# Format code
uv run ruff format .

# Serve documentation locally
uv run mkdocs serve

📋 Requirements

• Elden Ring (PC version)
• Siphon Server (C++ gRPC backend)
• Python 3.10+
• Windows (for game interaction)

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Gymnasium
• Documentation powered by MkDocs Material

📧 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

⭐ Star this repo if you find it useful!