English version

TPATools English Wiki

This Wiki is a complete guide for server owners / players / add-on developers.

1. Introduction and Features

TPATools is a server-side-only Minecraft mod that integrates commonly used survival-server teleport commands into one package: TPA requests, homes (including sharing/public/invitations), warps, back, graves, and random teleport (RTP). It also provides a fully Chinese/multi-language chat-panel-style configuration interface.

Feature	Description
No client mod required	All interactions are based on vanilla commands and clickable chat text; clients only need vanilla
Chat panels	`/tpatools`, `/home`, and `/warp` all open button-based panels with pagination support
Teleport delay check	Optional "stand still for N seconds before teleporting", with action bar countdown and progress bar; movement/damage cancels it
Multi-language	Built-in 6 languages (`zh_cn`, `zh_cn_cute`, `en_us`, `fr_fr`, `es_es`, `pt_br`), switchable at runtime
Dual storage backends	JSON files by default; MySQL can be enabled (10 tables, automatic table creation, reconnect on disconnect, automatic fallback on failure)
Fine-grained permissions	7 commands can individually be set to "requires OP"
Chat enhancements	`@player` or player-name mention notifications (title + sound), `&1`~`&9` to show hotbar items
Riding-chain teleport	Configurable "teleport together with mount/boat"

MySQL is still in the testing phase; I cannot guarantee it will run properly.

2. Installation

2.1 Server Installation

Install the corresponding loader (Fabric / NeoForge / Forge) and server core.
Put the built tpatools-*.jar into the server's mods/ directory.
Fabric users must also put fabric-api-*.jar there (version matching your MC version).
Start the server. If you see TPATools mod initialized successfully in the log, it succeeded.

This mod does not need to be installed on the client. Clients can join the server and see panels, buttons, and countdown prompts. Installing it on the client only makes it work in single-player; that is all.

2.2 What Is Generated on First Startup

Configuration and data directory: <server root>/config/tpatools/ (for the Forge 1.20.1 branch, the settings are in config/tpatools/tpatool.toml; data files remain in the same directory).
On first startup, config.json is written. Other data files (homes, warps, graves, etc.) are created only after data exists.

2.3 Recommended Initial Configuration

Scenario	Recommendation
Small survival server	Keep defaults: `maxHomes=2`, `maxWarpCount=3`, `rtpScope=100000` (reduce as needed)
Public/large server	Enable needop: `/tpatools configs needop warp true`, etc.; reduce `rtpScope` to `10000`~`50000` to lower search pressure
Need anti-AFK teleporting	`/tpatools configs teleportneedtime true`, `/tpatools configs teleportdelaytime 3`
Using MySQL	Change `databaseType` to `mysql`, fill in connection info, then restart the server

3. Command Reference

In the "Permission" column of the tables below:

Everyone = no OP required by default (but can be changed to require OP via needop);
OP2 = always requires permission level ≥ 2 (administrator).

3.1 TPA Series (Teleport Requests)

Command	Arguments	Permission	Description
`/tpa <player>`	Online player	Everyone	Request to teleport to the other player
`/tpahere <player>`	Online player	Everyone	Request the other player to teleport to you
`/tpaccept [player]`	Optional	Everyone	Accept a request; without arguments = accept the most recent one
`/tpadeny [player]`	Optional	Everyone	Deny a request
`/tpacancel [player]`	Optional	Everyone	Cancel a request you sent
`/tpatoggle`	—	Everyone	Toggle "receive TPA requests" (when off, others cannot request you)
`/tpalock <player>`	Online player	Everyone	Block TPA requests from one specific player
`/tpaunlock <player>`	Online player	Everyone	Unblock that player

Key rules:

Requests have a send cooldown (default 3 seconds, adjustable via tpacdtime) and a timeout (default 30 seconds, adjustable via tpawaittime).
If the other party turns off receiving (toggle), locks you, or either party dies/logs out, the request becomes invalid.
After acceptance, the teleport delay and teleport execution logic apply.

3.2 Homes

Command	Arguments	Permission	Description
`/home`	—	Everyone	Open the home panel
`/home set <name>`	String	Everyone	Set a home (count limited by `maxHomes`)
`/home tp <name>`	String	Everyone	Teleport home; also supports `playerName:homeName` to access public homes or homes shared with you
`/home list [page <page>]`	—	Everyone	List your homes
`/home remove <name>`	String	Everyone	Delete a home
`/home rename <oldName> <newName>`	String	Everyone	Rename a home
`/home share <homeName> <player>`	—	Everyone	Share with a specific player (only that player can access)
`/home unshare <homeName> [playerName]`	—	Everyone	Cancel sharing; without player name = cancel for everyone
`/home public <homeName>`	—	Everyone	Make a home public
`/home private <homeName>`	—	Everyone	Make a home private again
`/home otherhome <playerName:homeName>`	—	Everyone	Access another player's public home or a home shared with you
`/home otherlist [page <page>]`	—	Everyone	List "public homes + homes shared with me"
`/home sharelist <in\|out> [page <page>]`	—	Everyone	View "shared with me" / "shared by me"
`/home invite invite <homeName> <player>`	—	Everyone	Invite a player to your home (note the double `invite`)
`/home invite cancel [player]`	—	Everyone	Cancel an invitation you sent
`/home invite accept [player]`	—	Everyone	Accept an invitation (teleport to the other player's home)
`/home invite deny [player]`	—	Everyone	Deny an invitation

Key rules:

Home count is per player (maxHomes, default 2).
Invitations have a cooldown (homeInvitecdtime) and timeout (homeinviteovertime); on timeout both sides are notified.
Sharing is "per home + per player"; public is "per home". They are independent.
Accessing another player's home requires it to be public or shared with you; otherwise it is treated as "inaccessible".

3.3 Warps

Command	Arguments	Permission	Description
`/warp`	—	Everyone	Open the warp panel (paginated)
`/warp tp <name>`	String	Everyone	Teleport
`/warp list [page <page>]`	—	Everyone	List all warps
`/warp set <name>`	String	OP2	Set a warp
`/warp remove <name>`	String	OP2	Delete a warp

Note: maxWarpCount (default 3) is the server-wide total warp limit, not 3 per player. To allow more warps, use /tpatools configs setmaxwarpcount <amount>.

3.4 Other Teleport Commands

Command	Permission	Description
`/back`	Everyone	Return to the position before your last teleport (you can toggle back and forth repeatedly; persists after restart)
`/grave`	Everyone	Return to your last death point
`/rtp`	Everyone	Random teleport centered on (0,0), with safe-landing checks and cooldown (default 30 seconds)

3.5 Admin Commands

Command	Arguments (range)	Permission	Purpose
`/tpatools`	—	Everyone	Open the main settings panel (some buttons are only visible/usable to OPs)
`/tpatools about`	—	Everyone	About page (with links)
`/tpatools debug <true\|false>`	Boolean	OP2	Toggle debug logging
`/tpatools configs`	—	OP2	Open the configuration panel
`/tpatools configs setlanguage <language>`	`zh_cn`/`zh_cn_cute`/`en_us`/`fr_fr`/`es_es`/`pt_br`	OP2	Switch server-wide language (takes effect immediately)
`/tpatools configs setmaxhome <amount>`	≥1	OP2	Maximum homes per player
`/tpatools configs setmaxwarpcount <amount>`	≥0	OP2	Server-wide total warp limit
`/tpatools configs tpacdtime <seconds>`	≥0	OP2	TPA request cooldown
`/tpatools configs tpawaittime <seconds>`	≥0	OP2	TPA request timeout
`/tpatools configs homeinvitecdtime <seconds>`	≥0	OP2	Home invitation cooldown
`/tpatools configs homeinviteovertime <seconds>`	≥1	OP2	Home invitation timeout
`/tpatools configs allowteleportrideentity <true\|false>`	Boolean	OP2	Whether to teleport mounts together
`/tpatools configs safeteleport <true\|false>`	Boolean	OP2	Whether to automatically find a safe landing point
`/tpatools configs teleportneedtime <true\|false>`	Boolean	OP2	Whether to enable teleport delay checking
`/tpatools configs teleportdelaytime <seconds>`	≥1	OP2	Teleport delay in seconds
`/tpatools configs rtpcdtime <seconds>`	≥0	OP2	RTP cooldown
`/tpatools configs rtpscope <blocks>`	≥0	OP2	RTP random radius
`/tpatools configs needop <command> <true\|false>`	command = `tpa`/`home`/`grave`/`back`/`warp`/`rtp`	OP2	Command-level OP toggle

When the above configs subcommands are used without arguments, they open the corresponding settings menu (you can change values by clicking buttons).

4. Chat Panels and Buttons

/tpatools, /tpatools configs, /home, /home list, /home otherlist, /home sharelist, /warp, /warp list, and the various settings entries all output clickable panels in chat.
Two kinds of buttons:
- Click to execute (gray/light green, etc.): directly runs the corresponding command;
- Click to complete (cyan): fills the command into the input box so you can continue adding arguments.
Pagination: 5 entries per page, with "Previous page / Next page" buttons at the bottom.
Hovering shows the button description.
All button text comes from language files and can be changed in assets/tpatools/lang/<language>.json.

5. Configuration

5.1 Configuration File Locations

Loader	Settings File	Data Files
Fabric / NeoForge	`config/tpatools/config.json`	`config/tpatools/*.json`
Forge 1.20.1	`config/tpatools/tpatool.toml` (ForgeConfigSpec)	`config/tpatools/*.json`

Changing settings in-game with /tpatools configs ... automatically writes to disk and takes effect immediately; directly editing files requires a restart (exception: the language option, using setlanguage, reloads immediately).

5.2 Field Table (`config.json` for Fabric / NeoForge)

Field	Default	Unit	Purpose	Changeable in-game
`defaultLanguage`	`zh_cn`	—	Server-wide language	✅ `setlanguage`
`maxHomes`	`2`	per player	Maximum homes per player	✅ `setmaxhome`
`cooldownTime`	`3000`	milliseconds	TPA request cooldown	✅ `tpacdtime`
`waitSeconds`	`30`	seconds	TPA request timeout	✅ `tpawaittime`
`homeInviteCooldown`	`0`	seconds	Home invitation cooldown	✅ `homeinvitecdtime`
`homeInviteTimeout`	`30`	seconds	Home invitation timeout	✅ `homeinviteovertime`
`maxWarpCount`	`3`	server-wide	Total warp limit	✅ `setmaxwarpcount`
`safeTeleport`	`true`	—	Automatically find a safe point when the landing point is blocked	✅ `safeteleport`
`allowTeleportRideEntity`	`false`	—	Whether to teleport mounts together	✅ `allowteleportrideentity`
`teleportNeedTime`	`false`	—	Whether to enable teleport delay checking	✅ `teleportneedtime`
`teleportDelayTime`	`3`	seconds	Teleport delay in seconds	✅ `teleportdelaytime`
`rtpScope`	`100000`	blocks	RTP random radius (centered on 0,0)	✅ `rtpscope`
`rtpCooldownTime`	`30`	seconds	RTP cooldown	✅ `rtpcdtime`
`rtpMaxAttempts`	`50`	attempts	Maximum RTP attempts	❌ Edit file manually
`rtpMinY` / `rtpMaxY`	`-64` / `320`	Y	RTP search height range	❌ Edit file manually
`databaseType`	`json`	—	`json` or `mysql`	❌ Requires restart
`mysqlHost`	`localhost`	—	MySQL host	❌ Requires restart
`mysqlPort`	`3306`	—	MySQL port	❌ Requires restart
`mysqlDatabase`	`tpatools`	—	Database name	❌ Requires restart
`mysqlUsername`	`root`	—	Username	❌ Requires restart
`mysqlPassword`	empty	—	Password	❌ Requires restart
`debugMode`	`false`	—	Debug logs	✅ `debug`

5.3 Languages

Built-in 6 languages: zh_cn (Simplified Chinese), zh_cn_cute (Simplified Chinese, cute style), en_us, fr_fr, es_es, pt_br; each has 321 keys, with key names corresponding one-to-one to code.
The whole server uses only one language (not per-player).
To change text: directly edit assets/tpatools/lang/<language>.json (restart after editing; or override with a resource pack).
To add a language: copy en_us.json, rename it (e.g. de_de.json), translate it, then switch with /tpatools configs setlanguage de_de (the code loads by file name).
Text can contain %s (string) or %d (integer) placeholders; if placeholders do not match the code's arguments, it will not crash—it falls back to the original text and logs a WARN.

6. Data and Persistence

6.1 JSON File List (`config/tpatools/`)

File	Contents	When Written
`config.json`	All settings	Startup & every change
`tpatool.json`	Command needop toggles	Startup & when needop changes
`tpatool_toggles.json`	Each player's TPA receive toggle	On change, server shutdown
`tpatool_locks.json`	Each player's TPA block list	On change, server shutdown
`tpatool_homes.json`	All homes + public homes	After any home operation
`tpatool_warps.json`	All warps	After any warp operation
`tpatool_graves.json`	Each player's last death point	On death, server shutdown
`tpatool_back.json`	Each player's `/back` return point	Before each teleport
`tpatool_rtp_cooldowns.json`	RTP cooldown timestamps	After using RTP

Do not edit these files manually (they use Gson serialization; mistakes cause the file to be ignored and an ERROR to be logged). To clear data, delete the file or the corresponding entry.

6.2 MySQL Tables (auto-created when `databaseType=mysql`)

Note: The MySQL portion is untested. If you find any bugs, please submit feedback at issue.

Table	Main Fields	Purpose
`command_permissions`	`command`(PK), `need_op`	needop toggles
`toggle_states`	`player_uuid`(PK), `enabled`	TPA toggle
`locked_players`	`player_uuid`, `locked_uuid`	Block list
`player_homes`	`player_uuid`, `home_name`, `dimension`, `x/y/z`, `x_rot/y_rot`	Homes
`home_shares`	`player_uuid`, `home_name`, `shared_with`	Home sharing
`public_homes`	`player_uuid`, `player_name`, `home_name`	Public homes
`player_graves`	`player_uuid`(PK), `dimension`, `x/y/z`, rotation	Death points
`warp_points`	`name`(PK), `dimension`, `x/y/z`, rotation	Warps
`player_back`	`player_uuid`(PK), `dimension`, `x/y/z`, rotation	`/back`
`rtp_cooldowns`	`player_uuid`(PK), `last_used`	RTP cooldowns

Dimensions are uniformly stored as namespace:path strings (e.g. minecraft:overworld).

6.3 Database Switching and Failure Fallback

Change databaseType to mysql, fill in connection info, then restart the server; tables are created automatically.
If connection fails (network/account/driver missing): an ERROR log is printed and the system automatically falls back to the JSON backend (all reads/writes use JSON for the rest of this run). The server will not crash.
If MySQL disconnects during runtime: the next access automatically reconnects and recreates tables; if reconnection also fails, it falls back to JSON.
Note: Fallback is one-way (it will not automatically switch back to MySQL during this run). Restart after fixing the database.

6.4 Backup / Migration / Reset

# Backup (after shutdown)
cp -r config/tpatools ~/backup/tpatools-$(date +%F)
# MySQL backup
mysqldump -u root -p tpatools > tpatools-$(date +%F).sql

# Reset all player data (dangerous)
rm -rf config/tpatools/tpatool_*.json

Fabric ↔ NeoForge migration: JSON file names, fields, and MySQL table structures are completely identical; directly copy config/tpatools/ or export/import the database.
Forge 1.20.1: Data files are the same as Fabric/NeoForge and can be copied between them; however, the settings are in tpatool.toml, so refer to 5.2 for migration.

6.5 Historical Dirty Data Repair (Optional)

Older versions (1.2.0 and earlier) may have stored invalid dimensions such as minecraft:minecraft:overworld in MySQL. Current code catches the exception and logs an ERROR, but that record remains unusable. If needed, run the following once:

UPDATE player_homes  SET dimension = SUBSTRING(dimension, LENGTH('minecraft:') + 1) WHERE dimension LIKE 'minecraft:minecraft:%';
UPDATE player_graves SET dimension = SUBSTRING(dimension, LENGTH('minecraft:') + 1) WHERE dimension LIKE 'minecraft:minecraft:%';
UPDATE warp_points   SET dimension = SUBSTRING(dimension, LENGTH('minecraft:') + 1) WHERE dimension LIKE 'minecraft:minecraft:%';
UPDATE player_back   SET dimension = SUBSTRING(dimension, LENGTH('minecraft:') + 1) WHERE dimension LIKE 'minecraft:minecraft:%';

7. Teleport Delay Mechanism

How to enable: /tpatools configs teleportneedtime true (teleportDelayTime defaults to 3 seconds).

Item	Behavior
Applicable commands	`/back`, `/grave`, `/home tp`, `/home otherhome`, `/home invite accept`, `/warp tp`, `/rtp`, `/tpaccept`
Countdown display	action bar (above hotbar): `[remaining seconds] ██░░░░░░░░ prompt text`
Cancellation conditions	Moving more than 0.1 blocks, taking damage, dying, logging out
Sound	Beat prompt every second; success sound on completion
Creative mode	Skips the delay and teleports immediately
Multiple simultaneous requests	If a teleport is already pending, new ones are rejected with a message

Design recommendation: teleportDelayTime of 3~5 seconds is suitable; PVP servers can combine this with disabling /tpa (needop) to prevent escape during combat.

8. Teleport Execution

8.1 Safe Landing Point (`safeTeleport`, enabled by default)

If the target point is blocked (feet/head positions are full blocks, the block below is not standable, or the player would land on lava/fire/cactus/sweet berry bush, etc.), it searches for the nearest standable point within 11×11×5.
Criteria: a full collision block below, air in both feet and head positions, no liquid, and not on a dangerous block.

8.2 Riding Chain (`allowTeleportRideEntity`, disabled by default)

When enabled: the entire riding chain (horse/boat + passengers) is teleported together, preserving relative positions and orientations; the bottom-most vehicle is teleported first, then passengers are restored in order.
When disabled: only the player is teleported (the mount stays where it is).
Also applies across dimensions (implementation details differ per platform, but the external behavior is consistent).

8.3 Recording After Teleport

All teleport commands record the current position before executing, for /back to use (persisted; survives restart).

9. Chat Features

9.1 `@PlayerName` and Player-Name-Mention Notifications

When a complete word form of an online player's name appears in chat (case-insensitive, may have an @ prefix):
- The name is highlighted in the message (cyan);
- The mentioned player sees a center-screen title prompt + notification sound;
- The same player is notified only once per message; mentioning yourself does not trigger it.
"Complete word" rule: the name must be surrounded by spaces/punctuation or other separators, so Ann will not match Anna, but Steve's and @Steve will match.
Implementation differs by platform: Fabric uses "cancel the original message + rebroadcast"; NeoForge/Forge directly rewrites the message component via the chat event (console logs are unaffected).

9.2 `&1` to `&9` Item Display

Typing &1~~&9 in chat replaces it with the item name in hotbar slot 1~~9 (wrapped in golden brackets, preserving the original item color).
If that slot is empty, the original text &n is kept and not replaced.
Example: look at this &1 → look at this [Diamond Sword]

10. FAQ

Q1: The command says "You do not have permission" / buttons do not respond?
A: /warp set and /tpatools configs require OP level ≥ 2; if needop is enabled, the corresponding commands also require OP.

Q2: /home set says the limit is reached? A: maxHomes defaults to 2; adjust with /tpatools configs setmaxhome 5.

Q3: /warp set says the warp limit is reached? A: maxWarpCount is the server-wide total limit (default 3); adjust with /tpatools configs setmaxwarpcount 50.

Q4: Language changed but did not take effect? A: Using /tpatools configs setlanguage <language> is immediate; manually changing defaultLanguage in config.json requires a restart. If it still shows English, the key is missing from the language file (it falls back to the built-in English in code); check assets/tpatools/lang/<language>.json.

Q5: /back says there is no record? A: /back only has a record after you have teleported (there is none before the first teleport). Records are persisted and survive restarts; deleting tpatool_back.json clears them.

Q6: /grave says there is no death point? A: A record exists only after you have died; switching saves or deleting tpatool_graves.json clears it.

Q7: Teleport delay never appears? A: Confirm teleportneedtime=true and that the player is not in Creative mode; only the 8 commands listed above use the delay logic.

Q8: /rtp lags / the server stutters? A: RTP needs to find a safe point in new chunks; the larger rtpScope, the slower it is. It is recommended to set rtpscope to 10000~50000 and manually reduce rtpMaxAttempts (default 50).

Q9: MySQL reports connection closed or data is not written? A: Version 1.2.1 fixed the "close connection after one use" bug. If it still occurs, check database account permissions and timeout settings; the code automatically falls back to JSON on failure and logs an ERROR.

Q10: What happens if the server has no MySQL driver? A: An ERROR is logged at startup (MySQL driver not found ... fallback to json), and JSON is used for this run. It will not crash.

Q11: Can it be installed only on the client? A: No. This is a server-side mod; installing it on the client has no effect (and it is not needed).

Q12: How do I completely uninstall it? A: Delete the jar from mods/, then optionally delete config/tpatools/ (data) and the tpatools database in MySQL.

Q13: Will multiple players changing homes/warps at the same time conflict? A: All data operations execute on the server main thread, so they are naturally serialized; however, in MySQL mode every save rewrites the whole table. With many players, JSON is recommended, or upgrade to row-based updates.

11. Operations Recommendations

Item	Recommendation
Debugging	When issues occur, use `/tpatools debug true`; logs will have the `[DEBUG INFO]` prefix (including command execution, DB reads/writes, chat handling, etc.)
Log level	Failures that truly affect players (DB connection, missing translations, teleport exceptions) use ERROR/WARN and are not affected by the debug toggle
Performance	Do not set RTP's `rtpScope`/`rtpMaxAttempts` too high; `ModUtils.tick()` only does "timeout scanning + delay checking" each tick, with very low overhead
Data volume	Homes/warps/graves are fully rewritten (JSON or MySQL full-table DELETE+INSERT). With thousands of players, MySQL is recommended; monitor the growth of the `home` table

12. License

Code license: CC-BY-NC-4.0 (see each project's fabric.mod.json / neoforge.mods.toml).
Built-in icons and language files are released together with the code.
Issues / PRs are welcome; when redistributing, please retain the author information (kicobicn).

13. Author's Note

(Updated on 2026/11/3 12:00)
Actually, this is my first time writing a long-form Wiki like this, so if you see this and are willing to optimize the format or content of this Wiki, feel free to edit or change it yourself.
I will adopt all issues; your valuable suggestions are the source of my motivation.

14. Other

Task List (Updated on 2026/11/3 12:00)