# Chunk Inspector

Finds out **why chunks stay loaded** on a heavily modded Minecraft **1.21.1 / NeoForge** server.

Every loaded chunk on a vanilla-or-modded server is loaded because some *chunk ticket* holds it, or
because it is within propagation range of one. Chunk Inspector reads the live ticket table, replays
the game's own level propagation, and writes a report naming the tickets, the chunks they keep alive,
and — if you ask for it — the exact line of code that created each one.

Reports land in `<levelDir>/chunk-summaries` (i.e. next to `level.dat` in the world folder).

## Two cost tiers

| | Always on | `-Dchunkinspector.deep=true` |
|---|---|---|
| Bytecode injected into Minecraft | **none** | `DistanceManager.addTicket`, `Ticket` |
| Per-ticket cost | zero | one stack walk |
| Names the ticket type, level, age, owner key | yes | yes |
| Names the *code* that created the ticket | no | yes |

The default tier is genuinely free: an access transformer widens a few ticket fields, and a snapshot
walks them on demand. Nothing runs between snapshots. The instrumenting Mixins are not merely
disabled without `deep` — a Mixin config plugin declines to apply them, so Minecraft's classes are
left untouched.

Reach for `deep` when the always-on tier shows you *which* tickets leak but the owner key is opaque.
Many tickets already identify themselves (a NeoForge forced chunk carries the requesting mod's id),
so it is often unnecessary.

## Commands

All require permission level 2.

| Command | What it does |
|---|---|
| `/chunkinspector status` | Cheap in-chat summary of the current dimension |
| `/chunkinspector why [<chunkX> <chunkZ>]` | Every ticket contributing to one chunk's level, strongest first. Defaults to the chunk you are standing in |
| `/chunkinspector snapshot` | Writes a report now |
| `/chunkinspector snapshot full` | ... including the expensive chunk-to-ticket attribution pass |

A report is also written every `interval` ticks and once on shutdown. The shutdown one always runs
the full analysis, because it is the one people come back to.

## System properties

Pass these on the server's JVM command line, before `-jar` / `@libraries/...`.

| Property | Default | Meaning |
|---|---|---|
| `chunkinspector.enabled` | `true` | Master switch. When off, no hooks and no reports |
| `chunkinspector.deep` | `false` | Record the stack trace behind every ticket |
| `chunkinspector.interval` | `600` | Ticks between automatic snapshots; `0` disables them |
| `chunkinspector.attribution` | `false` | Run the chunk-to-ticket pass on *periodic* snapshots too |
| `chunkinspector.retention` | `48` | Snapshot files to keep; `0` keeps everything |
| `chunkinspector.textReport` | `true` | Also write the human-readable `latest.txt` |
| `chunkinspector.stackDepth` | `24` | Frames kept per call site (deep mode) |
| `chunkinspector.maxOrigins` | `8192` | Distinct call sites remembered (deep mode) |
| `chunkinspector.sampleRate` | `1` | Capture one stack per *N* ticket adds (deep mode) |

Example — free monitoring, one snapshot per minute, a day's history:

```
-Dchunkinspector.interval=1200 -Dchunkinspector.retention=1440
```

Example — a full investigation:

```
-Dchunkinspector.deep=true -Dchunkinspector.attribution=true
```

## Output

```
chunk-summaries/
  latest.json                            the newest report
  latest.txt                             the same thing, readable
  summary-20260731-103326-periodic.json  timestamped history, pruned to `retention`
  summary-20260731-103326-command.json
  summary-20260731-103340-shutdown.json
```

`latest.txt` of a server with a 4x4 `/forceload`:

```
══ minecraft:overworld ══  game time 528
  chunks: 113 loaded, 61 block-ticking, 25 entity-ticking (1741 tracked)
  tickets: 17 on 17 chunks, 17 never expire, 16 from /forceload

  by ticket type
    forced        16 tickets   16 chunks  level>=31  keeps 64 loaded  oldest 26s
    start          1 tickets    1 chunks  level>=30  keeps 49 loaded  oldest 26s

  most suspicious tickets
    chunk 103, 102       forced      level 31  chunk 103, 102
      -> permanent ticket, alive 26s, keeping 9 chunks loaded; entity-ticking, so mobs and machines run here

  loaded chunk clusters
       64 chunks  centre 101, 101  bounds 98, 98 .. 105, 105     forced x64
       49 chunks  centre 0, 0      bounds -3, -3 .. 3, 3         start x49
```

The JSON carries the same information plus everything that did not fit — see
`InspectionReport` for the field-by-field documentation.

### How to read it

- **suspects** are tickets with *no timeout* that the game does not manage itself. Only these can
  leak forever. `keeping N chunks loaded` is a partition, not a sum: each loaded chunk is credited to
  the single strongest ticket holding it, so the numbers across tickets add up rather than overlap.
- **loaded chunk clusters** group contiguous loaded chunks. A leak usually shows up as one cluster
  far from spawn with a single cause.
- **level** is the vanilla chunk level: `<=31` entity-ticking, `<=32` block-ticking, `<=33` full.
  An entity-ticking leak is far more expensive than a merely-loaded one.
- **unattributed** lists loaded chunks no ticket explains. Normally empty; entries here mean
  something is holding chunks outside the ticket system.

## Building

```
./gradlew build          # jar + unit tests
./gradlew e2eTest        # installs a real NeoForge dedicated server and asserts on its reports
```

`e2eTest` is deliberately not part of `check`: it downloads NeoForge and runs two servers end to end,
taking a few minutes. It boots a dedicated server in each tier, force-loads a 4x4 square of chunks
over the console, and verifies the reports name it.