-
Notifications
You must be signed in to change notification settings - Fork 0
Advanced
Advanced usage of mod functions
Numbers are normally random and permanent: a snail gets one the first time it's activated, and the mod's registry keeps track of which numbers are taken so the auto-generator never hands out a duplicate. Server owners have two ways to override that: the /snailnumber command, and setting a number by hand with NBT.
The built-in, safe way to inspect and manage the number pool — and to see who has been calling whom. Every subcommand works from the server console as well as in chat. Numbers are always four digits, 1000–9999.
| Permission | Commands |
|---|---|
| Level 2 | find, help, history, list, logs, lookup, stats |
| Level 3 | remove |
| Level 4 | remove all (and its confirm / cancel) |
To see a snail's current NBT before changing it, hover over the item and press F3+H for advanced tooltips, or use F3+I to copy its full data to your clipboard. For a placed block, /data get block <x> <y> <z> prints its stored data to chat.
Only the color tags above are meant to be edited by hand. The call number shown in a snail's tooltip is generated and tracked by the mod's own registry — editing it directly through NBT can leave the tooltip out of sync with what the snail is actually registered as, so it's best left alone.
Advanced usage of mod functionsNumbers are normally random and permanent: a snail gets one the first time it's activated, and the mod's registry keeps track of which numbers are taken so the auto-generator never hands out a duplicate. Server owners have two ways to override that: the /snailnumber command, and setting a number by hand with NBT.
The built-in, safe way to inspect and manage the number pool — and to see who has been calling whom. Every subcommand works from the server console as well as in chat. Numbers are always four digits, 1000–9999.
| Permission | Commands |
|---|---|
| Level 2 |
find, help, history, list, logs, lookup, stats
|
| Level 3 | remove <number> |
| Level 4 |
remove all (and its confirm / cancel) |
The server console counts as level 4.
| Command | What it does |
|---|---|
/snailnumber find <number> |
Shows where a snail is right now, with a ready-to-use teleport command |
/snailnumber history <number> [count] |
Every call to or from one number |
/snailnumber list |
Every assigned number with its full UUID |
/snailnumber logs [count] |
Every call ever placed on the server |
/snailnumber lookup <number> |
UUID, current status, who used the snail last, and its usage history |
/snailnumber remove <number> |
Resets one number — the snail registers a new one on its next use |
/snailnumber remove all |
Resets every number, after a confirmation prompt |
/snailnumber stats |
How many numbers are assigned vs. still available |
/snailnumber help |
Prints this list in-game |
/snailnumber find <number> shows the snail's UUID and where it is:
- Placed snail — its dimension and coordinates.
- Carried snail — the name of the player holding it, and where they are.
-
A teleport line —
/execute in <dimension> run tp @s <x> <y> <z>. In chat you can click it to run it; in the console it prints as plain text you can copy.
find can only see placed snails in loaded chunks and snails in the inventories of players who are online. A snail in a chest, in an unloaded chunk, or on an offline player is reported as not loaded, along with its last known location taken from the call log (with the time it was seen). A snail that has never been part of a call has no recorded location.
─── ☎ Snail #4821 ───
ID 73d5a0c4-1b2e-4c6f-9a3d-5e8f7b2c1d40
⌂ placed ⌖ minecraft:overworld 120 64 -300
➤ /execute in minecraft:overworld run tp @s 120 64 -300
/snailnumber lookup <number> is the one-stop summary for a single snail:
- its UUID and its current status (placed, held by a player, or not loaded)
- who used it last, with their UUID, the time, and what they did
- how many calls it has made and received
- every player who has used it, with how many times and when they first and last did
- its five most recent calls
A "use" means placing a call from the snail, or answering a call it received.
/snailnumber history <number> [count] lists every call to or from one number, oldest first, so the newest call is at the bottom. /snailnumber logs [count] does the same for every call on the server, written number to number. Add a count to see only the newest calls.
─── ☎ History #4821 ─── 4 calls
→ 3 out ← 1 in ✔ 2 ✘ 2 (missed 1, busy 1)
2026-09-20 14:32:05 → #1234 ✔ 3m 12s Steve → Alex
2026-09-20 15:10:44 ← #7777 ✘ missed Bob → Steve
2026-09-20 16:02:10 → #7777 ✘ busy Steve → Bob
2026-09-20 17:45:31 → #1234 ✔ 45s Steve → Alex
→ is a call the number placed, ← is one it received, ✔ is a connected call (with its talk time), ✘ is a call that never connected, and ● is a call still in progress. Each line ends with the players involved; a placed snail nobody has answered yet is shown as ⌂ placed.
| Result | Meaning |
|---|---|
| ✔ answered | The snails connected. If the call ended any way other than a normal hang-up, the reason follows in brackets: inactivity, player left, snail removed, number removed, or server stop. |
| ✘ missed | It rang until the ring timeout and nobody answered |
| ✘ rejected | The receiving side declined it |
| ✘ cancelled | The caller hung up, or left the game, before it was answered |
| ✘ busy | The target was already in a call |
| ✘ unreachable | The number exists, but nobody could be rung — the snail wasn't loaded, or wasn't being carried by an online player |
| ✘ no such number | The dialed number isn't assigned to any snail |
| ✘ failed | It ended before connecting for another reason, such as the snail being broken while it rang |
| ● ringing / in call | Still in progress |
Numbers can be handed to a different snail after a removal. If the log shows that more than one snail has held a number, history says so and tags each line with [id] — the first 8 characters of that snail's UUID — so you can tell them apart. lookup only counts calls belonging to the snail that holds the number now.
/snailnumber list prints every assigned number in order with its full UUID, all at once — there is no paging. Minecraft's chat only keeps roughly the last 100 lines, so on a busy server run list (and a full logs) from the console, or use logs <count>.
/snailnumber stats shows how many numbers are assigned, how many are still free, and a usage bar, and warns you once the pool is nearly full.
/snailnumber remove <number> (level 3) frees a number and resets the snail that held it. This is how you make an already-taken (and therefore normally excluded) number available again, and it's the tool for a snail that was lost, stolen, or duplicated. When you run it:
- the number goes back into the pool, and any call on that snail ends
- a placed snail in a loaded chunk is reset immediately
- a snail in an online player's inventory loses its number immediately
- a snail anywhere else — a chest, an unloaded chunk, an offline player — is reset the next time it is loaded or picked up and used, because its old ID is permanently revoked and can never register the old number again
- the next time anyone right-clicks the snail, it registers a brand-new number. Its colors are kept.
Removed numbers are gone for good and may later be given to a different snail. The call history for the number stays in the log.
/snailnumber remove all (level 4) does the same thing to every snail on the server at once. remove * works the same way. It never runs immediately — it prints a prompt showing how many numbers are about to go:
⚠ Remove ALL 25 snail numbers?
• every snail, placed or held, registers again on its next use
• active calls end · this cannot be undone
✔ /snailnumber remove confirm (30s)
✘ /snailnumber remove cancel
Type /snailnumber remove confirm within 30 seconds to go ahead, or /snailnumber remove cancel to back out. Confirmations belong to whoever asked: the console and each player confirm their own prompt, and nobody can confirm someone else's. Nothing is clickable, so it works the same in chat and in the console.
all, *, confirm and cancel deliberately don't appear in tab-completion — after remove it only offers <number> — so they can't be triggered by accident. They still need level 4.
Everything above runs from the server console with no player needed, including the full remove all confirmation. The only thing a console can't do is run the teleport command that find prints.
Players see the symbol layout shown in the examples. The console shows the same information, using symbols only if its output can display them, and plain text otherwise (for example Placed at minecraft:overworld 120 64 -300 instead of ⌂ placed ⌖ …). Nothing is bold, and nothing relies on hover text. If your console picks the wrong style, add -Dtranspondersnails.console=unicode or -Dtranspondersnails.console=ascii to the server's JVM arguments to force one.
-
Where is snail #4821? —
/snailnumber find 4821 -
A player says their snail stopped working —
/snailnumber history <number>shows whether calls to it are being missed, rejected, or never reaching it, and/snailnumber lookup <number>shows who has been using it. -
Who called whom last night? —
/snailnumber logs -
Reset a snail that was lost or stolen —
/snailnumber remove <number> -
Start over with fresh numbers for everyone —
/snailnumber remove all, then/snailnumber remove confirm
The mod keeps a permanent record of every call, and the history, logs, lookup and find commands read from it. For each call it records:
- when it was placed, when it connected (if it did), and when it ended
- both snail numbers, and the players on each end when they're known
- where each snail was — the block's position for a placed snail, or the holding player's position for a carried one
- how it ended (see the table above) and how long the talk time was
Good to know:
- It is never trimmed. Every call stays in the log for the life of the world.
-
It's a plain text file at
<world>/data/transponder_snails_call_log.jsonl, one line per finished call, so you can read, search, or back it up with normal tools. Calls that are still in progress show up in the commands right away, but are written to the file only when they end. Stop the server before moving or editing the file. - It contains player names, UUIDs, and coordinates. Treat it accordingly, and consider telling your players it exists.
- History starts when the feature was added. Calls made before that were never recorded.
- Not everything is logged. Wiretapping with a Black Transponder Snail isn't recorded, and neither are attempts that are blocked before dialing, such as calling your own snail or dialing while already in a call.
- A line in the file that has been damaged or hand-edited badly is skipped on load; the rest of the log is unaffected.
To hand someone a snail with a chosen number — including one that's currently excluded from random assignment because it's already taken — combine the command above with an NBT /give:
-
If the number you want is already assigned to another snail, free it first. Note that this resets that snail — it will register a new number the next time it's used (see [Removing Numbers]):
/snailnumber remove 1234 -
Give the new snail that number directly, along with a made-up ID so the game treats it as already-activated instead of generating a fresh number the first time it's used:
/give @s transpondersnails:transponder_snail{cached_snail_number:1234,snail_uuid:[I;0,0,0,1234]}Any unused ID works for the
snail_uuidvalue — it just needs to be one no real snail already has.
This guarantees what's shown on that specific item right away. Since incoming calls are routed by checking the registry for who owns a number, run /snailnumber lookup 1234 before you hand the snail out: it should report the number as not assigned, so you know nothing else has a claim on it and you don't end up with two snails quietly sharing the same number.
Beyond right-click dyeing, a snail's colors are also just NBT data, so you can set them directly with commands — handy for handing out a snail with a specific look, or fixing one that ended up wrong.
Target the entity and merge in BodyColor (HEX Color value) and/or ShellColor (a dye ID, 0–15):
/data merge entity @e[type=transpondersnails:den_den_mushi,limit=1,sort=nearest] {BodyColor:16750848,ShellColor:5}
Give yourself one pre-colored using /give with the same tags:
/give @s transpondersnails:black_transponder_snail{ShellColor:5}
The Portable Black Transponder Snail also has a separate BandColor (also a dye ID, 0–15) for its wrist strap, independent of the shell.
Once a Transponder Snail is placed, target the block position instead:
/data merge block ~ ~ ~ {shell_color:5}
Note the lowercase shell_color here — placed blocks store this tag a little differently from items and creatures. If a command doesn't seem to take effect, that's the first thing to check.
| ID | Color | ID | Color |
|---|---|---|---|
| 0 | White | 8 | Light Gray |
| 1 | Orange | 9 | Cyan |
| 2 | Magenta | 10 | Purple |
| 3 | Light Blue | 11 | Blue |
| 4 | Yellow | 12 | Brown |
| 5 | Lime | 13 | Green |
| 6 | Pink | 14 | Red |
| 7 | Gray | 15 | Black |
To see a snail's current NBT before changing it, hover over the item and press F3+H for advanced tooltips, or use F3+I to copy its full data to your clipboard. For a placed block, /data get block <x> <y> <z> prints its stored data to chat.
Only the color tags above are meant to be edited by hand. The call number shown in a snail's tooltip is generated and tracked by the mod's own registry — editing it directly through NBT can leave the tooltip out of sync with what the snail is actually registered as, so it's best left alone.