An interactive fantasy role-playing game powered by GitHub Issues and AI!
You've all seen those usual GitHub README's containing a list of skills, projects, about, etc. Well, that tends to get boring after a while. So, Presenting you with something that's actually fun and engaging!
Create your character, explore a rich fantasy world, and embark on epic adventures—all through GitHub Issues!
🚀 Quick Start • ⚔️ Choose Your Class • 📊 Game Stats • 📖 How to Play
Starting your adventure is simple!
- Choose your class below (click a class button)
- Your character is created automatically when you open the issue
- Start playing by commenting with actions like "I explore the forest"
💡 Pro Tip: Your character name will be your GitHub profile name automatically!
Click on a class below to start your adventure! Each class has unique abilities and stat bonuses.
|
High strength and constitution
|
High intelligence and wisdom
|
High dexterity and stealth
|
High wisdom and healing
|
|
Balanced dexterity and wisdom
|
Balanced strength and wisdom
|
High charisma and magic
|
High dexterity and wisdom
|
|
High intelligence and charisma
|
High wisdom and nature magic
|
High intelligence and charisma
|
High strength and constitution
|
- Click a class button above to create your character
- Your character is automatically created when the issue opens
- Start playing by commenting with natural language actions
Simply comment on your issue with actions in plain English:
I explore the forest
I talk to the merchant
I cast a fireball at the goblin
I search for treasure
I rest at the inn
I buy a sword from the blacksmith
The AI game master will interpret your actions and respond with immersive narrative!
Your character has:
- Health & Mana: Your life force and magical energy
- Six Core Attributes: Strength, Dexterity, Intelligence, Wisdom, Constitution, Charisma
- Level & Experience: Grow stronger as you play
- Gold & Inventory: Collect items and wealth
- Active Quests: Complete missions for rewards
Explore a rich fantasy world with:
- 🏘️ Villages & Cities: Safe havens to rest, trade, and receive quests
- 🏰 Dungeons & Caves: Dangerous areas filled with monsters and treasure
- 🌲 Forests & Wilderness: Discover resources, encounters, and secrets
- 👥 NPCs: Characters to interact with, trade with, or receive quests from
- 👹 Monsters: Creatures to fight for experience and loot
Each issue is locked to its creator. This ensures your adventure is personal and uninterrupted. Create your own issue to start playing!
Here are some actions you can try:
| Action Type | Examples |
|---|---|
| Exploration | I explore the dark forestI investigate the mysterious caveI walk to the market |
| Combat | I attack the bandit with my swordI cast a fireball at the goblinI defend against the dragon's breath |
| Interaction | I talk to the village elderI ask the merchant about rare itemsI accept the quest to find the lost artifact |
| Items | I buy a sword from the blacksmithI use my potion of healingI search for hidden treasure |
| Rest | I rest at the innI meditate to restore manaI sleep until morning |
Want to run this game in your own repository?
- Fork this repository
- Enable GitHub Actions in repository settings
- Add
GROK_API_KEYsecret (get your key from X.AI) - Create
game-activelabel in Issues → Labels - Start playing!
For detailed setup instructions, see SETUP.md.
- Player creates issue with
game-activelabel (or clicks class button) - GitHub Action triggers on issue creation
- Character is auto-created using GitHub profile name
- Game state is saved in the issue body
- Player comments with actions in natural language
- Grok AI interprets actions with full game context
- Lore validator ensures responses follow game rules
- Game state updates and AI responds with narrative
Customize your game by editing:
docs/lore.md: World lore and game rulesscripts/lore-validator.js: Validation rulesscripts/character-manager.js: Character creation logicscripts/game-engine.js: Game mechanics
Contributions are welcome! Feel free to:
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit pull requests
- 📖 Improve documentation
This project is licensed under the MIT License - see the LICENSE file for details.
Choose your class above and begin your journey in Aetheria! ✨
Made with ❤️ and AI magic