EchoCraft

EchoCraft is a temporal memory, reconstruction and player-trace system for Paper Minecraft servers.

It records structural changes, captures temporal snapshots, restores damaged builds and integrates with EchoPanel through an authenticated REST API.

Features

• Automatic structure snapshots
• Block reconstruction after explosions
• Temporal memory versions
• Player movement traces
• Player action tracking
• SQLite persistence
• Snapshot history grouped by timeline
• Manual memory restoration
• Confirmation step before restoration
• Automatic database backups
• EchoPanel heartbeat integration
• Activity synchronization with EchoPanel
• Remote restoration commands from EchoPanel
• Restoration audit logs
• Support for named timelines and snapshots

How it works

Structure changes
      │
      ▼
EchoCraft creates a temporal snapshot
      │
      ├── stores blocks
      ├── stores player traces
      ├── stores player actions
      └── assigns timeline and version metadata
      │
      ▼
Snapshot saved in SQLite
      │
      ├── can be restored in Minecraft
      └── can be synchronized with EchoPanel

When EchoPanel integration is enabled, the plugin also sends heartbeat data, reconstruction events, player traces and timeline snapshots to the web panel.

Technologies

• Java
• Paper API
• Gradle
• SQLite
• REST API
• JSON
• Java HTTP Client

Requirements

• Java 21 or newer
• A compatible Paper server
• Gradle wrapper included in the repository
• EchoPanel is optional

Building

Clone the repository:

git clone https://github.com/phmbezerra/EchoCraft.git
cd EchoCraft

Build the plugin:

Windows PowerShell

.\gradlew.bat clean build

Linux or macOS

./gradlew clean build

The compiled plugin will be generated in:

build/libs/

Installation

1. Stop the Minecraft server.
2. Build the plugin or download a release.
3. Copy the generated .jar into the server's plugins folder.
4. Start the server.
5. Configure EchoCraft in:

plugins/EchoCraft/config.yml

Do not delete the plugin database unless you intentionally want to remove saved temporal memories.

Configuration

Default configuration:

echopanel:
  enabled: true
  url: "http://echopanel.test/api/servers/heartbeat"
  token: ""
  interval-seconds: 30

Options

Option	Description
enabled	Enables or disables EchoPanel integration
url	EchoPanel heartbeat endpoint
token	API key generated by EchoPanel
interval-seconds	Heartbeat interval

Never commit a real API key to GitHub.

The plugin derives the activity and command endpoints from the configured EchoPanel URL.

Main commands

List memories

/echolist

Displays available temporal memories.

Restore a memory

/echorestore <memory-id>

Prepares the selected memory for restoration.

Confirm restoration

/echorestore <memory-id> confirm

Confirms and starts the restoration.

The plugin uses a confirmation step to reduce accidental restores.

Temporal memories

Each snapshot may contain:

• snapshot ID
• timeline ID
• version number
• memory type
• creation cause
• captured blocks
• player traces
• player actions
• world and coordinates
• creation timestamp

Common memory types include:

• explosion snapshot
• manual block change
• restoration snapshot

Player traces

EchoCraft records player movement around monitored structures.

A player trace event may include:

• player UUID
• player name
• location
• number of trace points
• number of recorded actions
• related snapshot
• related timeline and version

These traces can be sent to EchoPanel and displayed alongside reconstruction events.

EchoPanel integration

EchoCraft can communicate with EchoPanel using an API key.

Heartbeat

EchoCraft
→ sends server status
→ EchoPanel updates online state
→ player count and version are displayed

Activity synchronization

Snapshot or restoration occurs
→ EchoCraft sends activity data
→ EchoPanel stores the event
→ timeline and activity cards are updated

Remote restoration

User requests a restoration in EchoPanel
→ EchoPanel queues a command
→ EchoCraft claims the command
→ memory is restored
→ result is reported back to EchoPanel

The plugin periodically checks EchoPanel for pending commands when integration is enabled.

Persistence

EchoCraft stores temporal data in SQLite:

plugins/EchoCraft/echocraft.db

The plugin may also create automatic database backups.

Important local files:

plugins/EchoCraft/config.yml
plugins/EchoCraft/echocraft.db
plugins/EchoCraft/backups/

These files should be backed up before major updates.

Security

Sensitive and local files are ignored by Git, including:

• SQLite databases
• API tokens
• local server folders
• backups
• logs
• generated build files
• IDE configuration

The public config.yml should always use an empty token:

token: ""

Development notes

EchoCraft performs world changes on the Minecraft server thread and uses asynchronous HTTP requests for EchoPanel communication.

The project includes:

• snapshot capture logic
• restoration locking
• persistence layer
• player-trace recording
• activity synchronization
• remote-command polling
• audit logging

Related project

• EchoPanel — Web monitoring and remote-control panel for EchoCraft

Project status

EchoCraft is under active development.

Current features are functional in a local Paper server environment with EchoPanel integration.

Author

Developed by Paulo Henrique.