Gizmo | Custom Welcome Screen + More

Gizmo is a resource pack driven screen system for Minecraft servers. Create polished welcome, rules, guide, and information screens with custom layouts, clickable items, navigation, conditions, messages, commands, sounds, and fades; all without ever clearing or modifying a player's real inventory.


INSTALLATION

1. Install a ProtocolLib.
2. Install Gizmo.jar in your server's plugins folder.
3. Apply or merge the provided Gizmo resource pack.
4. Start the server once to generate Gizmo's configuration files.
5. Configure screens.yml, then restart or run /gizmo reload.

Important: Gizmo's assets must be included in the pack the player actually receives. Detecting Nexo, ItemsAdder, or Oraxen does not merge Gizmo assets into their pack automatically.

Nexo / ItemsAdder / Oraxen: Merge Gizmo assets into the provider-generated pack, regenerate it, and ensure that pack is sent to joining players.

FEATURES

• Named, reusable screens — define as many screens as needed and assign them to events.
• Join and first-join events — first-time players can receive their own screen, layout, colors, actions, and items.
• Screen navigation — use an item to open another configured screen without firing the previous screen's close actions.
• Conditions — restrict events, screens, or items by permission and world.
• 54 safe screen slots — Gizmo never clears, saves, restores, or writes to the player's actual inventory.
• ProtocolLib inventory masking — player inventory slots are hidden client-side while a screen is open.
• Custom items — material, slot, display name, lore, custom model data, and hidden item flags.
• Item actions — run player commands, console commands, or send messages from clicked items.
• Per-screen close actions — run commands, send messages, play sounds, and show a fade when a screen closes.
• Hex and legacy color support — supports & and &#RRGGBB color formatting.
• Resource-pack safeguards — optional blindness and invulnerability while the pack prompt is active.
• Decline handling — optionally kick players who decline or fail to download the required pack, with configurable multi-line text.
• Provider detection — supports vanilla server packs and detects Nexo, ItemsAdder, and Oraxen.
• Join/quit message controls — optionally hide standard server join and quit announcements.
• Config validation — validates screen mappings, layouts, item slots, materials, commands, navigation targets, sounds, and conditions at startup and reload.
• Once-per-restart screens — optionally show an event screen only once per player during a server session.
• Debug mode — resource-pack status diagnostics for troubleshooting.

SCREEN EXAMPLE
Supported conditions:

• permission — player must have one permission.
• permissions — player must have every listed permission.
• worlds — player must be in one of the configured worlds.

Supported action prefixes:
COMMANDS & PERMISSIONS

• /gizmo help — Displays command help. Alias: /g help
• /gizmo reload — Reloads Gizmo configurations and validates screens.yml. Permission: gizmo.reload. Alias: /g rl
• /gizmo show — Shows the configured join screen to yourself. Permission: gizmo.show
• /gizmo show <player> — Shows the configured join screen to a player. Permission: gizmo.show
• /gizmo show <screen> — Shows a named screen to yourself. Permission: gizmo.show
• /gizmo show <screen> <player> — Shows a named screen to a player. Permission: gizmo.show
• /gizmo fade <in> <stay> <out> — Displays a fade to yourself. Times use ticks. Permission: gizmo.fade
• /gizmo fade <in> <stay> <out> <player> — Displays a fade to a player. Permission: gizmo.fade

All Gizmo commands can be run from console. Commands that would normally target yourself require a player target when run from console.

COMPATIBILITY

• Spigot/Paper 1.18–26.1+
• ProtocolLib is required; install a version compatible with your Minecraft server.

Troubleshooting: If no screen appears, first confirm that the player was accepted and successfully loaded a resource pack. If player inventory items appear in an open Gizmo screen, confirm ProtocolLib is installed, enabled, and compatible with your server version.