Files
gui
config.yml
messages.yml
promot.txt
request-cooldown.yml
sounds.yml
world-nick.yml
Code
10 2,130
promot.txt
# AI Build Prompt — "TwilightTPA" Minecraft Plugin
Copy everything below the line into your code-generation AI (Claude Code, ChatGPT, etc.) as a single prompt. It is written so the AI has zero ambiguity about commands, permissions, files, and GUI behaviour.
---
## PROMPT TO GIVE THE AI
You are an expert Minecraft Paper/Spigot plugin developer. Build a complete, **100% production-ready** TPA (teleport request) plugin called **TwilightTPA** for Paper 1.20+ (Java 17+, Maven project). It must feel and behave like the "DonutTpa" style plugin (clean GUI, colored gradient text, sound effects, per-message toggle system), but be fully original code, well-structured, and **bug-free, lag-free, and dupe-proof**. Follow every requirement below exactly.
### ZERO-DEFECT REQUIREMENT (mandatory, non-negotiable)
- The final plugin must compile with `mvn clean package` with **zero errors and zero warnings**.
- No `NullPointerException`, `ConcurrentModificationException`, or unhandled exceptions may be possible anywhere in normal or edge-case use — wrap every risky call (offline players, null locations, async/main-thread violations, missing config keys) in proper null-checks / try-catch with sensible fallbacks, and log a clear warning instead of throwing.
- No memory leaks: every map keyed by player/UUID must be cleaned up on quit, on request resolution, and on plugin disable.
- No duplication exploits of any kind (items, teleports, requests, GUI state) — treat this as a hard security requirement, not a nice-to-have.
- No race conditions between chat-click, GUI-click, and typed-command paths (see resolved-flag requirement below).
- All async/database work must never touch the Bukkit API off the main thread (no async inventory edits, no async teleports, no async entity access) — schedule callbacks back onto the main thread with `Bukkit.getScheduler().runTask(...)`.
- Every YAML file must load safely even if a key is missing (use defaults, never crash on a malformed/partial config).
- Test mentally (and describe in the README) the following edge cases and make sure each one is explicitly handled: sender/target disconnects mid-request; sender/target disconnects mid-warmup; two players `/tpa` each other simultaneously; a player spams `/tpa` on cooldown; `/tpaccept` with zero pending requests; `/tpaccept` with an invalid name; clicking an already-expired GUI button; server reload/`/tpaadmin reload` while requests are pending; teleporting across worlds with different spawn/border settings.
- Deliver the plugin as if it will be dropped onto a live public server immediately — no placeholders, no `// TODO`, no stub methods, no half-finished features. Every method must be fully implemented and working.
### 1. Project setup
- Maven project, `groupId: com.twilight`, `artifactId: twilighttpa`, main class `com.twilight.tpa.TwilightTPA`.
- Target Paper API 1.20.x, Java 17.
- Use `plugin.yml` with name `TwilightTPA`, version `1.0.0`, main class path, `api-version: 1.20`.
- Use an internal SQLite database (`data.db`, via a lightweight embedded driver, same as the reference file `data.db`) ONLY for persistent stats/toggle settings (auto-accept, GUI toggle, tpa-enabled toggle) that must survive restarts. Everything else (live pending requests, cooldown timers, warmup tasks) stays in memory (HashMap/ConcurrentHashMap) — never write live request state to disk, since that is what causes duplicate/ghost requests after a restart.
- No external heavy dependencies. Everything async-safe: database reads/writes must run off the main thread; only teleports and inventory operations run on the main thread.
### 2. Config files (create these exact files, same folder layout as the reference `DonutTpa` plugin)
```
plugins/TwilightTPA/
config.yml
messages.yml
sounds.yml
world-nick.yml
request-cooldown.yml
gui/
tpa-send.yml
tpa-accept.yml
tpahere-send.yml
tpahere-accept.yml
```
Below are the **exact original config files** (copied verbatim from the reference plugin) that you must use as the literal starting content — just rename any "Donut" branding/comment to "Twilight" and keep every key, value, structure, indentation, and default identical unless a section further below explicitly tells you to add new keys.
**config.yml** (use exactly, only header comment renamed)
```yaml
# TwilightTPA - Main Configuration
# How long (seconds) the teleport warmup countdown lasts.
# Set to 0 for instant teleport.
teleport-warmup: 3
# How long (seconds) before a pending TPA request expires automatically.
request-timeout: 60
```
Add these NEW keys to the same file (required for the anti-bug/anti-dupe logic in this spec):
```yaml
cancel-on-move: true # cancel warmup countdown if the teleporting player moves
cancel-on-damage: true # cancel warmup countdown if the teleporting player takes damage
max-active-requests-per-player: 1
```
**request-cooldown.yml** (exact copy)
```yaml
request-cooldown: 1
```
**world-nick.yml** (exact copy — admins may add more world entries later, keep the loader dynamic/not hardcoded to just these three)
```yaml
world-nicknames:
world: '&7Overworld'
world_nether: '&7Nether'
world_the_end: '&7End'
```
**sounds.yml** (exact copy, values/keys unchanged)
```yaml
sounds:
count-down:
enabled: true
sound: BLOCK_NOTE_BLOCK_PLING
volume: 1.0
pitch: 1.2
teleport-done:
enabled: true
sound: ENTITY_ENDERMAN_TELEPORT
volume: 1.0
pitch: 1.2
world-click:
enabled: true
sound: ENTITY_CHICKEN_EGG
volume: 1.0
pitch: 1.0
player-head-click:
enabled: true
sound: ENTITY_CHICKEN_EGG
volume: 1.0
pitch: 1.0
fly-icon-click:
enabled: true
sound: ENTITY_CHICKEN_EGG
volume: 1.0
pitch: 1.0
accept/send:
enabled: true
sound: ENTITY_EXPERIENCE_ORB_PICKUP
volume: 1.0
pitch: 1.0
decline/cancel:
enabled: true
sound: ENTITY_VILLAGER_NO
volume: 1.0
pitch: 1.0
error:
enabled: true
sound: ENTITY_VILLAGER_NO
volume: 1.0
pitch: 0.8
```
**messages.yml** — use the full reference file below as the literal starting content (every key must exist exactly as shown; only reword any leftover "Donut" wording to "Twilight" and translate the one German string `not-player` to English "This command can only be used by players!" unless you intend the server to be German-language). Every message key already follows the required chat/actionbar/title/subtitle module structure — do not change that structure, only add new keys if a new feature in this spec needs one (e.g. `tpaccept-ambiguous`, `tpaccept-no-match`, `admin-cancelled-all`, `admin-toggle-forced`, `config-hot-reloaded`):
```yaml
messages:
chat-hover-on-here: '&fClick here to �f986accept'
here: '�f986Here'
receive-request-hover: '&fClick here to �f986accept'
flight-gui-yes: '&fYes'
flight-gui-no: '&fNo'
accept-hover-message: '&fClick here to accept the teleport request'
receive-here-request-hover: '&fClick to accept the teleport here request'
config-reload:
module:
chat:
enabled: true
message:
- '&fReloaded in �f986%ms%&fms.'
actionbar:
enabled: false
message:
- ''
title:
enabled: false
message:
- ''
subtitle:
enabled: false
message:
- ''
user-not-found:
module:
chat:
enabled: true
message:
- '&fPlayer �f986%player%&f was not found online.'
actionbar:
enabled: false
message:
- ''
title:
enabled: false
message:
- ''
subtitle:
enabled: false
message:
- ''
self-teleport:
module:
chat:
enabled: true
message:
- '&fYou cannot teleport to yourself.'
actionbar:
enabled: false
message:
- ''
title:
enabled: false
message:
- ''
subtitle:
enabled: false
message:
- ''
non-valid-request:
module:
chat:
enabled: true
message:
- '&fThis teleport request does not exist.'
actionbar:
enabled: false
message:
- ''
title:
enabled: false
message:
- ''