# EldenGym 🎮
[](https://pypi.org/project/eldengym/)
[](https://github.com/dhmnr/eldengym/actions/workflows/test.yml)
[](https://eldengym.dhmnr.sh/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Gymnasium-compatible reinforcement learning environment for Elden Ring.
## 🚀 Quick Start
```python
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 →](https://eldengym.dhmnr.sh/)**
- [Installation Guide](https://eldengym.dhmnr.sh/getting-started/installation/)
- [Quick Start Tutorial](https://eldengym.dhmnr.sh/getting-started/quickstart/)
- [API Reference](https://eldengym.dhmnr.sh/api/env/)
- [Examples](https://eldengym.dhmnr.sh/examples/random_policy/)
## 🔧 Installation
### From PyPI (Stable Release)
```bash
pip install eldengym
```
### From Source (Development)
```bash
# 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
```python
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
```python
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](examples/) directory:
- [`random_policy.ipynb`](examples/random_policy.ipynb) - Random agent baseline
- [`llm_agent.ipynb`](examples/llm_agent.ipynb) - LLM-based agent
## 🛠️ Development
```bash
# 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](https://eldengym.dhmnr.sh/development/contributing/).
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [Gymnasium](https://gymnasium.farama.org/)
- Documentation powered by [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)
## 📧 Contact
- Issues: [GitHub Issues](https://github.com/dhmnr/eldengym/issues)
- Discussions: [GitHub Discussions](https://github.com/dhmnr/eldengym/discussions)
---
⭐ Star this repo if you find it useful!
Raw data
{
"_id": null,
"home_page": null,
"name": "eldengym",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "deep-learning, elden-ring, game-ai, gymnasium, reinforcement-learning",
"author": null,
"author_email": "dhmnr <mail@dhmnr.sh>",
"download_url": "https://files.pythonhosted.org/packages/af/db/3d02b12b3bb076e38580e10a8070d657ffb2b9a4bbd2e7a79ec2293a52d6/eldengym-0.3.1.tar.gz",
"platform": null,
"description": "# EldenGym \ud83c\udfae\n\n[](https://pypi.org/project/eldengym/)\n[](https://github.com/dhmnr/eldengym/actions/workflows/test.yml)\n[](https://eldengym.dhmnr.sh/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA Gymnasium-compatible reinforcement learning environment for Elden Ring.\n\n## \ud83d\ude80 Quick Start\n\n```python\nimport gymnasium as gym\nimport eldengym\n\n# Create environment\nenv = gym.make(\"EldenGym-v0\", scenario_name=\"margit\")\n\n# Standard RL loop\nobs, info = env.reset()\nfor _ in range(1000):\n action = env.action_space.sample()\n obs, reward, terminated, truncated, info = env.step(action)\n\n if terminated or truncated:\n obs, info = env.reset()\n\nenv.close()\n```\n\n## \u2728 Features\n\n- \ud83c\udfaf **Gymnasium API** - Standard RL interface\n- \ud83c\udfae **Multiple Action Spaces** - Discrete, multi-binary, or continuous\n- \ud83d\udcca **Flexible Observations** - RGB frames, game state, or both\n- \u26a1 **High Performance** - gRPC-based C++ backend\n- \ud83d\udd27 **Customizable** - Easy reward functions and wrappers\n- \ud83c\udfc6 **Boss Scenarios** - Pre-configured boss fights\n\n## \ud83d\udcda Documentation\n\n**[Read the full documentation \u2192](https://eldengym.dhmnr.sh/)**\n\n- [Installation Guide](https://eldengym.dhmnr.sh/getting-started/installation/)\n- [Quick Start Tutorial](https://eldengym.dhmnr.sh/getting-started/quickstart/)\n- [API Reference](https://eldengym.dhmnr.sh/api/env/)\n- [Examples](https://eldengym.dhmnr.sh/examples/random_policy/)\n\n## \ud83d\udd27 Installation\n\n### From PyPI (Stable Release)\n\n```bash\npip install eldengym\n```\n\n### From Source (Development)\n\n```bash\n# Clone repository\ngit clone https://github.com/dhmnr/eldengym.git\ncd eldengym\n\n# Install with uv (recommended)\nuv sync\n\n# Or with pip\npip install -e .\n```\n\n## \ud83c\udfae Usage Examples\n\n### With Stable-Baselines3\n\n```python\nfrom stable_baselines3 import PPO\nimport gymnasium as gym\n\nenv = gym.make(\"EldenGym-v0\", scenario_name=\"margit\")\nmodel = PPO(\"CnnPolicy\", env, verbose=1)\nmodel.learn(total_timesteps=100_000)\n```\n\n### Custom Reward Function\n\n```python\ndef custom_reward(obs, info, terminated, truncated):\n reward = 0.0\n if 'target_hp_delta' in info:\n reward += info['target_hp_delta'] * 10.0\n return reward\n\nenv = gym.make(\"EldenGym-v0\", reward_function=custom_reward)\n```\n\n## \ud83d\udcd6 Examples\n\nCheck out the [examples](examples/) directory:\n\n- [`random_policy.ipynb`](examples/random_policy.ipynb) - Random agent baseline\n- [`llm_agent.ipynb`](examples/llm_agent.ipynb) - LLM-based agent\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# Install dev dependencies\nuv sync --group dev --group test --group docs\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run ruff format .\n\n# Serve documentation locally\nuv run mkdocs serve\n```\n\n## \ud83d\udccb Requirements\n\n- **Elden Ring** (PC version)\n- **Siphon Server** (C++ gRPC backend)\n- **Python 3.10+**\n- **Windows** (for game interaction)\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see our [Contributing Guide](https://eldengym.dhmnr.sh/development/contributing/).\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [Gymnasium](https://gymnasium.farama.org/)\n- Documentation powered by [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)\n\n## \ud83d\udce7 Contact\n\n- Issues: [GitHub Issues](https://github.com/dhmnr/eldengym/issues)\n- Discussions: [GitHub Discussions](https://github.com/dhmnr/eldengym/discussions)\n\n---\n\n\u2b50 Star this repo if you find it useful!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Gymnasium-compatible reinforcement learning environment for Elden Ring",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://eldengym.dhmnr.sh/",
"Homepage": "https://eldengym.dhmnr.sh/",
"Issues": "https://github.com/dhmnr/eldengym/issues",
"Repository": "https://github.com/dhmnr/eldengym"
},
"split_keywords": [
"deep-learning",
" elden-ring",
" game-ai",
" gymnasium",
" reinforcement-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d488188ddc6c0999a0c79fb3ebb5589890cff9a45716dbd418386a58609634c8",
"md5": "e9c28f3b7d259f8fd7f3faf58bba84b2",
"sha256": "b696786b1e083bc443eddf1c9a5bfe4527f70a7a09dc8d33b39693ca43f56827"
},
"downloads": -1,
"filename": "eldengym-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9c28f3b7d259f8fd7f3faf58bba84b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24965,
"upload_time": "2025-10-22T10:46:08",
"upload_time_iso_8601": "2025-10-22T10:46:08.160843Z",
"url": "https://files.pythonhosted.org/packages/d4/88/188ddc6c0999a0c79fb3ebb5589890cff9a45716dbd418386a58609634c8/eldengym-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "afdb3d02b12b3bb076e38580e10a8070d657ffb2b9a4bbd2e7a79ec2293a52d6",
"md5": "a5e0a6026a84426a9685634d222a4e03",
"sha256": "0b526da89a41f33315d8089a288cce74632ea9b8c60d61733f7b78bf6c180788"
},
"downloads": -1,
"filename": "eldengym-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "a5e0a6026a84426a9685634d222a4e03",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 240681,
"upload_time": "2025-10-22T10:46:09",
"upload_time_iso_8601": "2025-10-22T10:46:09.638125Z",
"url": "https://files.pythonhosted.org/packages/af/db/3d02b12b3bb076e38580e10a8070d657ffb2b9a4bbd2e7a79ec2293a52d6/eldengym-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 10:46:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dhmnr",
"github_project": "eldengym",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eldengym"
}
JSON
