Mob Control Apocalypse

 Description longue (Full Description)

  # Mob Control

  **Mob Control** is a powerful server-side Forge mod for Minecraft 1.20.1 that gives server administrators complete
  control over mob spawning, attributes, drops, and distribution. Whether you run a survival server, an RPG server, or a
   custom adventure map, Mob Control lets you fine-tune every aspect of hostile mob behavior.

  ---

  ## Key Features

  ### Global Spawn Control
  - **Whitelist / Blacklist mode**: Choose whether only configured mobs can spawn (whitelist) or configured mobs are
  blocked (blacklist)
  - **Per-player mob limit**: Cap the number of hostile mobs around each player (default: 30)
  - **Global mob cap**: Set an absolute maximum of hostile mobs in the entire world (default: 200)
  - **Spawn distance constraints**: Define minimum and maximum spawn distances from players
  - **Force despawn**: Automatically remove mobs that wander too far from all players
  - **Light level bypass**: Configured mobs can spawn regardless of light level, enabling daylight spawning
  - **Passthrough system**: Completely ignore mobs from specific mods (e.g., `customnpcs:*`) so they spawn normally

  ### Custom Mob Attributes
  Configure per-mob attributes via a simple JSON file:
  - **Health range**: Random HP between min and max values
  - **Movement speed**: Override vanilla speed
  - **Knockback resistance**: 0.0 (none) to 1.0 (immune)
  - **Aggro range**: Detection distance for players
  - **Follow range**: Pursuit distance
  - **Spawn chance**: 0-100% probability for each spawn attempt
  - **Sun protection**: Prevent zombies, skeletons, and phantoms from burning in sunlight

  ### Spawn Zones
  Create dedicated spawn zones with independent rules:
  - **Cubic volumes**: Define zones with two corner positions in any dimension
  - **Per-zone mob cap**: Limit total mobs within each zone
  - **Mob groups**: Configure multiple mob types per zone, each with its own cooldown, max count, spawn ring distance,
  and custom attributes
  - **Entry boost**: Temporarily multiply spawn rates when a player first enters a zone (e.g., 4x faster spawns for 5
  seconds)
  - **Mob balancing**: Automatically redistribute mobs so no single player gets overwhelmed
  - **Sun protection**: Zone-wide sunburn prevention for undead mobs
  - **XP bonus**: Award extra experience for killing zone-spawned mobs
  - **Fair distribution**: Mobs spawn near the least-loaded player, ensuring balanced gameplay
  - **Retry system**: Failed spawn attempts are retried on the next cycle (up to 5x multiplier)

  ### Mob Persistence
  Zone-spawned mobs survive chunk loading/unloading:
  - Mobs are saved to disk when their chunk unloads
  - Restored with their exact health and position when the chunk reloads
  - Alive counts stay accurate across chunk cycles

  ### Custom Drops
  Replace or supplement vanilla loot tables:
  - Per-mob drop tables in JSON
  - Variable item counts (min/max)
  - Drop chance percentage (0-100%)
  - Option to disable all vanilla drops
  - Option to disable XP orb drops
  - Zone XP bonus stacks on top of custom drops

  ### Real-Time Web Dashboard
  A built-in web server provides a live monitoring dashboard:
  - **Population timeline**: 5-minute rolling graph of total, zone, and natural mob counts
  - **Mob distribution**: Doughnut chart of mob types
  - **Zone stress**: Bar chart showing how full each zone is
  - **Spawns vs Kills**: Track spawn and death rates per zone
  - **Global analysis**: Theoretical vs actual mob counts with efficiency tracking
  - **Zone cards**: Click any zone for detailed stats, mob group breakdown, radar view, and analysis
  - **Entity radar**: Global map showing all mobs, players, zone boundaries, spawn rings, and despawn rings with terrain
   overlay
  - **Player radars**: Per-player mini-radars showing nearby mobs with distance rings
  - **Player table**: Position, dimension, nearby mob count, and current zone for each player
  - **Terrain mapping**: Automatic heightmap scanning with color-coded terrain types
  - **Configuration view**: See all active settings at a glance

  ---

  ## Commands

  | Command | Permission | Description |
  |---------|-----------|-------------|
  | `/mobcontrol reload` | OP level 2 | Reloads all configuration files (mobs, drops, zones). Refreshes passthrough
  patterns, resets zone counters, and restarts the web server if settings changed. |

  ---

  ## Configuration Files

  All configuration is done through files in the `config/` folder. No in-game GUI needed.

  ### mobcontrol-common.toml
  General spawn control settings:
  ```toml
  [general]
  whitelistMode = true          # true = whitelist, false = blacklist
  controlAllMobs = true         # Control all mob types, not just monsters
  mobLimitPerPlayer = 30        # Max mobs around each player
  mobCheckRadius = 64           # Radius to count nearby mobs
  globalMobCap = 200            # Max hostile mobs in the world
  spawnMinDistance = 24          # Min blocks from player to spawn
  spawnMaxDistance = 128         # Max blocks from player to spawn
  despawnDistance = 128          # Force despawn beyond this distance
  passthroughMods = ["customnpcs:*"]  # Mods to ignore completely
  debugSpawner = false          # Verbose spawn logging

  mobcontrol-mobs.json

  Per-mob configuration with attributes:
  {
    "minecraft:zombie": {
      "spawnChance": 80,
      "minHealth": 20,
      "maxHealth": 40,
      "speed": 0.23,
      "knockbackResistance": 0.0,
      "aggroRange": 35,
      "followRange": 40,
      "sunProof": true
    },
    "minecraft:skeleton": {
      "spawnChance": 70,
      "minHealth": 20,
      "maxHealth": 30,
      "speed": 0.25,
      "knockbackResistance": 0.0,
      "aggroRange": 16,
      "followRange": 24,
      "sunProof": true
    }
  }
  Set any attribute to -1 to keep the vanilla default. Comes pre-configured with 30+ vanilla mobs.

  mobcontrol-drops.json

  Custom drop tables:
  {
    "minecraft:zombie": {
      "drops": [
        { "item": "minecraft:rotten_flesh", "min": 1, "max": 3, "chance": 100 },
        { "item": "minecraft:iron_ingot", "min": 1, "max": 1, "chance": 5 }
      ]
    }
  }

  mobcontrol-drops.toml

  [drops]
  disableVanillaDrops = false   # Replace vanilla drops entirely
  disableXPDrops = false        # Disable XP orb drops

  mobcontrol-zones.toml

  Zone system settings:
  [zones]
  zonesEnabled = false          # Enable/disable the zone system
  webEnabled = false            # Enable/disable web dashboard
  webPort = 8080                # Web dashboard port
  persistenceEnabled = true     # Save/restore mobs on chunk unload
  defaultDespawnDistance = 70    # Default zone despawn distance
  defaultSpawnMinDistance = 16   # Default zone min spawn distance
  defaultSpawnMaxDistance = 40   # Default zone max spawn distance

  mobcontrol-zones.json

  Zone definitions:
  {
    "my_zone": {
      "enabled": true,
      "dimension": "minecraft:overworld",
      "corner1": { "x": 100, "y": 60, "z": 200 },
      "corner2": { "x": 300, "y": 120, "z": 400 },
      "maxMobs": 50,
      "despawnDistance": 80,
      "xpReward": 5,
      "sunProof": true,
      "entryBoost": {
        "enabled": true,
        "multiplier": 4.0,
        "durationTicks": 100
      },
      "balance": {
        "enabled": true,
        "threshold": 30,
        "maxDespawnPerCycle": 5
      },
      "mobGroups": [
        {
          "entityId": "minecraft:zombie",
          "cooldownTicks": 60,
          "maxAlive": 15,
          "spawnMinDistance": 16,
          "spawnMaxDistance": 40,
          "attributes": {
            "healthMin": 30,
            "healthMax": 50,
            "speed": 0.26,
            "knockbackResistance": 0.0,
            "followRange": 40
          }
        }
      ]
    }
  }

  ---
  Web Dashboard

  Access the dashboard at http://your-server-ip:8080 (default port).

  Dashboard Sections

  Overview Cards - Total mobs, zone mobs, natural mobs, player count, server uptime

  Charts:
  - Population Timeline (5-minute rolling history)
  - Mob Type Distribution (top 12 types)
  - Zone Stress (% capacity per zone)
  - Spawns vs Kills (per zone)
  - Global Analysis (theoretical vs actual population curves with efficiency %)

  Zone Cards - Each zone displays:
  - Current mob count / max capacity with stress bar
  - Active boost indicator (pulsing orange badge)
  - Convergence rate and ETA to full capacity
  - Per-player mob distribution
  - Spawn success rate with failure breakdown
  - Mini entity radar with terrain overlay

  Zone Detail Modal (click a zone card):
  - Stats tab: Dimensions, bounds, boost status, balance settings, player distribution
  - Groups tab: Per mob-group alive count, cooldown, spawn attempts/successes/failures, retry stats
  - Radar tab: Large radar view with terrain, entities, spawn rings, and player positions
  - Analyse tab: Detailed metrics comparing configured vs actual values (cooldown, spawn rate, saturation, death rate,
  fill time), per-group theoretical vs real population curves

  Global Radar - World map showing all zone boundaries, entities (red = zone mob, yellow = natural), players (green)
  with spawn distance rings (cyan = min, green = max, red = despawn)

  Player Radars - Individual mini-radars centered on each player showing nearby entities and distance rings

  Player Table - Name, position, dimension, nearby mob count, current zone

  Configuration - Live view of all active settings

  Terrain Legend

  ┌──────┬───────────────────────────┐
  │ Code │          Terrain          │
  ├──────┼───────────────────────────┤
  │ G    │ Grass / Podzol / Mycelium │
  ├──────┼───────────────────────────┤
  │ D    │ Desert Sand               │
  ├──────┼───────────────────────────┤
  │ W    │ Water                     │
  ├──────┼───────────────────────────┤
  │ L    │ Lava                      │
  ├──────┼───────────────────────────┤
  │ N    │ Snow / Ice                │
  ├──────┼───────────────────────────┤
  │ T    │ Tree Leaves               │
  ├──────┼───────────────────────────┤
  │ B    │ Dirt / Wood               │
  ├──────┼───────────────────────────┤
  │ S    │ Stone / Rock              │
  ├──────┼───────────────────────────┤
  │ R    │ Nether Blocks             │
  ├──────┼───────────────────────────┤
  │ E    │ End Stone                 │
  ├──────┼───────────────────────────┤
  │ V    │ Gravel                    │
  ├──────┼───────────────────────────┤
  │ C    │ Clay / Terracotta         │
  └──────┴───────────────────────────┘

  API Endpoint

  GET /api/data returns a complete JSON snapshot of all statistics, updated every 3 seconds. Useful for building custom
  monitoring tools or Discord bots.

  ---
  How Spawn Control Works

  1. A mob attempts to spawn naturally
  2. Passthrough check: If the mob matches a passthrough pattern, it spawns normally
  3. Whitelist/Blacklist check: Is the mob in the config? Allowed or blocked based on mode
  4. Spawn chance: Roll the configured percentage (e.g., 80% for zombies)
  5. Per-player limit: Count mobs around the nearest player. Block if over limit
  6. Global cap: Check total world hostile mobs. Block if over cap
  7. Distance check: Block if too close or too far from any player
  8. Attribute application: Apply custom health, speed, knockback resistance, aggro range, follow range, and sun
  protection

  Zone mobs bypass all global checks and follow their own independent rules.

  ---
  How Zones Work

  1. Every server tick, active zones check for players inside their bounds
  2. For each mob group, if the cooldown has elapsed and the group isn't full:
    - Select the player with the fewest nearby zone mobs (fair distribution)
    - Find a safe spawn location within the spawn ring (min/max distance from player)
    - Spawn the mob with zone-specific attributes
    - If spawning fails, queue a retry for the next cycle (up to 5x multiplier)
  3. Every 3 seconds: despawn mobs beyond the zone's despawn distance
  4. Every 5 seconds: balance mobs if any player has too many
  5. Entry boost: When a player enters a zone, cooldowns are divided by the boost multiplier for the configured duration

  ---
  Compatibility

  - Minecraft: 1.20.1
  - Mod Loader: Forge (47+)
  - Side: Server-side only (clients don't need the mod)
  - Modded mobs: Fully supported. Add any modded mob ID to the JSON configs
  - Passthrough: Use modid:* to let entire mods bypass spawn control (essential for NPC mods, quest mobs, etc.)

  ---
  Quick Start

  1. Install the mod on your server
  2. Start the server once to generate default config files
  3. Edit config/mobcontrol-common.toml for global settings
  4. Edit config/mobcontrol-mobs.json to configure mob attributes and spawn chances
  5. (Optional) Edit config/mobcontrol-drops.json for custom drops
  6. (Optional) Enable zones in config/mobcontrol-zones.toml and define zones in config/mobcontrol-zones.json
  7. (Optional) Enable the web dashboard for real-time monitoring
  8. Use /mobcontrol reload to apply changes without restarting

  ---