AMBUSH

Ambush Make the world fight back. Ambush is a data-driven encounter framework for Minecraft 1.21.1 NeoForge. Create custom hostile encounters using datapack JSON files—without writing Java, maintaining scripts, or rebuilding the mod. An ambush can be as simple as two zombies approaching from outside the player’s view, or as complex as a moving boss fleet with reinforcements, projectile attacks, fog, sounds, rewards, and shared structure health. Each encounter is handled per player, so one person triggering an event does not automatically affect everyone else. Features Per-player encounters, targeting, cooldowns, and cleanup Datapack-driven JSON configuration Flat chance, weighted rarity, and failure-based chance buildup Custom evaluation intervals and cooldown groups Persistent encounter state across restarts Land, air, water, underwater, ring, cluster, and surround placement Out-of-sight spawning so enemies can approach naturally Immediate, delayed, repeating, and death-triggered waves Custom equipment, effects, attributes, NBT, passengers, and tags Configurable aggression range and through-wall targeting Long-distance pursuit for flying enemies Spawn and despawn effects Directional sounds, fog, fireworks, and rewards Built-in validation, diagnostics, and testing commands Triggers and Conditions Ambushes can react to: Biomes and biome tags Dimensions, height, time, and weather Surface, cave, mountain, ocean, and underwater environments Structures, structure tags, and custom structure groups Visiting multiple structure types Portals and active blocks Compatible active machines Inventory items and item counts Entity kills and player kills Villager trades Remaining above or below a height for a set duration Structure checks use loaded world data. Ambush does not generate distant terrain just to place or trigger an encounter. Smarter Enemy Placement Enemies do not need to appear directly in front of the player. Ambush can place mobs outside the player’s line of sight, surround the player in clusters, approach from a selected direction, or move toward a structure before detecting their target. Flying enemies can spawn in open air and continue following their assigned player. Water encounters can require the ocean surface or underwater space, while land encounters can reject water completely. All placement uses bounded attempts and already-loaded chunks. Waves and Directional Attacks Encounters can contain multiple stages triggered by time, repeating intervals, or the death of an earlier wave. Directional attacks support: Normal, spectral, tipped, and compatible modded arrows Potion volleys Entity rain and flying attackers Validated modded projectiles Optional Create Big Cannons support Attacks can come from a direction, encounter origin, or named moving structure. Pack creators can configure launch height, delay, burst patterns, velocity, spread, safe radius, exact targeting, ballistic compensation, firing range, and staggered attacks from multiple sources. Optional Aircraft and Fleet Encounters With compatible Create Aeronautics, Simulated, and Sable mods installed, Ambush can turn structure-template NBT files into moving aircraft encounters. Aircraft support includes: Player-facing and cardinal orientation Fleets, surrounding formations, and from-above attacks Different ship designs in the same fleet Balloon fill and engine burn time Optional superheated engines Fixed or Y-level-based throttle controls Live steering based on the player’s position Forward and reverse propulsion Seated crews and additional deck enemies Crew-controlled weapons and redstone Container loot tables Structure lifetimes and damage cleanup Parent, child, and detached-fragment tracking Ships can move forward while the player is ahead, reverse when the player gets behind them, and automatically compensate their steering when propulsion changes. Ambush includes its own guarded Sable assembly support and does not require a separate assembly-helper mod. Generic encounters work normally without any aircraft mods installed. Structure Bosses Moving structures can use their remaining blocks as health and display that health with a boss bar. Several ships can share one health pool, allowing an entire fleet to act as one boss. Health percentage events can: Fire projectile waves Summon reinforcements Spawn additional ships Activate redstone components Apply fog or effects Play directional sounds Create fireworks Spawn reward structures Start another ambush Structure health uses bounded processing budgets to reduce lag during large encounters. Chance and Cooldown Control Pack creators control how often encounters are checked and how rare they are. Definitions can use flat chance, weighted selection, increasing chance after failed rolls, maximum buildup limits, custom evaluation intervals, and named cooldown groups. Cooldown groups can separate cave, surface, air, ocean, and structure encounters or make several encounters share one cooldown. Commands Commands require operator permission. /ambush <type> [player] Runs an ambush using its normal requirements. /ambush always <type> [player] Forces an ambush while bypassing chance, cooldowns, and trigger restrictions. /ambush list Lists loaded definitions. /ambush validate Reports validation results. /ambush weights Displays rarity and weight information. /ambush state Displays tracked encounter state. /ambush debug Enables detailed server-console diagnostics. Leaving out the player targets the command user. External datapack definitions can be updated with /reload. Changes to the mod jar or bundled resources require a restart. Included Examples Ambush includes five command-only examples: ambush:example_boss ambush:example_boss_fleet ambush:example_cannon_balloon_fleet ambush:example_directional_arrow_rain ambush:example_master The examples demonstrate structure bosses, shared fleet health, directional attacks, reinforcements, redstone, fog, rewards, crew placement, steering, and live propulsion. All bundled examples have natural chance set to zero. They will not appear during ordinary gameplay unless referenced by another datapack or manually started by an operator. Requirements Minecraft 1.21.1 NeoForge 21.1.228 or newer Java 21 Optional integrations: Create Create Aeronautics Simulated Sable Create Big Cannons Datapacks only need the mods required by the features and content they reference. Ambush is released under the MIT License. Full source code, documentation, examples, schematics, and build files are available in the GitHub repository.