> For the complete documentation index, see [llms.txt](https://xpressdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xpressdev.gitbook.io/docs/mods/entitycommands.md). # EntityCommands EntityCommands turns any entity into a **command trigger**. Right-click a mob, villager, armour stand - anything with a UUID - and it runs a chain of commands you configured in game, with optional delays between them and a permission node per entity. No client mod required; players just right-click. *** ## Features * **Turn any entity into a command trigger**, configured entirely through an in-game GUI * **Ordered command chains** per entity, up to 21 steps * **Per-command delay** before the next command runs * **Per-command execution source** - run as the server, or as the triggering player * **Per-entity permission node**, with a server-wide default fallback for unconfigured entities * **`{player}` placeholder** available in every command * **Works with any Fabric permissions plugin**, falling back to operator level 2 when none is installed * **Per-player interaction cooldown** to swallow duplicate right-click packets *** ## How it works 1. `/ecommands configure` - toggles Configure Mode. An action bar reminds you it is on. 2. Right-click the entity you want to configure. The Entity Menu opens. 3. **Add Command** creates a command slot and opens the Edit Command menu on it. 4. Set the command text with `/ecommands command `, typed in chat. 5. Optionally set a **delay** (seconds to wait before the *next* command) and a **source** (run as Server or as the Player). 6. Back in the Entity Menu, optionally set a **permission node** for the whole entity. 7. `/ecommands configure` again to leave Configure Mode. Commands are ordered - they run top to bottom, on the server thread, one step per tick plus whatever delay you set. ### Placeholders | Placeholder | Replaced with | | ----------- | ---------------------------------------- | | `{player}` | The name of the player who right-clicked | *** ## Commands All commands live under `/ecommands` (alias: `/entitycommands`). | Command | What it does | | ------------------------------ | ----------------------------------------------------------- | | `/ecommands configure` | Toggle Configure Mode | | `/ecommands command ` | Set the text of the command currently open in the Edit menu | | `/ecommands reload` | Reload `config.json`, `lang.json` and every storage file | *** ## Permissions EntityCommands uses [LuckPerms' Fabric permissions API](https://github.com/lucko/fabric-permissions-api). LuckPerms is supported but not required - every node falls back to **op level 2**. | Node | Grants | | -------------------------------- | ----------------------------------------------- | | `entitycommands.admin` | Every subcommand | | `entitycommands.admin.configure` | `/ecommands configure` and `/ecommands command` | | `entitycommands.admin.reload` | `/ecommands reload` | Per-entity **use** permissions are set in the GUI, not through a node here. An entity with no permission set is usable by **everyone**, unless you name a server-wide fallback in `permissions.defaultUseNode`. {% hint style="warning" %} A blank permission means no check at all. If you want unconfigured entities locked down by default, set `permissions.defaultUseNode` to a node your players don't have. {% endhint %} *** ## Configuration Config files live in `config/EntityCommands/`, generated on first start: | File | Purpose | | ------------- | ----------------------------------------------- | | `config.json` | Interaction, execution and permission settings. | | `lang.json` | Every player-facing message. | | `Storage/` | One JSON file per configured entity. | Edit a file and run `/ecommands reload`, or restart the server, to apply changes. ```json { "interaction": { "cooldownTicks": 4, "showConfigureActionBar": true }, "execution": { "maxDelaySeconds": 300, "cancelOnDisconnect": true }, "permissions": { "adminNode": "entitycommands.admin", "defaultUseNode": "" } } ``` ### `interaction` | Key | Default | Description | | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cooldownTicks` | `4` | Ticks before the same player can trigger another entity. Swallows the duplicate packets a single right-click produces. Per player, not server-wide. Max `1200`. | | `showConfigureActionBar` | `true` | Show the "Configure Mode active" action bar while a player has it toggled on. | ### `execution` | Key | Default | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maxDelaySeconds` | `300` | Largest delay accepted in the GUI. Max `3600`. | | `cancelOnDisconnect` | `true` | Drop a chain still in flight when its player logs out. Set `false` to run it to completion - commands set to run *as the player* are still skipped while they're offline. | ### `permissions` | Key | Default | Description | | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------ | | `adminNode` | `entitycommands.admin` | Root node for `/ecommands`. Blank falls back to op level 2 only. | | `defaultUseNode` | `""` | Node required by entities that have no permission of their own. Blank means anyone can use them. | {% hint style="info" %} Every value is read leniently: a key of the wrong type logs a warning and falls back to its default instead of failing the load. {% endhint %} *** ## Storage One file per entity, in `config/EntityCommands/Storage/.json`: ```json { "uuid": "6f3b1e0c-6c3a-4a2b-9f9d-2c1f0e5a7b31", "commands": [ { "command": "give {player} minecraft:diamond 1", "delay": 0, "type": "SERVER" }, { "command": "say thanks {player}", "delay": 3, "type": "SERVER" } ], "permission": "shop.blacksmith" } ``` | Field | Description | | -------------------- | --------------------------------------------------------------- | | `uuid` | The entity's UUID. | | `commands` | Ordered list of steps. | | `commands[].command` | The command, without a leading `/`. | | `commands[].delay` | Whole seconds to wait *after* this command before the next one. | | `commands[].type` | `SERVER` or `PLAYER` - who runs the command. | | `permission` | Blank means no permission check. | {% hint style="warning" %} Files are keyed by **entity UUID**. If the entity dies and respawns, its UUID changes and the configuration no longer applies. This mod is for permanent, named entities you don't expect to lose - a shopkeeper villager, a quest NPC, a decorative armour stand. {% endhint %} An entity is capped at **21 commands**, the number the Entity Menu has room for. Removing an entity's last command deletes its file and returns it to ordinary, unconfigured behaviour. *** ## Messages Every message players and admins see is in `lang.json` and uses [MiniMessage](https://docs.advntr.dev/minimessage/format.html) formatting. Legacy `&` and `ยง` colour codes work too. | Key | When it's shown | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `error.players_only` | A console tries to run a player-only subcommand. | | `error.not_in_configure_mode` | `/ecommands command` is used outside Configure Mode. | | `error.not_editing` | `/ecommands command` is used with no command open in the Edit menu. | | `error.edit_session_expired` | The command being edited no longer exists. | | `error.no_permission` | A player without the required node right-clicks a gated entity. | | `error.too_fast` | A player right-clicks an entity that's still running its previous chain. | | `error.invalid_permission` | The permission input is left blank. | | `error.invalid_delay` | The delay input isn't a whole non-negative number. | | `error.delay_too_long` | The delay entered exceeds `execution.maxDelaySeconds`. | | `error.too_many_commands` | Adding a command would exceed the 21-command cap. | | `info.configure_enabled` / `info.configure_disabled` | Configure Mode toggled. | | `info.configure_action_bar` | Action bar shown while Configure Mode is active. | | `info.reloaded` | `/ecommands reload` succeeded. | | `info.command_set` | A command's text is set from chat. | | `info.command_removed` | A command is removed in the Entity Menu. | | `info.permission_set` / `info.permission_cleared` | The entity's permission node is set or cleared. | | `info.delay_set` | A command's delay is set. | | `info.use_chat_command` | Reminder shown when the Command button is clicked. | | `gui.*` | Titles, item names and lore across the Entity Menu, Edit menu and delay/permission input screens. | Run `/ecommands reload` after editing `lang.json` to apply changes. *** ## Requirements * Minecraft 1.21.1 (Fabric) * Fabric API * Fabric Language Kotlin 1.13.6 or newer, **required** * LuckPerms - optional