Welcome to the AIDungeon administrator guide! This section contains everything you need to know about installing, configuring, and managing the AIDungeon plugin on your Minecraft server.

• Installation Guide - How to install the plugin
• Configuration - Complete configuration options
• Admin Commands - Administrative commands
• Gemini API Setup - Setting up the Google Gemini AI API
• Custom Mobs Integration - Integrating with custom mob plugins
• Performance Tuning - Optimizing for your server
• Troubleshooting - Common issues and solutions

AIDungeon is a unique plugin that leverages Google's Gemini AI API to generate custom, procedural dungeons throughout your Minecraft world. Each dungeon is:

• Uniquely designed: No two dungeons are exactly alike
• Biome-appropriate: Dungeons match their environment
• AI-generated: Complete layouts created by artificial intelligence
• Feature-rich: Custom bosses, traps, puzzles, and treasure

• Minecraft Version: 1.21.5 or higher
• Server Software: Spigot or compatible forks (Paper recommended)
• Java Version: Java 21 or higher
• Minimum RAM: 2GB (4GB+ recommended)
• Gemini API Key: Required for AI generation (free tier available)
• Database: MySQL (recommended for larger servers) or SQLite (included)

• Dungeons spawn based on biome, world seed, and server configuration
• Generation happens automatically as players explore
• Customizable spawn rates and conditions

• Monitor player progress through dungeons
• Automatic tracking of room exploration
• Optional dungeon collapse after full exploration

• Unique boss for each dungeon
• Special abilities and attack patterns
• Configurable difficulty

• Compatible with custom mob plugins (MythicMobs, etc.)
• Economy plugin support (optional)
• Permission system integration

1. Follow the Installation Guide to set up the plugin
2. Obtain a Gemini API key using the Gemini API Setup guide
3. Configure the plugin using the Configuration guide
4. Test the plugin using the admin commands detailed in Admin Commands

As a server administrator, we recommend this workflow for setting up AIDungeon:

1. Install in test environment: Start by testing on a development server
2. Configure generation settings: Adjust dungeon spawn rates and biome weights
3. Test with multiple players: Ensure performance is acceptable
4. Integrate with other plugins: Set up custom mobs and other integrations
5. Deploy to production: Move to your live server
6. Monitor and adjust: Fine-tune settings based on player feedback

AIDungeon is designed to be lightweight, but AI generation can have performance implications. Key considerations:

• API Usage: Monitor your Gemini API usage to avoid unexpected costs
• Generation Frequency: Adjust spawn rates based on your server population
• Concurrent Generation: Limit the number of dungeons being generated simultaneously
• World Size: Consider memory usage for very large worlds with many dungeons

See Performance Tuning for detailed optimization strategies.

If you encounter issues not covered in this documentation:

• Check the Troubleshooting guide
• Visit our GitHub repository to report issues
• Join our community Discord for admin support

Remember that configuring the plugin optimally takes time and experimentation. Don't hesitate to start with conservative settings and adjust as you learn how the plugin performs on your specific server.

This guide covers how to install and set up the AIDungeon plugin on your Minecraft server.

Before installing AIDungeon, ensure your server meets these requirements:

• Minecraft Version: 1.21.5 or higher
• Server Software: Spigot or compatible forks (Paper recommended)
• Java Version: Java 21 or higher
• Minimum RAM: 2GB (4GB+ recommended)
• Database: MySQL (optional) or SQLite (included)
• Gemini API Key: Required for AI generation (see Gemini API Setup)

Download the latest version of AIDungeon from one of these sources:

• [Polymart Resource Page](https://polymart.org/resource/aidungeongenerator.7457)

• [Modrinth Resource Page](https://modrinth.com/plugin/ai-dungeon-generator)

1. Stop your Minecraft server if it's running
2. Navigate to your server's plugins directory
3. Copy the downloaded AIDungeon-x.x.x.jar file into this directory

1. Start your Minecraft server
2. The plugin will generate default configuration files
3. Once the server is fully started, stop it again to configure the plugin

1. Navigate to plugins/AIDungeon/
2. Open config.yml in a text editor
3. Configure the basic settings (see Configuration Guide for details)
4. Important: Add your Gemini API key in the configuration

   gemini:
     apiKey: "YOUR_API_KEY_HERE"

By default, AIDungeon uses SQLite, which requires no additional setup. For larger servers, MySQL is recommended:

1. Create a MySQL database for AIDungeon

   CREATE DATABASE aidungeon;
   CREATE USER 'aidungeon'@'localhost' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON aidungeon.* TO 'aidungeon'@'localhost';
   FLUSH PRIVILEGES;

2. Update the database configuration in config.yml:

   database:
     type: mysql
     host: localhost
     port: 3306
     name: aidungeon
     user: aidungeon
     password: your_password

Start your server again. You should see a message in the console indicating that AIDungeon has been enabled.

To verify that AIDungeon is installed correctly:

1. Log into your Minecraft server
2. Run the command: /aid help
3. You should see a list of available AIDungeon commands
4. As an administrator, run: /aid scan to initiate a dungeon scan

To give administrators access to all AIDungeon commands, use a permissions plugin like LuckPerms and grant the aidungeon.admin permission:

/lp user <username> permission set aidungeon.admin true

For more granular permission control, see the Admin Commands page for a list of specific permissions.

AIDungeon has no hard dependencies - it works out of the box with a vanilla Spigot server.

For enhanced functionality, consider these plugins:

• MythicMobs: For custom dungeon bosses
• CustomMobs: Alternative for custom mob integration
• ItemsAdder: For custom items in dungeon loot
• LuckPerms: For permissions management
• Vault: For economy integration (if using reward money)

See Custom Mobs Integration for details on setting up mob plugins.

When updating AIDungeon to a newer version:

1. Stop your Minecraft server
2. Back up your plugins/AIDungeon folder
3. Replace the old JAR file with the new version
4. Start your server
5. Check the console for any migration messages
6. Verify functionality with basic commands

If you encounter issues during installation:

• Check the server console for error messages
• Verify your Java version (must be Java 21+)
• Ensure your server is running Spigot 1.21.5 or higher
• Confirm your Gemini API key is valid
• Check database connection details if using MySQL

For more detailed troubleshooting, see the Troubleshooting guide.

After installation, you should:

1. Fine-tune your configuration settings
2. Set up custom mob integration if desired
3. Optimize for performance using the performance tuning guide
4. Learn the admin commands

This guide explains all configuration options available in the AIDungeon plugin and how to adjust them for your server's needs.

The main configuration file is located at plugins/AIDungeon/config.yml. After installing the plugin and starting your server for the first time, this file will be generated with default values.

database:
  # Database type: mysql or sqlite
  type: sqlite
  # MySQL settings (only used if type is mysql)
  host: localhost
  port: 3306
  name: aidungeon
  user: root
  password: ""
  # SQLite settings (only used if type is sqlite)
  file: "aidungeon.db"

• type: Choose between mysql for a MySQL database or sqlite for a local SQLite database
• MySQL settings (only used if type is set to mysql):
  • host: Hostname of your MySQL server
  • port: Port of your MySQL server (usually 3306)
  • name: Name of the database to use
  • user: MySQL username with access to the database
  • password: Password for the MySQL user
• SQLite settings (only used if type is set to sqlite):
  • file: Filename for the SQLite database file

Recommendation: For small to medium servers, SQLite is sufficient. For larger servers with many players, or for servers with multiple instances sharing dungeon data, use MySQL.

gemini:
  # Your Gemini API key (required for AI dungeon generation)
  apiKey: ""
  # Gemini model to use
  model: "gemini-1.5-pro"
  # Timeout for API calls (in seconds)
  timeoutSeconds: 30
  # Maximum tokens for Gemini response
  maxTokens: 2048
  # Dynamic model selection based on server load (optional)
  peakHoursModel: "gemini-1.5-flash"
  offPeakModel: "gemini-1.5-pro"
  peakHoursStart: "16:00"
  peakHoursEnd: "22:00"
  # Language for dungeon descriptions and lore (e.g., en, de, fr, es)
  # Leave empty for default (English)
  language: ""

• apiKey: Your Google Gemini API key (required for AI dungeon generation)
• model: Gemini model to use (see Gemini API Setup for available models)
• timeoutSeconds: Timeout (in seconds) for API calls
• maxTokens: Maximum tokens for Gemini response
• Dynamic model selection (optional):
  • peakHoursModel: Model to use during peak server hours
  • offPeakModel: Model to use during off-peak hours
  • peakHoursStart: Start time for peak hours (24-hour format)
  • peakHoursEnd: End time for peak hours (24-hour format)
• language: Language for dungeon descriptions and lore (leave empty for English)

Recommendation: You must obtain a Gemini API key from the Google AI Studio and enter it here. Without a valid key, the plugin will fall back to basic predefined dungeon layouts. For most servers, the default gemini-1.5-pro model offers a good balance between quality and performance.

scheduler:
  # How often (in minutes) to check for potential dungeon locations around players
  periodicCheckMinutes: 10
  # When to perform a full world scan (24-hour format HH:MM)
  dailyScanTime: "03:00"

• periodicCheckMinutes: How often (in minutes) the plugin checks for potential dungeon locations around active players
• dailyScanTime: Time of day (24-hour format) when the plugin performs a more thorough scan of the world

Recommendation: The default values work well for most servers. Decrease periodicCheckMinutes if you want dungeons to appear more frequently, or increase it if you're experiencing server lag.

generation:
  # Minimum distance (in blocks) between dungeons
  minDistanceBetweenDungeons: 500
  # Distance (in blocks) that players can see a dungeon being generated
  playerSightRange: 100
  # Chance (0.0 to 1.0) that a suitable location will spawn a dungeon
  dungeonSpawnChance: 0.2
  # Maximum number of dungeons per region (16x16 chunk region)
  maxDungeonsPerRegion: 3
  # Maximum number of rooms per dungeon
  maxRoomsPerDungeon: 15
  # Whether to allow dungeons in non-overworld dimensions
  allowInOtherDimensions: false
  # Maximum room size (in blocks)
  maxRoomSize: 20
  # Maximum offset between rooms (in blocks)
  maxRoomOffset: 50
  # Radius (in blocks) to scan around players for potential dungeon locations
  scanRadius: 100
  # Biome-specific weights (higher = more likely to spawn)
  biomeWeights:
    DESERT: 1.0
    BADLANDS: 1.0
    FOREST: 1.0
    TAIGA: 1.0
    PLAINS: 0.7
    MOUNTAINS: 1.2
    SNOWY: 0.8
    JUNGLE: 1.2
    SWAMP: 1.2
    MUSHROOM: 1.5
    OCEAN: 0.8
    RIVER: 0.5
    BEACH: 0.6
    NETHER: 1.5
    END: 1.3
    CAVE: 1.3

• minDistanceBetweenDungeons: Minimum distance (in blocks) between two dungeons
• playerSightRange: Dungeons won't generate within this range of a player to avoid players seeing the generation process
• dungeonSpawnChance: Base chance (0.0 to 1.0) that a suitable location will spawn a dungeon
• maxDungeonsPerRegion: Maximum number of dungeons in a 16x16 chunk region
• maxRoomsPerDungeon: Maximum number of rooms that can be generated in a dungeon
• allowInOtherDimensions: Whether to generate dungeons in the Nether and End dimensions
• maxRoomSize: Maximum size of a room in blocks
• maxRoomOffset: Maximum distance between rooms in blocks
• scanRadius: How far around players to scan for potential dungeon locations
• biomeWeights: Relative likelihood of a dungeon spawning in different biome types

Recommendation: Adjust these values based on your world size and player count. For larger servers with many players, consider increasing minDistanceBetweenDungeons and decreasing dungeonSpawnChance to prevent oversaturation. Adjust biome weights based on your world's biome distribution.

themes:
  # Whether to use biome-appropriate themes
  useBiomeThemes: true
  # List of possible dungeon themes
  options:
    - ancient_temple
    - abandoned_mine
    - haunted_mansion
    - forgotten_laboratory
    - cursed_crypt
    - monster_den
    - bandit_hideout
    - wizard_tower
    - alien_structure
    - military_bunker

• useBiomeThemes: When true, themes are chosen based on the biome type. When false, a random theme is chosen from the options
• options: List of possible themes to choose from when not using biome-specific themes

Recommendation: Keep useBiomeThemes enabled for more immersive gameplay. You can add custom themes to the options list, but ensure the DungeonGenerator class has appropriate block palettes for them.

bosses:
  # Health multiplier for boss entities
  healthMultiplier: 10.0
  # Damage multiplier for boss entities
  damageMultiplier: 2.0
  # Experience dropped by boss entities
  experienceDropped: 500
  # Boss ability cooldown (in seconds)
  abilityCooldown: 15

• healthMultiplier: Multiplier for boss entity health relative to normal mobs
• damageMultiplier: Multiplier for damage dealt by boss entities
• experienceDropped: Base experience points dropped when a boss is defeated
• abilityCooldown: Cooldown time (in seconds) between boss special abilities

Recommendation: Adjust these values based on your server's difficulty level. Increase values for more challenging bosses, or decrease for more casual gameplay.

loot:
  # Number of treasure chests per dungeon
  chestsPerDungeon: 5
  # Chance of rare loot (0.0 to 1.0)
  rareItemChance: 0.2
  # Chance of epic loot (0.0 to 1.0)
  epicItemChance: 0.05
  # Chance of legendary loot (0.0 to 1.0)
  legendaryItemChance: 0.01

• chestsPerDungeon: Average number of treasure chests placed in each dungeon
• rareItemChance: Chance (0.0 to 1.0) of a chest containing rare loot
• epicItemChance: Chance (0.0 to 1.0) of a chest containing epic loot
• legendaryItemChance: Chance (0.0 to 1.0) of a chest containing legendary loot

Recommendation: Adjust loot chances based on your server's economy. Lower the chances for servers where you want to keep rare items scarce.

exploration:
  # Whether dungeons collapse after being fully explored
  collapseAfterExploration: true
  # Time (in hours) before a dungeon collapses after being fully explored
  collapseDelay: 24
  # Whether players can return to a dungeon after it has been fully explored
  allowReturnAfterExploration: false

• collapseAfterExploration: If true, dungeons will collapse after being fully explored
• collapseDelay: Time (in hours) before a fully explored dungeon begins collapsing
• allowReturnAfterExploration: If true, players can re-enter a dungeon after exploring it fully

Recommendation: Keep dungeon collapse enabled to prevent world clutter. Adjust collapseDelay based on your server activity levels - longer for less active servers to give players time to revisit.

custom_mobs:
  # Global toggle for custom mob support
  enabled: true

  # Plugin priority (first match wins)
  plugin_priority:
    - "MythicMobs"
    - "CustomMobs"
    - "ItemsAdder"
    - "EcoPets"
    - "Citizens"

  # Biome-specific custom mob configurations
  biome_mobs:
    DESERT:
      - name: "Ancient Pharaoh"
        plugin: "MythicMobs"
        id: "desert_guardian"
        weight: 1.0
        themes:
          - "ancient_temple"
          - "abandoned_mine"

    FOREST:
      - name: "Forest Spirit"
        plugin: "ItemsAdder"
        id: "forest_spirit"
        weight: 1.2
        themes:
          - "haunted_mansion"
          - "wizard_tower"

  # Global fallback mobs if no thematic match is found
  fallback_mobs:
    - name: "Dungeon Guardian"
      plugin: "MythicMobs"
      id: "generic_boss"
      weight: 1.0

• enabled: Global toggle for custom mob support
• plugin_priority: Order in which to check plugins for custom mobs
• biome_mobs: Configuration for biome-specific custom mobs
  • name: Display name of the mob
  • plugin: Plugin providing the mob
  • id: Unique identifier for the mob in its respective plugin
  • weight: Spawn priority
  • themes: Dungeon themes where this mob can appear
• fallback_mobs: Mobs to use if no biome-specific mob is available

See Custom Mobs Integration for detailed setup instructions.

performance:
  # Maximum number of dungeons to generate concurrently
  maxConcurrentGeneration: 1
  # Maximum number of collapse operations to run concurrently
  maxConcurrentCollapses: 1
  # Blocks to process per tick during generation/collapse (higher = faster but more lag)
  blocksPerTick: 20
  # Use lightweight generation during high server load (TPS < 18)
  adaptiveGeneration: true

• maxConcurrentGeneration: Limit how many dungeons can be generated at the same time
• maxConcurrentCollapses: Limit how many dungeons can be collapsing at the same time
• blocksPerTick: How many blocks to process per server tick during generation/collapse
• adaptiveGeneration: Whether to switch to simpler generation during high server load

Recommendation: On servers with more than 20 concurrent players, consider using the faster gemini-1.5-flash model during peak hours and enabling adaptiveGeneration to prevent lag spikes.

debug:
  # Enable debug logging
  enabled: false
  # Log dungeon generation steps
  logGeneration: false
  # Log API calls
  logApiCalls: false
  # Log database operations
  logDatabase: false
  # Log custom mob resolution
  logCustomMobs: false

• enabled: Enable or disable debug logging
• logGeneration: Log detailed information about dungeon generation steps
• logApiCalls: Log detailed information about Gemini API calls
• logDatabase: Log detailed information about database operations
• logCustomMobs: Log custom mob resolution attempts

Recommendation: Enable these settings only when troubleshooting issues, as they can significantly increase log file size.

gemini:
  model: "gemini-2.5-pro-experimental"
  timeoutSeconds: 60
generation:
  dungeonSpawnChance: 0.3
  maxDungeonsPerRegion: 5
exploration:
  collapseDelay: 48
performance:
  blocksPerTick: 25

gemini:
  model: "gemini-1.5-pro"
  timeoutSeconds: 30
generation:
  dungeonSpawnChance: 0.2
  maxDungeonsPerRegion: 3
exploration:
  collapseDelay: 24
performance:
  blocksPerTick: 20
  adaptiveGeneration: true

gemini:
  peakHoursModel: "gemini-1.5-flash"
  offPeakModel: "gemini-1.5-pro"
  peakHoursStart: "16:00"
  peakHoursEnd: "23:00"
  timeoutSeconds: 30
generation:
  dungeonSpawnChance: 0.15
  minDistanceBetweenDungeons: 800
performance:
  blocksPerTick: 15
  adaptiveGeneration: true
  maxConcurrentGeneration: 1

After making changes to the configuration file:

1. Save the file
2. Restart your server or use a plugin like PluginManager to reload the AIDungeon plugin
3. Check the console for any error messages
4. Test the changes in-game

Most configuration changes will take effect immediately after reload, but some (like database settings) may require a full server restart.

This document explains how to set up the Google Gemini API for use with the AIDungeon plugin, including obtaining an API key, understanding different models, and managing API usage.

To use the AI dungeon generation features, you need a Google Gemini API key:

1. Visit Google AI Studio
2. Sign in with your Google account
3. Create a new API key from the dashboard
4. Copy the API key and add it to your config.yml file:

   gemini:  apiKey: "YOUR_API_KEY_HERE"
   

Your Gemini API key grants access to the AI service and should be kept secure:

• Never share your API key publicly
• Use environment variables or a secure vault service for production servers
• Regularly rotate your keys if you suspect they've been compromised
• Set usage limits in the Google AI Studio to prevent unexpected charges

AIDungeon supports different Gemini models, each with its own strengths and performance characteristics. You can specify which model to use in your config.yml:

gemini:
  model: "gemini-1.5-pro"  # Default model

• Speed: Fastest response time among available models
• Detail Quality: Provides simpler dungeon designs with fewer unique features
• Resource Usage: Lowest token consumption
• Ideal For: High-traffic servers, performance-focused setups, or servers with tight API budgets
• Limitations: Less variety in room layouts, simpler boss designs

• Speed: Good balance between response time and quality
• Detail Quality: Detailed dungeon designs with varied room layouts and features
• Resource Usage: Moderate token consumption
• Ideal For: Most standard server configurations
• Limitations: May occasionally produce inconsistent designs

• Speed: Slowest response time but highest quality output
• Detail Quality: Extremely detailed dungeons with intricate themes, complex room connections, and unique features
• Resource Usage: Highest token consumption
• Ideal For: Premium servers where dungeon quality is prioritized over generation speed
• Advantages: Creates more coherent dungeon narratives, better biome-specific theming, and more creative boss designs
• Limitations: Longer generation time may be noticeable to players, higher API costs

• For servers with more than 50 concurrent players: Use gemini-1.5-flash to minimize generation delays
• For standard servers with moderate player counts: Use gemini-1.5-pro (default)
• For premium gameplay experiences where generation time isn't critical: Use gemini-2.5-pro-experimental

You can also adjust the model dynamically based on server load:

gemini:
  # Use faster model during peak hours, better model during off-peak
  peakHoursModel: "gemini-1.5-flash"  
  offPeakModel: "gemini-1.5-pro"
  # Define peak hours (24-hour format)
  peakHoursStart: "16:00"  # 4 PM
  peakHoursEnd: "22:00"    # 10 PM

You can adjust how long the plugin will wait for a response from the Gemini API before timing out:

gemini:
  # Maximum time (in seconds) to wait for dungeon generation
  timeoutSeconds: 30  # Default: 30 seconds
  # Increase for gemini-2.5-pro-experimental
  # timeoutSeconds: 60  # For gemini-2.5-pro-experimental

If using gemini-2.5-pro-experimental, it's recommended to increase the timeout to at least 45-60 seconds to account for the longer generation times.

The Gemini API has token limits that affect how much content can be generated:

gemini:
  # Maximum tokens for Gemini response
  maxTokens: 2048

A token is roughly 4 characters or 0.75 words. The default setting (2048 tokens) is sufficient for most dungeon designs. Higher values may result in more detailed dungeons but will consume your API quota faster.

To monitor your Gemini API usage:

1. Enable API call logging in the config:

   debug:
     logApiCalls: true
   

2. Check your server logs for API call information

3. Review your usage in the Google AI Studio dashboard

Remember that the Gemini API may have usage limits based on your account type. Monitor your usage to avoid unexpected charges or rate limiting.

If the Gemini API call fails for any reason (invalid key, API limits, connectivity issues), the plugin will fall back to a predefined dungeon layout:

• Simple dungeon with entrance, corridor, treasure room, and boss room
• Basic structure using biome-appropriate blocks
• Generic "Ancient Guardian" boss (modified zombie)

This ensures players can still experience dungeons even if the AI generation isn't available.

You can configure the language used for dungeon descriptions and lore:

gemini:
  # Language for dungeon descriptions and lore
  language: "de"  # Use German

Supported languages include:

• English (default, leave blank)
• German (de)
• French (fr)
• Spanish (es)
• Italian (it)
• Portuguese (pt)
• Russian (ru)
• Japanese (ja)
• Korean (ko)
• Chinese (zh)

1. "No Gemini API key provided":

   • Add your API key to the config.yml file

2. "Gemini API request failed with status code: 403":

   • Invalid API key or API key has reached its quota limit
   • Check your key in the Google AI Studio dashboard

3. "Gemini API error, using fallback generation":

   • Temporary API issue or malformed response
   • Check the server logs for more details

4. "Failed to extract text from Gemini API response":

   • Response format has changed or is unexpected
   • Update to the latest plugin version if available

5. "Timeout waiting for Gemini API response":

   • If using gemini-2.5-pro-experimental, increase the timeoutSeconds in config.yml
   • Check your network connection to Google's API servers

If your server has connectivity issues to the Gemini API:

1. Verify your server can reach generativelanguage.googleapis.com
2. Check if your hosting provider blocks outgoing API calls
3. Ensure your server's DNS resolution is working correctly
4. Consider using a proxy if direct connectivity is problematic

To optimize API usage and control costs:

1. Caching: The plugin doesn't make redundant API calls for similar dungeon types
2. Batching: Pending dungeon locations are processed in batches to limit API calls
3. Retry Logic: Failed API calls are retried with exponential backoff
4. Timeout Control: API calls have a configurable timeout to prevent hanging

The Gemini API has a free tier with limits, after which usage is billed. To manage costs:

1. Start with the free tier to gauge your usage patterns
2. Set budget alerts in Google Cloud to avoid unexpected bills
3. Consider using the gemini-1.5-flash model which uses fewer tokens
4. Adjust dungeon generation frequency based on your budget
5. Monitor your usage regularly

With proper configuration, most small to medium servers can operate within the free tier limits or with minimal costs.

AIDungeon can integrate with various custom mob plugins to enhance dungeon encounters with specialized enemies and bosses. This guide explains how to set up and configure these integrations.

AIDungeon supports integration with the following custom mob plugins:

• MythicMobs - Full support with advanced mob capabilities
• CustomMobs - Complete integration for custom mob spawning
• ItemsAdder - Support for custom entities
• EcoPets - Support for combat-capable pets
• Citizens - Support for NPC-based enemies

Custom mob integration is configured in the config.yml file under the custom_mobs section:

custom_mobs:
  # Global toggle for custom mob support
  enabled: true
Plugin priority (first match wins)
plugin_priority:
- "MythicMobs"
- "CustomMobs"
- "ItemsAdder"
- "EcoPets"
- "Citizens"
Biome-specific custom mob configurations
biome_mobs:
DESERT:
- name: "Ancient Pharaoh"
plugin: "MythicMobs"
id: "desert_guardian"
weight: 1.0
themes:
- "ancient_temple"
- "abandoned_mine"
FOREST:
  - name: "Forest Spirit"
    plugin: "ItemsAdder"
    id: "forest_spirit"
    weight: 1.2
    themes:
      - "haunted_mansion"
      - "wizard_tower"

Global fallback mobs if no thematic match is found
fallback_mobs:
- name: "Dungeon Guardian"
plugin: "MythicMobs"
id: "generic_boss"
weight: 1.0

custom_mobs:
  enabled: true

Set to false to disable all custom mob integration and use only vanilla Minecraft mobs.

plugin_priority:
  - "MythicMobs"
  - "CustomMobs"
  - "ItemsAdder"
  - "EcoPets"
  - "Citizens"

This list determines the order in which plugins are checked for mob availability. If a mob is configured to use MythicMobs but that plugin isn't installed, the system will try the next plugin in the list.

Each mob configuration includes:

• name: Display name of the mob
• plugin: Plugin providing the mob
• id: Unique identifier for the mob in its respective plugin
• weight: Spawn priority (higher values increase likelihood)
• themes: Dungeon themes where this mob can appear

These mobs are used when no biome-specific mob is available that matches the current dungeon's theme. They should be generally appropriate for any dungeon theme.

1. Install MythicMobs on your server
2. Create or install custom mob configurations
3. Reference the mob's internal ID in the AIDungeon configuration:

   biome_mobs:  DESERT:    - name: "Ancient Pharaoh"      plugin: "MythicMobs"      id: "ancient_pharaoh"  # MythicMobs internal ID
   

Example MythicMobs configuration:

ancient_pharaoh:
  Type: HUSK
  Display: '&6Ancient Pharaoh'
  Health: 500
  Damage: 15
  Options:
    PreventOtherDrops: true
    PreventRandomEquipment: true
  Skills:
    - skill{s=SandstormAura} @Self ~onTimer:100
    - skill{s=SummonMummies} @Self ~onCombat
  Drops:
    - gold_block 1-3 1.0
    - exp 500 1.0

1. Install CustomMobs on your server
2. Create your custom mobs
3. Reference the mob's ID in the AIDungeon config:

   biome_mobs:  MOUNTAINS:    - name: "Stone Elemental"      plugin: "CustomMobs"      id: "stone_elemental"
   

1. Install ItemsAdder on your server
2. Create custom entities following the ItemsAdder documentation
3. Reference the entity's namespace ID in the AIDungeon config:

   biome_mobs:  FOREST:    - name: "Forest Spirit"      plugin: "ItemsAdder"      id: "forest_spirit"
   

1. Install EcoPets on your server
2. Set up combat-capable pets
3. Reference the pet ID in the AIDungeon config:

   biome_mobs:  JUNGLE:    - name: "Jungle Guardian"      plugin: "EcoPets"      id: "jungle_guardian"
   

1. Install Citizens on your server
2. Create NPC templates that can be used as enemies
3. Reference the NPC template ID in the AIDungeon config:

   biome_mobs:  SWAMP:    - name: "Swamp Witch"      plugin: "Citizens"      id: "swamp_witch"
   

1. Install the mob plugin of your choice
2. Create custom mobs specific to different biomes and themes
3. Test the mobs to ensure they function correctly
4. Add the mob configurations to AIDungeon's config.yml
5. Restart your server or reload the plugin
6. Test in-game to verify mob spawning in dungeons

For the best dungeon experience, custom mobs should have:

• Appropriate difficulty: Stronger than vanilla mobs but not unbeatable
• Thematic abilities: Powers that match their biome and dungeon theme
• Visual distinctiveness: Unique appearance that signals their special status
• Balanced drops: Rewards that match the challenge level

When creating custom mobs for dungeons, consider these balance factors:

• Health: 2-10x normal mob health (higher for bosses)
• Damage: 1.5-3x normal mob damage
• Abilities: 1-3 special abilities for regular mobs, 3-5 for bosses
• Rewards: Value should match the difficulty
• Spawn Count: Higher health mobs should spawn in smaller numbers

1. Mobs not spawning: Check if the plugin is properly installed and the mob ID is correct
2. Wrong plugin being used: Check your plugin priority order
3. Biome mismatch: Verify that your mob is configured for the correct biome
4. Theme mismatch: Check that the mob's themes include the dungeon's theme

Enable custom mob logging in config.yml:

debug:
  logCustomMobs: true

This will provide detailed information in the server log about custom mob resolution attempts.

Custom mobs can have a performance impact on your server:

• Mob AI complexity: More complex AI behaviors may cause lag
• Particle effects: Excessive particles can impact client performance
• Concurrent abilities: Many mobs using abilities simultaneously can cause lag
• Entity count: Too many custom entities can strain the server

To optimize performance:

• Limit the number of concurrent custom mobs
• Use simpler AI behaviors for less important mobs
• Reserve complex abilities for boss encounters
• Test on a staging server before deploying to production

biome_mobs:
  DESERT:
    # Tier 1 (Common)
    - name: "Desert Scout"
      plugin: "MythicMobs"
      id: "desert_scout"
      weight: 3.0
      themes:
        - "ancient_temple"
        - "abandoned_mine"
# Tier 2 (Uncommon)
- name: "Mummy Guardian"
  plugin: "MythicMobs"
  id: "mummy_guardian"
  weight: 1.5
  themes:
    - "ancient_temple"
    
# Tier 3 (Boss)
- name: "Ancient Pharaoh"
  plugin: "MythicMobs"
  id: "ancient_pharaoh"
  weight: 0.5
  themes:
    - "ancient_temple"

biome_mobs:
  FOREST:
    # MythicMobs entity
    - name: "Forest Guardian"
      plugin: "MythicMobs"
      id: "forest_guardian"
      weight: 1.0
      themes: 
        - "haunted_mansion"
        - "wizard_tower"
# ItemsAdder entity (as backup)
- name: "Forest Guardian"
  plugin: "ItemsAdder"
  id: "ia_forest_guardian"
  weight: 1.0
  themes: 
    - "haunted_mansion"
    - "wizard_tower"

By providing a complete and detailed custom mob configuration, you can create unique and memorable dungeon experiences for your players that go well beyond what vanilla Minecraft offers.

This guide covers optimization strategies for running AIDungeon efficiently on your Minecraft server, balancing quality dungeons with server performance.

AIDungeon can impact server performance in several ways:

1. Dungeon Generation: Building complex structures in the world
2. API Calls: Network requests to the Gemini API
3. Entity Processing: Custom bosses and mob spawners
4. Block Updates: During dungeon collapse sequences
5. Database Operations: Tracking dungeons and player progress

The following settings in config.yml can be adjusted to optimize performance:

performance:
  # Maximum number of dungeons to generate concurrently
  maxConcurrentGeneration: 1
  # Maximum number of collapse operations to run concurrently
  maxConcurrentCollapses: 1
  # Blocks to process per tick during generation/collapse (higher = faster but more lag)
  blocksPerTick: 20
  # Use lightweight generation during high server load (TPS < 18)
  adaptiveGeneration: true

• maxConcurrentGeneration: Limits how many dungeons can be generated simultaneously. Higher values speed up generation but increase server load.
• maxConcurrentCollapses: Limits how many dungeons can be in the collapse process simultaneously. Higher values speed up cleanup but increase server load.
• blocksPerTick: Controls how many blocks are processed per server tick during generation/collapse. Higher values complete operations faster but may cause more lag spikes.
• adaptiveGeneration: When enabled, the plugin will use simpler generation methods when server TPS is low, helping maintain stability during high-traffic periods.

Different Gemini AI models have varying performance characteristics:

• Good for servers with 30+ concurrent players
• Minimal impact on server performance
• Works well with default timeout (30 seconds)
• Recommended settings:

  gemini:  model: "gemini-1.5-flash"  timeoutSeconds: 30performance:  blocksPerTick: 30  adaptiveGeneration: false
  

• Good for servers with up to 30 concurrent players
• Moderate impact on server performance during generation
• Works well with default timeout (30 seconds)
• Recommended settings:

  gemini:  model: "gemini-1.5-pro"  timeoutSeconds: 30performance:  blocksPerTick: 20  adaptiveGeneration: true
  

• Best for servers with up to 15 concurrent players
• Higher impact on server performance during generation
• Requires increased timeout
• Recommended settings:

  gemini:  model: "gemini-2.5-pro-experimental"  timeoutSeconds: 60performance:  blocksPerTick: 15  adaptiveGeneration: true  maxConcurrentGeneration: 1
  

For servers with varying player counts throughout the day, use dynamic model selection:

gemini:
  peakHoursModel: "gemini-1.5-flash"
  offPeakModel: "gemini-1.5-pro"
  peakHoursStart: "16:00"
  peakHoursEnd: "22:00"

This configuration automatically switches to the faster model during peak hours and the higher quality model during off-peak hours.

generation:
  # Maximum number of rooms per dungeon
  maxRoomsPerDungeon: 15
  # Maximum room size (in blocks)
  maxRoomSize: 20
  # Maximum offset between rooms (in blocks)
  maxRoomOffset: 50

• Reducing maxRoomsPerDungeon creates smaller, less complex dungeons that generate faster
• Lowering maxRoomSize limits the physical footprint of each room
• Decreasing maxRoomOffset makes dungeons more compact

generation:
  # Minimum distance (in blocks) between dungeons
  minDistanceBetweenDungeons: 500
  # Chance (0.0 to 1.0) that a suitable location will spawn a dungeon
  dungeonSpawnChance: 0.2
  # Maximum number of dungeons per region (16x16 chunk region)
  maxDungeonsPerRegion: 3

• Increasing minDistanceBetweenDungeons reduces overall dungeon density
• Decreasing dungeonSpawnChance makes dungeon generation less frequent
• Lowering maxDungeonsPerRegion prevents regions from becoming oversaturated

Dungeon collapse operations can be resource-intensive. Use these settings to manage their impact:

exploration:
  # Whether dungeons collapse after being fully explored
  collapseAfterExploration: true
  # Time (in hours) before a dungeon collapses after being fully explored
  collapseDelay: 24

• Setting collapseAfterExploration to false will prevent dungeons from collapsing automatically (may lead to world bloat)
• Increasing collapseDelay spreads out collapse operations over a longer period
• Use /aid collapse <dungeonId> administrative command during low-traffic periods to manually manage collapse operations

For small servers (under 20 concurrent players), SQLite is sufficient:

database:
  type: sqlite
  file: "aidungeon.db"

For larger servers or networks with multiple server instances, MySQL is recommended:

database:
  type: mysql
  host: localhost
  port: 3306
  name: aidungeon
  user: aidungeon
  password: "your_secure_password"

The plugin uses HikariCP for efficient database connection pooling. For very large servers, you can customize these settings:

database:
  # Advanced connection pool settings (optional)
  maxPoolSize: 10
  connectionTimeout: 30000
  idleTimeout: 600000
  maxLifetime: 1800000

Enable specific debug logs to monitor performance-critical aspects:

debug:
  # Log dungeon generation steps
  logGeneration: true
  # Log API calls
  logApiCalls: true
  # Log database operations
  logDatabase: true

Be cautious with debug logging on production servers as it can increase disk I/O and log file size.

Monitor these metrics to gauge AIDungeon's impact:

1. TPS (Ticks Per Second): Should remain close to 20
2. MSPT (Milliseconds Per Tick): Should remain under 50ms
3. Memory Usage: Watch for significant increases during dungeon operations
4. Lag Spikes: Note if they correlate with dungeon generation or collapse

gemini:
  model: "gemini-2.5-pro-experimental"
  timeoutSeconds: 60
generation:
  dungeonSpawnChance: 0.3
  maxDungeonsPerRegion: 5
exploration:
  collapseDelay: 48
performance:
  blocksPerTick: 25

gemini:
  model: "gemini-1.5-pro"
  timeoutSeconds: 30
generation:
  dungeonSpawnChance: 0.2
  maxDungeonsPerRegion: 3
exploration:
  collapseDelay: 24
performance:
  blocksPerTick: 20
  adaptiveGeneration: true

gemini:
  peakHoursModel: "gemini-1.5-flash"
  offPeakModel: "gemini-1.5-pro"
  peakHoursStart: "16:00"
  peakHoursEnd: "23:00"
  timeoutSeconds: 30
generation:
  dungeonSpawnChance: 0.15
  minDistanceBetweenDungeons: 800
performance:
  blocksPerTick: 15
  adaptiveGeneration: true
  maxConcurrentGeneration: 1
database:
  type: mysql
  # MySQL configuration

AIDungeon performs best on optimized server software:

• Paper: Recommended for best performance
• Purpur: Good for servers with many custom mobs
• Spigot: Minimum supported platform

For optimal performance with AIDungeon:

• CPU: 4+ cores, emphasis on single-thread performance
• RAM: 4GB minimum, 8GB+ recommended
• Storage: SSD strongly recommended for database operations
• Network: Low-latency connection to Gemini API servers (for minimal API call delays)

1. Scheduled Restarts: Regular server restarts help keep memory usage in check
2. Timings Analysis: Use /timings command to identify performance bottlenecks
3. Pre-generation: Generate dungeons during low-traffic periods using the /aid scan command
4. World Borders: Limit world size to prevent excessive chunk generation
5. Entity Limits: If using custom mobs, limit other entities in the world
6. Region File Cleanup: Periodically clear unused chunks to reduce world size

1. Lag Spikes During Generation

   • Decrease blocksPerTick setting
   • Increase maxConcurrentGeneration to spread operations over more ticks
   • Enable adaptiveGeneration

2. High Memory Usage

   • Reduce maxDungeonsPerRegion and maxRoomsPerDungeon
   • Ensure regular garbage collection through server restarts
   • If using MySQL, check connection pool settings

3. Slow API Responses

   • Switch to a faster model during peak hours
   • Ensure good network connectivity to Google API servers
   • Verify your server location isn't geographically distant from Google's servers

4. Database Performance Issues

   • For large servers, migrate from SQLite to MySQL
   • Optimize MySQL server configuration
   • Add indexes to frequently queried fields

By carefully tuning these settings, you can find the optimal balance between rich dungeon experiences and server performance for your specific Minecraft community.

This guide addresses common issues that may arise when using the AIDungeon plugin and provides solutions to help you resolve them.

Symptoms: Server console shows errors during startup, AIDungeon commands don't work.

Possible Causes and Solutions:

1. Incorrect Java Version

   • Error: Unsupported major.minor version or class file version errors
   • Solution: Ensure you're using Java 21 or higher. Check with: java -version

2. Missing Dependencies

   • Error: NoClassDefFoundError or ClassNotFoundException
   • Solution: Verify you're using Spigot 1.21.5+ or a compatible fork

3. Plugin JAR Corruption

   • Error: Invalid plugin.yml or zip file errors
   • Solution: Re-download the plugin JAR file

4. Incompatible Server Version

   • Error: This server is running X but the plugin requires Y
   • Solution: Update your server to a supported version (1.21.5+)

Symptoms: Plugin enables but console shows database errors.

Possible Causes and Solutions:

1. Invalid MySQL Credentials

   • Error: Access denied for user or Communications link failure
   • Solution: Check username, password, and database name in config.yml
   • Solution: Ensure the MySQL user has appropriate permissions

2. MySQL Server Unavailable

   • Error: Connection refused or Connection timed out
   • Solution: Verify MySQL server is running and accessible from your Minecraft server
   • Solution: Check firewall settings if MySQL is on a different machine

3. SQLite File Permission Issues

   • Error: Failed to open database file or Permission denied
   • Solution: Ensure the server process has write permissions to the plugins directory
   • Solution: Check if antivirus software is blocking file operations

4. Database File Corruption

   • Error: Database disk image is malformed
   • Solution: Stop the server, remove the SQLite database file, and restart

Symptoms: Dungeons generate with basic layouts, fallback generation is used.

Possible Causes and Solutions:

1. Missing or Invalid API Key

   • Error: No Gemini API key provided or Gemini API request failed with status code: 403
   • Solution: Check if you've added a valid API key in the config.yml file
   • Solution: Verify the API key in Google AI Studio dashboard

2. API Quota Exceeded

   • Error: Gemini API request failed with status code: 429
   • Solution: Check your quota usage in Google AI Studio
   • Solution: Consider upgrading your API plan

3. Network Connectivity Issues

   • Error: Connection timed out or Unable to resolve host
   • Solution: Verify your server can access external APIs
   • Solution: Check if a firewall is blocking outbound connections

4. API Timeout Issues

   • Error: Timeout waiting for Gemini API response
   • Solution: Increase timeoutSeconds in the config (especially for gemini-2.5-pro-experimental)
   • Solution: Switch to a faster model during peak times

Symptoms: No dungeons appear in the world despite exploration.

Possible Causes and Solutions:

1. Low Spawn Chance

   • Solution: Increase dungeonSpawnChance in the config
   • Solution: Check biome weights for your world's predominant biomes

2. Dungeon Density Limits

   • Solution: Check if you've reached maxDungeonsPerRegion limit
   • Solution: Explore new areas further from existing dungeons

3. Player Presence during Generation

   • Solution: Dungeons won't generate when players are nearby (to avoid seeing the generation)
   • Solution: Use /aid pending to check for locations awaiting generation
   • Solution: Have players explore an area, then leave it for a while

4. World Type or Dimension Issues

   • Solution: Verify allowInOtherDimensions is true if trying to generate in Nether/End
   • Solution: Some custom world types may not be compatible

Symptoms: Dungeons appear but have missing rooms, floating blocks, or disconnected sections.

Possible Causes and Solutions:

1. Complex Terrain Interactions

   • Solution: Adjust maxRoomOffset to reduce spread between rooms
   • Solution: Enable debug logging to check for terrain-related errors

2. Generation Interruptions

   • Solution: Check if there were server crashes during generation
   • Solution: Ensure TPS was stable during generation

3. Conflicting Plugins

   • Solution: Test for conflicts with other world generation or terrain modification plugins
   • Solution: Disable suspect plugins and test again

Symptoms: Dungeons don't collapse properly after exploration.

Possible Causes and Solutions:

1. Collapse Feature Disabled

   • Solution: Check if collapseAfterExploration is set to true

2. Collapse Delay Not Elapsed

   • Solution: Verify collapseDelay setting and wait the configured time
   • Solution: Use /aid collapse <dungeonId> to force collapse

3. Plugin Reload or Server Restart

   • Solution: Scheduled collapses might be lost on plugin reload
   • Solution: Manually trigger collapse with /aid collapse <dungeonId>

4. Performance Throttling

   • Solution: The plugin limits concurrent collapses; check for a backlog
   • Solution: Adjust maxConcurrentCollapses if needed

Symptoms: Dungeons use vanilla mobs instead of configured custom mobs.

Possible Causes and Solutions:

1. Custom Mob Plugin Not Detected

   • Solution: Verify the specified plugin (MythicMobs, etc.) is installed and enabled
   • Solution: Check plugin load order; custom mob plugins should load before AIDungeon

2. Incorrect Mob IDs

   • Solution: Double-check mob IDs in the configuration match exactly with the mob plugin
   • Solution: Enable logCustomMobs in debug settings to see resolution attempts

3. Theme/Biome Mismatch

   • Solution: Ensure mobs are configured for the correct biome and dungeon theme
   • Solution: Add appropriate themes to the mob configuration

4. Plugin Version Incompatibility

   • Solution: Update custom mob plugins to versions compatible with your server

Symptoms: Bosses don't use abilities or behave incorrectly.

Possible Causes and Solutions:

1. Ability Configuration

   • Solution: Check ability cooldowns and triggers in the mob plugin's configuration
   • Solution: Adjust abilityCooldown in bosses section of config

2. Entity Limitations

   • Solution: Some abilities may be constrained by vanilla entity limitations
   • Solution: Verify your mob plugin can override vanilla AI for the base entity type

3. Performance Throttling

   • Solution: Boss abilities might be throttled during server lag
   • Solution: Consider simplifying boss mechanics if server struggles to handle them

Symptoms: Commands return "Unknown command" or don't function as expected.

Possible Causes and Solutions:

1. Plugin Not Enabled

   • Solution: Check the server console to verify AIDungeon loaded successfully
   • Solution: Try /plugins to see if AIDungeon is listed

2. Command Syntax

   • Solution: Ensure you're using the correct command format
   • Solution: Try /aid help to see available commands

3. Permission Issues

   • Solution: Check if you have the required permissions
   • Solution: Try running commands as server operator (OP)

Symptoms: "You don't have permission" errors when using commands.

Possible Causes and Solutions:

1. Missing Permissions

   • Solution: Grant the required permission node
   • Solution: For admin commands, grant aidungeon.admin or specific permission nodes

2. Permission Plugin Conflicts

   • Solution: Check for conflicts with permission plugins
   • Solution: Try temporarily OPing the user to test if it's a permission issue

3. Incorrect Permission Syntax

   • Solution: Double-check the format of the permission node
   • Solution: Refer to the Admin Commands page for permission nodes

Symptoms: Server lag spikes when dungeons are being generated.

Possible Causes and Solutions:

1. Block Placement Rate

   • Solution: Lower blocksPerTick in the performance section
   • Solution: Enable adaptiveGeneration to throttle during high server load

2. Concurrent Generation

   • Solution: Set maxConcurrentGeneration to 1
   • Solution: Space out dungeon generation using scheduled scans

3. Complex Dungeons

   • Solution: Reduce maxRoomsPerDungeon and maxRoomSize
   • Solution: Use a faster AI model (gemini-1.5-flash) during peak hours

Symptoms: Increasing memory usage over time, possibly leading to crashes.

Possible Causes and Solutions:

1. Uncollapsed Dungeons

   • Solution: Ensure collapseAfterExploration is enabled
   • Solution: Manually collapse unused dungeons with /aid collapse

2. Database Growth

   • Solution: Monitor database size, especially for SQLite
   • Solution: Consider periodic cleanup of very old dungeon data

3. Memory Leaks

   • Solution: Ensure you're using the latest version of the plugin
   • Solution: Monitor memory usage patterns and report persistent issues

To help diagnose issues, enable debug logging in the config:

debug:
  # Enable debug logging
  enabled: true
  # Log dungeon generation steps
  logGeneration: true
  # Log API calls
  logApiCalls: true
  # Log database operations
  logDatabase: true
  # Log custom mob resolution
  logCustomMobs: true

After enabling debug logging:

1. Restart the server or reload the plugin
2. Reproduce the issue
3. Check the server log for detailed information
4. Disable debug logging when finished to avoid log file bloat

Key information to look for in logs:

1. Error messages: Lines containing "ERROR" or "SEVERE"
2. Dungeon generation events: Messages about dungeon creation or API calls
3. Database queries: Information about database operations
4. Custom mob resolution: Details about mob plugin integration

When seeking help, provide:

1. Plugin version: Output of /version AIDungeon
2. Server information: Version, platform (Paper, Spigot, etc.)
3. Relevant log excerpts: Errors and context around them
4. Configuration: Your config.yml file (with API key removed)
5. Steps to reproduce: Clear sequence of actions that trigger the issue

If you can't resolve an issue using this guide:

1. Check for Updates: Ensure you're using the latest version of AIDungeon
2. Community Forums: Post on the SpigotMC resource discussion
3. GitHub Issues: Report bugs on the official GitHub repository
4. Discord Support: Join the community Discord for direct assistance

Remember to provide detailed information about your issue, including logs and configuration, when seeking help.