A multi-mode game engine supporting both story-driven incremental RPG and traditional MUD (Multi-User Dungeon) gameplay through a unified AWS backend.

Eidolon Engine provides three deployment modes with a fully automated infrastructure deployment system:

• MUD Mode: Traditional Multi-User Dungeon without story features
• Incremental Mode: Story-driven gameplay with narrative progression
• Hybrid Mode: Full feature set combining MUD and story elements (default)

The system features a complete end-to-end deployment pipeline that provisions all AWS infrastructure and automatically deploys the frontend application.

• Character progression through skills and attributes (no levels)
• Timer-based incremental gameplay mechanics
• Real-time MUD interactions via SSH
• Persistent game state across sessions

• AWS Lambda backend for all game logic (23 functions)
• DynamoDB for data persistence (14 tables)
• Infrastructure as Code using AWS CDK (9 stacks)
• Fully automated deployment with portal build
• Three deployment modes with dynamic stack ordering
• Fixed logical IDs preventing resource recreation
• Post-deployment Lambda updates from S3 artifacts
• Flutter web applications with IndexedDB caching
• Go-based SSH server for MUD mode
• Lua scripting for game mechanics and content

The engine uses a modern cloud-native architecture with a unified backend serving multiple frontends:

• Frontend Applications:

  • Flutter web app for incremental gameplay (/incremental)
  • Flutter portal for MUD web interface (/portal)
  • SSH server for traditional MUD access (/server)

• Unified Backend Services (shared by all game modes):

  • AWS Lambda functions for all game logic (/lambda)
  • DynamoDB tables for persistent game state
  • Character GameMode field prevents concurrent MUD/Incremental access
  • S3 for content storage and scripts
  • Cognito for unified authentication
  • API Gateway providing RESTful endpoints

• Shared Libraries:

  • Python utilities for AWS services (/eidolon)
  • Lua scripts for MUD game mechanics (/scripts_lua)

• Python 3.12
• Go 1.24+ (for MUD server)
• Flutter 3.32+ (for web interfaces)
• AWS CLI configured with appropriate credentials
• AWS CDK 2.x

1. Clone the repository:

   git clone https://github.com/robinje/eidolon-engine.git
   cd eidolon-engine

2. Deploy AWS infrastructure:

   cd deployment
   pip install -r ../requirements/deployment-requirements.txt
   python deploy.py

3. Deployment Process:

   The deployment system will:

   • Prompt for configuration (AWS region, domain, deployment mode)
   • Deploy infrastructure in the correct order based on selected mode
   • Build Lambda functions and layer automatically
   • Execute portal build and deploy to CloudFront
   • Display the portal URL upon completion

4. Deployment Modes:

   • MUD Mode: Traditional MUD without story features (uses portal.yml buildspec)
   • Incremental Mode: Story-driven gameplay (uses incremental.yml buildspec)
   • Hybrid Mode: Full feature set (default, uses incremental.yml buildspec)

5. Access your game:

   • Portal URL: https://portal.yourdomain.com (displayed after deployment)
   • API endpoint: https://api.yourdomain.com
   • SSH server can be run locally or on EC2 (MUD mode)

Status: Production-ready and fully functional.

Status: Core gameplay functional, but critical mechanics broken.

• ✅ Character creation and progression
• ✅ Story progression and branching narratives
• ✅ Skill/attribute XP system
• ✅ Combat mechanics (rounds execute, wounds apply)
• ⚠️ Item drops (items acquired but names not displayed)
• ❌ Inventory display (players see UUIDs instead of item names)
• ❌ Death mechanics (dead characters can continue playing)
• ❌ Currency rewards (broken - applies 0 gold)
• ❌ Store system (not implemented)
• ❌ Item consumption (not implemented)

Current State: Players can create characters, run stories, gain XP, and collect items. However, inventory displays raw UUIDs instead of item names ("a47ac10b-..." instead of "Healing Potion"), dead characters become immortal zombies that can play indefinitely, and no currency is earned. The economy loop (earn currency → buy items → use items) is incomplete.

Details: See Incremental Status Document for a complete code-level analysis of what works, what's broken, and what's missing.

Comprehensive documentation is available in the /documentation directory:

• Incremental Implementation Status - Current state analysis (updated regularly)
• Deployment Design - Architecture and infrastructure design
• Deployment Guide - Step-by-step deployment instructions
• Incremental Game Design - Game system design
• Game Mechanics - Core gameplay mechanics
• API Reference - Lambda function specifications

eidolon-engine/
├── incremental/          # Flutter incremental game UI
├── portal/              # Flutter web portal for MUD
├── server/              # Go MUD server (SSH)
├── lambda/              # AWS Lambda functions
├── eidolon/             # Shared Python libraries
├── deployment/          # CDK infrastructure code
├── scripts_lua/         # Lua game scripts
├── documentation/       # Project documentation
└── data/               # Game configuration data

• Python Style Guide - Python coding standards
• Flutter Style Guide - Flutter/Dart conventions
• AWS Style Guide - Infrastructure patterns
• Documentation Style Guide - Writing standards

Each component can be developed independently:

# Incremental UI
cd incremental
flutter run -d chrome

# MUD Server
cd server
go run .

# Deploy infrastructure changes
cd deployment
python deploy.py --analyze-only

Choose the deployment mode based on your game focus:

• MUD Mode: Excludes story features, uses traditional MUD interface (portal.yml)
• Incremental Mode: Excludes S3/CloudWatch stacks, uses story interface (incremental.yml)
• Hybrid Mode (Default): All features enabled, uses story interface (incremental.yml)

The deployment automatically adjusts stack order and buildspec selection based on the chosen mode.

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

• GitHub Issues: For bug reports and feature requests
• Email: contact@darkrelics.net