# SMP Utilities - Official Wiki **SMP Utilities** is a multi-loader administration, customization, and survival-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](#supported-loaders--optional-integrations) 2. [Admin Items & Blocks](#admin-items--blocks) 3. [Commands (`/smpu`)](#commands-smpu) - [Item Customization (`/smpu rename` & `/smpu lore`)](#item-customization-smpu-rename--smpu-lore) - [Creative Lectern (`/smpu lectern`)](#creative-lectern-smpu-lectern) - [Objectives (`/smpu objective`)](#objectives-smpu-objective) - [Canon Hearts (`/smpu canon`)](#canon-hearts-smpu-canon) - [Hot Reload (`/smpu reload`)](#hot-reload-smpu-reload) - [Colors & Formats](#colors--formats) 4. [Restriction System (`restrictions.toml`)](#restriction-system-restrictionstoml) - [All 14 Restriction Categories](#all-14-restriction-categories) - [Wildcards, Placeholders & Priority Rules](#wildcards-placeholders--priority-rules) 5. [Canon Hearts System (`canon_hearts.toml`)](#canon-hearts-system-canon_heartstoml) 6. [Potions & Effects](#potions--effects) 7. [Waystone Suppression (`waystones.toml`)](#waystone-suppression-waystonestoml) 8. [Utilities Configuration (`utilities.toml`)](#utilities-configuration-utilitiestoml) 9. [FAQ](#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 ![Absurd Damage Sword](https://cdn.modrinth.com/data/cached_images/6437d6820ad740fe1f27f437aa88c9e4e94ededa.png) 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 ![Ban Sword](https://cdn.modrinth.com/data/cached_images/29fe45325caaa6317a0c1c331ebe1681a786b125.png) 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 ![Chapolin Colorado's Sledgehammer](https://cdn.modrinth.com/data/cached_images/b7f50a974e2a6965195808c4d113beed4aa32991.png) 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 ![Mind Wrench](https://cdn.modrinth.com/data/cached_images/1b7857b44109b9083d5ae312dd257de8a2e283fb.png) 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 ![Little Poop](https://cdn.modrinth.com/data/cached_images/1dcc21e0ec6538f599c8da543747567d22823c37.png) A throwable projectile item that deals **0 damage** on impact, spawns item break particles, and plays a custom splat sound. --- ### Realm Coin ![Realm Coin](https://cdn.modrinth.com/data/cached_images/1b7310d8265fb02721ae23894a4770e64a1cebc2.png) A collectible/currency item designed for SMP server economies, quests, shops, and special events. --- ### Rename Ticket & Lore Ticket ![Rename Ticket](https://cdn.modrinth.com/data/cached_images/037f02fafb857afdee0b38dea0235aafed0cde60.png) ![Lore Ticket](https://cdn.modrinth.com/data/cached_images/c7ca21f9393fbe201204853e586041b0a59a1216.png) 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 ![Security Block](https://cdn.modrinth.com/data/cached_images/e1436504b18f72b3b2ee9c05635fef364c57ea16.png) An **unbreakable**, Bedrock-strength opaque structural block intended for secure admin rooms, borders, and event arenas. --- ### Creative Lectern ![Creative Lectern](https://cdn.modrinth.com/data/cached_images/854a0b713470ca00c91f9d90a798958e18c63171.png) 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 ` 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 [amount] [targets]` | OP Level `2` | Gives dye-colored Creative Lecterns using `#RRGGBB` or `#RGB` hex codes. | | `/smpu objective ...` | OP Level `2` | Displays persistent typewriter action-bar objectives globally or per player. | | `/smpu canon ` | 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 ```mcfunction /smpu rename clear /smpu rename /smpu rename normal /smpu rename ``` **Examples:** ```mcfunction /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 ```mcfunction /smpu lore clear /smpu lore /smpu lore normal /smpu lore ``` **Examples:** ```mcfunction /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 `` / `` are also supported! --- ### Creative Lectern (`/smpu lectern`) Requires **permission level 2**. Gives one or more Creative Lecterns pre-dyed with any hexadecimal color. ```mcfunction /smpu lectern /smpu lectern /smpu lectern ``` **Examples:** ```mcfunction /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). ```mcfunction /smpu objective global [style] /smpu objective player [style] /smpu objective clear /smpu objective clear global /smpu objective clear player ``` **Examples:** ```mcfunction /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: ```mcfunction /smpu canon get [player] /smpu canon set [player] /smpu canon add [player] /smpu canon setmax [player] /smpu canon reset [player] /smpu canon revive ``` **Examples:** ```mcfunction /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 `** 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**. ```mcfunction /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: ```text 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`) ```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 `. #### Default `canon_hearts.toml` ```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 ![Canon Loss](https://cdn.modrinth.com/data/cached_images/5d26cf33a7c582c1e813a712e3ba09f20fc2a383.png) - **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 ![Imbalance](https://cdn.modrinth.com/data/cached_images/12d0ce6d01de046825fd24037a8d661702f9b8a9.png) - **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 ![Waystone Suppression](https://cdn.modrinth.com/data/cached_images/54977a1997d65967b4d2036768bee006ce8f512a.png) - **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`** ```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`** ```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.**

forgotten.and.stuff