> For the complete documentation index, see [llms.txt](https://epromc.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://epromc.gitbook.io/docs/etools/core-features-and-mechanics/database-and-lifespans.md).

# Database & Lifespans

Technical architecture of eTools SQLite/MySQL database engine, lifespan countdowns, and anti-dupe UUID tracking.

eTools is backed by an asynchronous database engine powered by **HikariCP**, capable of handling thousands of item transactions with zero main-thread hitching.

***

## Lifespan Modes Explained

**eTools** supports three distinct operational lifespan modes:

### 1. `ONLINE_TIME` (Active Playtime)

* **How It Works:** The tool's lifespan **only counts down while the player is actively connected** to the server.
* **Smart Auto-Pause:** When the player logs off, the countdown instantly pauses. The remaining time is safely saved in both the item's NBT (`PersistentDataContainer`) and the database.
* **Ideal For:** Survival, SMP, and RPG servers where players expect full value from their purchased or earned tools without losing time while offline.

{% hint style="info" %}
**Bypass Permission:** Players with `etools.bypass.timer` will never consume time on their tools, making it easy to grant perks to VIPs or staff.
{% endhint %}

### 2. `REAL_TIME` (Continuous Elapsed Time)

* **How It Works:** Lifespan counts down continuously in real-world time based on UNIX timestamps, regardless of whether the player is online or offline.
* **Ideal For:** Weekend tournaments, seasonal events, or battle pass rewards with strict expiration deadlines.

### 3. `UNLIMITED` (Permanent)

* **How It Works:** The tool never expires and has no countdown.

***

## Instant Container Expiration

What happens if a player stores a near-expired tool inside a Chest, Ender Chest, Barrel, or Shulker Box and logs off?

* The moment any player opens that container (`InventoryOpenEvent`):
  * eTools performs a sub-microsecond asynchronous scan of the container's contents.
  * If an expired tool is found, it is **instantly destroyed** with a crystal-shattering sound effect (`BLOCK_AMETHYST_CLUSTER_BREAK`), an explosion particle burst, and an alert message: `An expired <tool> shattered upon opening the container!`
  * Completely prevents players from hoarding expired custom items in offline storage.

***

## Emergency Two-Stage Recall (`/etools recall`)

In the event of an economic imbalance, server exploit, or the need to revoke a specific tool server-wide:

{% hint style="danger" %}
**Irreversible Action:** Recall permanently deletes items across player inventories, world storage containers, item entities, and unloaded chunks. Always confirm with care.
{% endhint %}

### Execution Flow:

1. **Initiate:** `/etools recall all` (or `/etools recall <player>`)
2. **Confirm:** `/etools recall confirm` within 15 seconds.
3. **Purge Scope:**
   * **Player Inventories:** Main inventory, hotbar, armor slots, offhand, and Ender Chest.
   * **Mouse Cursors:** Any item actively held on a player's cursor.
   * **Ground Drops:** All dropped item entities across every loaded world.
   * **World Storage:** Chests, Double Chests, Barrels, Hoppers, Droppers, Dispensers, and Shulker Boxes.
   * **Entity Storage:** Chest Boats, Chest Minecarts, Hopper Minecarts, Donkeys, Mules, and Llamas.
   * **Nested Shulkers:** Recursively inspects inside Shulker Boxes inside chests or inventories to remove recalled items.
   * **Unloaded Chunks:** Tools are flagged as revoked in the database and automatically purged when the chunk is loaded later (`ChunkLoadEvent`).

***

## Duplication Protection (UUID Tracking)

Every tool generated by eTools receives a unique **Random UUID (v4)** stored inside its `PersistentDataContainer` (PDC):

* If a player attempts to duplicate an item via client/server exploits or glitches, the eTools database engine flags the duplicate UUID and automatically confiscates the illegal clone.
* Fully resilient against server crashes, world rollbacks, and player username changes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://epromc.gitbook.io/docs/etools/core-features-and-mechanics/database-and-lifespans.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.