NobleSteeds Wiki

Generated File Layout Example

plugins/NobleSteeds/

plugins/NobleSteeds/
├── config.yml
├── network/
│   └── config.yml
├── language/
│   ├── messages_en.yml
│   └── ...
└── data/
    ├── data.sql
    └── yaml/

Normal Player Flow

Claim a mount while riding it, give it a clear name, then open My Horses to verify it appears in an active slot. Set a favorite if you want /ns call to work without typing a mount name. Set a stable at a safe location so the mount can be sent home later, and use storage when you want to keep a mount without leaving it active in the world.

Transfers, Gifts, and Market Use

Giving a mount creates a pending transfer instead of silently moving ownership. The receiver opens /ns receive and accepts the offer when they have a free active slot. Selling through the market is different: the listed mount enters market state and normal owner actions are blocked until it sells or is removed from the market.

When a Mount Cannot Be Called

Check whether the mount is dead, stored, listed on the market, already loaded elsewhere, or missing from saved storage. In network mode, an "already loaded on another server" style message means staff should check /ns admin network, Redis, MySQL, and unique backend server IDs.

Main Menu and My Horses

/ns displays the player help entry point and /ns manage opens the main player management GUI. Server owners can point new players to this menu first because it shows the current state of the player's mounts without requiring players to memorize every command.

The My Horses menu uses fixed active slots, marks the favorite with a star, and shows state such as alive/dead, stable assignment, sharing, and market listing status. If a mount is listed on the market, NobleSteeds blocks normal management actions until the listing is removed or sold.

Empty active slots help players understand why a transfer can or cannot be accepted. If all active slots are full, a received gift cannot be accepted until the player releases, stores, or otherwise frees a slot.

Horse Management Menu

The management menu is the center of player workflows. It is reached by selecting a claimed mount from My Horses. Normal actions include call mount, set favorite, rename, set/send/unset stable, toggle auto-stable, manage sharing, move to storage, open market listing options, revive dead mounts, and release with confirmation.

Options can be unavailable depending on mount state and configuration. Stored mounts must be restored before active-only actions make sense. Dead mounts use revive instead of call. Market-listed mounts are intentionally locked down so owners cannot duplicate value by calling, giving, renaming, storing, or riding a listed mount.

Screenshot pending: 03-horse-manage-menu.png

Screenshot pending: 04-favorite-toggle.png

Screenshot pending: 07-stable-menu.png

Storage Menus

The storage GUI restores stored mounts into free active slots. Store Active Mount saves, despawns, and moves an active mount into storage. This is useful for players who collect more mounts than they want active in the world.

Stored mounts are not the same as active mounts. They cannot be called, shared from the active management menu, sent to stable, or managed as active entities until restored. If the player has no free active slot, restore actions should remain blocked.

Screenshot pending: 08-store-horse-menu.png

Screenshot pending: 06-call-horse-success.png

Market and Shop Menus

The market hub opens browsing, listing source selection, my listings, price entry, and item payout receive flows. Players use it to compare listings by price, seller, rarity, breeding quality, and vanilla stat bars. Listing a mount moves it into market state until it sells or is removed.

The shop menu shows enabled admin-created entries. Shop mounts are server-created products, not player listings, so they are useful for economy balancing, starter mounts, donor-free public shops, or seasonal server rewards. Both market and shop menus can hide or block purchase paths when economy requirements are not met.

Screenshot pending: 16-market-browse.png

Screenshot pending: 17-market-list-horse.png

Screenshot pending: 18-market-price-menu.png

Screenshot pending: 19-market-my-listings.png

Screenshot pending: 21-shop-menu.png

Receive, Share, Revive, and Admin Menus

Receive Mounts handles pending transfer offers. Players should use it when another player sends a mount with /ns give. The receiver chooses whether to accept, and acceptance requires a free active slot so the mount has somewhere to go.

Share menus support private, everyone, and specific-player access where available. Sharing is for access control; giving is for ownership transfer. Keep those workflows separate when explaining the plugin to players.

Revive appears for dead owned active mounts when revive is enabled. If paid revive is configured, NobleSteeds prompts the player to confirm before charging. Release/delete actions use confirmation because they remove the player's ownership record.

Admin tools cover player mounts, stored mounts, market listings, shop entries, storage tools, NPC registration, and network diagnostics. The admin network output is especially useful after enabling Redis/MySQL network mode because it reports whether the required safety managers are ready.

Screenshot pending: 12-receive-gifts-menu.png

Screenshot pending: 10-share-menu.png

Screenshot pending: 14-revive-confirm-menu.png

Screenshot pending: 15-release-confirm-menu.png

Screenshot pending: 25-admin-tools-menu.png

Screenshot pending: 27-admin-shop-menu.png

Screenshot pending: 29-admin-network-menu.png

Admin Horse Management

/ns admin tools opens the central admin GUI. Source-confirmed reachable admin menu paths include claimed horse/player selection, player mount options, player active mounts, player stored mounts, unclaim confirmation, admin market tools, admin shop tools, and NPC registration. Storage and network administration are command-output workflows, not normal admin GUI buttons.

Use these menus when a player loses track of a mount, a stored mount needs review, or staff need to inspect mount state before taking action. Admin restore/edit respawn paths are covered by the same network mount safety preparation used by normal restore and call workflows, so network servers should still keep Redis/MySQL healthy before staff force mount movement.

Screenshot pending: 26-admin-horse-tools.png

Admin Shop Workflow

Admin shop entries are server-created mount products. They are separate from player market listings and are useful for starter mounts, economy sinks, event rewards, or consistent public shop offerings. Create entries with the exact source-confirmed command tags, then review them through the admin shop GUI before players use /ns shop.

Confirmed admin shop command pattern

/ns admin shop add --v horse --s 75 --j 70 --h 80 --b 65 --price 5000 --name "Swift Starter"
/ns admin shop list
/ns admin shop remove <id|shortId|name:shortId>

The stat tags are percentages. High speed, jump, health, and breeding quality should be priced as premium entries. If item currency is enabled, shop prices can use the item-price format accepted by the source command; if item currency is disabled, keep shop entries on normal money pricing.

Screenshot pending: 28-admin-shop-entry-detail.png

Market Moderation

Market-listed mounts are intentionally locked from normal owner actions while listed. Staff should use admin market tools when a listing is stale, abusive, mispriced by mistake, or connected to a support issue. Admin market removal uses confirmation and participates in network-safe respawn/listing cleanup paths.

• Check whether the player can remove the listing through My Listings first.
• Confirm the mount should return to the owner or be removed according to server policy.
• Use admin market management from /ns admin tools for staff removal instead of editing storage directly.
• On a network, rerun /ns admin network if listings look stale across backend servers.

Clear Claim Data

/ns admin clearclaim exists for stale cleanup. It targets the mount the admin is riding, or a supported mount the admin is looking at within range. Use it when old NobleSteeds or vanilla owner data remains on an entity after data cleanup, testing, or support intervention.

Clearclaim is not a normal unclaim workflow for player-owned mounts. For normal ownership removal, use the player release confirmation or the admin unclaim confirmation tools. Clearclaim is best reserved for stale entity metadata and cases where a mount cannot be reclaimed because old owner data is still attached.

Screenshot pending: 30-admin-clearclaim-result.png

Staff Workflow Examples

• Player cannot find a mount: check My Horses, stored mounts, market listings, and whether the mount is dead or loaded remotely before restoring anything.
• Market support ticket: inspect the listing, verify buyer/seller state, check economy/item-currency requirements, then remove only through admin market tools if policy allows.
• Network support ticket: run /ns admin network on every backend, verify MySQL and Redis, then test call/storage with a disposable mount.
• Shop balancing pass: list entries, compare stat percentages and breeding quality, adjust prices by removing/re-adding entries, then test purchase from a non-admin account.
• NPC access setup: register a staging Citizens NPC, test with a non-admin account, then register public NPCs only after permissions and economy requirements are correct.

Admin Shop Syntax

The source parser accepts removal by full UUID, short UUID prefix, or normalized name:shortId. Use /ns admin shop list after adding entries so staff copy the exact identifier shown by the plugin instead of guessing.

Source-confirmed shop examples

/ns admin shop add --v BROWN --s 80 --j 70 --h 65 --b 50 --price 5000 --name Noble Steed
/ns admin shop list
/ns admin shop remove <id>
/ns admin shop remove <shortId>
/ns admin shop remove <name:shortId>

Common Command Workflows

Player claim and manage flow

/ns claim Emberhoof
/ns manage
/ns set favorite Emberhoof
/ns call

Safe storage preparation for network mode

/ns admin storage current
/ns admin storage convert MYSQL
/ns admin storage current
/ns admin network

Admin shop example

/ns admin shop add --v brown --s 75 --j 70 --h 80 --b 65 --price 1000 --name Swift Brown
/ns admin shop list
/ns admin shop remove swift_brown:1a2b3c4d

Admin Cleanup Workflow

/ns admin clearclaim is for stale claim cleanup when a mount still carries NobleSteeds or vanilla owner data after an admin reset, migration, or manual cleanup. Run it while riding the mount or looking directly at the target mount. It clears NobleSteeds claim data when present and also clears vanilla owner data.

Screenshot pending: 30-admin-clearclaim-result.png

Common Safe Defaults

For a standalone survival server, keep storage.type: SQLITE, keep network.enabled: false, and leave item currency disabled until you intentionally design item-price market or shop behavior. Vault can be installed later if you decide to use money market, shop, or paid revive features.

Economy and Item Currency Settings

market.require-economy and shop.require-economy control whether those systems require a Vault economy for money use. Item currency is configured under item-currency, supports up to three material entries per price, and uses Bukkit material names in the configured format.

Revive and Rarity Settings

Revive is enabled under horse-management.revive.enabled. Paid revive is separate and off by default under horse-management.revive.cost.enabled. Rarity uses configured stat ranges, weights, and tier thresholds, while breeding quality uses its own generated range and offspring inheritance settings.

Locale and Update Settings

locale.default chooses the fallback language and locale.auto-detect-player-locale lets the plugin choose a supported language from the player's client locale. The update section can check the website endpoint on startup and notify admins with the configured notify permission.

Example config.yml sections

This is a short reference using confirmed NobleSteeds keys. Edit your generated file rather than replacing it wholesale, especially after updates that may add comments or new defaults.

Example config.yml sections

locale:
  default: en
  auto-detect-player-locale: true

storage:
  type: "SQLITE"

market:
  enabled: true
  require-economy: true
  listing-expiration-hours: 0
  send-mailboxgui-money:
    enabled: false

item-currency:
  enabled: false
  format: "Diamond:3,Emerald:2,Gold_Nugget:2"
  send-mailboxgui-package: false

shop:
  enabled: true
  require-economy: true

horse-management:
  revive:
    enabled: true
    cost:
      enabled: false
      base-price: 1000

updates:
  enabled: true
  check-on-startup: true
  notify-admins-on-join: true
  notify-permission: "noblesteeds.admin"
  channel: "release"

Single Server vs Network Mode

Most servers should start in standalone mode. Standalone mode is the default, uses the configured local/shared storage provider, and does not require Redis. SQLite is the recommended default for fresh single-server installs.

Network mode is only for multiple backend servers behind a proxy where the same players and mounts need to move between backends. In that setup, every backend runs NobleSteeds, every backend uses the same shared MySQL/MariaDB database, and Redis is used for backend-to-backend coordination.

Network Requirements

• MySQL/MariaDB storage: required on every backend. Do not use YAML or SQLite for multiple active backend servers.
• Redis: required for cross-backend messages, data refreshes, loaded-mount safety, stable routing, give/receive sync, and payout routing.
• Same NobleSteeds version: install the same jar version on every backend before enabling network mode.
• Unique server ID: set a different network.server-id on each backend, such as survival, resource, or lobby.
• Consistent feature config: keep market, shop, item currency, language, and dependency expectations aligned across backend servers.
• Economy and MailboxGUI: if Vault, item currency, or MailboxGUI payouts are used across the network, install and configure the needed dependencies on the backends where those actions can occur.

Before Enabling Network Mode

NobleSteeds has a source-backed storage conversion command. Convert the existing production data to MySQL while network mode is still disabled, then verify the data before turning on Redis/network coordination.

Pre-network storage conversion

/ns admin storage current
/ns admin storage convert MYSQL
/ns admin storage current

• Run this on the current production backend first, before adding additional NobleSteeds backend nodes.
• Back up plugins/NobleSteeds/, the SQLite/YAML data, and the target MySQL database before converting.
• The conversion copies claimed horses, market listings, horse share entries, auto-stable entries, and shop entries, then validates counts before switching storage.type.
• Conversion is blocked while NETWORK_NODE mode is active. If conversion fails, keep network mode disabled and fix the storage error first.
• After conversion, restart and test real data: My Horses, stored mounts, market listings, shop entries, sharing, and stable state.

Step-by-Step Network Setup

1. Back up NobleSteeds data and the current database.
2. Stop all backend servers that will run NobleSteeds.
3. Configure MySQL/MariaDB in plugins/NobleSteeds/config.yml on the existing production backend.
4. Start the production backend with network mode still disabled.
5. Run /ns admin storage current, then /ns admin storage convert MYSQL.
6. Confirm /ns admin storage current reports active MySQL storage.
7. Stop the production backend again and copy the cleaned config/language setup to the other backends, changing only backend-specific values.
8. Install the same NobleSteeds jar on every backend.
9. In network/config.yml, set network.enabled: true and network.mode: "NETWORK_NODE".
10. Set a unique network.server-id on every backend.
11. Configure Redis host, port, username, password, SSL, timeout, and channel on every backend.
12. Start one primary backend first and run /ns admin network.
13. Start the remaining backends and run /ns admin network on each one.
14. Test /ns, /ns manage, storage restore, /ns call, stable send, market listing/buy, and /ns give//ns receive across servers if those features are enabled.
15. Watch console logs for MySQL connection errors, Redis validation errors, duplicate server IDs, and network readiness warnings.

Network Safety Behavior

NobleSteeds uses a network mount safety manager before local spawn/respawn operations. In standalone mode it removes a duplicate loaded copy on the same backend. In network mode it also publishes a Redis request asking other backends to save and despawn the same mount if it is loaded remotely, waits for the configured safety window, then refreshes shared data before spawning locally.

• Protected paths include /ns call, storage restore, revive, stable send/respawn, market buy/unlist/admin removal, shop purchase, admin stored restore/edit respawn, give/receive transfer completion, and saved-mount respawn utilities.
• This prevents two copies of the same saved mount from staying active on two backends after a player moves servers or triggers a remote workflow.
• network.operation-timeout-millis controls the short wait used for cross-backend safety operations. Higher values may be safer on slower Redis hosting but can make GUI actions feel slower.
• If Redis is down, the safety request cannot coordinate remote nodes. Stop and fix network readiness before allowing production cross-server mount movement.

Example network/config.yml

This example shows the confirmed network and Redis keys. Keep the Redis password private and set a different network.server-id on every backend.

Example network/config.yml

network:
  enabled: true
  mode: "NETWORK_NODE"
  server-id: "survival"
  operation-timeout-millis: 250

redis:
  host: "127.0.0.1"
  port: 6379
  username: ""
  password: ""
  use-ssl: false
  timeout-millis: 5000
  channels:
    network-calls: "noblesteeds:network:calls"

Network Troubleshooting

• Redis failed: verify the backend can reach the configured host/port, password, username, SSL setting, and firewall path. Redis on 127.0.0.1 means "inside this backend host/container", not always the physical machine.
• MySQL failed: verify database name, user permissions, host bind address, SSL setting, table prefix, and that every backend points at the same database.
• Wrong server ID: duplicate network.server-id values make stable routing and loaded-mount safety ambiguous. Give every backend a unique stable ID.
• SQLite by mistake: /ns admin network reports a storage requirement failure when NETWORK_NODE is active without MySQL.
• Remote loaded warning: wait for data refresh, verify Redis, and avoid forcing extra spawns. The safety system is protecting the server from duplicate active mounts.
• Market or give does not sync: check Redis, MySQL, backend logs, and whether all nodes run the same NobleSteeds version.
• Server started before Redis/MySQL: fix the dependency, restart the backend, and rerun /ns admin network.

Screenshot pending: 37-network-remote-loaded-warning.png

Recommended Storage Choices

• Use SQLITE for fresh standalone servers that do not need shared backend data.
• Use MYSQL for networks and for larger servers that already maintain database infrastructure.
• Use YAML only when you intentionally want flat-file storage and understand the maintenance tradeoff.
• Redis is not a storage provider. Redis coordinates network actions; persistent mount data stays in YAML, SQLite, or MySQL.

Market Admin and Failure Checks

• Players cannot list dead mounts, unclaimed mounts, mounts they do not own, or mounts that are already listed.
• Market-listed mounts are blocked from call, give, rename, normal management, and riding access until unlisted or sold.
• Stored-market unlisting requires the seller to have a free active mount slot before the stored mount can return.
• Admin market tools can remove stale or problem listings from the admin GUI. If a saved world no longer exists, unlisting or spawn return can fail and should be handled during maintenance.
• For item-currency listings, use Bukkit material names and at most three entries. Sellers claim item payouts with /ns market receive unless MailboxGUI package payout is enabled and available.

Admin Shop Workflow

1. Decide the mount role: starter, utility storage mount, fast travel mount, high jumper, high-health mount, or premium breeder.
2. Create the entry with /ns admin shop add using confirmed stat tags and a price that matches your economy.
3. Run /ns admin shop list and copy the displayed short ID or name:shortId for future removal.
4. Open the admin shop GUI from /ns admin tools to review enabled state, stat bars, price display, and player-facing presentation.
5. Test purchase from a non-admin account with the same permissions and economy setup normal players will have.

How Players Should Read Stats

Rarity is a summary of current mount performance. Breeding Quality is a future-facing quality value. A mount with excellent current stats may not be the best breeder, and a mount with strong Breeding Quality may be worth keeping even if its current rarity is not top tier.

Registering an NPC

1. Open /ns admin tools.
2. Open NPC Registration and choose the NPC type.
3. Confirm the type is enabled. For Market and Shop, confirm the feature is usable and economy requirements are satisfied.
4. Click Register. The inventory closes and NobleSteeds waits for a Citizens NPC right-click.
5. Right-click the desired Citizens NPC. NobleSteeds stores the Citizens ID under that access type and adds its NobleSteeds NPC trait.

Deregistering and Managing NPCs

Use the Deregister action when you know which NPC to click, or open Manage Registered NPCs to see all registered Storage, Market, and Shop NPC IDs. The management menu lists the NPC type, Citizens ID, and NPC name; clicking an entry deregisters it. This is the safest cleanup path after removing or replacing a Citizens NPC.

Example language file layout

The wiki does not use screenshots for language files. The generated language folder contains one message file per supported locale.

plugins/NobleSteeds/language/

plugins/NobleSteeds/
└── language/
    ├── messages_en.yml
    ├── messages_de.yml
    ├── messages_es.yml
    ├── messages_fr.yml
    ├── messages_it.yml
    ├── messages_ja.yml
    ├── messages_ko.yml
    ├── messages_nl.yml
    ├── messages_pl.yml
    ├── messages_ru.yml
    ├── messages_sv.yml
    ├── messages_uk.yml
    ├── messages_zh_cn.yml
    └── messages_zh_tw.yml

Does NobleSteeds require Redis?

No for normal single-server installs. Keep network.enabled: false and NobleSteeds can use SQLite without Redis. Redis is required only when you enable NETWORK_NODE mode for multiple backend servers sharing NobleSteeds data.

Does it require Vault?

No for claiming, managing, calling, storage, and many player workflows. Vault plus an economy provider is required for money-based market purchases, admin shop purchases, and paid revive when those features are configured to require economy.

Does it require Citizens?

No. Citizens is optional and only needed for NPC access points. If Citizens is not installed, players can still use commands and GUIs normally.

Does it support Paper and Purpur?

Yes. NobleSteeds is documented for Spigot-compatible backend servers, including Paper and Purpur, across the supported Minecraft version range listed in the overview.

Does it support Velocity networks?

Yes, by running NobleSteeds on backend servers in NETWORK_NODE mode with shared MySQL/MariaDB storage and Redis messaging. NobleSteeds does not require a proxy-side plugin for this documented network mode.

Can players sell horses?

Yes, when the player market is enabled and usable. Listed mounts enter market state, which prevents normal owner actions until the listing sells or is removed.

Can admins create shop horses?

Yes. Admins can create shop entries with /ns admin shop add and manage them through command output or the admin shop GUI. Entries include variant, speed, jump, health, breeding quality, price, and name.

Can users share or give horses?

Yes. Sharing controls who can access a mount, while giving transfers ownership through a pending request. The receiver accepts from /ns receive and needs a free active mount slot.

What versions are supported?

This wiki documents NobleSteeds 1.0.0 for Minecraft server versions 1.18.2 through 1.21.11, plus 26.1.x compatibility, on Java 17 or newer.

Where do screenshots belong?

Upload screenshots to the NobleSteeds GitHub repository folder assets/wiki/1.0.0/. This wiki reads them from https://raw.githubusercontent.com/Rismr1/NobleSteeds/main/assets/wiki/1.0.0/.