PotatoBuildWorld(Atmospheric)

# PotatoBW — Detailed Overview (Parts I–III)

## I. Project Positioning

**PotatoBW** is a gameplay-oriented lightweight mod for **Minecraft 1.21.1 / NeoForge 21.1.235** (mod id `potato_bw`, version `0.15.0`). Its entire premise fits in one sentence:

> **Every enclosed space is an independent gas container — with its own oxygen amount, total gas amount and pressure, continuously consumed by breathing, fire and furnaces.**

It is not a decoration or utility mod. It is a **server-authoritative "sealed-space gas simulator"**: any room, cave, diving bell or airship cabin the player physically seals out of blocks is detected in real time and becomes a "gas vessel" that participates in simulation. Oxygen here is a **virtual property** — a single `double` in SavedData; no oxygen fluid or block is ever registered.

---

## II. At a Glance

| Item | Value |
|---|---|
| Version | `0.15.0` (single source of truth: `mod_version` in [gradle.properties](gradle.properties)) |
| Platform | Minecraft `1.21.1` · NeoForge `21.1.235` · Java `21` |
| Build | Gradle Wrapper `9.2.1` + `net.neoforged.gradle.userdev 7.1.38`, offline build (cache at `E:\gradle-home`) |
| Artifact | [potato_bw-0.15.0.jar](build/libs/potato_bw-0.15.0.jar) — **196,888 B / 141 entries**, production jar excludes `com/potatobw/test/**` |
| Code size | **42 .java files / 5,616 lines / 12 packages**; largest: `OxygenGameTests` 1,611, `OxygenManager` 987, `SpaceRecord` 323 |
| Registered content | 4 blocks, 4 items, 2 mob effects, 1 sound, 4 data-pack tags, 4 damage types |
| Verification | Offline build ✅ · GameTest **53/53** (log: `All 53 required tests passed :)`) · same source 53/53 with real Sable 2.0.6 |
| License | All Rights Reserved |

---

## III. Core Gameplay Mechanics

### 1. Sealed-Space Detection — Geometric Flood Fill

Starting from the player's block, a **6-connected flood fill** expands; only blocks that can stop the spread count as "sealing":

```text
isSealing(state):
    if state.isAir()                          -> false
    if leaves (LeavesBlock / #minecraft:leaves) -> false   # leaves leak
    return state.isCollisionShapeFullBlock()  # must be a full 1×1×1 collision box
```

Consequently **fences, brick walls, skulls, trapdoors, doors, glass panes, slabs, stairs, carpets and chests** all leak. Two further hard failure conditions apply:

- any cell **open to the sky** (`MOTION_BLOCKING` heightmap) → treated as leaking;
- **unloaded chunks** or **world height bounds** → treated as leaking.

**Space identity = bounding box**: the `(minX,minY,minZ)-(maxX,maxY,maxZ)` string from the flood fill is the space key, which makes persistence trivial. The trade-off is that any shape change is treated as a new space.

### 2. Gas & Pressure Model (v0.9.0 semantics)

```text
Volume V(L)        = 1000 L × all passable cells in the space   # 1 block = 1 m³
Reference Vref(L)  = largest volume since sealing               # used for display %
Total gas Gas(L)   and oxygen O2(L) tracked separately
Pressure P(atm)    = Gas / V                                    # 1 atm = 101.325 kPa
Display O2 (%)     = clamp(O2 / Vref × 100, 0, 100)
```

Key "semantic decisions":

- **Capacity counts passable cells** (air, water, torches, fences, doors — all 1000 L/block), so a water-filled room is not zero-capacity but `27,000 L / 243 L (0.9%)`;
- **Oxygen mass is conserved**: digging out blocks enlarges volume but **never conjures oxygen**, so 1 block at 21% dug into 2 blocks = 10.5%;
- **Filling blocks raises pressure but not displayed O₂%** (Vref is the denominator), preventing "stuff the room with blocks to farm oxygen percentage";
- **Consumption only removes oxygen, not total gas** (respiration ≈ O₂↔CO₂), so pressure is driven mainly by volume change while displayed oxygen falls with consumption.

### 3. Dimensional Atmosphere & Altitude Atmosphere

| Dimension | Pressure multiplier | Oxygen volume fraction | Pure-air reading |
|---|---|---|---|
| Overworld | `1.0` | `21%` | 21% |
| Nether | `1.6` | `27%` | 27% |
| End | `0.8` | `19.5%` | 19.5% |

The Overworld additionally layers an **altitude atmosphere** ([HeightAtmosphere.java](src/main/java/com/potatobw/oxygen/HeightAtmosphere.java)):

- `y < -64` → vacuum (0 atm / 0%);
- `-64 ≤ y ≤ 192` → legacy approximation `P = exp(-0.004×(y−sea))`, oxygen 21%;
- `y > 192` → realistic altitude model (1 block = 10 m): `P = exp(-((y−sea)×10)/8500)`, oxygen = 21% × P (≈ **17.9%** at y=200).

Paired with the data pack [overworld.json](src/main/resources/data/minecraft/dimension_type/overworld.json) raising the Overworld to `min_y=-128`, `height=2160`, the **maximum buildable Y is 2031** (the 1.21.1 engine's `DimensionType.MAX_Y` hard cap — 2048 is unreachable; only the height fields are overridden, all generation rules stay vanilla).

### 4. Oxygen Consumption (per tick)

| Source | Consumption |
|---|---|
| Player idle / moving / vigorous | `0.005` / `0.01` / `0.05` L |
| Other mobs | `hitbox volume / player volume × state rate × 1.2` |
| Each torch / lantern | `0.005` L |
| Each fire block (`#minecraft:fire`) | `0.1` L |
| Lit furnace / blast furnace | `0.15` / `0.3` L |

**Exempt from consumption and from low-oxygen effects**: undead (`#minecraft:undead`), golems (`potato_bw:oxygenless_mobs`, default iron/snow golem), non-Mob entities like armor stands/paintings/item frames, and water-breathing mobs.

### 5. Two-Way Low/High-Oxygen Effects

The most "gameplay" part of the project — **too little oxygen kills you, and too much does too**:

| Displayed O₂ | Effect |
|---|---|
| `< 15%` | Blindness + Weakness II, 4 suffocation damage/sec (`potato_bw:hypoxia`, armor-piercing, no knockback), heartbeat sound, **all torches/lanterns replaced by "smoldering" blocks**, **furnaces stop ticking** |
| `< 6%` | **20 damage/tick** of `potato_bw:critical_hypoxia`, **can kill Creative players**, punches through Infinity armor / Manaita-style death protection |
| `22.5–23.5%` | Jump Boost I + Speed I |
| `25–30%` | Hunger I |
| `30–40%` | Hyperoxia (camera sway + periodic FOV shift, no shaders, shader-pack friendly) |
| `> 40%` | Oxygen poisoning (one level per 5%, up to 19), `25 >> amplifier` ticks for 1 damage and **can be lethal**, health bar overlaid red |

Plus fire reacting to concentration: extinguished below `14.5%` (soul fire excepted), explodes at power 2 above `50%`.

### 6. Pressure Physiology (v0.14.0, applies to all mobs)

Every `LivingEntity` carries a "body pressure" that equalizes toward the target at most `0.05 atm` per 5 ticks, settled every 20 ticks:

| Phenomenon | Condition | Effect |
|---|---|---|
| Barotrauma | Δ > 0.6 atm | `(|Δ|−0.6)×6` damage/sec as `potato_bw:pressure` |
| Crush (water/high pressure) | > 3 atm and not water-breathing | `(P−3)×1.5` damage/sec |
| Nitrogen narcosis | > 2 atm and not water-breathing | Nausea + Slowness (up to III) |
| Low-pressure hypoxia | < 0.6 / 0.35 / 0.25 atm | Weakness → Slowness → extra damage |

Hydrostatic pressure: water `0.0968 atm/block`, lava `0.242 atm/block` (capped at 20 atm).

PotatoBW 是一个面向 Minecraft 1.21.1 / NeoForge 21.1.235 的玩法向轻量模组（mod id potato_bw，版本 0.15.0）。核心设定：

每一个密闭空间都是一个独立的气体容器——有自己的氧气量、总气体量和气压，并会随着呼吸、燃烧、炉子运转持续被消耗。

它不是装饰/工具类模组，而是一套服务端权威的"封闭空间气体模拟器"：玩家用方块亲手封出来的房间、洞穴、潜水钟、飞艇舱室，都会被实时识别为一个个"气体容器"并参与模拟。氧气在本项目中是虚拟属性（SavedData 里的一个 double），不注册任何氧气流体或方块。