TimeLens

Explore your Minecraft world's past.

TimeLens reconstructs how an area of your world looked at an earlier point in time and shows it to a single player, using the block history that CoreProtect has already recorded.

The real world is never modified. TimeLens reads CoreProtect's records, works out what each affected block was at the moment you asked for, and sends those blocks to one player's client as a private overlay. The server continues to hold, simulate and serve the real world exactly as before, and every other player online sees the present, unchanged.

TimeLens is a visualisation tool. It is not a rollback tool. It never writes to the world and never modifies CoreProtect's data.

/timelens 7d
/timelens 2026-08-20 14:30
/timelens exit

Please read before installing

This is an alpha release.

The central promise of TimeLens, that a historical view is visible only to the player who requested it, has been verified by design and by code review, but it has not yet been confirmed with two clients on a live server. Please do not run this on a production server.

If you would like to help test it, the validation checklist is in the repository, and reports of anything it gets wrong are very welcome.

Requirements

CoreProtect is a required dependency. It is the only source of history in this release, and TimeLens will refuse to enable without it. CoreProtect's API must also be enabled, which means api-enabled: true in plugins/CoreProtect/config.yml.

TimeLens uses Paper-only APIs and will not load on Spigot or CraftBukkit. Folia is not supported and has never been tested.

TimeLens can only show history that CoreProtect has already recorded. On a server where CoreProtect was installed recently, there is no past to show yet.

How to use it

Stand where you want to look, then ask for a point in time. This can be an age counted back from now, or a calendar date.

/timelens 30m
/timelens 7d
/timelens 2026-08-20
/timelens 2026-08-20 14:30

TimeLens replies while it works, then reports what it found.

TimeLens > Loading world history from 7 days ago...
TimeLens > Viewing the world from 7 days ago.
TimeLens > 1,284 blocks restored within 48 blocks of you.
TimeLens > Use /timelens exit to return to the present.

If part of a build is missing, the view was smaller than the build. Pass a radius to widen it.

/timelens 7d 96

While a view is open you are held where you stood, and you cannot break, place or interact with blocks. Looking around is unrestricted, and normal movement returns as soon as you exit.

Accepted time formats

An age, counted back from now:

Months and years are not accepted as ages, because their length is ambiguous. Use a date instead.

A calendar moment, read in the server's own time zone:

Note that times are read in the server's time zone, not the player's. A host running in UTC while its players are in Europe will resolve /timelens 14:30 to 14:30 UTC.

Commands

All subcommands are case-insensitive and tab-completed. The optional [radius] overrides the configured radius for that single view.

Permissions

timelens.admin grants nothing in this release. It exists so that permission groups can be set up once, before later versions add administrative commands.

Configuration

view:
  radius: 48
  vertical-radius: 48
  maximum-radius: 96
  freeze-movement: true
  block-interactions: true

history:
  maximum-lookback: 30d
  maximum-results: 25000

messages:
  prefix: "<green>TimeLens <dark_gray>></dark_gray> "

view.radius is the setting that matters most. A view only reconstructs blocks inside it, so a build extending further will look half restored. TimeLens reports the radius it used with every view, which makes the cause visible.

Values are validated at startup. Anything unusable is reported in the console and replaced with the shipped default, so a mistake in the file cannot stop the plugin from enabling.

What has been measured

• Reconstruction agrees with an independent SQL calculation on 1,971 of 1,971 positions taken from a real CoreProtect database.
• Main-thread render preparation costs 0.5 to 2.8 ms for up to 2,400 blocks on Paper 1.21.11, where one server tick is 50 ms.
• History lookups run off the main server thread, so the database work does not affect tick time.
• Two independent limits bound the cost of a single view. A request exceeding either one is refused with an explanation rather than rendered slowly.
• 83 unit tests, and a clean build from a fresh checkout.

Current limitations

Please read this before reporting behaviour as a problem.

• Views are player-specific. Only the requesting player sees the past. This is intended.
• Only block state is reconstructed. Chat, commands, container transactions and interactions are ignored.
• Entities are not reconstructed. Mobs, pets, villagers, boats, minecarts, item frames, armour stands and dropped items all appear as they are now. This cannot be closed against CoreProtect, which records only that an entity died, with a time and a place, and never where anything stood or moved.
• Inventories and container contents are not reconstructed. A historical chest is shown as a chest, and opening it shows its present contents.
• Block entity and NBT data may be incomplete, including sign text, banner patterns and skull owners, because CoreProtect's block history does not carry all of it.
• A block added since the viewed moment simply disappears, because nothing was there. This does mean an empty area and an area TimeLens did not reach can look the same.
• The view does not follow you. It is rendered once, around where you stood.
• Collision still uses the real world. The server does not know about your historical view, so a recently built block is invisible to you but still solid. Movement is held still while viewing for exactly this reason.
• Rolled-back history is skipped. A change CoreProtect has marked as rolled back is no longer reflected in the world, so reversing it would move away from the truth rather than towards it.
• Reconstruction is accurate to about one second, because history timestamps have one-second resolution.

Deliberately not included in this release: timeline playback, graphical interfaces, block inspection, contributor visualisation, compare mode, rollback, Folia support and metrics. The foundation should prove itself first.

Links

• Source code
• Issue tracker

Released under the MIT License.