FAQ

Frequently Asked Questions (FAQ) & Troubleshooting

This page provides answers and troubleshooting steps for common questions, configuration issues, and error resolutions when running UltimateDonutSMP.

---

1. PlaceholderAPI & Placeholders Troubleshooting

Question: Why are my %economy_*% placeholders showing as unparsed raw text (e.g. %economy_money%) or blank in scoreboards, chat, tablists, or DeluxeMenus?

Root Causes & Solutions:

1. PlaceholderAPI is not installed:

   • Fix: UltimateDonutSMP requires the PlaceholderAPI plugin to parse %economy_*% tags. Download and place PlaceholderAPI.jar into your server's plugins/ folder and restart the server.

2. UltimateDonutSMP started before PlaceholderAPI:

   • Fix: Place PlaceholderAPI.jar in the plugins/ directory and ensure soft dependencies load correctly. Run /uds reload or restart the server to trigger the expansion registration.

3. Typo in Placeholder Identifier:

   • Fix: UltimateDonutSMP uses %economy_*% as its identifier prefix.
     • Correct: %economy_money%, %economy_shards%, %economy_team%
     • Incorrect: %ultimatedonutsmp_money%, %uds_money%

4. Player is Offline or Context Missing:

   • Fix: Placeholders like %economy_ping%, %economy_shard_cuboid_status%, or %economy_shard_cuboid_display% require an active online player session. When called from console or headless holograms without player context, they return default fallback values (0, outside, -).

5. Display plugin does not support PlaceholderAPI:

   • Fix: Verify that your scoreboard, tablist, chat formatting, or hologram plugin has PlaceholderAPI integration enabled in its configuration.

---

2. Vault & Economy Integration

Question: Why are third-party plugins (like ChestShop, CMI, or ShopGUIPlus) not detecting player money balances?

Solutions:

• Install Vault: UltimateDonutSMP registers itself as a Vault Economy provider on startup. Ensure Vault.jar is installed in your plugins/ folder.
• Check Startup Logs: Look for [UltimateDonutSMP] Vault economy provider registered successfully in server startup logs.
• Remove Conflicting Economy Plugins: Remove plugins like EssentialsX Economy or Reserve that might override the Vault economy registration.

---

3. Database & Storage Issues

Question: Why is player money, shards, or home data resetting after a server restart?

Solutions:

• SQLite File Permissions: If using SQLite (default), ensure the server process has read/write permissions for plugins/UltimateDonutSmp/database.db.
• MySQL / MongoDB Credentials: If using MySQL or MongoDB (database.yml), check that your database host, port, username, and password are correct and that the database server allows remote connections.
• Check Console Logs: Check for SQL connection timeouts or pool exhaustion errors on startup.

---

4. Cuboids & Portals Troubleshooting

Question: Why is /portal not teleporting players or /cuboid bind not giving AFK/Shard rewards?

Solutions:

• Verify Region Bounds: Use /cuboid list to ensure the target cuboid region exists and spans the correct coordinates.
• Check Binding Status: For AFK or Shard zones, run:

  /cuboid bind <cuboid_name> spawn true
  /cuboid bind <cuboid_name> shard true

• Set Warp / Spawn Locations: If a portal has destination type WARP, ensure the specified warp name exists (/warp).

---

5. Spawners & Silk Touch

Question: Why do custom spawners break into default pig spawners or fail to drop when mined?

Solutions:

• Silk Touch Requirement: By default, breaking stacked spawners requires a pickaxe enchanted with Silk Touch unless the player has administrator permission (ultimatedonutsmp.admin.spawner or ultimatedonutsmp.spawner.bypass).
• Check spawners.yml: Ensure SILK-TOUCH-REQUIRED: true/false is configured according to your server rules.

---

6. Staff Mode & Vanish

Question: Why can players still see vanished staff members in tablist or game?

Solutions:

• Install ProtocolLib: UltimateDonutSMP uses ProtocolLib for packet-level vanish suppression, chest animation silencing, and equipment hiding. Install ProtocolLib.jar for full vanish protection.
• Check Staff Permissions: Ensure normal players do not have see-vanish permissions (ultimatedonutsmp.admin.vanish.see).

---

7. Duels & Fast Crystals

Question: Why are End Crystals placing at normal vanilla speed during duels?

Solutions:

• Check duels.yml and ensure FAST-CRYSTAL.ENABLED: true and PLACEMENT-DELAY-TICKS: 0.
• Verify that ProtocolLib is active to handle zero-tick crystal packet processing.

---

8. Player Ranks, Plus (+), and Media Privileges

Question: How do I give Plus (+), Media, Streamer, or Donut+ ranks and privileges to a player?

1. Assigning Rank Groups via LuckPerms

To assign a permanent or temporary rank group to a player using LuckPerms:

• Permanent Rank:

  /lp user <player> parent add <group_name>

  Example: /lp user Steve parent add plus or /lp user Steve parent add media
• Temporary Rank (e.g. 30 Days):

  /lp user <player> parent addtemp <group_name> 30d

2. Configuring Prefix Tags (Chat & Tablist)

Set custom rank prefixes for the + or MEDIA rank groups in LuckPerms:

/lp group plus meta setprefix 100 "&d[DONUT+] "
/lp group media meta setprefix 100 "&c[MEDIA] "

3. Granting UltimateDonutSMP Rank Perks

Attach specific UltimateDonutSMP permission nodes to your plus or media groups:

• Expanded Home Limits: ultimatedonutsmp.command.sethome.multiple.<amount>
• Ender Chest Row Expansion: ultimatedonutsmp.enderchest.rows.<1-6>
• RTP Cooldown Bypass: ultimatedonutsmp.command.rtp.bypasscooldown
• Key Giveaways & Rewards:
  • Give Crate Keys: /crate key <player> <crate_name> <amount>
  • KeyAll Broadcast: /crate keyall <crate_name> <amount>
  • Server Multiplier Booster: /booster give <player> <money|shards> <multiplier> <seconds>