{"id":24009384,"url":"https://github.com/prgrmcode/ai-dungeon-game","last_synced_at":"2026-05-02T22:32:11.860Z","repository":{"id":271175476,"uuid":"909869682","full_name":"prgrmcode/ai-dungeon-game","owner":"prgrmcode","description":"AI powered Dungeon adventure game is an advanced text-based adventure game powered by Large Language Models. ","archived":false,"fork":false,"pushed_at":"2025-01-06T03:56:38.000Z","size":312,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-06T04:17:52.284Z","etag":null,"topics":["gradio","huggingface-transformers","llama3","llms","python","safety"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prgrmcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-29T23:51:36.000Z","updated_at":"2025-01-06T03:56:42.000Z","dependencies_parsed_at":"2025-01-06T04:18:05.974Z","dependency_job_id":"651170a7-7a30-4a91-b972-373b810839e4","html_url":"https://github.com/prgrmcode/ai-dungeon-game","commit_stats":null,"previous_names":["prgrmcode/ai-dungeon-game"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prgrmcode%2Fai-dungeon-game","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prgrmcode%2Fai-dungeon-game/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prgrmcode%2Fai-dungeon-game/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prgrmcode%2Fai-dungeon-game/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prgrmcode","download_url":"https://codeload.github.com/prgrmcode/ai-dungeon-game/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234809020,"owners_count":18890104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gradio","huggingface-transformers","llama3","llms","python","safety"],"created_at":"2025-01-08T03:45:13.249Z","updated_at":"2026-05-02T22:32:11.855Z","avatar_url":"https://github.com/prgrmcode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: AI Dungeon Game\nemoji: 🎮\ncolorFrom: indigo\ncolorTo: purple\nsdk: gradio\nsdk_version: 5.9.1\napp_file: main.py\npinned: false\n---\n\n# AI-Powered Dungeon Adventure Game\n\n## Table of Contents\n- [Overview](#overview)\n- [Technical Architecture](#technical-architecture)\n- [Key Features](#key-features)\n- [Game Mechanics](#game-mechanics)\n- [AI/ML Implementation](#aiml-implementation)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Project Structure](#project-structure)\n- [Technologies Used](#technologies-used)\n- [Future Enhancements](#future-enhancements)\n- [Requirements](#requirements)\n- [Deployment Options](#deployment-options)\n- [Final Words](#final-words)\n\n\n\n## Overview\nAn advanced text-based adventure game powered by Large Language Models (LLMs) that demonstrates the practical application of AI/ML in interactive entertainment. The game features dynamic quest generation, intelligent NPC interactions, and content safety validation using state-of-the-art language models.\n\n![AI Dungeon Gameplay Demo](assets/AI_Dungeon_Game.gif)\n*Gameplay demonstration showing prompts and responses*\n\n## Technical Architecture\n- **Core Engine**: Python-based game engine with modular architecture\n- **AI Integration**: Hugging Face Transformers pipeline for text generation\n- **UI Framework**: Gradio for interactive web interface\n- **Safety Layer**: LLaMA Guard for content moderation\n- **State Management**: Dynamic game state handling with quest progression\n- **Memory Management**: Optimized for GPU utilization with 8-bit quantization\n\n## Key Features\n1. **Dynamic Quest System**\n   - Procedurally generated quests based on player progress\n   - Multi-chain quest progression\n   - Experience-based leveling system\n\n2. **Intelligent Response Generation**\n   - Context-aware narrative responses\n   - Dynamic world state adaptation\n   - Natural language understanding (NLP)\n\n3. **Advanced Safety System**\n   - Real-time content moderation\n   - Multi-category safety checks\n   - Cached response validation\n\n4. **Inventory Management**\n   - Dynamic item tracking\n   - Automated inventory updates\n   - Natural language parsing for item detection\n\n## Game Mechanics\n- **Dungeon Generation:** Randomly generated dungeons with obstacles.\n- **Player and NPCs:** Players can move, fight NPCs, and use items.\n- **Combat System:** Turn-based combat with simple AI decision-making.\n- **Inventory Management:** Collect and use items to aid in your adventure.\n- **Quest System:** Complete quests to earn rewards and progress through the game.\n\n\n## AI/ML Implementation\n1. **Language Models**\n   - Primary: LLaMA-3.2-3B-Instruct\n   - Safety: LLaMA-Guard-3-1B\n   - Optimized with 8-bit quantization\n\n2. **Natural Language Processing**\n   - Context embedding\n   - Response generation\n   - Content safety validation\n\n3. **Memory Optimization**\n   - GPU memory management\n   - Response caching\n   - Efficient token handling\n\n## Installation\n```bash\n# Clone repository\ngit clone https://github.com/prgrmcode/ai-dungeon-game.git\ncd ai-dungeon-game\n\n# Create virtual environment\npython -m venv dungeon-env\nsource dungeon-env/Scripts/activate  # Windows\nsource dungeon-env/bin/activate      # Linux/Mac\n\n# Install dependencies (`pip freeze \u003e requirements.txt` to get requirements)\npip install -r requirements.txt\n# Or install libraries directly:\npip install numpy matplotlib pygame\npip install python-dotenv\npip install transformers\npip install gradio\npip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118\npip install psutil\npip install 'accelerate\u003e=0.26.0'\n\n# Create a .env file in the root directory of the project and add your environment variables:\nHUGGINGFACE_API_KEY=your_api_key_here\n```\n\n## Usage\n```bash\n# Run the game locally using gpu-compute branch\ngit checkout gpu-compute\npython main.py\n\n# Start the game using deployed main branch\ngit checkout main\npython main.py\n\n# Access via web browser\nhttp://localhost:7860\n# or:\nhttp://127.0.0.1:7860\n```\n\n## Project Structure\n```\nai_dungeon_game/\n├── assets/\n│   └── ascii_art.py\n├── game/\n│   ├── combat.py\n│   ├── dungeon.py\n│   ├── items.py\n│   ├── npc.py\n│   └── player.py\n├── shared_data/\n│   └── Ethoria.json\n├── helper.py\n└── main.py\n```\n\n## Technologies Used\n- **Python 3.10+**\n- **PyTorch**: Deep learning framework\n- **Transformers**: Hugging Face's transformer models\n- **Gradio**: Web interface framework\n- **CUDA**: GPU acceleration\n- **JSON**: Data storage\n- **Logging**: Advanced error tracking\n\n## Skills Demonstrated\n1. **AI/ML Engineering**\n   - Large Language Model implementation\n   - Model optimization\n   - Prompt engineering\n   - Content safety systems\n\n2. **Software Engineering**\n   - Clean architecture\n   - Object-oriented design\n   - Error handling\n   - Memory optimization\n\n3. **Data Science**\n   - Natural language processing\n   - State management\n   - Data validation\n   - Pattern recognition\n\n4. **System Design**\n   - Modular architecture\n   - Scalable systems\n   - Memory management\n   - Performance optimization\n\n## Future Enhancements\n1. **Advanced AI Features**\n   - Multi-modal content generation\n   - Improved context understanding\n   - Dynamic difficulty adjustment\n\n2. **Technical Improvements**\n   - Distributed computing support\n   - Advanced caching mechanisms\n   - Real-time model updating\n\n3. **Gameplay Features**\n   - Choose character at the beginning\n   - Multiplayer support\n   - Advanced combat system\n   - Dynamic world generation\n\n4. **Visual Enhancements**\n   - **Graphical User Interface (GUI):** Implement a GUI using Pygame to provide a more interactive and visually appealing experience.\n\n   - **2D/3D Graphics:** Use libraries like Pygame or Pyglet for 2D graphics.\n\n   - **Animations:** Add animations for player and NPC movements, combat actions, and other in-game events.\n\n   - **Visual Effects:** Implement visual effects such as particle systems for magic spells, explosions, and other dynamic events.\n\n   - **Map Visualization:** Create a visual representation of the dungeon map that updates as the player explores.\n\n\n## Requirements\n- Python 3.10+\n- CUDA-capable GPU (recommended)\n- 8GB+ RAM\n- Hugging Face API key\n\n\n## Deployment Options\n\n### Local Docker Deployment\n```bash\n# Build and run with Docker\ndocker-compose --env-file .env up --build\n```\n\n### Hugging Face Spaces Deployment\n1. Fork repository\n2. Connect to Hugging Face Spaces\n3. Deploy through GitHub Actions\n\n### AWS Deployment\n\n1. Push to ECR:\n```bash\naws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com\ndocker build -t ai-dungeon .\ndocker tag ai-dungeon:latest $AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/ai-dungeon:latest\ndocker push $AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/ai-dungeon:latest\n```\n\n2. Deploy to ECS/EKS\n\n\n### Kubernetes Deployment\n\n```bash\nkubectl apply -f kubernetes/\n```\n\n## Final Words\n\nThank you for exploring the AI Dungeon Game! This project showcases:\n\n- Practical AI/ML implementation in interactive gaming\n- Clean, maintainable code following best practices\n- Robust security with input validation and safety checks\n- Performance optimization and scalable architecture\n\nThe codebase demonstrates strong software engineering principles while creating an engaging gaming experience. Your feedback and contributions are invaluable in making this game even better.\n\nHappy adventuring in the world of AI-powered dungeons! 🎮\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprgrmcode%2Fai-dungeon-game","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprgrmcode%2Fai-dungeon-game","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprgrmcode%2Fai-dungeon-game/lists"}