Mining System Design Specification

1. Vision & Session Architecture

1.1 Design Pillars & Vision

The Mining System serves as the single resource-gathering engine for the game, built upon a non-violent, cozy subterranean exploration framework.

Combat-Free Subterranean Exploration Goals

Environmental & Navigation over Combat: Challenge of the mine floors come from balancing your resources such as light, pickaxe and inventory capacity instead of encountering combat enemies.

Intrinsic Discovery: The mine is designed as an infinite, organic ant-nest cavern system where every descent offers unique procedurally generated spatial layouts, hidden wall pockets, evnironmental hazards and cavern fog which applies darkness.

Resource-Driven Purpose: Mining directly feeds the Blacksmithing and Shopkeeping loops. Every swing of the pickaxe yields materials with tangible crafting utility or monetary value.

Atmospheric Tension & Cozy Player-Driven Pacing

Soft Efficiency Caps: Players are never forcibly ejected from the mine by artificial “day/night” limits or collapsing tunnels. Instead certain resource drain creates a subtle tension and finite duration for them.

Low-Stress Strategic Risk: Death or total inventory loss mechanics do not exist. The core tension revolves around inventory space optimization, tool durability efficiency, pathfinding in dark caverns and deciding when to push deeper versus returning to the shop to process gathered wealth.

Atmospheric Solitude: The underground environment emphasizes tactile, satisfying audiovisual interactions, echoing pickaxe impacts, harmonic sonar pulses, ambient cave resonance, and luminescent flora.

1.2 Core Mining Loop & State Diagram

The mining session follows a clean 4-stage lifecycle:

Base Entry > Exploration > Depth Escalation > Base Return

1.3 Session Lifecycle & Transition Logic

1.3.1 Entering the Mine

Access Point: Interacting with the Base Mine Entrance (located in the shop) triggers the Mine Layout UI.

Entry Point Selection: Players can choose one of the three following entry points;

• Level -1: Default entry point. Always accessible.

• Elevator Shaft Milestones: Allows fast-travel directly to any unlocked Elevator Shaft Hub. (e.g. -10, -20, -30, … -70, -150)

1.3.2 Elevator Shaft Checkpoint & Repair Mechanics

Every 10th level (-10, -20, -30, …) there’s a ruined Old Elevator Shaft. This acts both as progression gate and permanent fast-travel checkpoint once restored.

Evelevator Repair Source Requirements

To repair an Elevator Shaft and gain access to the deeper floors, the player must meet the requirements at the shaft interface. These requirement fall into three categories consistent with every Old Elevator Shaft, only the contents of those change:

1. X amount of Raw Ore (Found in nearby floors)

Raw, unrefined ores collected from the current or immediately preceding 4 floors.

2. Y amount of Processed Materials (Crafted in workshop)

Metal ingots, alloys, reinforced beams, chains or structural hardware forged at the workshop.

3. Z amount of Special Components (Either found or purchased)

Rare mechanical or mystical components can only be obtained in the mine -with a low chance- or purchased from the sellers in town by medium to high cost.

1.3.3 Depth Escalation (Descending & Ascending)

Descending points work both ways, meaning player can use the same point when they used for descending N-1 from N, also when ascending to N from N-1.

In order to use the descend point players simply interact with it in its interaction range.

In every interaction the system does a Hazard Gate Check to see if lower floors are available. If true, the players are shown Guild Notice, if false they can proceed regularly.

Players cannot hire/make contract with mercanaries unless they’re in the shop. Mid-session contracts are not allowed.*

1.3.4 Returning to Base

Execution:

• Always accessible via a dedicated HUD button or Pause Menu action while in the EXPLORING_FLOOR state.

• Triggering the action enters the CHANNELING_RETURN state and 5.0 second channel bar fills on the HUD.

• Moving, taking an action or getting hit by environment cancels the channel and resets the timer. The channel can be started again after 0.5 seconds cooldown.

Upon Completion:

Player is teleported back to Base Shop Portal.

Sytem executes the SESSION_CLEANUP

• Unsaved temporary floors are flushed from RAM memory.

• Repaired Elevator Shaft flags are registered permanently.

• Inventory items remain fully intact in player storage. Overflow items left behind are deleted regardless of the floor they’re in.

1.4 Organic Efficiency Limits & Soft Caps

1.4.1 Sunstone Energy System (Primary Organic Clock)

The player carries a Sunstone that steadily consumes its internal energy while exploring. Drain rate is 1 unit of energy per 10 seconds (the last unit lasts 25 seconds). The base Sunstone holds 30 units, creating a natural 5-minute 15-second duration per full charge.

As energy depletes, the radiance of the Sunstone decreases incrementally rather than shutting off abruptly.

• 100% – 50% Energy: Maximum illumination radius.

• 49% – 15% Energy: Medium illumination radius (soft light change with a gradually dimming animation).

• 14% – 1% Energy: Dim emergency glow (only illuminates adjacent 2 tiles).

• 0% Energy (Empty): Energy completely depleted. The player is left with only a faint glowing outline of their sprite, enough to see adjacent walls and ground, but nothing further.

Note: The final unit of energy has a 2.5x duration boost, lasting 25 seconds instead of 10.

Replenishment Mechanics:

• Carried Sunstones: Players can carry up to 3 reserve Sunstones . Swapping or using a reserve Sunstone restores energy to the active slot.

• Base Charging: Sunstones do not restore automatically on return; they must be recharged at base. Sunstones charge individually at a rate of 0.5% per second (200 seconds for a full charge).

• Sunbeams: During an active session in the mine, players can discover natural Sunbeams that illuminate specific spots. Placing a Sunstone in a Sunbeam recharges it at a rate of 2% per second (50 seconds for a full charge), up to its maximum 100% capacity.

1.4.2 Tool Durability

The pickaxe is the player’s permanent primary tool for mining and digging. It features an explicit durability pool that is both upgradable and repairable.

A. Durability

Every successful swing (hitting a hittable object) subtracts durability from the pool based on the target’s hardness score:

• Node Hardness Scaling: Hittable objects have varying hardness scores (e.g., a wooden barrel is 0.5, while diamond ore is 8.0).

• Direct Subtraction: The hardness score is directly subtracted from the durability pool per successful hit (e.g., a 600 durability pickaxe drops to 592 after striking diamond ore).

Note: Swinging the pickaxe in the air spends no durability.

B. Degradation States

When the primary durability pool reaches 0, the pickaxe degrades into secondary performance states:

1. Critical Durability: Triggered when primary durability hits 0. This spawns a secondary durability pool equal in size to the first. While active, every hit deals 0.5x damage to hittable objects.

2. Impaired State: Triggered when the Critical Durability pool hits 0. The axe turns Impaired, and hits deal 0.25x damage until repaired.

UI/UX Feedback

• Critical Durability State: When the primary pool hits 0 and the Critical Durability pool activates, the HUD durability bar changes color (e.g., from green to orange/warning state) and triggers a distinct audio cue (e.g., metal cracking sound effects) to alert the player.

• Impaired State: When the tool enters the Impaired state, the HUD durability bar flashes red or displays a critical warning, accompanying a heavier metallic straining sound to indicate severely reduced efficiency (0.25x damage).

C. Repairing

Repairs can restore the pickaxe’s durability pools, can be done two ways:

• Workshop Repairs: Performed at the workshop for a standard, economical cost.

• In-Mine Repairs: Performed at abandoned camp sites in the mine. These ask a much higher cost than workshop repairs.

D. Pickaxe Upgrades

Upgrades can be crafted to enhance three core attributes:

1. Total Durability: Changing the metal head and handle of the pickaxe increases its max durability parallel to general game progression.

2. Hit Damage: Increases damage dealt to hittable objects, making them easier to destroy and collect.

3. Hit Speed: Decreases the intervals between every hit (subject to a strict hard cap).

1.4.3 Carrying Capacity

Ores are categorized into three distinct weight classes: Light , Medium , and Heavy . Rather than pooling total weight, the inventory tracks the slot composition of each category independently.

If a player crosses the threshold for any single category, they incur a universal movement speed penalty. This structure allows players to maintain a 100% full inventory without penalty as long as their haul is properly balanced across weight classes.

Thresholds :

Light Ores: Incurs penalty at ≥80% total inventory slot capacity.

Medium Ores: Incurs penalty at ≥60% total inventory slot capacity.

Heavy Ores: Incurs penalty at ≥40% total inventory slot capacity.

Penalty State:

Flat -15% movement speed.

Note: Crossing multiple category thresholds does not stack the penalty; the modifier remains a flat -15%, serving as a clear functional boundary rather than a compounding punishment.

Example: 20-Slot Inventory Reference

• Light Class:

  • ≤16 slots: No penalty.

  • ≥17 slots: -15% movement speed penalty.

• Medium Class:

  • ≤12 slots: No penalty.

  • ≥13 slots: -15% movement speed penalty.

• Heavy Class:

  • ≤8 slots: No penalty.

  • ≥9 slots: -15% movement speed penalty.

Design Intents & Player Experience

Anxiety-Free Fullness: Players can fill their backpacks to maximum capacity (e.g., a mix of 8 Heavy, 8 Medium, and 4 Light items in a 20-slot bag) entirely free of penalties. The restriction acts as a gentle guideline rather than a hard logistical wall.

Anti-Hoarding: The lower threshold on Heavy items discourages players from recklessly mass-hoarding rare heavy ores, encouraging strategic composition of their mining haul. Creating and encouraging diverse inventories.

Upgradability: Expanding the backpack slot count (e.g., from 20 to 30 slots) organically scales these thresholds up, removing late-game capacity friction and linear anxiety.

UI & Clarity: Supported by a simple HUD tooltip warning when a category approaches its threshold, keeping the mechanic intuitive and transparent without forcing complex math on the player.

2. Procedural Mine Generation

2.1 Feature Overview

The Procedural Mine Generation (PMG) system dynamically builds organic, cave-like levels for the player to explore. Every floor provides a fresh, distinct layout featuring winding tunnels, varied cavern shapes, water features, and deliberate environmental pacing.

Key Design Goals

• Meaningful Traversal: Ensure every floor feels like a journey by placing the entry and goal at opposite ends of the map.

• Organic Exploration: Avoid repetitive square rooms or grid-like corridors in favor of natural, cavernous layouts with multiple interconnecting paths.

• Guaranteed Progression: Ensure every generated floor is 100% playable, fully connected, and free from soft-locks or unreachable areas.

2.2 World & Topology Structure

2.2.1 Cavern Room Types & Roles

Each floor is composed of connected cavern chambers, categorised into four distinct roles:

• Entry Room: Located in the northernmost region of the floor. Serves as the safe landing zone containing the entry ladder.

• Exit Room: Located in the southernmost region of the floor. Houses the descend shaft leading deeper into the mine.

• Hall Rooms: Promoted filler chambers designed as wider, open transit zones to prevent navigational monotony.

• Pocket Rooms: Standard cavern chambers where the majority of encounters, resource nodes, and environmental props spawn.

Design Note: To maintain visual variety, the generator can periodically insert handcrafted room layouts (Room Templates) alongside purely procedurally shaped caverns.

2.2.2 Navigation & Path Layout

To ensure exploration feels open yet structured, the floor navigation follows these specific topological rules:

• Guaranteed Connectivity: All rooms on a floor must be interconnected. Dead-end clusters are intentionally minimized.

• Loop Traversal: Rather than a strict single-path maze, floors generate short-circuit loops between nearby rooms. This allows players to circle back or choose alternate routes without tedious backtracking.

• Organic Corridors: Tunnels curve and wind naturally, avoiding straight, artificiallooking paths or rigid 90° turns.

2.3.2 Visual & Map Framing

• Rugged Walls: Cave perimeters feature eroded, jagged rock walls rather than flat edges, enhancing the underground aesthetic.

• Void Isolation*:** The playable cave network is framed by a bedrock boundary transitioning into deep void space, keeping player focus inside the active mine bounds.

2.3.3 Clearances & Safety Buffers

• Interactive Anchors: Entry ladders and Exit shafts guarantee an unobstructed 3x3 interaction buffer, ensuring players never spawn trapped inside rock faces or cramped corners.

• Elevator Floors: On elevator levels (every 10th floor), the Exit zone transitions into an Elevator Hub , featuring wider structural clearances to accommodate large machinery.

2.4 System Logic & Safety Checks

2.4.1 Floor Integrity & Validation

To guarantee high-quality levels, every generated floor undergoes automated quality validation before being presented to the player:

1. Reachability Check: The system verifies a clear, walkable path exists from the Entry ladder to the Exit shaft.

2. Orphan Cleanup: Any isolated floor patches disconnected from the main cave network are automatically sealed back up as solid rock.

3. Fail-Safe Retries: If a floor fails reachability or generation bounds, the layout is discarded and regenerated silently using a new variance seed.

2.5 Configurable Balance Parameters

3. Cavern Lighting, Visibility & Fog-of-War

3.1 Lighting Radius & Visual Tiers

3.1.1 Dynamic Sunstone Aura

Sunstone is dynamic ligth source players carry around with them and it’s the primary light source in mine floors during exploration.

A. Illumination

Omnidirectional Light: The sunstone emits a 360° radial light field centered on the player character.

Uniform Illumination: The illuminated area is fully lit regardless of the remaining energy percentage. As the energy depletes the intensity of the light stays the same, only the radius of the area contracts in steps towards the player.

Dynamic Radius Scaling: Maximum light range scales directly based on the energy level of the Sunstone (defined in Section 1.4.1)

• Full Energy (100% – 50%): Max Radius = 7 tiles.

• Low Energy (49% – 15%): Max Radius = 4 tiles.

• Critical Energy (< 15%): Max Radius = 2.5 tiles (with a rapid flickering/instability effect).

B. Occlusion Logic

2D Raycasting: Light rays check against solid cavern wall colliders and solid cavern rock blocks light rays, preventing the aura from clipping into unexplored adjacent tunnels behind solid walls.

C. Environmental Triggers

• Detection Trigger: Any interactable resource node (e.g., ore nodes, gem clusters, destructable hidden wall pockets etc.) inside the on-occluded light radius switches its visual state from “idle” to “lit”

• Shimmering: When illuminated by the Sunstone Auro, interactables trigger a subtle shimmer shader effect across their surface texture to draw attention of the players, signaling its interactability.

• Occlusion Masking: Nodes behind solid walls do not trigger this effect. (Unless they’re specially scanned, check 8.4)

D. Visual Aesthetics

• Atmospheric Palette: Emits a warm subterranean glow to complement the cozy aesthetic while maintaining strong contrast against unlit cave floors.

• Idle Pulse Effect: Subtle breathing effect to make the light feel organic and dynamic.

3.1.2 Deployable Light Sources

A. Wall Torch

Player can place wall torches with a dedicated key to the nearest wall tile if they are in the interaction zone.

Storage

• Max Stack Capacity: The player can carry a maximum of 12 Wall Torches in active inventory at any given time.

• Permanent Placement: Once placed on a cavern wall, a Wall Torch becomes a permanent fixture for its duration and cannot be removed, picked up, or relocated .

Placement Rules

• Dedicated Binding: Deployed using a dedicated quick-key input ([Place Torch]).

• Proximity Check: Placement is valid only if the player character is within an Interaction Zone of ≤1 tile from a solid cavern wall.

• Auto-Snap Behavior: Upon input validation, the torch automatically snaps to the face of the nearest adjacent wall tile, orienting its light projection outwards into the open cavern corridor or room.

Lighting Projection

• 180° Directional Arc: Unlike the Sunstone’s omnidirectional 360° light aura, Wall Torches project a wide 180° semi-circular light cone extending outward from the wall face.

• Warm Colors: Emits a distinct, warm campfire-style tone (visually warmer/deeper than the central Sunstone aura) to provide clear visual distinction between mobile personal light and static placeable light.

• Node & Ore Activation: Any resource node covered within the active 180° torch beam switches to its “lit” visual state, triggering node shimmer and surface highlights

Lifespan & Timer Logic

Active Duration: Each deployed Wall Torch remains lit for a total active lifespan of 5.0 minutes (300 seconds).

Visual Transitions:

• Standard Phase (0:00 – 4:30): Full brightness with standard warm illumination.

• Warning Phase (4:30 – 5:00 / Last 30 Seconds): The light hue shifts to a distinct reddish glow accompanied by an erratic flickering shader to signal impending burnout.

• Extinguished Phase (5:00+): Light projection turns off completely, the torch sprite visually transitions to a burnt-out ash state.

Cross-Floor Pause Rule: Torch timers are linked exclusively to active floor runtime. If the player ascends or descends to a different floor, active torch timers on non-loaded floors are paused and resume precise countdown upon the player returning to that floor.

B. Glow Marker

Glow Marker is a tool that lets players to place permanent arrow markers on the floor with 8- directional way. These are permanent non-illuminating marks with a soft blue glow.

Mechanics & Placement Rules

• Footprint & Orientation: Occupies a single 1x1 floor tile. Upon placement, the player selects one of 8 cardinal/intercardinal directions (N, NE, E, SE, S, SW, W, NW) to orient the arrow indicator.

• Placement Surface: Can be stamped directly onto any walkable ground tile. Cannot be placed inside solid rock walls or water tiles. Cannot be placed on occupied floor tiles.

• Infinite Supply & Cooldown: Glow Markers do not consume inventory stack slots or crafting materials. Deployment is governed solely by a global 5.0-second cooldown timer to prevent spamming.

• Permanence: Placed markers remain permanently on the floor for the entire duration of the mine session.

Lighting & Visual Characteristics

• Zero Lux Emission: Glow Markers emit no ambient light rays onto surrounding tiles, walls, or ore nodes. They do not trigger resource shimmer overlays or reveal hidden wall pockets.

• Self-Luminescent Overlay: Rendered with an unlit/emissive shader overlay (light blue aura). Markers remain self-illuminated, and clearly legible even when in complete darkness.

• Readability: Rendered flat on the ground plane with high contrast against subterranean rock textures to ensure immediate visual identification at camera distances.

Player Utility

• Breadcrumb Mapping: Intended as a permanent directional guide pointing towards key landmarks (e.g., Return Elevator Shaft, unchecked branch corridors, or hazardous zones).

• Non-Blocking Collision: Fully walkable, possesses no physics or tile colliders, allowing the player to pass over placed markers freely.

3.1.3 Environmental Beacons

Environmental Beacons are static or ambient light sources dynamically scattered throughout the subterranean environment during procedural generation. They serve three core functional roles:

• Passive Navigation & Orientation: They break complete pitch darkness, giving players natural visual anchors to navigate and orient themselves without relying entirely on active player lighting.

• Spatial Feature Highlighting: They draw player attention toward key points of interest, such as valuable ore deposits, open cavern chambers, water features, or traversal hazards.

• Atmospheric Immersion: They enrich the subterranean aesthetic, reinforcing the cozy, non-violent exploration tone through varied color temperatures and gentle visual effects.

A. Core Natural Environmental Beacons

B. Artificial Beacons: Abandoned Camp Lampposts

In addition to natural bioluminescence, player-made structures from past mining expeditions exist within the cavern network:

Placement: Abandoned Camp Lampposts spawn exclusively within hand-crafted or procedural Abandoned Camp room templates.

Visual:

• Emits a warm 360° incandescent orange glow (5-6 tile light radius).

• Feature an atmospheric flickering effect, contrasting against the cool ambient tones of natural cave bioluminescence.

State & Interaction Rules:

• Pre-Lit Lampposts: A percentage of camp lampposts remain actively burning upon floor generation, serving as immediate safe-haven landmarks.

• Dormant Lampposts: Unlit lampposts can be interacted with using minor fuel or scrap items to permanently illuminate the camp for the remainder of the session floor run.

C. Procedural Spawning & Balance Rules

Density Soft Caps:

• Environmental beacons are capped per room during Stage 5 ( SpawnObjects ) of the generation pipeline to prevent over-lighting.

• Target Density: 5% - 20% of total floor tiles across a generated cavern floor should fall within an environmental beacon’s ambient light halo.

Fog-of-War Integration:

• Environmental beacons interact with the fog system: when in unexplored fog, glowing ores and fireflies display subtle visual shimmers/particle overlays through the dark, teasing unexplored areas ahead.

Performance Optimization:

• All natural beacons utilize optimized 2D tilemap point-light emitters and static falloff shaders, ensuring zero performance impact during large procedural layout renders.

3.2 Fog-of-War Framework

3.2.1 Unexplored Cavern & Map Tracking

A. Screen-space Discovery

The game uses a Screen-Space Fog-of-War System . Rather than relying on a HUD minimap, map discovery is handled entirely through the full-screen map overlay ( [M] key).

The core principle of map tracking is “Visual Line-of-Sight”:

“If an illuminated area or object enters the player’s active screen view, it is permanently drawn onto the map.”

This allows players to spot distant bioluminescent flora, shimmering ore veins, or glowing puddles at the edges of their screen and immediately have those locations saved on their map layout while player centered illimunators staying primary way of revealing map.

B. The Dual-Condition Map Reveal Pipeline

For any given tile on the cavern floor to transition from " UNEXPLORED " to “EXPLORED” on the [M] Map Overlay, it must meet one of two discovery rules:

RULE 1: Direct player proximity

[Tile in Range of Sunstone / Torch / Lamppost] > Reveal on Map

RULE 2: Screen-space environmental discorvery

[Tile is “lit” by beacon] AND [Tile inside camera viewport] > Reveal on Map

Rule 1: Direct Proximity Light (Sunstone / Torches / Lampposts)

Automatically clears fog in a 360° radius around the player or placed fixture, logging those tiles to the map continuously regardless of camera orientation.

Rule 2: Viewport-Gated Environmental Light (Fungi / Ores / Puddles / Fireflies / Sunbeams)

• Environmental light sources illuminate the cavern floor in-game at all times.

• However, they only register onto the [M] Map overlay once the lit tiles pass within the bounds of the active Camera Viewport (the player’s visible screen frame).

Island Map Patches: If an environmental beacon is located near the edge of the player’s screen, its lit halo is logged onto the map as an isolated “island” of revealed terrain in the fogof-war, giving the player clear navigational reference points across unvisited rooms.

C. Light Source & Map Registration Matrix

All light sources in the game contribute to permanent map reveals, governed by whether screen visibility is required:

D. Full-Screen Map Overlay System ([M] Key)

Camera Viewport Bounding Box Check

During exploration, the engine runs an efficient 2D bounding-box overlap test for environmental light sources:

Viewport Bounds (Bcam): Defined by the current orthographic/isometric camera view rectangle.

• Light Bounds (Blight): The spatial footprint of any active environmental beacon.

• Evaluation: When Bcam ∩ Blight ≠ 0 all tiles within Blight are flagged in the floor’s “ExplorationGrid” array as “IsExplored = true”.

Asynchronous Texture Baking

• Performance Rule: The map UI does not re-render every frame.

• Bake Event: When the player presses [M], the system checks “IsMapDirty”. If new tiles were lit via proximity OR entered the camera screen since the last check, the map overlay bakes the updated “ExplorationGrid” state into the map canvas UI texture.

Real-Time Node Logging

• Automatic Node Logging: As soon as a glowing ore node or resource enters the screen frame, its specific (X, Y) coordinate and resource type are recorded to ActiveMapNodes.

• Map Legend Display: The node appears instantly on the map display with its corresponding icon and increments the count in the Map Legend sidebar .

• Depletion Handling: Upon completely mining an ore node, the OnNodeDepleted event removes it from ActiveMapNodes. The next time [M] is pressed, the icon is removed from both the map image and the legend count.

4. Spatial Navigation & Traversal Systems

4.1 Core Player Movement

4.1.1 Movement Scheme

Player movement is driven by a smooth, polished 8-directional WASD input vector tailored specifically for the game’s faux-isometric perspective.

Normalized Movement Vector : Diagonal inputs ( W+A ,W+D, S+A, S+D ) are mathematically normalized to maintain a consistent movement speed across all 8 cardinal and intercardinal directions, preventing diagonal speed boosts.

No High-Velocity Mechanics: High-impact movement abilities such as dashes, dodge-rolls, tackles, blinks, or sprints are intentionally excluded. Now allowing sudden acceleration mechanics reinforces the game’s non-combat, relaxing design pillars and maintains an uninterrupted, cozy exploration pace.

4.1.2 Directional Change

Instant Directional Flipping: Visual rotation times and turn-rate delays are eliminated. Sprite orientation updates instantly upon keypress, providing crisp and immediate input feedback. No Vertical Movements: Player movement is strictly bound to a 2D floor plane. Jumping, falling, airborne movement, or free vertical positioning do not exist.

Vertical Impermanence: Floor ascension and descension are exclusively triggered via dedicated environmental travel nodes (e.g., Entry/Exit Points and Elevator Shafts).

4.1.3 Corner Correction

Corner Nudging/Correction: To prevent players from awkwardly snagging or sticking against sharp 90° tile corners during movement, a Corner Correction mechanism is active along solid tile boundaries.

Smooth Traversal Glide: When a movement vector partially collides with the corner of a nonwalkable tile, the collision pipeline applies force to smoothly guide the player past the corner into the open path ahead.

Boundary Limits: Player physics colliders are rigidly bounded by floor tile geometry. Players are restricted strictly to valid TileType.WalkableFloor or bridged tiles.

4.1.4 Camera Trailing

SmoothDamp Trailing Camera: The virtual camera follows the player’s spatial position with a subtle, delayed drag rather than being rigid-locked to the player anchor.

Natural Deceleration: When player movement ceases, the camera does not snap to a rigid halt; instead, it executes a smooth deceleration curve (SmoothDamp), easing gently to a complete stop.

4.2 Procedural Chasms & Plank Bridge Mechanics

4.2.1 Procedural Chasm Generation Rules

Definition & Role: Chasms are bottomless void channels procedurally generated within the cavern grid. They act as impassable terrain features that prevents direct movement across cavern paths unless covered with plank bridges.

Floor Level Floor-Gate: - Floors 1–5: Chasms are strictly disqualified from spawning on the first 5 floors (Floors 1 through 5) to allow players to master basic mining and navigation loops without encountering void barriers.

• Floors 6+: Chasms begin spawning as low-probability procedural features.

Placement Constraints:

• Shortcut Isolation: Chasms generate only on optional side branches, secondary loops, and bonus resource islands. They are strictly prohibited from generating along the primary path between the floor entry point and descend shaft.

• Spawn Frequency & Cap: Chasm spawn chances are kept intentionally low and will not appear on every floor level. A hard ceiling limits generation to a maximum of 3 chasms per floor .

Topology Geometry:***

• Chasms spawn as organic clusters ranging from 1 to 3 tiles wide.

4.2.2 Impassable Void Collision

Safety Floor Rule: Players cannot fall into chasms or suffer fall injuries. In alignment with cozy design principles, chasm edges function as solid, impassable collision barriers.

4.2.3 Plank Bridge Deployment

Plank Bridges are 1x1 items deployed individually.

Deployment Interaction:

• Standing on a walkable tile directly adjacent to an open Chasm tile and facing the void triggers an interaction prompt.

• Pressing [E] consumes one Wooden Plank from player inventory and places it onto the targeted Chasm tile.

Instant Tile Transformation:

• Upon placement, the underlying tile state instantly transforms:

TileType.Chasm → TileType.WalkablePlankBridge

• The collider updates instantly from an impassable void boundary into a fully walkable floor surface. Non-Retrievable Placement: Once a Wooden Plank Bridge is placed on a chasm tile, it becomes permanently fixed to that floor grid for the remainder of the session and cannot be picked back up into inventory.

5. Infinite Depth Architecture & Scaling

5.1 Infinite Vertical Depth Framework

5.1.1 L1-L200 Authored Progression

A. Authored Progression Range

• Primary Range: L1–L200.

• L1–L200 represents the complete authored mining progression range.

• Authored Progression: L1–L200 is an authored progression framework, not a collection of 200 handcrafted/designed maps.

• Depth progression defines increase of:

  • Environmental complexity

  • Resource availability

  • Node hardness

  • Resource quality and yield

• Standard floors remain procedurally generated; authored progression defines the rules, parameters, resource tables, and milestone layouts for those floors.

• The existing tool progression places Tier 5’s optimal resource range at L142–L200+ , providing the final authored endgame depth range.

B. Depth vs. Progression

• Floor depth does not directly determine player progression or equipped pickaxe tier.

• Pickaxe tiers are unlocked through required ores and blueprint discovery rather than automatically reaching a specific floor.

• Deeper floors remain accessible with lower-tier pickaxes.

• Lower-tier tools become highly inefficient against higher-hardness nodes through the Tier Differential and durability systems.

• Higher-tier tools remain effective on upper floors, allowing easy and efficient extraction.

C. Resource Relevance

• Depth does not permanently make resources from shallower floors irrelevant.

• Upper floor materials may remain required for:

  • Workshop crafting

  • Customer requirements

  • Shopkeeping orders

  • Other resource-specific economic demands

• Resource availability and resource relevance are treated as separate systems:

  • Depth: Determines where resources can be obtained .

  • Economy: Determines when those resources are valuable .

D. Procedural Generation

• Standard floors within L1–L200 are generated using the existing deterministic floorgeneration architecture.

• Levels must preserve deterministic reconstruction when revisited.

• Authored milestone floors may use fixed layouts/templates rather than fully procedural layouts.

5.1.2 L200+ Technical Continuation

A. Continuation Range

• Start: L201.

• Upper Limit: None.

• L200+ represents technical continuation beyond the authored progression range.

• No additional authored mining progression is required beyond L200.

B. Final Depth Profile

• L200+ continues using the final depth profile established for the final authored tier.

• No additional biome/depth tiers are required after L200.

• No additional pickaxe tiers are required after Tier 5.

• No Workshop, Shopkeeping, or customer progression is dependent on L200+.

C. Procedural Continuation

• Floors beyond L200 continue using the existing procedural generation architecture.

• Floor generation remains deterministic and reproducible.

• Existing generation rules continue to determine:

  • Cavern layout

  • Resource placement

  • Node properties

  • Environmental features

D. Gameplay Role

• L200+ is an optional continuation layer , not a mandatory progression layer.

• Players may continue descending beyond L200 for additional mining, exploration, resource collection, or personal goals.

• The game does not require descent to complete its intended progression.

• L200 is therefore the end of authored progression , while L200+ is the technical continuation of the mine system .

5.1.3 Floor Identities

Each mine floor is assigned a unique Floor Identity based on its absolute depth and the active depth profile.

A. Floor Identity

• Every floor is identified by its absolute depth level:

  • L1, L2, L3, …, L75, etc.

• Floor Identity is persistent and deterministic.

• The same floor number always resolves to the same underlying floor generation identity when revisited.

• Floor Identity determines which depth parameters are applied during generation.

• Standard floor layouts remain procedurally generated within those parameters.

• Milestone floors may use authored fixed layouts while retaining their corresponding floor identity.

B. Depth-Driven Identity Parameters

A Floor Identity may define or reference:

• Geological / environmental profile,

• Room and corridor generation parameters,

• Resource generation tables,

• Node hardness range,

• Structural wall properties,

• Environmental feature availability,

• Enviromental feature density.

• Lighting and atmospheric parameters.

C. Floor Identity vs. Floor State

• Floor Identity defines the original generated composition of the floor.

• Floor State records persistent changes made during gameplay .

• Floor State may include:

  • Destroyed nodes,

  • Destroyed wall sections,

  • Collected resources,

  • Dropped items,

  • Placed props.

  • Other persistent mutations defined by Section 6.

5.1.4 Depth Progression Philosophy

Depth progression is designed around increasing environmental complexity, extraction difficulty, and resource value opportunity. Rather than a simple linear increase in player power, it ensures the scale is complex and feel organic.

A. Progressive Depth

Deeper floors introduce:

• Greater structural resistance,

• Greater node hardness,

• Higher resource quality,

• Greater potential resource yield.

• Individual depth variables use independent scaling functions defined in Section 5.3 .

• No universal depth multiplier is applied across all gameplay values in order to prevent monotony and predictability.

• Scaling is intended to create increasing depth differentiation without making deeper floors simple numerical upgrades of shallower floors.

B. Non-Linear Progression

• Depth progression does not advance at a constant rate across all tiers.

• Later depth tiers occupy larger floor ranges as it progress.

• Optimal resource ranges and their mathematical allocation are defined in Sections 5.2 and 5.3 .

Note : These ranges represent optimal material mining zones , not mandatory player progression gates.

C. Resource Relevance

• Deeper progression does not permanently replace shallower resources.

• Earlier-depth resources may remain relevant through Workshop and Shopkeeping requirements.

D. Player Choice

• Players are encouraged to choose depth according to the current objective rather than always descending to the deepest available floor.

• The optimal floor for exploration is determined by the current goal and not the deepest floor.

5.1.5 Asymmetrical Progression (Depth ≠ Tool Progression)

Depth progression and tool progression are related but independent progression branches .

• Depth = Represents the mine’s environmental and resource progression.

• Tool Tier = Represents the player’s extraction capability.

• Neither system directly determines the other.

• Deeper floors may be accessed before obtaining the corresponding optimal pickaxe tier.

• Pickaxe progression is achieved by blueprint discovery, required materials, and Workshop crafting, all at the same time.

• Optimal tool/resource depth relationships define efficiency targets , not mandatory floor-access requirements.

• Under-geared and over-geared mining behavior is governed by the existing mining and durability systems defined in Section 8 .

5.2 Biome & Depth Tier Taxonomy

5.2.1 Shallow Shafts

Depth Range: L-1 to L-10

Primary Character: Familiar, safe, grounded mining environment

A. Overview

• Shallow Shafts is the uppermost part of the mining network. These floors provide the player’s foundational understanding of subterranean mining and establish the visual and mechanical baseline for deeper exploration.

• The environment feels familiar, intuitive and straightforward. Shallow floors are not intended to feel mysterious or alien. T

• The transition toward deeper environments begins gradually within the latter portion of the tier rather than occurring as a hard boundary.

B. Environmental Identity

Shallow Shafts are characterized by:

• Warm, earthy dirt and stone coloration,

• High density of visible mining infrastructure,

• Abandoned mine carts and related mining equipment,

• Wooden support structures and decorative beams,

• Clear evidence of previous excavation and mining activity,

• Early appearances of subterranean mushrooms.

C. Procedural Generation Profile

Shallow Shaft generation favors accessibility, readability, and efficient mining.

Compared to deeper tiers, the generator should preferentially produce:

• A greater number of rooms,

• More compact and easily navigable rooms,

• Higher accessibility between mining areas,

• More exposed resource nodes,

• Lower environmental complexity,

• Higher density of established mining infrastructure.

_D. Resource Profile*_**

Shallow Shafts introduce and offers the lowest tier resources.

The first 4 entries of the game’s resource progression are associated with this tier:

1. Stone

2. Iron

3. Bronze

4. Silver

E. Environmental Flora

• Subterranean mushrooms are introduced towards the end of the Shallow Shafts as natural environmental element.

• Their initial presence should be relatively sparse and visually restrained. As the player descends beyond the Shallow Shaft profile, mushroom density gradually increases.

F. Depth Transition

The Shallow Shaft profile gradually loses its strength toward L-10.

The transition does not create a visible or mechanical “biome border.” Instead, deeper characteristics progressively enter the generation profile:

• Natural geological formations become more prominent.

• Man-made structures become less dominant.

• Mushroom presence increases.

• Deep Cavern characteristics progressively replace the straightforward Shallow Shaft profile.

This creates a gradual progression form.

5.2.2 Deep Caverns

Depth Range: L-11 to L-30

Primary Character: Vast, natural, established subterranean caverns

A. Overview

• Deep Caverns represent the portion of the mining network where natural subterranean formations begin to balance the environment.

• These floors are still part of the network and continue to contain evidence of generations of mining activity. However, natural character of the caverns become increasingly prominent.

B. Environmental Identity

Deep Caverns are characterized by:

• Darker and more varied stone coloration.

• Larger natural cavern formations.

• More variation in chamber size and shape.

• Reduced visual dominance of wooden mining structures.

• Abandoned mining infrastructure remaining throughout the environment.

• Increasing density of mushrooms.

Man-made elements remain an important part of the environment. Old carts, wooden supports, abandoned camps, tracks, and other mining remnants continue appearing

However, these elements increasingly feel embedded within the natural environment rather than defining it .

C. Procedural Generation Profile

Deep Caverns shift the procedural generation toward larger and more varied natural spaces.

Compared to Shallow Shafts, the generator preferentially produce:

• Larger and more various rooms,

• More irregular cavern shapes,

• Longer connecting passages,

• More opportunities for isolated resource deposits,

• More exposed and wall-embedded resource nodes within larger cavern spaces.

Deep Caverns make exploration feel broader and less predictable .

_D. Resource Profile*_**

Deep Caverns introduce the next stage of the game’s resource progression.

The foundational materials introduced in the Shallow Shafts remain available.

However, the resource profile begins shifting toward the next group of materials in the ore progression:

TBD

E. Enviromental Flora

• Mushrooms become a more noticeable part of the Deep Caverns environment.

• Their distribution gradually increase throughout the tier, with later Deep Cavern floors beginning to show denser mushroom growth.

• This provides a natural visual bridge toward the increasingly distinct environments of the deeper tiers.

Man-Made Presence

The presence of infrastructure remains high enough that the player should never mistake these floors for unexplored territory.

However, its condition and relationship with the environment changes. In the Deep Caverns these infrastructure elements look older and aged.

F. Depth Transition

The Deep Cavern profile becomes strongest around the middle of the tier before gradually giving way to Subterranean River characteristics.

Toward approximately L-25 to L-30, the generation profile should begin introducing early signs of the next geological environment:

• Increasingly damp-looking environments,

• Occasional water features,

• More water-adjacent cavern formations,

• Greater presence of moisture-related environmental decoration,

• Gradual reduction of completely dry cavern dominance.

The transition should remain gradual rather than establishing a hard biome boundary.

Thus, a late Deep Cavern floor may contain a large dry chamber with a small pool or damp passage, while an early Subterranean River floor can still contain enormous, completely dry caverns.

5.2.3 Subterranean Rivers

Depth Range: L-31 to L-60

Primary Character: Water-carved caverns, underground waterways, damp geological environments

A. Overview

• Subterranean Rivers represent the portion of the mining network where underground water becomes a dominant geological force.

• These floors remain part of the established mining network, with abandoned infrastructure, carts, supports, camps, and other traces of previous mining activity continuing to appear throughout the environment. However, natural water formations increasingly shape the caverns around these remnants.

B. Enviromental Identity

Subterranean Rivers are characterized by:

• Damp, darker stone and earth coloration,

• Increasing presence of shallow water pools,

• Larger and more irregular water formations,

• Water-carved cavern edges and passages,

• Dense subterranean mushroom growth.

• Infrastructure partially integrated into water-worn environments.

Water should not completely dominate every floor. Dry chambers, mining corridors, and established infrastructure remain common enough to maintain variety.

C. Procedural Generation Profile

The procedural generator gradually shifts from the characteristics of the Deep Caverns toward more water-influenced layouts.

Subterranean River floors should produce:

• Larger cavern chambers,

• Irregular chamber boundaries,

• More water-containing rooms,

• More isolated pillars,

• Larger water formations within suitable rooms,

• Greater variation between wet and dry sections,

• More natural geological pockets,

• Greater environmental prop density.

The depth profile should therefore primarily modify how frequently and how prominently existing water features appear , rather than introducing a new system.

_D. Resource Profile*_**

Subterranean Rivers continue to contain resources from previous depth tiers, while shifting the optimal resource profile toward the next stage of the game’s material progression.

TBD

E. Enviromental Flora

Mushrooms become significantly more prevalent throughout the Subterranean Rivers. Early floors should contain scattered growth, while deeper floors can feature:

• larger mushroom groupings,

• more frequent wall mushrooms,

• denser floor growth,

• mushrooms concentrated around damp areas.

F. Depth Transition

The Subterranean River profile gradually becomes dominant after the Deep Cavern transition and reaches its strongest expression around the middle of the tier.

Toward L-50 to L-60, the environment should begin showing early characteristics of the next geological tier:

• increasingly unusual rock coloration,

• warmer environmental tones,

• less uniformly damp environments,

• occasional geological heat indicators,

• increasingly mineralized formations,

• early signs of thermal activity.

The transition should remain gradual.

A late Subterranean River floor should still be capable of containing a large water-dominated cavern, while an early Magma & Thermal Vent floor can still contain substantial water formations

5.2.4 Magma & Thermal Vents

Depth Range: L-61 to L-100

Primary Character: Extreme heat, thermal activity, mineral-rich volcanic geology

A. Overview

Magma & Thermal Vents mark the point where subterranean geology becomes increasingly affected by extreme heat and deep-earth thermal activity.

The environment shifts away from the wet, water-shaped caverns of the previous tier toward hot, dry, heavily mineralized formations . Magma itself remains an environmental presence rather than becoming a constant gameplay obstacle; the identity of the tier comes from heat, volcanic rock, vents, glowing formations.

B. Environmental Identity

The visual language is dominated by:

• Dark, heavily mineralized rock.

• Warm earth and stone coloration.

• Glowing cracks and mineral formations.

• Thermal vents and steam emissions.

• Volcanic rock formations.

• Increasingly dramatic environmental lighting.

Magma should be visible but comparatively uncommon . Large magma formations can serve as memorable environmental landmarks, while smaller thermal vents provide the more consistent identity of the tier.

Infrastructure continues to exist, but increasingly appears weathered, reinforced, or adapted to the hostile geological conditions.

C. Procedural Generation Profile

The generator shifts toward large, dramatic and thermally influenced cavern spaces .

Preferred characteristics include:

• Large chambers.

• Wider cavern openings.

• More exposed rock formations.

• Thermal-vent clusters.

• Occasional magma-adjacent chambers.

• Increased environmental landmark density.

_D. Resource Profile*_**

This tier represents the transition into the game’s more valuable and specialized mineral progression.

Its principal resource range is:

TBD

E. Environmental Flora

Mushroom presence is minimized as the environment becomes hotter and more mineralized. Rather than introducing a completely new biological environment, flora should gradually give way to non-biological environmental decoration :

• Glowing mineral formations.

• Heat-affected rock.

• Sparse surviving mushroom clusters in cooler areas.

F. Depth Transition

The transition from Subterranean Rivers should begin gradually around the upper portion of the previous tier.

Early Magma & Thermal Vent floors can still contain:

• Water pools,

• Damp chambers,

• River remnants,

• Cool natural caverns.

As depth increases, these progressively give way to:

• Dry environments,

• Warmer coloration,

• Thermal vents,

• Mineralized formations.

Approaching L-100, the first characteristics of The Nethermost begin entering the profile. The environment should start feeling increasingly unusual, establishing the visual bridge into the final depth tier.

5.2.5 The Nethermost

Depth Range: L-101 to L-200+

Primary Character: Ancient, strange, unnatural deep-earth environment

A. Overview

The Nethermost is the deepest environment of the mine and represents the point where conventional geological progression begins to give way to the unusual and unknown.

The environment should feel old, remote, and increasingly difficult to explain through ordinary mining geology . The mining network continues into these depths, but it’s extremely sparse. L-200 marks the end of authored depth progression. Beyond L-200, the same Nethermost depth profile continues indefinitely.

B. Environmental Identity

The Nethermost is defined by an increasingly unfamiliar subterranean visual language:

• Extremely dark and bone-toned rock formations.

• Unusual mineral formations and crystalline structures.

• Large, irregular cavern spaces.

• Ancient-looking geological formations.

• Sparse but striking environmental lighting.

• Rare formations that appear unlike those found in the upper mine.

• Increasing visual emphasis on the scale and age of the underground world.

The man-made presence remains part of the environment. Old shafts, infrastructure, abandoned equipment, and other evidence of generations of excavation can still appear, but these elements are increasingly feel small and insignificant compared with the spaces surrounding them .

C. Procedural Generation Profile

The Nethermost features large-scale and irregular cavern generation .

Preferred characteristics include:

• Large chambers with substantial spatial variation.

• Irregular cavern boundaries.

• Greater frequency of unusual geological formations.

• Larger isolated pockets and side chambers.

• Occasional extremely open cavern spaces contrasted with narrow passages.

• Continued use of interconnected ant-nest topology rather than linear dungeon layouts.

_D. Resource Profile*_**

The Nethermost contains the deepest and most unusual portion of the game’s resource progression.

The resource sequence includes:

TBD

E. Environmental Flora

Mushrooms become increasingly sparse as the environment moves beyond the conditions that supported the denser growth found in the upper tiers.

Environmental decoration increasingly shifts toward primal and ancient elements, allowing the Nethermost’s visual identity to come primarily from the cavern itself rather than biological growth.

F. Depth Transition

The transition from Magma & Thermal Vents begins before L-100, with Nethermost characteristics gradually entering the generation profile.

Early Nethermost floors may still contain:

• Thermal formations.

• Magma-adjacent areas.

• Warm mineralized rock.

• Occasional remnants of the previous environment.

5.2.6 Transition Band Zones

The transition between biomes does not act as hard boundaries but two biomes blends together where what’s called Transition Band Zones. The two adjacent biome characteristics overlap in these floors, creating gradient and natural passage to the deeper biomes.

For example:

• Shallow Shafts → Deep Caverns: around L-8 to L-14

• Deep Caverns → Subterranean Rivers: around L-27 to L-35

• Subterranean Rivers → Magma & Thermal Vents: around L-56 to L-65

• Magma & Thermal Vents → The Nethermost: around L-95 to L-105

Note: These ranges are design examples rather than fixed mathematical boundaries . The actual floor-by-floor values are authored through the depth profiles.

A. Gradual Interpolation

Within a transition band, the active characteristics of the preceding tier gradually decrease while the following tier’s characteristics increase. So a floor near the beginning of a transition retains a strong identity from the previous environment, while a floor near the end increasingly resembles the next environment.

B. Independent Characteristic Transitions

Not every characteristic needs to transition at the same rate.

Environmental features, resource distributions, room structures, flora and geological characteristics may each have their own depth curves.

C. Resource Transition

Resource distributions also use the transition system, this is independent from the transition bands.

A resource does not become instanly unavailable because the player descents into lower depths. Earlier resources can continue appearing at reduced distribution strength while new resources gradually become more prominent.

D. Procedural Generation Effect

Transition bands influence procedural generation parameters such as:

• Room size and shape,

• Corridor characteristics,

• Environmental feature frequency,

• Water or thermal feature presence,

• Flora density,

• Man-made prop density,

• Lighting and atmospheric characteristics,

• Resource distribution.

5.2.7 Depth Profiling

Depth Profile is the collection of parameters used to determine the environmental and procedural identity of each mine floor.

Each floor is evaluated using its absolute depth and the active depth profile. The profile determines what types of spaces, resources, environmental features, and atmospheric characteristics are will be used for that floor.

A. Floor Profile

Each floor from L-1 through L-200 has a depth profile containing weighted characteristics appropriate to its position.

A profile may reference:

• Geological characteristics,

• Room and corridor generation parameters,

• Resource distribution tables,

• Node hardness ranges,

• Structural wall properties,

• Environmental feature availability,

• Environmental feature density.

B. Profile Values

Depth-dependent characteristics are represented as independent values or curves rather than being driven by one universal depth multiplier.

For example, a floor can simultaneously have:

Water Characteristics: 75

Mushroom Density: 80

Large Cavern Probability: 65

Thermal Activity: 10

Man-made Trace Density: 30

These values describe different aspects of the floor and do not need to rise or fall together.

C. Weighted Distribution

Resource and other content profiles use weighted distribution strengths rather than direct spawn percentages.

For resources, the authored distribution matrix uses values from 0–100 :

• 0: Doesn’t included.

• Low values: Uncommon presence.

• Medium values: Established presence.

• High values: Strong or optimal presence.

The current resource-balancing system is designed around editable 0–100 weighted values for every resource across L-1 through L-200.

Note: These values represent relative distribution strength , not guaranteed quantities or direct spawn probabilities.

D. Authored vs. Procedural Values

The L-1 through L-200 progression is treated as an authored depth profile , even though individual floors remain procedurally generated.

Desired characteristics of each depth is established through profile values and distribution curves.

The procedural generator then uses those values to construct the actual floor layout.

5.3 Mathematical Depth Scaling

Depth scaling defines how mining changes across the mine without making deeper floors simple numerical upgrades of shallower floors. Depth and tool tier remain independent in order to create complex and immersive space for players; the scaling system establishes efficiency targets rather than mandatory progression gates.

5.3.1 Time-to-Mine Scaling

Time-to-Mine (TTM) is the approximate time required to fully destroy a resource node when using the intended pickaxe tier for its depth range.

The target TTM remains approximately consistent (with slight variations) across depth for matched-tier mining. Deeper nodes therefore receive increased HP, while the corresponding pickaxe tier provides slightly greater effective damage.

Node HP

NodeHP = BaseHPResource × DepthHPModifier

BaseHP is defined individually for each resource. The depth modifier increases node HP progressively across the mine.

TTM

TTM ≈ NodeHP/EffectiveDamage

The matched pickaxe tier should maintain the intended TTM target regardless of depth.

Under-tier and over-tier efficiency is handled separately by the Tool-tier Relationship defined in Section 5.3.3.

5.3.2 Hardness Scaling

Hardness is independent from Node HP and therefore does not directly determine TTM.

Time-to-Get-Impaired (TTGI) represents the approximate amount of mining a pickaxe can perform before reaching the impaired durability state .

• Matched-tier mining experiences a slight reduction in TTGI as depth increases.

• Under-tier mining experiences a significantly greater reduction due to the increased hardness of deeper resources.

• Over-tier mining improves TTGI, but the benefit is limited to prevent high-tier tools from trivializing early resources.

5.3.3 Tool-tier Efficiency Relationship

Tool tier and depth are independent progression systems. A player may mine beyond the optimal depth range of their current pickaxe, but extraction efficiency changes according to the difference between tool tier and intended resource tier.

Matched-tier mining represents the intended efficiency target for each depth range.

Over-tier tools may improve mining efficiency but should not reduce TTM to trivial or instantaneous values. This preserves the usefulness of lower-depth resources throughout later progression.

5.3.4 Yield Scaling

Resource Abundance is the total material contained within a node. Yield scaling remains intentionally small so that resource quantity does not become an inciting reason to abandon shallower floors.

For a matched-tier tool, the same resource provides approximately the same base yield regardless of depth.

Tool-tier relationship may apply modest yield modifiers:

• Under-tier: Reduced yield

• Matched-tier: Base yield

• Over-tier: Increased yield

The exact modifiers are balancing parameters.

Resource yield remains independent from Node HP so that high-HP nodes does not automatically produce significantly greater material.

5.3.5 Resource Distribution

Resource distribution determines where the resources occur across the mine. Each resource uses an independent depth profile rather than following a universal distribution curve.

Each resource has an independent depth distribution profile across L1–L200. Each floor is assigned a weight from 0–100, which determines the resource’s likelihood of appearing at that depth.

Resource profiles may define an introduction range, optimal range, peak occurrence, decline range, and final depth. Profiles are independently editable and may use different curve shapes depending on the resource.

Resource distribution is handled through weighted probability rather than fixed spawn counts. The distribution editor is used as the primary balancing tool for these profiles.

5.4 Depth Milestone Shafts

5.4.1 10-Floor Milestone Floors

Every 10th floor is a milestone floor. These floors serve as progression points within the mine and provide access to milestone-specific infrastructure.

Milestone floors occur at every 10th floor:

L10, L20, L30 … L200+

They do not represent hard progression gates. Players may continue past them normally.

5.4.2 Manually-designed Milestone Layouts

Milestone floors use manually authored layouts rather than the standard procedural floorgeneration rules.

Layouts may contain:

• Elevator hub (mandatory)

• Workshop/utility infrastructure where applicable

• Repair facilities

• Permanent shortcuts

• Environmental landmarks

• Connections to surrounding procedural floors

The layout should remain compatible with the mine’s standard traversal and visual language.

5.4.3 Elevator Hubs

Every 10th floor contains an Elevator Hub replacing the standard Exit Zone.

Initial State:

The elevator is inactive until its repair requirements are fulfilled through the shaft interface. Repair requirements may include Raw Ore, Processed Materials, and Special Components.

Repair:

Once repaired, the elevator becomes an active milestone checkpoint and is permanently registered as an available fast-travel destination.

Fast Travel:

From the Mine Layout UI at Base, the player may select any previously repaired Elevator Hub as their mine entry point. L1 remains the default entry point. All of the fast-travel work both ways.

In-Mine Interaction:

The active Elevator Hub serves as the player’s return point for that milestone and can be used to ascend through the established elevator network.

Persistence:

Repaired Elevator Hubs remain registered independently of the rolling floor-memory system and are restored when the corresponding floor is regenerated.

5.4.4 Repair Mechanics

Milestone floors provide access to repair functionality for mining equipment.

Repair restores impaired or damaged tools according to the repair rules defined elsewhere in the document.

Repair stations are intended to provide reliable recovery points during extended mining runs.

Further specifications and work pipeline explained in Section 8.2.3

5.4.5 True Persistence

Milestone floors and their layout and infrastructure persist permanently once unlocked.

The following remain persistent:

• Reached milestone floors

• Elevator access

• Repaired infrastructure

• Other authored milestone-state changes

Returning to a milestone floor restores its previous state rather than generating a new version.

6. Session Memory & Floor Persistence

6.1 Rolling Floor Memory Buffer

Purpose of this buffer is to define which temporary floors exist in RAM during an active session.

• Total of 5-size ring buffer.

• Stores the current floor and the 4 most recent visited floors.

• Floors enter the buffer as the player visits them.

• When capacity is exceeded, the oldest non-protected floor is purged using FIFO.

• Purged floors lose their runtime state and reconstructed from their deterministic Floor Identity if visited again.

• Persistent milestone floors are excluded from normal FIFO purging.

6.2 Delta Mask Tracking

Purpose: Define how modifications to persistent floors are recorded so they survive RAM flushes and are reapplied when the floor is reconstructed

The system records only changes made to the Persistent Floor Identity.

Tracked mutations:

• Mined Nodes — depleted/removed resource nodes.

• Cracked/Destroyed Walls — altered wall tiles and passages.

• Dropped Items — item instances currently present on a persistent floor.

• Placed Props — player-created or player-placed objects that must remain.

The delta is applied to the deterministic floor when a persistent floor is reconstructed.

This fits the existing distinction between Floor Identity and Floor State .

6.3 Persistent Floor Regeneration

This exlpains what happens when a persistent milestone floor is reconstructed after leaving memory.

This is where the special treatment of elevator/milestone floors belongs.

Process:

1. Reconstruct the original floor from its deterministic Floor Identity.

2. Apply its stored Delta Mask.

3. Restore persistent infrastructure and player-created changes.

4. Replenish eligible resource content according to the milestone-floor regeneration rules.

The important concept is:

Persistent floors are regenerated, not reset.

The original generation remains the foundation; regeneration only restores eligible content without removing permanent player changes.

6.4 Session Cleanup & Memory Flush

When the player returns to Base and the session cleanup executes:

• Temporary floor states are removed from RAM.

• Non-persistent floor modifications are discarded.

• Persistent floor state remains registered.

• Player inventory remains intact.

• Dropped items on temporary floors are destroyed.

• Dropped items on persistent floors remain stored through that floor’s Delta Mask.

• Inventory overflow left on a floor is therefore lost when that floor’s temporary state is flushed.

7. Depth Gating & Mercenary Clearance System

7.1 Subterranean Hazard Gates

After L30, floors may become inaccessible due to a Subterranean Hazard. A hazardous floor must be cleared by hiring the appropriate mercenary group before mining access is restored.

Initial Hazardous Floor: Upon first reaching L31, the floor is guaranteed to contain a hazard. This serves as the introduction to the Hazard Gate system and requires the player to hire the appropriate mercenary group before proceeding.

Hazard probability is evaluated when the player first reaches a previously unresolved floor. Future hazard floors are not predetermined

The system maintains a persistent Floors Since Last Hazard counter. The counter tracks forward depth progression rather than session duration or physical floor movement.

• Reaching a new floor advances the counter.

• Returning to previously resolved floors does not advance or reset the counter.

• Ascending to shallower floors does not affect the counter.

• Ending a session does not affect the counter.

• Entering the mine through an Elevator Hub does not reset the counter.

• The cycle resets after each hazard encounter.

The exact values are subject to change after playtests*

Hazard Types

Three hazard types may occur:

1. Toxic Gas Pockets: Requires Alchemist mercenaries and specified clearance materials.

2. Flooded Floors: Requires Aarinaq-related mercenaries and specified clearance materials.

3. Dermin-Invaded Floors: Requires Adventurer mercenaries and specified weapons, trinkets, armor, and coin.

Hazard type selection is influenced by depth and biome.

From the mining system’s perspective, all three hazards function identically: the floor is inaccessible until the required clearance is completed. Mercenary hiring and clearance systems exist outside this document.

7.1.1 Visual Cues & Descend Shaft Blocking

The visual manifestation of the hazard below level is present around the descend shaft with sutble clues depending on the hazard type

Toxic Gas Pocket: Green gauseous winds waft through the shaft and sits on around it like a fog.

Flooded Floor: The soil/ground around the shaft looks wet cracked and small puddles form around it. Differnt from regular water tiles.

Dermin-Invaded Floor: Purple-ish light radiates from the shaft.

On all three, the next tile of the shaft features a warning note on a pole and when interacter there’s a notice from the adventurer’s guild (name will change) and the actual shaft is blocked with a wooden guard.

7.2 Mercenary Contract System

7.2.1 Hiring Mercenaries

Mercenary hiring is performed through the Guild in the surface world.

Each hazard type has a dedicated NPC who acts as an intermediary between the player and available mercenary parties. The NPC provides a catalogue of available parties and determines the requirements for each contract.

Mercenary contracts cannot be initiated during an active mining session.

The general hiring pipeline and mercenary management systems are defined outside the mining document

7.2.2 Clearance Payment Structures

Clearing a Hazard Gate requires a mercenary contract with a fixed payment structure.

Each contract requires:

• Coin Fee — determined by the depth-based contract cost curve.

• Hazard-Specific Materials — determined by the hazard type and depth.

The required materials may include ores, processed materials, weapons, armor, trinkets, or other specified resources.

The player must satisfy all requirements before the Hazard Gate can be cleared.

7.3 Economic Soft Cap Architecture

Mercenary contract costs increase with depth to create a soft cap on extreme-depth progression.

In the intended primary mine range, costs increase progressively with depth. Beyond L200, the growth rate increases substantially, making further progression technically possible but increasingly inefficient.

The system is intended to discourage infinite depth pushing without making it mechanically impossible.

7.3.1 Exponential Cost Scaling Formulas for Contract Fees

Contract coin fees use an exponential depth curve.

The curve is tuned around milestone depths and increases its growth rate beyond L200.

The general form is:

Cost(D) = BaseCost x DepthMultiplier(D)

The exact curve parameters are balancing values and may be adjusted through playtesting.

7.3.2 Requirement Progression Table Across Depth Tiers

In addition to the coin fee, Hazard Gate contracts require hazard-specific materials. Material requirements increase in quality and quantity as depth increases, while remaining appropriate to the resources and progression available within the corresponding depth tier.

Requirements are defined by depth tier rather than through a universal mathematical scaling formula.

7.4 Global Profile Clearance Flags

Global clearance flags record persistent progression states that determine whether sections of the mine network are accessible.

These flags exist independently from individual floor memory and are not removed during session cleanup.

7.4.1 Sequence-Break Protection & Persistent Floor Unlocks

Hazard Clearance

A Hazard Gate represents a hard progression barrier in the mine network.

When a Hazard Gate is active on floor Lx:

• Lx cannot be entered until the hazard is cleared.

• Normal descent cannot continue beyond Lx.

• Previously discovered floors below Lx remain inaccessible.

• Repaired elevators below Lx cannot be used to bypass the Hazard Gate.

Once the Hazard Gate is cleared, the clearance is permanently recorded and normal descent may continue beyond the affected floor.

Elevator Access

Elevator discovery and elevator activation are separate states.

• Reaching a milestone floor does not activate its elevator.

• An unrepaired elevator cannot be used for fast travel.

• Once repaired, the elevator becomes a permanent fast-travel destination.

• Fast travel is available only between repaired Elevator Hubs.

• Elevator activation persists across sessions.

Elevator access does not override an active Hazard Gate blocking deeper progression.

Sequence-Break Protection

The access system must always evaluate the player’s current global clearance state before allowing deeper descent or milestone travel. This prevents discovered floors or repaired elevators from creating alternate routes around an uncleared Hazard Gate.

8. Mining Mechanics, Tools & Gathering

8.1 Pickaxe Mechanics & Node Hardness

The pickaxe serves as the primary permanent gathering tool within the subterranean exploration loop. Player action is triggered using either [LMB] or [Space].

Swingint the pickaxe initiates a locked directional hitting animation; during this animation, player movement is completely frozen. Swings do not require collision validation to execute (swings in empty air cycle through the animation without triggering impact logic or durability costs).

Resource nodes are defined by three foundational attributes:

• Health Points (HP): Structural integrity of the node.

• Hardness Rating: Durability tax exacted against the pickaxe upon impact.

• Abundance (Total Yield Pool): The total quantity of materials/ores contained inside the node.

Yielding Ores

Resources drop in 4 stages with equal thresholds. Note material yield is tied to these structural destruction thresholds (75%, 50%, 25% and 0 HP) Visual Mesh Degradation & Milestone Yield Matrix

Threshold Calculation

To handle non-divisible Abundance values (e.g., 3 Diamonds or 7 Copper Ores), Stages 1–3 calculate drops using integer flooring. Stage 4 automatically absorbs all remaining un-dropped items from the initial Total Abundance pool to guarantee zero material loss.

Stage 1 Drop = (Abundance x 0.15)

Stage 2 Drop = (Abundance x 0.15)

Stage 3 Drop = (Abundance x 0.20)

Stage 4 Drop = Total Abundance – (Stage 1 Drop + Stage 2 Dropğ + Stage 3 Drop)

Example (7 Ores Total):

• Stage 1 (75% HP): 7 x 0.15 = 1 Ore

• Stage 2 (50% HP): 7 x 0.15 = 1 Ore

• Stage 3 (25% HP): 7 x 0.20 = 1 Ore

• Stage 4 (0% HP): 7 - (1-1-1) = 4 Ores

8.1.1 Tool Tier vs Node Hardness Check

To ensure players have satisfactory play times with each tier and upgrades feel earned, the progression model allocates toor tier thresholds exponentially. These thresholds are aligned with certain floor levels however, reaching a specific floor level does not automatically trigger the progression. To forge a higher-tier pickaxe, players must explore the subterranean cavern floors to harvest specific raw ores and discover lost Tool Blueprints .

The floor depth ranges defined below represent Optimal Material Mining Zones . These are the depth bands where the specific raw ores and blueprint secrets needed to craft the next pickaxe tier naturally spawn.

[Mine Floors] [Workshop] Mine Raw Ores ---------------------------------------------------------------- Craft Pickaxe Discover Blueprint ------------------------------------------------------------- Unlock Recipe

Non-Linear Stages: Lower depth tiers cover wider floor ranges due to the exponential progression logic.

Endgame: Tier 5 crafting materials/blueprints are discovered around floor 142, granting players over 60+ engame floors.

A. Mathematical Multiplier Curve & Depth Allocation

The target floor span for each tier’s optimal material zone is calculated using a base floor span (S1 = 15 floors) multiplied by an exponential depth modifier (Mt):

Floor Span(t) = Round (S1 x Mt)

B. Blueprint Discovery Mechanics (Mining Loop Integration)

• Acquisition: Blueprints do not clutter standard resource drops. They are discovered through environmental search in the mine:

  • Hidden Wall Pockets: 35% spawn chance inside destructible cavern rock walls (Section 8.3).

  • Utility Props: Searchable Mine Carts and Relic Chests (Section 10.2).***

  • Water Tiles: Searching inside the water tiles can lead to dicovery.

• First-Time Discovery: Once a Tool Blueprint is collected, it instantly registers in the player’s profile data.

• Repeated Discovery: If a player finds an already-unlocked blueprint in subsequent mining runs, it’s stored in the inventory and can be sold on shop.

• Crafting/Workshop Relation: Collecting a blueprint does not grant the pickaxe immediately. The player must safely extract from the mine session and visit the Town Workshop to forge the upgraded pickaxe using gathered ores.

C. Efficiency vs. Depth Hardness

Because pickaxes do not hard-gate player movement through floors, a player can venture into deeper floors (e.g., Floor 50) using a Tier 1 Pickaxe. However, environmental soft caps regulate efficiency:

Mining Under-Geared (Low Tier vs. High Hardness Node): Striking high-hardness nodes (e.g., Hardness 14.0 Diamond) with a low-tier pickaxe inflicts massive Durability Taxes per hit, rapidly pushing the pickaxe into Critical or Impaired durability states.

Mining Over-Geared (High Tier vs. Low Hardness Node): Returning to upper floors with a Tier 4 or Tier 5 Pickaxe allows breaking early-game stone and copper nodes in 1 swing with negligible durability wear.

8.1.2 Damage Calculation Formula

A. Mathematical Damage Equation

Every valid pickaxe swing that impacts a resource node or destructible object calculates final structural damage using the following equation:

Finale Damage Per Hit = Base Damage x MdurabilityState x MTierDifferential

Where:

• Base Damage: Derived from the Pickaxe’s active Tool Tier plus any Workshop Upgrades (e.g., Tier 1 Base = 10 Damage; Tier 3 Base = 35 Damage).

• MDurabilityState (Tool Performance Modifier):

  • Primary State (Durability >0): 1.0 x (Full efficiency)

  • Critical State (Primary Pool Depleted): 0.5 x (50% damage output)

  • Impaired State (Both Pools Depleted): 0.25 x (25% damage output)

• MTierDifferential(Tool vs. Node Armor Check):

  • Matched / Over-Geared (Pickaxe Tier ≥ Node Tier Requirement): 1.0 x

  • Under-Geared Penalty (Pickaxe Tier < Node Tier Requirement): 0.5 x

B. Hit Speed & Swing Cadence Mechanics

Because mining uses single swings with movement locking , “Hit Speed” determines the duration of the animation and the minimum delay between every swing:

Swing Duration (seconds) = max ( Tmin ceiling , Base Swing Time/Hit Speed Stat)

Base Swing Time: Default 0.8 per swing.

Hit Speed Hard Cap (Tmin ceiling): Animation cannot drop below 0.25s (4 swing per second) under any circumstances.

Air Swing: Swings in empty air execute the animation but do not trigger durability taxes or impact audio/particles.

C. Damage Application

When “Final Damage Per Hit” is applied to a node:

1. HP Reduction: Node Current HP = max(0, Node Current HP - Final Damage).

2. Threshold Check: The system checks if Node Current HP drops across 75%, 50%, 25%, or 0% thresholds.

3. Loot Burst: If a threshold is crossed, the corresponding Stage yield drops and updates the visual mesh degradation state.

D. Calculation Examples

8.2 Pickaxe Durability

The Pickaxe Durability regulates operational tool life during mining sessions and acts as a soft cap element. Due to the cozy nature of the game the pickaxe never shatters upon complete depletion but incrementally degrades creating non-efficient gameplay and nudges players to keep the core loop moving.

8.2.1 Durability Deduction Rules

A. Valid Hit

Durability subtraction is evaluated on every swing contact, based on the entity struck:

Current Durability = max (0, Current Durability – Target Hardness Score)

Flat Hardness Deduction: Every hit taxes tool durability directly based on the structural hardness score of the object struck (e.g., striking a node with a Hardness Rating of 2.5 deducts exactly 2.5 points from the active durability pool).

B. Empty Air Swing (Missed Swing)

• Durability Cost: 0.0 points.

• Logic: Swings into open air or non-collidable space triggers the swing animation without triggering contact algorithms or deducting durability.

C. Hitting Bedrock

• Bedrock: Bedrock is the impenetrable outer structural boundary of each cavern floor (map boundary walls). Bedrock possesses no Health Points (HP), cannot be damaged, and cannot be destroyed under any circumstances.

• Durability Cost: Fixed flat tax (Cost = 0.5 durability points per hit).

• Design Purpose & Feedback: The flat 0.5 penalty prevents mindless boundaryspamming or automated macro-mining along outer walls. Striking Bedrock immediately triggers a deflection contact response:

  • Audio: High-pitched metallic deflection “chink”.

  • Visual: Bright yellow impact spark particle burst along the collision plane with camera micro-shake.

8.2.2 Intact, Critical, and Impaired Performance States

The pickaxe durability operates on two sequential durability pools (Primary Pool and Critical Pool) before shifting to an infinite Impaired fallback state.

A. Intact State (Primary Durability Pool)

• Capacity: Dmax

• Operational Rules: While Primary Durability is greater than zero, effective hit damage is 100% of base tool damage 1.0x. Target Hardness is flatly deducted from this primary pool on each valid impact.

• HUD Indicator: Solid blue/green durability bar displayed on the active tool widget.

B. Critical Durability State (Secondary Durability Pool)

• Trigger: Initiated automatically when Primary Durability reaches 0.

• Capacity: Secondary pool with capacity equal to 100% of Primary Dmax (e.g., a pickaxe with 600 Max Durability gains a 600-point Critical pool).

• Operational Rules: Striking targets while in this state deducts Target Hardness flatly from the Critical pool and applies a 0.5x Hit Damage Penalty.

• HUD Indicator: The durability bar turns warning amber/orange with a pulsing crack overlay icon.

C. Impaired Performance State

• Trigger: Initiated when the Critical Durability pool reaches 0.

• Capacity: Infinite (Tool never breaks, shatters, or leaves inventory).

• Operational Rules: Effective damage output drops to a 0.25x Hit Damage Multiplier. No further durability can be lost.

• HUD Indicator: Flashing red “IMPAIRED” status tag on tool HUD slot.

• Design Purpose: Ensures players can always dig through soft walls or clear escape routes to return to base regardless of session length, reinforcing the cozy, non-punitive design pillar.

8.2.3 Workshop vs. In-Mine Camp Repairs

A. Overview

Tool durability maintenance can be done in two different locations: the Shop Workbench and Abandoned Mine Camp Workbenches. This structure gives players freedom of maintaining their tools and extend their mining sessions.

1. Workshop Workbench: Offers more economical, low-cost repairs with instant execution

2. Camp Workbench : Provides emergency, high-cost repairs mid-session to extend exploration without having to return to base. It has a short duration.

Both workbenches restore the pickaxe’s integrity back to 100% maximum capacity across all durability pools (Primary and Critical)

B. Material-Based Repair

1. Material Matching Condition: Repair costs are determined by the material of the currently equipped pickaxe. Requirement is in materials raw ore form.

Tier 1 [A Pickaxe] = Requires A ore Tier 2 [B Pickaxe] = Requires B ore Tier 3 [C Pickaxe] = Requires C ore Tier 4 [D Pickaxe] = Requires D ore Tier 5 [E Pickaxe] = Requires E ore

2. Cost Multiplier & Differential Formula

To penalize reckless field maintenance and prevent possible abuse, repair cost formula applies a Location Markup Multiplies (Mlocation)

Repair Cost (Ore Count) = Round (Base Material Multiplier x (1.0 – Current Durability/Maximum Durability) x Mlocation)

C. Camp Work Interaction Pipeline

1. UI-Less Direct Interaction

Unlike the Workshop Workbench (which opens a full GUI menu), the Camp Workbench features no UI to maintain immersion and prevent screen clutter.

2. World-Space Dynamic Interaction Prompt

When the player enters the interaction range (2.0m radius) of an In-Mine Camp Workbench:

• Trigger Condition: Evaluated continuously while inside the interaction boundary.

• Durability Evaluation:

• If Durability < 100%: Displays floating world-space text directly over the workbench:

“Repair [Key]. (Cost : [amount] [ore type])”

(Example: “Repair [E]. (Cost : 6 Iron Ore)”)

• If Durability = 100%: Prompt dynamically hides or displays “Pickaxe at Full Integrity”.

3. Execution, Progress Bar & Channeling Logic

When the player presses the designated interaction key ([Key]):

1. Material Deduction: The system verifies raw ore counts in inventory. If valid, the required materials are automatically deducted immediately.

2. Channel Progress Bar : A 4.0-second timed repair bar appears above the workbench.

3. Cancellation Rule: Animation locks player movement and it’s not cancelable in any way.

4. Completion: Upon successful completion of the 4.0s channel, all durability pools (Primary, Critical) 100% capacity.

4. Unlimited Reusability

Abandoned Mine Camp Workbenches are permanent, non-depleting props for the duration of that floor session. Players can return to and use the same camp workbench infinitely without destroying or deactivating the fixture.

D. Comparison Summary Matrix

8.3 Destructible Cavern Walls & Hidden Ores

8.3.1 Crackable Rock Tile Destruction

A. Overview

The entirety of the cavern’s perimeter and internal rock structures are constructed from a single, unified destructible wall tile type. This gives players complete freedom to modify the cavern topology, they can choose to trade pickaxe durability and time for navigational efficiency.

B. Depth-Based HP & Hardness Scaling

To maintain progression tension as players craft higher-tier pickaxes, the structural resistance of cavern walls scales dynamically with subterranean depth ( D , where Floor 1 → D = 1):

1. Wall Health Point Formula

Wall HP ( D ) = Round (Base Wall HP x (1.0 + α x ( D -1)))

• Base Wall HP = 30 HP (Floor 1 baseline)

• α = 0.08 (8% HP increase per descending floor)

2. Wall Hardness Formula

Wall Hardness ( D ) = Base Hardness + (( D -1)/15 x 0.5)

• Hardness scales in tandem with regional Depth Tiers, subjecting under-geared tools to standard durability penalties if digging through deep-cavern walls.

C. Embedded Resources

• Resource Yields : A subset of standard destructible wall tiles contain embedded resources.

• Collection Logic: When the wall tile’s HP reaches 0, embedded resources are automatically gathered directly into player inventory (or dropped as spatial loot entities if inventory capacity is exceeded).

D. Tilemap Mutation

1. Grid Mutation:

Upon destruction, the tile instantly updates:

TileType.DestructibleWall → TileType.WalkableFloor

• The tile’s static physics collider is removed.

• The spatial pathfinding grid node (GridGraph.SetWalkable(x, y, true)) updates immediately to incorporate the new opening into AI/navigation calculations.

2. Floor State & Seed Serialization:

• Destruction mutations are permanently saved within the active session floor state.
• Returning to a previously visited floor within the session or rolling memory buffer preserves all player-dug tunnels and modified cavern shapes.

E. Pickaxe Interaction

Excavation uses the exact same pickaxe mechanics as resource nodes ([LMB] / [Space], directional locked animation, damage evaluation, and durability deductions based on Intact, Critical, or Impaired tool states).

Note: If the wall is mounted with a prop or torch destroying the wall triggers the destruction of the attached entitiy with all its properties (illumination).

8.3.2 Hidden Wall Pockets

A. Overview

Hidden Wall Pockets are procedural secret tiles embedded along cavern boundaries. They reward curious players who inspect wall contours for visual cues, yielding rare materials, highgrade ores, and valuable items when broken open.

B. Visual

Rendered using a distinct cracked mesh overlay variant, displaying visible fissures and faint structural stress lines to signal its presence.

C. Procedural Placement

1. Outward-Facing Boundary Rule:

• A wall tile is ONLY eligible to roll as a Hidden Wall Pocket if at least one of its 4 cardinal orthogonal neighbors (N, S, E, W) is a “walkable floor”

• Deep inner-mass wall tiles (encased by other walls on all 4 sides) are strictly disqualified to prevent unreachable secret spawns.

2. Spawn Probability Rate:

• During floor object generation, every eligible outward-facing wall tile undergoes a 5% random roll (p = 0.05) to become a Hidden Wall Pocket.

3. Hard Floor Cap:

• Maximum amount of Hidden Wall Pockets cannot exceed 5 per floor.

8.4 Ore Detection System (Resonance Crystal)

A. Overview

The Resonance Crsytal in a non-consumable, permanent exploration tool that allow players to detect valuables and resources inside the cavern walls. Preventing them guessing and mindlessly digging walls and promotes intentional discovery.

Placing the crystal starts a scan process that at the end of it, embedded ores and valuables are revealed and recorded in the map.

B. Mechanics

1. Dedicated Slot

The Resonance Crystal doesn’t occupy a regular inventory space and burden the maximum carrying capacity. Instead it has its own keybind and slot.

• It’s permanently avaliable to the players outside its cooldown and cannot be unequipped, dropped or destroyed.

2. Placement & Interaction

• Pressing the dedicated key, initiates the placement.

• It’s placed on the single closes walkable floor directly in front of the player’s facing direction.

• It triggers a brief, non-interruptible placament animation (0.5s) where the player character places the crsytal on the cavern floor. Movement is locked during this animation.

3. Scanning State

• Once it’s placed, the player movement is unrestricted again. Player can walk, mine, and interact any other way regularly.

• After 0.5s of placement the crystal starts the 5.0s scan protocol.

• Pressing the placement key again, inside the interaction range allows player to retrieve the crystal.

• In case of retrieving mid-scan, cancels the scan without triggering full cooldown (60.0s)

C. Active Scanning Phase

During the active scanning phase, the crystal executes a stationary channel on the grid.

• A world-space 5.0s UI progress bar floats directly below the deployed crystal entity, visible from anywhere within the current screen view.

• Waves of resonance expands from the crystal in a radial way every 1.0s, creating an immersive visual. Also resonating VFX and SFX complements the presentation.

D. Technical vs. Visual Range

While the waves are purely cosmetic, the actual effective range of the crsytal is 8-tile radius.

E. Map Marking & Detection Target

Upon reaching 100% completion:

1. Target Identification

Crystal scans all tiles within range for:

• Hidden Wall Pockets embedded inside boundary rock.

• Unopened Ore Veins / Embedded Resources withing destructable walls.

2. Persistant Map Marking:

• Identified target tiles are automaticall and permanently registeren on the map

• Visual map markers displayed at their location with specialized icons.

• Markers persist on the map until the node/wall tile is destroyed or depleted.

• Markers do not specify the exact type of resource but only tags them as “Unknown Resource”

Note: There’s only 1 resonance crystal and players cannot equip/find or use a second one.

9. Environmental Features & Interactive Props

9.1 Water Pool Mechanics

Water Pools are static environmental features used to add visual and spatial variety to cavern floors. At launch, water is purely cosmetic and does not introduce a separate gameplay system.

9.1.1 Static Water Tile Behavior (Non-Flowing)

TileType.WaterPool represents shallow, static water.

• Water tiles are fully walkable.

• Water does not flow, spread, drain, or alter surrounding tiles.

• Does not damage, slow, push, or otherwise affect the player.

• Cannot be mined, destroyed, or otherwise modified.

9.1.2 Procedural Placement & Visual Behavior

• Water Pools may spawn within cavern rooms during procedural generation.

• A Water Pool can occupy a single tile, but will most commonly appear as a small puddle consisting of a group of adjacent TileType.WaterPool tiles.

• Pool shapes are irregular and organic rather than rigid geometric shapes.

• Water has subtle surface animation/reflection to distinguish it from standard cavern floor.

9.1.3 Launch Scope

Water Pools are intentionally limited to cosmetic/environmental functionality for the initial release.

Not Included at Launch:

• Submerged item discovery.

• Resource or treasure spawning inside water.

• Blueprint discovery inside water.

• Any inventory/item interaction with water.

9.2 Utility Props

Utility Props are environmental objects placed throughout mine floors that provide small exploration, resource, or utility interactions. They are not the core focus and remains lightweight within the mining loop.

9.2.1 Searchable Old Mine Carts

Old Mine Carts are abandoned mining equipment found throughout cavern floors.

1. Placement:

• Spawn as environmental props within suitable cavern rooms and corridors.

• May appear as individual carts or as part of small abandoned mining scenes.

• Placement does not obstruct required traversal routes.

2. Interaction:

• Players can interact with an Old Mine Cart to search it.

• Searching may provide a small selection of mining-related rewards.

• The interaction is a short environmental discovery moment rather than a major source of resources.

3. State:

• Once searched, the cart becomes depleted for the remainder of the active floor/session state.

• Searched carts remain visually distinguishable from unopened carts.

Reward table: TBD.

9.2.2 Abandoned Mine Camps

Abandoned Mine Camps are small environmental landmarks left behind by previous mining expeditions. They provide a temporary point of safety and utility during exploration.

Placement:

• Camps spawn within dedicated Abandoned Camp room templates or suitable procedural cavern areas.

• Camps contain an In-Mine Camp Workbench and may contain additional environmental props such as lampposts.

Camp Workbench:

• Defined in Section 8.2.3

Camp Lighting:

• Camps may contain abandoned lampposts.

• Some lampposts can spawn already lit.

• Dormant lampposts can be activated.

9.2.3 Dumbwaiter Carts

Dumbwaiter Carts are rare utility props embedded within cavern walls. They allow the player to transfer a limited amount of inventory directly to the Workshop without returning to the surface and ending the current mining session.

1. Placement:

• Dumbwaiter Carts spawn inside the cavern wall structures as rare environmental props.

• The cart remains accessible from the adjacent walkable floor tile.

• A discovered cart can be interacted with once the player enters its interaction range.

2. Inventory Transfer Interface:

• Interacting with a Dumbwaiter Cart opens a dedicated inventory transfer interface with both the player inventory and the cart inventory are displayed at the opposite sides.

• Items can be transferred between both inventories using drag-and-drop or RMB.

• [Shift + RMB] transfers “all the same type” into the other inventory.

• Only available inventory slots can receive transferred items.

• The cart has a smaller storage capacity than the player’s full inventory but provides enough capacity to make the transfer meaningful during a mining session.

3. Transfer Confirmation:

• The player confirms the transfer after arranging the desired items inside the cart.

• Confirmation closes the inventory interface.

• The Dumbwaiter Cart plays a mechanical departure animation accompanied by a dedicated SFX.

• The cart is removed from its position in the mine once the transfer is confirmed. The transferred items are removed from the player’s active mine inventory and sent to the dedicated Workshop storage.

• The player can cancel the transfer by closing the window. Reopening it does not reset the inventories.

• Should the player desccend to the floor that will delete the floor with the dumbwaiter, the game warns them with a pop up. “You have items in the Dumbwaiter at floor [FloorLevel], if you leave now they are destroyed do you want to proceed?”

4. Workshop Storage:

• Transferred items become available at the Workshop after the player returns to the surface.

• Dumbwaiter deliveries are stored in a dedicated Workshop storage inventory.

• Items remain stored there until the player retrieves or otherwise uses them.

• The Dumbwaiter Cart does return to the mine after completing a delivery and completely gone.

5. Capacity:

• Dumbwaiter Cart storage capacity is smaller than the player’s inventory capacity.

• Capacity is defined by a fixed number of inventory slots.

• Items occupying multiple quantities can be stacked according to their normal inventory stack rules.

9.3 Environmental Flora & Terrain Props

Environmental flora and terrain props provide visual variety, and subtle navigational cues throughout the subterranean cavern network. These elements reinforces the organic cave aesthetic without turning every environmental feature into a resource node or interactive object.

9.3.1 Luminescent Mushrooms

Luminescent Mushrooms are naturally occurring bioluminescent fungi scattered throughout mine floors. They serve primarily as environmental decoration and passive navigation landmarks, act as beacons for natural illumination that break up otherwise dark cavern spaces.

Mushrooms use three distinct visual formations:

A. Wall Mushrooms

Small clusters of mushrooms that grow directly on the solid cavern walls.

• Spawn on eligible cavern wall tiles.

• Produce a soft radial glow around their position.

• Primarily used to visually accentuate cavern boundaries, corners, and winding passages.

• Can naturally form clusters along longer stretches of cave wall.

• Do not obstruct player movement.

• Do not require player interaction.

Wall Mushrooms are particularly useful when there are winding long corridors in the floor.

B. Floor Mushrooms

Small individual or clustered mushrooms growing directly on walkable cavern floor tiles.

• Spawn on eligible walkable ground tiles.

• Produce a soft localized glow.

• Primarily serve as atmospheric environmental dressing.

• Can appear individually or in small irregular clusters in various sizes.

• Do not obstruct player movement.

• Do not require player interaction. Floor Mushrooms provide organic visual variation on the cavern floors and help prevent large open areas from appearing visually empty.

C. Mushroom Circles

Circular arrangements of small luminescent mushrooms growing on the cavern floors.

• Spawn as a visual formation occupying a larger floor footprint than individual Floor Mushrooms.

• Produce a soft glow across the surrounding area.

• The center of the formation remains walkable.

• Primarily serve as environmental landmarks and points of visual interest.

• Do not obstruct player movement.

• Do not require player interaction.

Mushroom Circles are relatively uncommon compared to Wall and Floor Mushrooms, allowing them to function as memorable environmental landmarks when encountered.

General Mushroom Rules

All three mushroom formations share the following rules:

• Mushrooms are non-destructible environmental flora.

• Mushrooms are not mined with the pickaxe .

• Mushrooms do not yield resources .

• Mushrooms do not block traversal or pathfinding .

• Mushrooms provide a soft environmental light source.

• Mushroom placement must respect the generated cavern topology and never obstruct Entry, Exit, Elevator Hub, or other required interaction zones.

• Mushroom density should remain controlled so that their illumination are secondary, rather than overtaking Player Sunstone or other primary light sources.

The visual language of the three formations can vary, with differences primarily being their shapes, colors and sizes.

10. Edge Cases & Technical Validation

10.1 Edge Case Matrixes

10.1.1 Session & Lifecycle

10.1.3 Navigation & Traversal

10.1.4 Mining & Tools

10.1.5 Inventory

10.1.7 Persistence & Regeneration

10.1.8 Environmental Systems

10.1.9 Cross-System Interactions

10.2 Data Integrity & Save Flags

10.2.1 Global vs Session State Isolation

Persistent progression data is kept separate from temporary mining-session data, preventing unintended state persistence, loss, or cross-session contamination.

Global State - Persistent Save Data

The following data is stored permanently and remains available across mining sessions :

• Repaired Elevator Hub Flags: Records which milestone elevators have been permanently restored and unlocked.

• Depth Clearance Flags: Records completed hazard clearances and resulting access to deeper floors.

• Player Progression Data: Permanent player, tool, inventory, workshop, and other progression states.

• Persistent Hub Data: Stored modifications belonging to elevator milestone floors, as defined by Section 6.

Global state must only be modified by validated progression or persistence events. Temporary floor activity must not directly alter global progression flags.

Session State - Temporary Runtime Data

The following data exists only during the active mining session unless explicitly promoted to persistent state:

• Generated floor instances currently held in the memory buffer.

• Player position and current floor state.

• Temporary floor modifications not belonging to a persistent elevator hub.

• Active resource depletion, placed objects, and other runtime changes on temporary floors.

• Temporary interaction, channeling, and generation states.

When a session ends, temporary floor instances is flushed from memory. Persistent data is committed separately during session cleanup. This follows the existing cleanup rule in which temporary floors are removed while repaired elevator flags are permanently registered.