# battlecache

**Repository Path**: he666zz/battlecache

## Basic Information

- **Project Name**: battlecache
- **Description**: minecraft mod
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Battle Cache (战地补给)

A **Minecraft Forge 1.20.1** mod that brings military-style supply caches into the game.

Find a military supply cache in the wild, walk up to its front and **right click** — no GUI,
no inventory screen: the lid swings open and the loot **bursts out** with sound. After one full
Minecraft day-night cycle (configurable) the cache reseals itself and restocks, ready for the next
drop.

## Features

- **Supply Cache block** — a 1×2 military crate with open/close
  lid animations ported from the original Blockbench model (`装备箱.bbmodel`).
- **Right click to open, from the front** — an interact prompt above the crosshair shows
  the bound use key (`Right click Open`). Interaction only works when standing in front of the
  crate's face (the latch side). Opening can be disabled with `rightClickOpens`.
- **No GUI loot burst** — loot rolls once and bursts out of the crate **towards its front**, in a
  staggered stream with a deep, weighty opening thunk and a scatter of small metal parts (steel
  nuts on the ground) per item, plus a heavy reseal sound (all synthesized, CC0).
- **Restock timer** — after `refreshTicks` (default 24000 = one day-night cycle, configurable) the
  cache closes with its animation and the loot refreshes.
- **Visual loot configuration (F8, creative only)** — aim at a cache and press **F8** to open the
  configuration screen. It has two tabs: **This Cache** (a loot list that replaces the loot
  table roll) and **Global Pool** (an installation-wide pool every unconfigured cache draws from,
  shared by all saves). Browse every registered item with a searchable, tab-filtered grid, import
  items straight from your inventory (full NBT/components preserved), set quantities, and save.
  Every entry has a **weight (1–999)** and a **quantity range (min–max)**. Controls over a
  configured slot: wheel = weight (Shift = ±10), left/right click = max ±1, Ctrl + left/right =
  min ±1, middle click = delete. Aim at **any other container** (chest, barrel, shulker box …)
  and press F8: the screen shows a **Read container** button that adds its contents to the
  global pool instead of editing a cache.
  The tab strip scrolls horizontally with arrows/wheel, so it never overflows no matter how many
  modded creative tabs are installed. The global pool holds up to 108 entries (a 9x12 grid with
  a vertical scrollbar, 6 rows visible at a time); each open draws 2–4 entries
  by weight (duplicates allowed) and rolls a quantity inside each entry's range.
  Loot priority is: this cache's saved list → global pool → loot table roll.
  Items inherited from a replaced chest still burst out with pool loot. The screen cannot be opened
  outside creative mode (enforced by the server). All GUI text is bilingual (English + 简体中文).
- **Flat loot** — burst items lie flat on the ground where they land (no vanilla spin/hover).
- **World generation** — caches spawn on the surface of overworld biomes (skips oceans/rivers),
  configurable on/off and rarity. When a cache spawns flush against terrain, its latch side turns
  outward so it can always be opened from open ground.
- **Chest replacement (optional)** — naturally generated vanilla chests become supply caches and
  **inherit the chest's loot table** (shipwreck/village/dungeon loot). Modded chests can also be
  replaced (off by default). Renamed chests are protected to keep player bases safe.
- MIT licensed, v0.3.2.

## Configuration

`config/battlecache-common.toml` (server side):

| Section | Key | Default | Meaning |
|---|---|---|---|
| worldgen | enabled | true | supply caches spawn naturally |
| worldgen | rarityPerChunk | 6 | higher = rarer (1 in N chunks) |
| gameplay | refreshTicks | 24000 | ticks until a opened cache reseals & restocks (24000 = 1 day-night) |
| gameplay | rightClickOpens | true | right click also opens the cache |
| replacement | replaceVanillaChests | true | replace generated vanilla chests (inherits loot) |
| replacement | replaceModdedChests | false | also replace other mods' chests |
| replacement | protectNamedChests | true | never replace renamed chests |

## Crafting

4× iron ingot around 1× chest:

```
I I I
I C I
I I I
```

## Building from source

Requirements: JDK 17 (or a newer JDK to *run* Gradle + 17 toolchain for compilation), internet access.

```bash
gradlew build        # produces build/libs/battlecache-0.3.2.jar
gradlew runData      # regenerate lang/loot/recipe data into src/generated/resources
gradlew runGameTestServer   # run the server-side game tests
gradlew runClient    # dev client
```

Notes for this machine (see git history of struggle): the system default Java is 25, which Gradle 8.8
cannot run on — set `JAVA_HOME` to a supported JDK (17–19) or add
`org.gradle.java.home`/`GRADLE_OPTS=-Dorg.gradle.java.home=...`. If your network intercepts TLS,
Java also needs `-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT` to trust the system certificate store.

## Regenerating assets

```bash
node tools/convert-model.js "<path-to-model>/装备箱.bbmodel" src/main/resources src/main/java
node tools/gen-sounds.js .scratch/sounds-wav
# then encode the WAVs with .scratch/ffmpeg into assets/battlecache/sounds/block/
for f in .scratch/sounds-wav/*.wav; do
  ffmpeg -y -i "$f" -c:a libvorbis -q:a 5 \
    "src/main/resources/assets/battlecache/sounds/block/$(basename "${f%.wav}").ogg"
done
```

## Design notes (v0.1.0)

- The crate is authored as a Blockbench generic-format model; the lid is a single bone, so the
  renderer bakes the cubes into vertex arrays (`CrateMesh`, generated by `tools/convert-model.js`)
  and animates the lid with the original catmull-rom keyframes around the hinge.
- Both halves of the crate render the whole mesh; the depth test makes the duplicate harmless.
- The LEFT half owns the loot state (loot table + seed, inherited items, per-cache custom loot,
  restock timer). The global loot pool is an installation-wide weighted list stored in
  `config/battlecache-global-pool.dat`, shared by every save and dimension.
- Chest replacement runs once per chunk on first server-side load and marks the chunk, so it is
  save-game safe and idempotent.