Distant Ticking

🚀 Overview

DistantTicking is a powerful PaperMC plugin designed to enhance your server's performance while keeping your essential redstone contraptions and automated farms continuously active, regardless of player proximity. Say goodbye to AFK farms and chunks unloading at inconvenient times!

Traditionally, Minecraft only "ticks" chunks within a player's `simulation-distance`. This means complex machines and farms stop working when players move too far away or log off. DistantTicking solves this by intelligently detecting and permanently loading chunks that contain player-placed "tick-worthy" blocks by tracking their exact locations.

Who is this for?

This is not for large scale servers. This is for private, smaller, high end serveres which focus on immersion and aim to have the maximum simulation distance. This plugin can allow you to reduce your simulation distance.

For example, on my server with a sim distance of 16, we would simulate about 1089 chunks per player. With this plugin there are about 60 chunks being loaded. Because simulation distance doesn't matter as much anymore, we lowered the sim distance to 10. This means about 648 less chunks being simulated per player, while effectively making the simulation distance unlimited as far as experience goes, since things like crops, furnances, chunks with chests, etc. are still loaded.

It's effectively a discreet chunk loader.

Watch the video

✨ Features

- Debug Logging: Automatically detects and force-loads chunks by tracking the Debug Logging: of player-placed blocks (e.g., Furnaces, Hoppers, Redstone, Pistons, Rails). - Debug Logging: Automatically hibernates chunks when there are no players online after a predefined time. - Debug Logging: Ensures your machines, farms, and redstone contraptions keep working 24/7, even when no players are nearby or in the same dimension. - Debug Logging: Allows server owners to lower the global `simulation-distance` in `server.properties` (e.g., to 4-8) for better overall TPS and reduced server load, while DistantTicking manages the critical ticking areas. - Debug Logging: Easily customize which block materials trigger chunk loading directly in the `config.yml`. - Debug Logging: Robust persistence using a hybrid approach of a central index and per-chunk Persistent Data Containers (PDCs). Recovers gracefully from accidental data file deletions or server crashes. - Debug Logging: Automatically cleans up outdated force-loaded entries if blocks are removed without proper plugin notification (e.g., world editing, server crashes). - Debug Logging: Intuitive commands for monitoring plugin status, listing force-loaded chunks, refreshing chunk data, and debugging. - Debug Logging: A specific command to remove legacy tick-worthy block data stored in PDCs from previous plugin versions. - Debug Logging: Specific debug mode to get detailed plugin logs without flooding the entire server console.

⚙️ How it Works

DistantTicking operates on a hybrid data storage model:

1. Synchronization: When a player places a configurable "tick-worthy" block, the plugin marks that chunk's data using Minecraft's built-in Persistent Data Containers (PDCs). Instead of just a count, it now stores the Synchronization: of each tick-worthy block within that chunk. This data is serialized to a JSON string and stored directly within the chunk's file, persisting even if the main plugin data file is lost. 2. Synchronization: A lightweight JSON file maintains a list of all chunks that are currently force-loaded by the plugin across all worlds. This file is loaded on server startup to immediately initiate force-loading of all relevant chunks. 3. Synchronization: - When a player places a tick-worthy block, its chunk is added to the centralized index and force-loaded if it's the first tick-worthy block in that chunk. - When a player breaks (or a block is destroyed) a tick-worthy block, its location is removed from the chunk's PDC. If, after removal, no tick-worthy blocks remain in that chunk's PDC, it's removed from the centralized index and un-force-loaded. - A periodic background task verifies that chunks in the centralized index still have corresponding tick-worthy blocks in their PDC. If a chunk's PDC shows no stored block locations, the entry is removed from the centralized index, ensuring "self-healing" from data inconsistencies.

This approach provides precise tracking, reliable persistence, and efficient resource management.

Known Bugs

- If you track crops, it won’t detect them being broken if you jump on them. However the consistency check will eventually realise.

📥 Installation

1. Download the latest `DistantTicking-X.Y.Z.jar`. 2. Place the `DistantTicking-X.Y.Z.jar` file into your server's `plugins/` folder. 3. Restart your PaperMC server. 4. A `DistantTicking` folder will be created in your `plugins/` directory, containing `config.yml` and `active_chunks.json`. 5. IMPORTANT! If you add this to an existing world, you will want to run `/dt refresh <chunk radius> <vertical-up> <vertical-down>` to populate the new location-based tracking data for existing blocks. I advise doing this surgically, with a low chunk radius and appropriate vertical limits, as scanning many chunks or large vertical ranges can be slow. > You may want to run /dt cleanup after updating, in case I've changed anything.

🛠️ Configuration (`config.yml`)

The `config.yml` file is automatically generated on first run. You can customize the plugin's behavior here.

```yaml

DistantTicking Plugin Configuration

settings:

Interval for automatically saving the force-loaded chunks data to active_chunks.json.

Measured in minutes. (20 ticks = 1 second)

auto-save-interval-minutes: 5 # Default: 5

Interval for the periodic consistency check.

This check verifies if chunks marked for force-loading still contain tick-worthy blocks in their PDC.

Measured in hours.

consistency-check-interval-hours: 6 # Default: 6

Enable debug mode for more verbose console logging.

Set to 'true' to see detailed plugin activity (e.g., individual chunk loads/unloads).

These logs are *only* for DistantTicking and will not flood your console with other plugin's debug messages.

debug-mode: false # Default: false

Settings for the server hibernation feature.

When the server is empty, the plugin can unload all chunks to save resources.

hibernation:

Set to true to enable this feature.

enabled: true

How long the server must be empty before chunks are unloaded.

Measured in minutes.

unload-delay-minutes: 60

How many chunks to reload at a time when a player joins an empty server.

Higher values reload faster but may cause more lag.

reload-chunks-per-batch: 5

How often (in ticks) to process a batch of chunks for reloading. 20 ticks = 1 second.

A value of 5 means a batch is reloaded every 5 ticks.

reload-stagger-ticks: 5

List of materials that, when placed by a player, should make their chunk tick-worthy and force-loaded.

Ensure material names are valid Minecraft Material enums (case-insensitive in plugin, but use uppercase for clarity).

#

IMPORTANT: Even non-BlockEntities (like Redstone Wire, Repeaters, Pistons) will cause a chunk to stay loaded,

allowing them to function continuously if they are part of an active redstone circuit.

# tick-worthy-blocks: - Blocks you want to tick

Suggestion for server owners:

For optimal performance, consider lowering your server's 'simulation-distance' in server.properties

to a value like 4-8. This allows DistantTicking to manage persistent ticking for your machines

while significantly reducing the load on your server's CPU for areas without critical contraptions.

```

🎮 Commands

All commands start with `/dt` (or `/distantticking`).

| Command | Description | Permission | | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- | | `/dt help` | Displays the plugin's help message. | `distantticking.command.base` | | `/dt pdcinfo` | Shows the count of tick-worthy blocks (from PDC) in your current chunk. | `distantticking.command.pdcinfo` | | `/dt status` | Displays the current status of the DistantTicking plugin. | `distantticking.command.status` | | `/dt list [page]` | Lists all chunks currently force-loaded by the plugin, with pagination. | `distantticking.command.list` | | `/dt removehere` | Removes the chunk you are standing in from the force-load list. | `distantticking.command.removehere` | | `/dt reload` | Reloads the plugin's `config.yml` and restarts internal tasks. | `distantticking.command.reload` | | `/dt refresh <radius> <vertical-up> <vertical-down>` | Scans a square area of chunks defined by the <radius> argument, and clamped by the vertical up and down args to prevent detecting unwanted map structures (eg mineshafts.) | `distantticking.command.refresh` | | `/dt cleanup` | Cleans up old PDC keys used before tracking was block specific. | `distantticking.command.cleanup` | | `/dt check` | Performs a consistency check and tells you how long it took to run. This is meant to be more of a profiling tool than actually used, since these checks run automatically. | `distantticking.command.cleanup` |