AMBUSH

Build encounters that make your modpack fight back.

Ambush is a data-driven encounter framework for Minecraft 1.21.1 NeoForge, built for modpack creators who want full control over hostile events.

Create custom encounters using datapack JSON files without writing Java, maintaining KubeJS scripts, or rebuilding the mod whenever you want to make a change. The mod contains ambushes already if you want to try it out!

An encounter can be as simple as enemies approaching from outside the player’s view, or as complex as a multi-stage fleet boss with skeleton crews, cannon volleys, reinforcements, fog, sounds, rewards, and shared health.

Made for Modpack Creators

Ambush gives you control over nearly every part of an encounter.

Trigger conditions can use biomes, dimensions, structures, weather, time, player height, inventory items, mob kills, villager trades, portals, active machines, and more.

Spawn behavior can place enemies outside the player’s view, around the player, inside caves, in open air, on land, at sea, underwater, or near structures.

Combat behavior can include custom equipment, effects, attributes, targeting ranges, pursuit behavior, projectile attacks, reinforcements, and multiple encounter stages.

Progression and rarity can use flat chance, weighted selection, cooldown groups, increasing chance after failed rolls, and player-based unlock conditions.

Definitions can be updated through datapacks and reloaded without rebuilding the mod. Documentation is at https://github.com/TiyunSol/AMBUSH which should help you create your own datapacks! join the discord and ask questions if you need help!

Encounters That Feel Natural

Enemies do not need to appear directly in front of the player.

Ambush can place them outside the player’s line of sight, send them in from a chosen direction, surround the player in multiple groups, or have them approach a structure before detecting their target.

Flying enemies can spawn in valid open-air locations and continue pursuing their assigned player over long distances.

Water encounters can require the ocean surface or underwater space, while land encounters can reject water entirely.

Placement only uses loaded chunks and bounded spawn attempts.

Waves and Directional Attacks

Encounters can have several stages that begin after a delay, repeat on an interval, activate when an earlier wave dies, or trigger when a boss reaches a health threshold.

Directional attacks can include normal arrows, spectral arrows, tipped arrows, potion volleys, flying attackers, entity rain, compatible modded projectiles, and Create Big Cannons ammunition.

You can configure firing direction, launch height, velocity, spread, burst size, delay, safe radius, firing range, exact targeting, ballistic compensation, and attacks from several staggered sources.

Moving Ships and Fleet Battles

With compatible Create Aeronautics, Simulated, and Sable mods installed, Ambush can turn structure-template files into moving ship and aircraft encounters.

Ships can track players, steer based on their position, move forward or reverse, hold firing distance, and choose the correct side for broadside attacks.

Skeleton crews and other custom crews can actively acquire targets, operate redstone-controlled weapons, and fire cannon volleys from the correct side of the ship.

Ships can appear alone, surround the player in formations, attack from above, or arrive as coordinated fleets.

Several ships can share one boss health bar, call in reinforcements, activate weapons at different health levels, and begin destruction sequences as they take damage.

Ship movement, steering, crew aggression range, cannon timing, propulsion, balloon fill, engine power, formations, loot, and health events are all configurable.

this also supports cars and boats.

Aeronautics support is optional. Standard mob encounters work normally without Aeronautics installed.

Structure Bosses

Moving structures can use their remaining blocks as health and display that health with a boss bar.

A single ship can act as a boss, or an entire fleet can share one health pool.

Health-based events can fire cannon volleys, summon reinforcements, spawn additional ships, activate redstone components, apply fog or effects, play directional sounds, create fireworks, place reward structures, trigger destruction sequences, or begin another ambush.

Structure health uses bounded processing limits to reduce lag during large encounters.

Per-Player Encounter Tracking

Ambush tracks encounters, cooldowns, targeting, unlocks, and cleanup separately for each player.

One person triggering an ambush does not automatically affect everyone else on the server.

Encounter state can persist across server restarts, allowing more advanced progression and long-running encounter systems.

Built-In Creator Tools

Ambush includes commands for loading encounters, forcing tests, validating datapack definitions, viewing rarity weights, inspecting player state, enabling detailed diagnostics, clearing active encounters, controlling natural spawning, and unlocking gated content during development. It also includes /ambush admin inspect, /ambush admin unlocks, and /ambush admin unlockall for active-ship and unlock debugging.

Natural spawning can be controlled globally, by datapack namespace, or for one encounter. /ambush admin spawning <id> disable disables one encounter’s natural spawning across server restarts; use enable to restore it, and /ambush admin spawning status to view the current state.

External datapack definitions can be updated with /reload.

Requirements

Minecraft: 1.21.1
NeoForge: 21.1.228 or newer
Java: 21

Optional Integrations

Create: 6.0.10 through 6.0.x
Create Aeronautics: 1.3.0 through 1.3.x
Simulated: 1.3.0 through 1.3.x
Sable: 2.0.3 through 2.0.x
Create Big Cannons: 5.11.7 through 5.x
FTB Quests: 2101.1.30 or newer

Lootr: Optional compatibility for per-player ship-container loot Datapacks only require the mods used by the entities, items, projectiles, machines, ships, or other content they reference.

(Temporary) I am working on a modpack to showcase ambush! if you want your ambush idea, or schematic in the modpack join the discord!