# benjaminl11-au/fallingtimber architecture

> Architecture diagram of the GitHub repository benjaminl11-au/fallingtimber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benjaminl11-au/fallingtimber
- Repository: https://github.com/benjaminl11-au/fallingtimber

## Overview

FallingTimber is a Paper plugin whose main workflow starts with a player breaking a log: the listener checks eligibility and safeguards, asks the scanner to validate and collect a natural tree, then schedules batched felling and optional replanting/leaf decay. Plugin command handling also exposes preferences, inspection, statistics and global controls; durable player state and settings support these features. README documents capabilities such as sounds, particles, leaderboards and TPS/rate limits beyond the sampled excerpts, so their internal links are not asserted. The update checker’s GitHub integration is shown directly; unsampled configuration details are represented conservatively.

Main entry points: [`src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java) (Plugin lifecycle and commands), [`src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java) (Break-event handling), [`src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java`](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java) (Update checker and notices), [`src/main/java/io/github/benjaminl11au/fallingtimber/PlayerDataStore.java`](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/PlayerDataStore.java) (Preferences and statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Plugin runtime"]
  node_plugin["Plugin lifecycle and commands"]
end

subgraph group_tree["Tree felling"]
  node_listener["Break-event handling"]
  node_scanner["Natural-tree scanner<br/>[TreeScanner.java]"]
  node_felling["Cascade and effects"]
  node_leaves["Leaf decay"]
  node_replant["Sapling replanting"]
end

subgraph group_state["Settings and player state"]
  node_settings["Runtime settings"]
  node_playerdata["Preferences and statistics"]
  node_datafile[("player-data.yml")]
  node_migration["Configuration migration"]
  node_configfile["config.yml<br/>[config.yml]"]
end

subgraph group_updates["Version updates"]
  node_checker["Update checker and notices<br/>[UpdateChecker.java]"]
end

node_player(("Player"))
node_github["GitHub releases API"]
node_paper["Paper server"]

node_player -->|"breaks log"| node_paper
node_paper -.->|"dispatches event"| node_listener
node_plugin -->|"registers events"| node_listener
node_listener -->|"scans tree"| node_scanner
node_scanner -->|"reads limits"| node_settings
node_listener -->|"reads rules"| node_settings
node_listener -->|"reads preferences"| node_playerdata
node_listener -->|"starts cascade"| node_felling
node_felling -->|"schedules decay"| node_leaves
node_felling -->|"schedules replanting"| node_replant
node_plugin -.->|"loads settings"| node_settings
node_plugin -->|"creates store"| node_playerdata
node_playerdata -->|"loads and saves"| node_datafile
node_plugin -->|"migrates config"| node_migration
node_migration -->|"backs up and updates"| node_configfile
node_plugin -->|"starts checker"| node_checker
node_checker -->|"requests release"| node_github
node_player -.->|"uses commands"| node_plugin
node_checker -->|"sends notices"| node_player

click node_plugin "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java"
click node_listener "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java"
click node_scanner "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TreeScanner.java"
click node_felling "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java"
click node_leaves "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java"
click node_replant "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java"
click node_settings "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberSettings.java"
click node_playerdata "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/PlayerDataStore.java"
click node_migration "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/ConfigMigrator.java"
click node_configfile "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/resources/config.yml"
click node_checker "https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin toneBlue
class node_listener,node_scanner,node_felling,node_leaves,node_replant toneAmber
class node_settings,node_playerdata,node_datafile,node_migration,node_configfile,node_github,node_paper toneMint
class node_checker toneRose
class node_player toneIndigo
```

## Components

### Plugin runtime

- [Plugin lifecycle and commands](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java): `src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`

### Tree felling

- [Break-event handling](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java): `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`
- [Natural-tree scanner](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TreeScanner.java): `src/main/java/io/github/benjaminl11au/fallingtimber/TreeScanner.java`
- [Cascade and effects](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java): `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`
- [Leaf decay](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java): `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`
- [Sapling replanting](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java): `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`

### Settings and player state

- [Runtime settings](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/TimberSettings.java): `src/main/java/io/github/benjaminl11au/fallingtimber/TimberSettings.java`
- [Preferences and statistics](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/PlayerDataStore.java): `src/main/java/io/github/benjaminl11au/fallingtimber/PlayerDataStore.java`
- **player-data.yml**
- [Configuration migration](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/ConfigMigrator.java): `src/main/java/io/github/benjaminl11au/fallingtimber/ConfigMigrator.java`
- [config.yml](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/resources/config.yml): `src/main/resources/config.yml`

### Version updates

- [Update checker and notices](https://github.com/benjaminl11-au/fallingtimber/blob/main/src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java): `src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java`

### Other components

- **Player**
- **GitHub releases API**
- **Paper server**

## Connections

- Player → Paper server: breaks log (evidence: `README.md`)
- Paper server → Break-event handling: dispatches event
- Plugin lifecycle and commands → Break-event handling: registers events (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`)
- Break-event handling → Natural-tree scanner: scans tree (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`)
- Natural-tree scanner → Runtime settings: reads limits (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TreeScanner.java`)
- Break-event handling → Runtime settings: reads rules (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`)
- Break-event handling → Preferences and statistics: reads preferences (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`)
- Break-event handling → Cascade and effects: starts cascade (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`)
- Cascade and effects → Leaf decay: schedules decay (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`)
- Cascade and effects → Sapling replanting: schedules replanting (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/TimberListener.java`)
- Plugin lifecycle and commands → Runtime settings: loads settings (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`)
- Plugin lifecycle and commands → Preferences and statistics: creates store (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`)
- Preferences and statistics → player-data.yml: loads and saves (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/PlayerDataStore.java`)
- Plugin lifecycle and commands → Configuration migration: migrates config (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`)
- Configuration migration → config.yml: backs up and updates (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/ConfigMigrator.java`)
- Plugin lifecycle and commands → Update checker and notices: starts checker (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/FallingTimberPlugin.java`)
- Update checker and notices → GitHub releases API: requests release (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java`)
- Player → Plugin lifecycle and commands: uses commands
- Update checker and notices → Player: sends notices (evidence: `src/main/java/io/github/benjaminl11au/fallingtimber/UpdateChecker.java`)