SMP: Utilities

SMP: Utilities - Official Wiki

SMP Utilities is a multi-loader administration, customization, and SMP mechanics mod for Minecraft 1.20.1 & 1.21.1 (Forge, NeoForge, and Fabric).

It equips server owners and SMP creators with a declarative TOML restriction engine, a Canon Hearts (permadeath/revive) system, custom admin tools and blocks, typewriter action-bar objectives, item renaming & lore customization, and custom potions & effects - with optional integrations for JEI, Curios, Trinkets, Accessories, Waystones, and AppleSkin.

---

Table of Contents

1. Supported Loaders & Optional Integrations
2. Admin Items & Blocks
3. Commands (/smpu)
   • Item Customization (/smpu rename & /smpu lore)
   • Creative Lectern (/smpu lectern)
   • Objectives (/smpu objective)
   • Canon Hearts (/smpu canon)
   • Hot Reload (/smpu reload)
   • Colors & Formats
4. Restriction System (restrictions.toml)
   • All 14 Restriction Categories
   • Wildcards, Placeholders & Priority Rules
5. Canon Hearts System (canon_hearts.toml)
6. Potions & Effects
7. Waystone Suppression (waystones.toml)
8. Utilities Configuration (utilities.toml)
9. FAQ

---

Supported Loaders & Optional Integrations

SMP Utilities works completely standalone (only Minecraft, the mod loader, and Fabric API on Fabric are required). Every complementary mod below is 100% optional and accepts any compatible version for your Minecraft + loader version ([0,) on Forge/NeoForge, "*" on Fabric):

Integration	Loaders	What It Enables When Installed
JEI (Just Enough Items)	Forge, NeoForge, Fabric	Independent hidden_jei_items hiding (separate from Creative tabs), hiding blocked crafting recipes (blocked_crafting_items), Brewing recipe display for Waystone Suppression, and Creative Lectern dye variants.
Curios API	Forge, NeoForge	Blocks & auto-ejects restricted items in Curios slots (blocked_curios_items / aliases).
Trinkets	Fabric	Blocks & auto-ejects restricted items in Trinkets slots with hover-spam prevention and Shift+Click item-loss protection.
Accessories	Fabric	Native CanEquip / AccessoryChange hooks + Shift+Click protection for Accessories slots (also works with tclayer).
Waystones / Balm	Fabric (API hook) + Forge/NeoForge (item/block suppression)	Cancels Waystone teleportation events (WaystoneTeleportEvent.Pre) and blocks teleport items/blocks while affected by Waystone Suppression.
AppleSkin	Fabric (HUD mixin compatibility)	Automatically offsets hunger/saturation/armor overlays when the Canon Hearts HUD row is visible.

---

Admin Items & Blocks

Absurd Damage Sword

A lethal admin sword with 1,000,000 attack damage, infinite durability, fire resistance, and a custom strike sound. Instantly kills virtually any mob or player on hit.

---

Ban Sword

An admin moderation sword with infinite durability, fire resistance, and a custom strike sound:

• Attacking a player without Mending → disconnects (kicks) the player.
• Attacking a player with Mending enchantment → permanently bans the player (Banned by Ban Sword, configurable in utilities.toml).

---

Chapolin Colorado's Sledgehammer

A special Epic weapon with zero lethal damage, infinite durability, fire resistance, a custom hit sound, and extreme knockback (configurable multiplier, default 20.0). Launches any entity far away without killing them. Pairs well with the Imbalance potion!

---

Mind Wrench

A precision admin tool with zero damage, infinite durability, and fire resistance (also breaks blocks instantly without dropping items, like in Creative):

• Left-click (attack) on a mob → applies configurable Slowness 255 (default infinite duration -1, hidden particles & icon), effectively freezing movement without disabling AI.
• Right-click (interact) on a mob → toggles the mob's AI (NoAI):
  • AI enabled → disables AI and tags the mob with MindWrenched.
  • AI disabled → restores AI and removes the tag.

Ideal for posing NPCs/mobs for events, decoration, builds, or screenshots.

---

Little Poop

A throwable projectile item that deals 0 damage on impact, spawns item break particles, and plays a custom splat sound.

---

Realm Coin

A collectible/currency item designed for SMP server economies, quests, shops, and special events.

---

Rename Ticket & Lore Ticket

Consumable customization tickets used by /smpu rename and /smpu lore while holding the target item in your main hand:

• Rename Ticket (smp_utilities:rename_ticket, Uncommon): Craftable by default using 4 Gold Nuggets (corners), 4 Gold Ingots (top/bottom/left/right), and 1 Name Tag (center).
• Lore Ticket (smp_utilities:lore_ticket, Epic): Admin/event ticket for adding custom item descriptions.

---

Security Block

An unbreakable, Bedrock-strength opaque structural block intended for secure admin rooms, borders, and event arenas.

---

Creative Lectern

An unbreakable admin lectern (only breakable by Creative players with OP permission level 2):

• Books: Accepts Book and Quill (minecraft:writable_book) and Written Book (minecraft:written_book) - players can read the placed book cleanly via a dedicated GUI without breaking the lectern.
• Full RGB Dyeing: Can be dyed using:
  • Crafting Table recipe (Creative Lectern + DyeItem(s))
  • Right-clicking the placed block with any Minecraft Dye in-world
  • /smpu lectern <hex> command (supports any #RRGGBB or #RGB hex color!)
• Washing Dye Off: Right-click the placed lectern with a Water Bucket or Wet Sponge, or click a Water Cauldron while holding the item.

---

Commands (/smpu)

All commands are unified under two identical root prefixes: /smpu and /smp_utilities.

Command	Permission	Description
/smpu rename <...>	Any player (requires Rename Ticket unless bypassed)	Renames the held item with colors and styles, or clears custom name.
/smpu lore <...>	Any player (requires Lore Ticket unless bypassed)	Sets or clears custom lore text on the held item.
/smpu lectern <hex> [amount] [targets]	OP Level 2	Gives dye-colored Creative Lecterns using #RRGGBB or #RGB hex codes.
/smpu objective <global|player|clear> ...	OP Level 2	Displays persistent typewriter action-bar objectives globally or per player.
/smpu canon <get|set|add|setmax|reset|revive>	OP Level 2	Inspects, modifies, resets, or revives player Canon Hearts.
/smpu reload	OP Level 2	Reloads all TOML configs from config/smp_utilities/ and syncs to all online players.

---

Item Customization (/smpu rename & /smpu lore)

Both commands customize the item currently held in your main hand while consuming 1 matching ticket from your inventory (unless bypassed by Creative mode, OP Level 2, or feature whitelist, configurable in utilities.toml).

/smpu rename Syntax

/smpu rename clear
/smpu rename <color> <name>
/smpu rename <color> normal <name>
/smpu rename <color> <format> <name>

Examples:

/smpu rename red normal Fire Sword
/smpu rename gold bold Royal Shield
/smpu rename blue italic &lArcane &rWand
/smpu rename green bold italic Lucky Amulet
/smpu rename dark_red bold italic underlined strikethrough Forbidden Relic
/smpu rename clear

/smpu lore Syntax

/smpu lore clear
/smpu lore <color> <text>
/smpu lore <color> normal <text>
/smpu lore <color> <format> <text>

Examples:

/smpu lore dark_gray normal A very rare artifact.
/smpu lore gold bold Forged by ancient kings.
/smpu lore blue italic Said to bring fortune to its bearer.
/smpu lore dark_red strikethrough Confiscated by server staff.
/smpu lore clear

Note: You cannot rename or add lore to a Rename/Lore Ticket itself while holding it - hold the target item in your main hand and keep the ticket anywhere in your inventory. Inline & color/formatting codes inside <name> / <text> are also supported!

---

Creative Lectern (/smpu lectern)

Requires permission level 2. Gives one or more Creative Lecterns pre-dyed with any hexadecimal color.

/smpu lectern <hex>
/smpu lectern <hex> <amount>
/smpu lectern <hex> <amount> <targets>

Examples:

/smpu lectern #FF5500
/smpu lectern F50 4
/smpu lectern #2B82FF 1 @a

---

Objectives (/smpu objective)

Requires permission level 2. Displays a persistent typewriter-animated objective on the action bar (above the hotbar).

/smpu objective global <color> [style] <text>
/smpu objective player <target> <color> [style] <text>
/smpu objective clear
/smpu objective clear global
/smpu objective clear player <target>

Examples:

/smpu objective global gold bold Defeat the Ender Dragon!
/smpu objective global light_purple normal Special Event Active!
/smpu objective player Steve aqua italic Gather 16 Diamonds.
/smpu objective clear player Steve
/smpu objective clear

Behavior:

• Plays a smooth typewriter entrance animation (speed configured via [objective] speed_ticks in utilities.toml).
• Automatically refreshes once per second so vanilla action-bar fading does not clear it.
• Temporarily yields whenever a higher-priority restriction warning (such as blocked item/block feedback) is playing, then returns automatically.
• Player-specific objectives override the global objective; clearing the global objective leaves per-player objectives intact.
• Supports the 16 named Minecraft colors and inline & formatting codes (hex color codes like #FF5500 are exclusive to /smpu lectern).

---

Canon Hearts (/smpu canon)

Requires permission level 2. Manages player Canonical Hearts directly in-game:

/smpu canon get [player]
/smpu canon set <amount> [player]
/smpu canon add <amount> [player]
/smpu canon setmax <amount> [player]
/smpu canon reset [player]
/smpu canon revive <player>

Examples:

/smpu canon get Steve
/smpu canon set 5.5 Steve
/smpu canon add -1.0 Steve
/smpu canon setmax 15.0 Steve
/smpu canon reset Steve
/smpu canon revive Steve

• Decimal values (0.5 = half a heart) are supported.
• Setting or reducing hearts to 0.0 triggers the configured ban if ban_on_zero_hearts = true in canon_hearts.toml.
• /smpu canon revive <player> unbans a banned player (works both online and offline - offline players are queued via world SavedData and automatically restored to full Canon Hearts upon rejoining!).

---

Hot Reload (/smpu reload)

Requires permission level 2.

/smpu reload

Reloads restrictions.toml, canon_hearts.toml, waystones.toml, and utilities.toml from config/smp_utilities/, rebuilds client Creative tabs, updates JEI hidden overlays, and pushes fresh rules to all connected players immediately (standard /reload also reloads configs automatically).

---

Colors & Formats

Named Colors (for /smpu rename, /smpu lore, /smpu objective):
black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white
(plus &0-f / &k-r inline codes; hexadecimal #RRGGBB / #RGB colors are supported exclusively by /smpu lectern)

Single Styles:
normal, bold, italic, underlined, strikethrough

Chained Style Combinations (for /smpu rename and /smpu lore, in canonical order):

• bold italic, bold underlined, bold strikethrough
• italic underlined, italic strikethrough
• underlined strikethrough
• bold italic underlined, bold italic strikethrough, bold underlined strikethrough, italic underlined strikethrough
• bold italic underlined strikethrough

---

Restriction System (restrictions.toml)

SMP Utilities replaces old imperative /idrestrict / /idcontrol / /idlock commands with a single human-readable, hot-reloadable TOML config located at:

config/smp_utilities/restrictions.toml

Every rule automatically synchronizes from server to client when players join, respawn, switch dimensions, or when an admin runs /smpu reload or /reload.

All 14 Restriction Categories

Section in restrictions.toml	Field	Effect
[restrictions.drop_items]	items	Forces matching items out of inventory/pickup onto the ground (despawn_ticks configurable, default 1200). Cannot be picked up.
[restrictions.deleted_items]	items	Permanently deletes matching items immediately upon entering inventory or ground pickup.
[restrictions.blocked_use_items]	items	Blocks using/right-clicking the item in air, on blocks, or on entities.
[restrictions.zero_damage_items]	items	Sets attack damage dealt with the item to 0.0 (and appends an in-red tooltip warning on the client).
[restrictions.blocked_break_items]	items	Zeroes mining speed and cancels block breaking while holding the item.
[restrictions.blocked_armor_items]	items	Prevents equipping into vanilla armor slots (click, Shift+Click, hotbar swap, right-click); auto-ejects back to inventory.
[restrictions.blocked_trinkets_items] (or aliases blocked_curios_items, blocked_accessories_items)	items	Prevents equipping into Curios, Trinkets, or Accessories slots (protects manual click, Shift+Click, and right-click); auto-ejects if already equipped.
[restrictions.blocked_offhand_items]	items	Blocks placing/swapping matching items into the offhand slot.
[restrictions.indestructible_blocks]	blocks	Zeroes block break progress (0.0) and cancels block breaking server- & client-side.
[restrictions.unplaceable_blocks]	blocks	Prevents placing matching blocks into the world.
[restrictions.uninteractable_blocks]	blocks	Cancels right-click interaction with matching blocks (chests, levers, doors, etc.).
[restrictions.blocked_crafting_items]	items	Disables crafting output recipes matching these IDs across crafting grids and hides those recipes from JEI.
[restrictions.hidden_creative_items]	items	Hides matching items from Creative inventory tabs & search without removing them from JEI.
[restrictions.hidden_jei_items]	items	Hides matching items from JEI's ingredient panel & search without hiding them from Creative tabs.

(Each section with action-bar feedback also lets you customize message, speed_ticks, and hold_ticks; setting message = "" silences the notification.)

---

Wildcards, Placeholders & Priority Rules

Pattern Formats

• Exact ID: "minecraft:elytra"
• Entire Mod Namespace: "artifacts:*" or "waystones:*"
• All Items / Blocks / Players: "*"

Message Placeholders & Formatting

• %item% or {item} → localized item name
• %block% or {block} → localized block name
• %player% or {player} → triggering player's username
• Color codes: supports & and § (e.g., &c%item% cannot be worn...)

Rule Resolution Priority (Highest → Lowest)

For every category, permissions are evaluated in strict order using player usernames or UUIDs:

1. [...player_blacklist] - Per-player item/mod blacklist (always blocked for that player, even if in a category whitelist).
2. [...player_whitelist] - Per-player item/mod whitelist (allowed for that player even if blocked globally).
3. blacklist = [...] - Players permanently restricted across the entire category.
4. whitelist = [...] - Players completely exempt from the entire category.
5. items = [...] / blocks = [...] - Default global blocklist.

Example Snippet (restrictions.toml)

[restrictions.blocked_curios_items] # or blocked_trinkets_items / blocked_accessories_items
items = ["artifacts:snorkel", "artifacts:running_shoes"]
whitelist = ["AdminPlayer"]
blacklist = []
message = "&c%item% cannot be worn as an accessory..."
speed_ticks = 1
hold_ticks = 30

[restrictions.blocked_curios_items.player_whitelist]
"VIP_Player" = ["artifacts:running_shoes"]

[restrictions.blocked_curios_items.player_blacklist]
"RestrictedPlayer" = ["artifacts:*"]

[restrictions.hidden_creative_items]
items = ["minecraft:diamond_block", "minecraft:gold_block"]

[restrictions.hidden_jei_items]
items = ["minecraft:diamond_ore", "minecraft:gold_ore"]

---

Canon Hearts System (canon_hearts.toml)

Located at: config/smp_utilities/canon_hearts.toml

SMP Utilities includes a complete Canonical Lives / Hearts mechanic inspired by roleplay SMP servers:

• Persistent Storage: Saved reliably across deaths, respawns, and dimension changes (Cardinal Components on Fabric, Capabilities/Attachments on Forge & NeoForge).
• Custom Right-Side HUD: Renders empty, half, and full Canon Heart icons with blink animations below the hunger/air/vehicle bars when enabled (render_hud = true), cleanly shifting vanilla bars upward (and aligned alongside AppleSkin).
• Canon Loss Penalty: Dying while affected by the Canon Loss effect deducts hearts using:
  lost_hearts = effect_level * base_heart_loss
  (automatically rounded UP to the nearest 0.5 if not already a half-heart increment).
• Zero-Heart Banning & Revival: When a player hits 0.0 Canon Hearts (and ban_on_zero_hearts = true), they are automatically banned ("normal" profile ban or "ip" ban), disconnected with a customizable message, and optionally announced in chat - until revived by an admin via /smpu canon revive <player>.

Default canon_hearts.toml

[general]
max_canon_hearts = 10.0
starting_canon_hearts = 10.0
base_heart_loss = 0.5

[ban]
ban_on_zero_hearts = true
ban_type = "normal" # "normal" or "ip"
ban_message = "You were banned from the server for losing all your Canonical Hearts!"
broadcast_ban = true
broadcast_message = "&c[SMP Utilities] &4%player% &clost all Canonical Hearts and was banned from the server!"

[display]
render_hud = true

---

Potions & Effects

SMP Utilities adds three status effects, each available as Drinkable Potion, Splash Potion, Lingering Potion, and Tipped Arrow (custom durations: 5:00 drinkable, 2:30 splash capped at 3000 ticks, 0:10 tipped arrow at 200 ticks):

Canon Loss

• Effect ID: smp_utilities:canon_loss | Potion: smp_utilities:canon_loss_p (Level I)
• Color: Deep Crimson (#8A001A) | Category: Harmful
• Effect: While active, if the player dies, they lose level * base_heart_loss Canon Hearts (rounded up to 0.5).

---

Imbalance

• Effect ID: smp_utilities:imbalance | Potion: smp_utilities:imbalance_p (Level V by default)
• Color: Dark Slate (#3D4B5B) | Category: Harmful
• Effect: Reduces Knockback Resistance by -1.0 per level (-5.0 at Level V), making targets dramatically more vulnerable to knockback effects such as Chapolin Colorado's Sledgehammer.

---

Waystone Suppression

• Effect ID: smp_utilities:waystone_suppression | Potion: smp_utilities:waystone_suppression_p (Level I)
• Color: Purple (#AE37D5) | Category: Harmful
• Brewing Recipe: Potion of Slowness (Extended 8:00) + Popped Chorus Fruit → Potion of Waystone Suppression
• Effect: Prevents the affected player from using, breaking, placing, or interacting with any item/block listed in waystones.toml - and blocks Waystones teleportation hooks cleanly.

---

Waystone Suppression (waystones.toml)

Located at: config/smp_utilities/waystones.toml

[suppression]
suppressed_items = ["waystones:*"]
suppressed_blocks = ["waystones:*"]
whitelist = []
message = "&dYou cannot use this while under the Waystone Suppression effect!"
speed_ticks = 1
hold_ticks = 30

• Supports exact IDs ("minecraft:ender_pearl") and namespace wildcards ("waystones:*").
• Players listed in whitelist = ["PlayerName"] are completely immune to Waystone Suppression even if hit by the potion or tipped arrow.
• Supports %item%, %block%, %player% placeholders and &/§ formatting codes.

---

Utilities Configuration (utilities.toml)

Located at: config/smp_utilities/utilities.toml

[ban_sword]
kick_without_mending = true
permanent_ban_with_mending = true
ban_reason = "Banned by Ban Sword"

[mind_wrench]
slowness_amplifier = 255
effect_time = -1

[chapolin_sledgehammer]
knockback_strength = 20.0

[tickets]
creative_bypass = true
op_bypass = true

[objective]
speed_ticks = 1

---

FAQ

Optional Dependencies

Do I need Curios, Trinkets, Accessories, Waystones, or JEI installed?
No. All complementary mods are strictly optional across Forge, NeoForge, and Fabric. SMP Utilities boots normally standalone and automatically activates each integration only when the matching mod is installed.

Accessory Config Aliases

Which accessory section should I use (blocked_curios_items, blocked_trinkets_items, blocked_accessories_items)?
All three map internally to the same accessory-slot category! By default, Forge/NeoForge generates [restrictions.blocked_curios_items] and Fabric generates [restrictions.blocked_trinkets_items], and all loaders accept any of the three aliases so configs stay portable across modpacks.

Creative Tabs vs. JEI

If I hide an item from Creative tabs, does it also disappear from JEI?
No. hidden_creative_items and hidden_jei_items are handled independently. You can hide an item from Creative tabs while keeping it visible in JEI (for recipe lookups), or vice versa!

Hot-Reloading Configs

How do I reload configuration changes without restarting the server?
Edit the .toml files inside config/smp_utilities/ and run /smpu reload (or vanilla /reload). Updated rules immediately sync to all online players.

Admin Bypasses

Can an admin bypass restrictions cleanly for testing or events?
Yes - add usernames or UUIDs to any category's whitelist = [...] (for global bypass) or [...player_whitelist] (for specific item/mod exceptions). Note that [...player_blacklist] always takes highest priority.

---

SMP: Utilities - Keep your SMP organized.