Dynamic Biter Wave System & Miner Attraction Mechanic

Overview

The Mineshafts mod features two interconnected threat systems that create escalating danger the longer a player stays underground and the more they mine:

1. Dynamic Biter Waves — Timed waves that spawn near the player after a threshold
2. Miner Nest Spawning — Placing underground miners has a chance to awaken nearby biters

Both systems can be toggled via runtime settings.

1. Dynamic Biter Wave System

How It Works

The game tracks how long each player has spent on a mine surface. After a grace period, periodic biter waves spawn in a ring around the player and immediately attack.

Timing

Wave Scaling (by Mine Tier)

The mine's tier determines which biter types spawn and how many:

Wave Size Formula: 3 + (tier × 3) + random(0-4)

Spawn Behavior

• Biters spawn in a ring 15-30 tiles away from the player
• Each biter is given an immediate attack command targeting the player's character
• Biters have no distraction — they will not stop to attack other entities, only the player
• Waves spawn at random angles around the player (360° coverage)
• The system uses find_non_colliding_position to avoid spawning inside walls

Resetting

• Leaving the mine resets the timer completely
• Re-entering the mine starts a fresh 5-minute grace period
• Switching between different mine surfaces also resets the timer

Runtime Setting

• Setting: mineshafts-enable-biter-waves
• Default: Enabled
• Can be toggled during gameplay without restarting

2. Miner Nest Spawn Mechanic (Miners Attract Biters)

Concept

Placing underground miners disturbs the cave ecosystem. Higher-tier miners dig deeper and louder, attracting more dangerous creatures. When a player places a miner, there is a chance a biter spawner nest materializes nearby — representing biters being awakened by the mining vibrations.

Spawn Chances by Miner Tier

Spawn Behavior

• On miner placement, a random check is performed against the spawn chance
• If triggered, a biter-spawner is placed 15-30 tiles away from the miner at a random angle
• The spawner is a standard Factorio biter spawner that will continuously produce biters
• Only one spawner can spawn per miner placement (not cumulative)
• The spawner persists permanently — the player must destroy it or deal with ongoing biter production

Placement Restrictions

• Underground miners can only be placed inside mine surfaces
• Attempting to place them on the overworld (Nauvis) will refund the item and show a warning message
• Only whitelisted entity types can be placed inside mines

Strategic Implications

Combined Threat Timeline (Example: Tier 3 Mine)

Design Philosophy

The wave and attraction systems create a natural risk-reward loop:

• Short raids (under 5 minutes) are safe — grab loot and leave
• Extended mining requires active defense planning
• Higher tiers offer better ore but demand better combat preparation
• The player is never permanently safe underground — the mine fights back

Future Ideas & Expansion Concepts

Everything below is brainstorming only — not yet implemented. These are ideas for what could be added to make the wave and miner systems deeper and more engaging.

Wave System Expansions

Escalating Wave Difficulty

• Each consecutive wave in the same mine visit gets +15% stronger (more biters, tougher types)
• After wave 5, a mini-boss unit joins the wave (e.g. a behemoth biter with 3x HP)
• After wave 10, the mine becomes "Overrun" — constant biter spawning, no more breaks between waves
• Warning message: "The tunnels are collapsing with enemies... You should leave!"

Wave Composition Variety

• Mixed waves — Instead of all one type, waves contain a mix: 60% melee biters, 25% spitters, 15% worms that burrow out of the ground
• Flanking waves — Some waves split into 2-3 groups attacking from different tunnels
• Swarm waves — Rare wave type: 3x the number of biters, but all one tier lower
• Siege waves — Waves that include small worms that deploy themselves as static defenses

Wave Announcements & Audio

• Warning audio cue 10 seconds before each wave (rumbling, screeching in the distance)
• Chat warning: "You hear movement in the tunnels..." (30s before), "They're coming!" (5s before)
• Ground tremor effect — Screen shake before large waves
• Radar ping — Brief unchart/rechart pulse showing incoming biter positions on minimap

Wave Rewards

• Each survived wave spawns a small loot drop where the biters died (ammo, repair packs, rare items)
• Wave streak bonus — Surviving 5 waves without leaving grants a special chest with tier-scaled loot
• Bounty system — Killing X biters in a mine unlocks a "Mine Cleared" bonus on the ore output (+10% yield)

Environmental Wave Triggers

• Explosion trigger — Using explosives (grenades, rockets) in a mine has a 30% chance to trigger an immediate bonus wave
• Light trigger — Placing too many lights or lamps attracts biters faster (reduces grace period)
• Noise level — More active miners in the mine = shorter wave intervals (1 miner = 3 min, 5 miners = 1.5 min)

Miner Attraction Expansions

Vibration Mechanic

• Each active miner generates a "vibration level" that accumulates over time
• Higher vibration = higher chance of spawning nests, shorter wave intervals
• Vibration dampers — New craftable item that reduces vibration from miners (research-gated)
• Vibration level shown as a small GUI indicator when in a mine

Progressive Nest Spawning

• Instead of instant spawner placement, a "nest formation" entity appears first
• The nest formation takes 60 seconds to mature into a full spawner
• Players can destroy it before it matures (200 HP, fragile)
• Visual: A pulsating organic growth that slowly expands

Miner Defense Upgrades

• Fortified Miners — Research upgrade that gives miners a built-in turret (weak, short range)
• Sonic Repeller Module — Module that can be inserted into miners, reduces nest spawn chance by 50%
• Decoy Miners — Fake miners that attract biters away from real mining operations. Cheap to build, explode when attacked (dealing damage)

Biter Adaptation

• If the player always uses the same defense (e.g. only gun turrets), biters evolve resistance to that damage type over subsequent waves
• Forces players to diversify their defensive strategy
• Shown as a buff icon on the wave announcement: "The biters have adapted to physical damage!"
• Resets when the player leaves and re-enters the mine

New Threat Types

Cave-Ins

• Prolonged mining in an area has a small chance to trigger a cave-in event
• A section of tunnel collapses: floor tiles turn to rubble, blocking passage
• Entities (miners, belts) in the collapse zone take heavy damage
• Player caught in a cave-in takes damage and gets slowed
• Cave-ins can be prevented by placing support beams (new craftable structure)

Gas Pockets

• Mining into certain areas releases toxic gas clouds
• Gas deals damage over time and reduces visibility
• Players need gas masks (equipment grid item) or must wait for the gas to dissipate
• Gas is attracted to light sources — lamps pull gas toward them, creating safe/dangerous zones

Flooding

• Deep mines (Level 3+) have a chance of water flooding events
• Water slowly fills low sections of the mine, damaging electrical equipment
• Players must place pumps to drain flooded sections
• Water attracts unique aquatic enemies (cave leeches?)

Darkness Stalkers

• Invisible enemies that only exist in complete darkness (no lamp/light nearby)
• They deal chip damage to the player and make eerie sounds
• Placing lights reveals and kills them
• Forces players to manage their light coverage while exploring

Multiplayer Enhancements

Shared Threat Level

• In multiplayer, each player in the mine adds to the overall threat multiplier
• 2 players = 1.5x wave size, 3 players = 2x, 4 players = 2.5x
• But wave loot also scales — more players = more rewards

Rescue Missions

• If a player dies in a mine, their death location is marked on the surface map
• Other players can enter the mine for a rescue mission — retrieve the fallen player's items
• The mine enters a "corpse run" mode with reduced waves for 5 minutes

Competitive Mining

• Multiple players can enter the same mine simultaneously
• First player to reach the boss room gets a discovery bonus
• Biters aggro to the nearest player, creating natural "tank and DPS" roles

Economy & Progression Ideas

Mine Reputation

• Each mine tracks a danger rating that increases with time spent and waves survived
• Higher danger rating = better ore quality but increasingly difficult waves
• Danger rating slowly decreases when the mine is left alone

Underground Outposts

• Allow players to build permanent outposts deep in mines
• Outposts require constant power supply (via power poles from surface)
• Outposts reduce wave frequency in their radius but attract a siege event every 30 minutes
• Siege events are massive coordinated attacks from all tunnels simultaneously

Mine Depletion & Regeneration

• After extensive mining, ore deposits in a mine slowly deplete
• Depleted mines enter a dormant state — no more ore, but also no waves
• After a long cooldown (real-time hours), the mine regenerates with new layout, new ore, higher tier
• Creates a natural cycle of explore → exploit → move on → return

Trophy System

• Killing boss enemies drops trophies (unique items)
• Trophies can be placed as decorative items on the surface (bragging rights)
• Collecting all 5 ore-variant boss trophies unlocks a secret super-mine with all ore types and the hardest boss

Quality of Life Ideas

Mine Difficulty Indicator

• Before entering a mine, the entrance shows a difficulty rating (skull icons, color coding)
• Hovering over the entrance shows: ore type, tier, estimated danger, number of rooms
• Players can make informed decisions before committing

Expedition Timer

• Optional HUD element showing: time spent in mine, next wave countdown, active miners, vibration level
• Can be toggled on/off in mod settings

Quick Retreat Teleporter

• One-time-use craftable item that instantly teleports the player back to the mine entrance
• Expensive to craft, but invaluable when overwhelmed
• Destroyed after use — must craft a new one each time

Mine Map

• Craftable item that, when used, reveals the full mine layout on the minimap
• Shows room locations, boss room position, exit locations
• Does NOT reveal enemy positions
• Expensive to craft, one-time use per mine