NobleSteeds Wiki

Overview

NobleSteeds 1.0.0 is a completely free, vanilla-friendly mount management plugin for Spigot, Paper, and Purpur servers. It adds persistent ownership and management tools around Minecraft mounts while retaining their normal vanilla entities and statistics.

Players can claim supported mounts and manage them through commands and inventory menus. NobleSteeds includes calling, stable locations, storage, sharing, transfers, revive and release workflows, rarity, breeding quality, a player market, and an administrator-created shop. Each system can be configured for the server using it.

Requirements

• Java 17 or newer.
• A Spigot, Paper, or Purpur backend server.
• Minecraft 1.18.2 through 1.21.11, plus the supported 26.1.x server line.
• Write access to the server's plugins directory so configuration, language, and storage files can be created.

NobleSteeds does not require Vault, Citizens, or MailboxGUI for its core mount features.

• Vault is optional: install Vault and a compatible economy only for configured money-based market, shop, or revive costs.
• Citizens is optional: install it only when using NobleSteeds NPC access points.
• MailboxGUI is optional: it can be used for configured market payout delivery; normal fallback payout behavior remains available without it.

Installation

1. Stop the Minecraft server completely.
2. Download the NobleSteeds JAR from the official NobleSteeds download page.
3. Place NobleSteeds-1.0.0.jar in the server's plugins folder.
4. Install any optional integrations you intend to use before the first startup.
5. Start the server and wait for NobleSteeds to finish enabling.
6. Read the startup console and confirm that NobleSteeds selected an available storage provider.

plugins/
├── NobleSteeds-1.0.0.jar
└── NobleSteeds/
    ├── config.yml
    ├── language/
    └── data/

The plugin creates plugins/NobleSteeds/config.yml, its bundled language files, and the selected storage location. The default provider is SQLite and its default database path is plugins/NobleSteeds/data/data.sql.

First Setup

1. Stop the server after the first successful startup.
2. Open plugins/NobleSteeds/config.yml and keep a backup before changing it.
3. Confirm storage.type. SQLite is the recommended default for a normal installation; YAML and MySQL/MariaDB are also supported.
4. Review the default claim limit, enabled mount systems, storage, market, shop, revive, language, and optional-integration settings.
5. Assign player and staff permissions through the server's permissions plugin.
6. Start the server and check the console again for configuration, storage, or integration warnings.
7. Run /ns admin storage current as an administrator to confirm the configured and active storage provider.
8. Use /ns to confirm player help loads, then test claiming with a supported adult tamed mount before opening the plugin to players.

The default language is English. Player client-locale detection is enabled by default, so a bundled matching language file is used when available and English is used as the fallback.

Supported Mounts

NobleSteeds 1.0.0 can claim these vanilla entity types:

• Horses, including every vanilla horse color and style.
• Donkeys.
• Mules.
• Llamas.
• Trader llamas.
• Skeleton horses.
• Zombie horses.

The mount must be an adult and tamed before a player can claim it. The player must also be riding the mount. Baby mounts, untamed mounts, unsupported entities, and mounts already claimed by another player are rejected safely.

Claiming a Mount

Players need the noblesteeds.claim permission, which is granted by default.

1. Tame a supported adult mount.
2. Mount and ride it.
3. Run /ns claim, or provide a name with /ns claim <name>.
4. Read the confirmation showing the assigned slot, rarity, and current claim count.
5. Open /ns manage to continue managing the claimed mount.

Examples

/ns claim
/ns claim Silvermane
/ns claim Storm Runner

A name supplied after /ns claim takes priority. If no name is supplied, NobleSteeds keeps the mount's existing custom name. If it has no custom name, the plugin selects a configured random name. When random naming is disabled or its list is empty, the fallback name is NobleSteed.

A successful claim saves the mount's identity, owner, numbered slot, location, vanilla statistics, calculated rarity, breeding quality, inventory snapshot, and management state. The first successfully claimed mount becomes the player's favorite.

Claim Limits

The default claim limit is 7. NobleSteeds assigns the first available numbered mount slot from 1 through the player's effective limit. When no slot is available, another mount cannot be claimed until a slot becomes available or the player's permission limit is increased.

claim-limits:
  default: 7

Servers can give individual groups larger limits with noblesteeds.claims.<amount>. NobleSteeds reads the player's effective permissions and uses the highest valid numeric value above the configured default.

Permission examples

noblesteeds.claims.10
noblesteeds.claims.15
noblesteeds.claims.25

• The wildcard node noblesteeds.claims.* does not set a numeric limit by itself.
• Invalid or nonnumeric suffixes are ignored.
• Giving several numeric nodes uses the highest number.
• A permission value lower than the configured default does not reduce the player's limit.

Opening My Horses

The My Horses menu is the central place for viewing and managing claimed mounts. Players need the noblesteeds.manage permission, which is granted by default. The commands can only be used by a player in game.

Commands

/ns manage
/ns myhorses

Both commands open the same 54-slot inventory. Each page contains up to 14 numbered mount slots, with Previous Page and Next Page controls at the bottom. Empty numbered slots remain visible so players can see where their next claimed mount will be placed.

The menu header shows the favorite mount, active mount count, current claim limit, and stored mount count. If the player has no usable favorite, the header displays that no favorite is available. A market-listed favorite is not treated as a usable favorite while its listing is active.

Mount Information

Each occupied slot identifies the mount and displays its current recorded details:

• Name and numbered owner slot.
• Mount type and configured rarity.
• Overall score, speed, jump, and health stat bars.
• Breeding quality when that mount is eligible to display it.
• Alive or dead status.
• Sharing status.
• Whether a stable is set and whether the mount is currently at it.
• Favorite status, marked with a gold star.
• Market status, including the listing price when listed.

A normal manageable mount appears as a saddle. A mount listed on the player market appears separately as an emerald and cannot be opened from My Horses while the listing remains active. Stored mounts are counted in the header but are managed from the Mount Storage menu rather than as active entries here.

Management Actions

Click a saddle entry to open that mount's management menu. The overview at the top repeats the mount's identity, statistics, and current status. The available controls are:

• Call: bring the mount to the player when calling conditions are met.
• Set Favorite: make this the player's favorite mount.
• Revive: restore a dead mount when revival is enabled and any configured requirements are met.
• Set Stable: save the player's current location as the mount's stable.
• Send to Stable: send the mount to its saved stable; shift-click this control to toggle Auto-Stable when that feature is enabled.
• Unset Stable: remove the stable location and clear Auto-Stable for the mount.
• Share: open the mount sharing controls.
• Store: move the mount into storage when the server has enabled the management-menu storage button.
• Rename: begin the in-chat rename process for this mount.
• Stats: review the mount's detailed recorded statistics.
• Release: open a separate confirmation menu before permanently removing ownership.
• Back: return to the My Horses list.

Calling Mounts

Calling brings an owned active mount to the player's current location. Players need the noblesteeds.call permission, which is granted by default. Run the command without an identifier to call the favorite mount, or supply a numbered slot or exact mount name to call a specific mount.

Examples

/ns call
/ns call 3
/ns call Silvermane
/ns call Storm Runner

The same Call action is available after selecting a mount in /ns manage. On a successful call, NobleSteeds finds the existing entity or safely restores it from its saved profile, moves it to the player, reaffirms its vanilla owner, marks it as no longer at stable, and saves the updated snapshot.

• The mount must be alive.
• A market-listed mount cannot be called.
• Calling without an identifier requires an available favorite mount.
• Calls use a per-player cooldown. The default is 4.0 seconds.
• The source and destination chunks must be available for the move to finish.

horse-management:
  summon-cooldown-seconds: 4.0

Stable Locations

A stable is a saved destination for one specific mount. Players need the noblesteeds.stable permission, which is granted by default. Set the stable while standing at the exact location where the mount should be sent.

Stable command examples

/ns stable set 3
/ns stable send 3
/ns stable unset 3

/ns stable set Silvermane
/ns stable send Silvermane
/ns stable unset Silvermane

1. Use /ns stable set <slot|name> at the intended destination.
2. Use /ns stable send <slot|name> whenever the living mount should return there.
3. Use /ns stable unset <slot|name> to remove the saved destination.

These controls are also available in the mount management menu as Set Stable, Send to Stable, and Unset Stable. Sending loads the required location, ejects any rider, teleports the mount, records that it is at stable, and refreshes its saved state. Unsetting a stable also clears Auto-Stable for that mount.

• Dead mounts cannot be sent to a stable.
• The mount must have a stable before it can be sent.
• The saved stable world must still exist and be loaded by the server.
• Stored and market-listed mounts cannot use stable management commands.

Auto-Stable

Auto-Stable sends selected mounts to their saved stable when their owner logs out. It must first be enabled globally by the server administrator and then enabled separately for each mount. The feature is disabled by default.

horse-management:
  auto-stable:
    enabled: false
    queue-delay-ticks: 20

Player commands

/ns stable auto 3 on
/ns stable auto 3 off

/ns stable auto Silvermane on
/ns stable auto Silvermane off

Players can also shift-click Send to Stable in the mount management menu to toggle Auto-Stable. The control is hidden or rejected when the server-wide feature is disabled, and the mount must already have a stable location.

At logout, NobleSteeds only queues a mount when all of these conditions are true:

• The mount is alive and not stored.
• The mount has a stable location.
• The mount is not listed on the player market.
• Auto-Stable is enabled for that individual mount.

Eligible mounts are processed one at a time. The default queue delay is 20 ticks, or one second, between a player's mounts. This reduces the amount of chunk loading and entity work performed at once.

Storage Overview

Mount Storage lets players keep owned mounts outside their active claim slots. A stored mount remains in the player's saved NobleSteeds data, but its live entity is removed from the world until the mount is restored. This frees its numbered active slot for another claimed or restored mount.

Players need the noblesteeds.storage permission, which is granted by default. When storage and command access are enabled, open the 54-slot storage menu with:

/ns storage

The menu shows the stored count, active count, pages, and up to 21 stored mounts per page. Each entry includes the mount's name, former slot, type, rarity, overall score, breeding quality when applicable, speed, jump, health, life status, and market-listing status. Use Store Active Mount to choose an active mount, the arrows to change pages, or Back to return to My Horses.

horse-storage:
  enabled: true
  command-enabled: true
  manage-button-enabled: true
  slots: 10

• enabled controls the player storage system.
• command-enabled controls access through /ns storage.
• manage-button-enabled controls the Store button in an individual mount's management menu.
• slots sets each player's storage capacity; the default is 10.

Storing Mounts

Players can store an active mount in either of two ways:

1. Open /ns storage, select Store Active Mount, and click an eligible saddle entry.
2. Open /ns manage, select a mount, and click Store when the management-menu button is enabled.

Before removing the entity, NobleSteeds loads its saved chunk when possible and refreshes the profile from the live mount. This preserves the current name, vanilla statistics, variant, saddle, armor, chest inventory, item metadata, and other saved mount details. Any rider is ejected and the live entity is then removed.

Storing a mount also changes its management state:

• The mount no longer occupies an active numbered slot.
• Favorite status is removed.
• Auto-Stable is disabled for that mount.
• Global and specific-player sharing access is cleared.
• The mount is marked as not currently at stable.

Storage rejects the action when the system is disabled, the storage capacity is full, the management button is disabled for that route, the profile is no longer valid, or the mount has an active player-market listing.

Restoring Mounts

Open /ns storage and click a normal saddle entry to restore it. NobleSteeds selects the first available numbered slot within the player's effective claim limit, changes the profile back to active, and respawns the mount at the player's current location using its saved vanilla data and inventory.

A restore requires all of the following:

• The stored profile must still belong to the player.
• The player must have a free active slot within their current claim limit.
• The stored mount must not have an active market listing.
• The server must be able to create the entity safely in the player's current world and location.

Market-listed stored mounts appear as emerald entries and cannot be clicked for restoration. Remove the listing through the Player Market first. If entity creation fails after a slot is assigned, NobleSteeds returns the profile to storage instead of leaving a broken active entry.

A restored mount does not automatically regain its former slot, favorite selection, sharing list, or Auto-Stable setting. Reconfigure those options after restoration if they are still wanted.

Sharing Access

Sharing lets other players interact with and ride a claimed mount without changing its owner. Open /ns manage, select the mount, and choose Share. The Share menu provides three access modes:

• Private: only the owner and authorized administrators can use the mount. Selecting Private also clears the specific-player list.
• Specific Players: only the owner, administrators, and players on that mount's saved share list can use it.
• Everyone: any player can interact with and ride the mount while it remains available.

In Specific Players, choose Add Player and type a known player name in chat. The player does not need to be online, but they must exist in the server's known player data. Click a listed name to remove it, use the page controls for longer lists, and choose Use Specific List to make that list the active access mode. Type cancel when prompted to leave chat input without making a change.

A listed or stored mount cannot be ridden through sharing. Storing, transferring, or releasing a mount clears its specific-player sharing data; storing and transferring also return its general sharing state to private.

Giving a Mount

Giving starts an ownership-transfer request; ownership does not change until the receiving player accepts it. The giver needs noblesteeds.give, which is granted by default, and both players must be online.

Command examples

/ns give 3 Alex
/ns give Silvermane Alex
/ns give Storm Runner Alex

The final argument is the receiving player's name, so mount names containing spaces are supported. Players can also select Give Mount from the Share menu and type the recipient's name in chat.

A request is rejected when:

• The mount does not belong to the giver or is no longer available.
• The mount has an active market listing.
• The recipient is unknown, offline, or is the giver.
• The recipient has no free active slot within their claim limit.

Receiving a Mount

The recipient needs noblesteeds.receive, which is granted by default. Open the pending-transfer menu and click an offer to accept it:

/ns receive

NobleSteeds validates the offer again at acceptance time. The giver must still be online and own the mount, the mount must remain unlisted, and the recipient must still have a free active slot. Invalid offers are removed or rejected safely.

When accepted, the mount receives the first free numbered slot under the new owner. NobleSteeds updates the live entity's vanilla owner when it is loaded and preserves the mount's identity, name, type, inventory snapshot, statistics, rarity, life state, and stable information. The previous favorite status, sharing access, and Auto-Stable selection are cleared, and the mount is active rather than stored for its new owner.

Reviving Mounts

Revive creates a replacement entity for a dead active mount using its saved vanilla type, variant, statistics, inventory, name, and ownership data. Players need noblesteeds.revive, which is granted by default, and the server must have revival enabled.

Command examples

/ns revive 3
/ns revive Silvermane
/ns revive Storm Runner
/ns revive confirm

Revival is also available from the selected mount's management menu. The mount must be dead, active rather than stored, owned by the player, and not listed on the market. The replacement appears at the player's current location.

Revival is free by default. When paid revival is enabled, Vault and a compatible economy are required. The price is calculated from the configured base price, rarity multiplier, overall-score scale, and minimum and maximum limits. Command-based paid revival displays the price first and requires /ns revive confirm.

horse-management:
  revive:
    enabled: true
    cost:
      enabled: false
      base-price: 1000.0
      score-scale: 1.0
      min-price: 1.0
      max-price: 100000000.0

Ownership and balance are checked again before completion. If money was withdrawn but entity creation or profile replacement fails, NobleSteeds attempts to refund the revive payment and removes any incomplete replacement entity.

Releasing Mounts

Releasing removes a mount from the player's NobleSteeds ownership and active slots. Open /ns manage, select the mount, choose Release, and review the separate confirmation menu. The menu displays the mount name, slot, rarity, favorite, sharing, and life status before the destructive action is accepted.

• Confirm Release completes the ownership removal.
• Cancel returns to the mount management menu without changing anything.
• Any player-market listing for the mount is removed during confirmation.
• Favorite, sharing, Auto-Stable, and other NobleSteeds records for the mount are cleaned up.
• The remaining active slots are compacted after the release.

Cleanup Behavior

When the released physical mount is loaded, NobleSteeds clears its former vanilla owner while leaving the entity tamed. This prevents the old NobleSteeds owner from remaining attached through Minecraft's vanilla ownership data and allows the released mount to be claimed again later.

If the entity is loaded at release time, cleanup happens immediately. If its chunk is unloaded, NobleSteeds records the entity UUID in plugins/NobleSteeds/data/released-mount-cleanup.yml. Cleanup is completed later when the mount's chunk loads, the entity spawns, or a player interacts with it; the pending record is then removed.

Releasing a dead profile still removes its NobleSteeds data, but there may be no living physical entity to clean or reclaim. Releasing is therefore different from storing: storage preserves an owned profile for later restoration, while release ends ownership entirely.

Rarity System

NobleSteeds converts a mount's vanilla movement speed, jump strength, and maximum health into separate ratings from 0 to 100. Values below or above the configured vanilla ranges are clamped to that scale. The three ratings are then combined using configurable weights to produce the Overall Score.

Overall Score =
  (Speed Rating × 40 + Jump Rating × 35 + Health Rating × 25)
  ÷ 100

The default tier thresholds use the highest minimum score the mount reaches:

• Common: 0.0–20.99
• Uncommon: 21.0–40.99
• Rare: 41.0–60.99
• Epic: 61.0–80.99
• Legendary: 81.0–94.99
• Mythic: 95.0–100.0

rarity:
  enabled: true
  weights:
    speed: 40.0
    jump: 35.0
    health: 25.0

Administrators can change stat ranges, weights, tier minimums, and display names in config.yml. The weights are divided by their combined total, so they do not have to add up to exactly 100. Rarity must remain enabled for players to claim mounts.

Breeding Quality

Breeding Quality is a separate 0–100 value used for breeding outcomes. It does not directly affect Overall Score or rarity. It is displayed for horses, donkeys, llamas, and trader llamas; mules, skeleton horses, and zombie horses do not display it.

Newly generated or claimed eligible mounts receive a value from the configured random range unless they already carry a NobleSteeds breeding-quality tag. For valid breeding pairs, the child quality combines the parents' average with a new random value. By default, inheritance contributes 70% and the random value contributes 30%, with a 10% chance to add 10 extra points. Final values are clamped to 0–100.

breeding-quality:
  enabled: true
  generated-range:
    min: 0.0
    max: 100.0
  offspring:
    inheritance-weight: 70.0
    high-quality-bonus-chance: 10.0
    high-quality-bonus-amount: 10.0

Supported parent combinations are:

• Horse with horse.
• Horse with donkey, in either parent order.
• Donkey with donkey.
• Llama with llama.

When outcome boosting is enabled, the parents' average quality can move the child's vanilla speed, jump, and health closer to their configured maximums. At 100% average parent quality, the default maximum boost moves each stat up to 20% of its remaining distance toward that maximum. Unclaimed parents use the configured fallback quality, which is 0.0 by default.

Mount Statistics

Players with noblesteeds.info, granted by default, can ride a supported mount and run /ns info. The chat report shows its name, type, variant, rarity, Overall Score, speed, jump, health, and Breeding Quality when eligible.

/ns info

Each percentage is rendered as a ten-segment bar. NobleSteeds recalculates the live mount's vanilla statistics for this report. Claimed mounts use their saved Breeding Quality; eligible unclaimed mounts retain or receive an entity tag for that value.

Saved stat bars also appear throughout My Horses, Mount Storage, the player market, the administrator shop, and mount-management screens. Auto-save periodically refreshes loaded claimed mounts so changes to their vanilla data remain current.

Player Market

The Player Market lets players list owned mounts for other players to buy. It is separate from the administrator-created shop. Players need noblesteeds.market, granted by default, and can open the market with:

/ns market

The hub provides Browse Listings, List a Mount, My Listings, and Receive Item Payouts. Both active and stored living mounts can be listed. Select the source, choose an eligible mount, choose Vault or item currency when available, and enter the price in chat. Type cancel to stop price entry.

Vault price: 2500
Item price: DIAMOND:32
Combined item price: DIAMOND:32,EMERALD:5,GOLD_NUGGET:10

• Vault prices default to a configured range of 1.0 through 100000000.0.
• Item currency is disabled by default and supports one to three valid item-and-amount entries.
• Dead, already-listed, missing, or differently owned mounts cannot be listed.
• Listing removes the live entity when loaded and disables Auto-Stable for that mount.
• Listed mounts cannot be ridden, called, given, renamed, restored, or normally managed.

A buyer cannot buy their own listing and needs the full price plus an available active slot. On success, the mount is spawned at the buyer, transferred into the first free slot, and assigned to the buyer as its vanilla owner. My Listings lets the seller remove a listing; configured expiration can also return listings automatically. The default expiration value is 0, meaning listings do not expire.

Market Payouts

For a Vault sale, NobleSteeds normally deposits the full listing price into the seller's economy account. Servers can instead enable MailboxGUI money delivery. If MailboxGUI is missing or delivery fails, NobleSteeds falls back to the Vault deposit.

market:
  send-mailboxgui-money:
    enabled: false
    from: "&a&lNobleSteeds Market Payout"
    delay: 0

Item-currency sales create a saved payout for the seller by default. Claim it from Receive Item Payouts in /ns market, or open it directly with:

/ns market receive

When item-currency.send-mailboxgui-package is enabled, NobleSteeds first attempts to send the items as a MailboxGUI package. If MailboxGUI is unavailable or package delivery fails, the payout returns to the saved Receive Item Payouts flow. Each payout records the price, sold mount, and buyer and is removed after it is claimed.

Admin Shop

The Admin Shop is a server-controlled catalog rather than a player resale market. Players need noblesteeds.shop, granted by default, and use /ns shop to browse enabled entries. Each entry can define the mount type, variant, name, speed, jump, health, Breeding Quality, and Vault or item price.

A buyer needs the required currency and a free active slot. A successful purchase creates a new adult, tamed mount at the player's location, applies the configured variant and statistics, claims it to the player, and assigns its numbered slot. If spawning or claiming fails after payment, NobleSteeds refunds the payment.

Administrators need noblesteeds.admin.shop or the main administrator permission. The Admin Tools shop menu lists enabled and disabled entries: left-click toggles an entry and right-click removes it. Commands can list, add, or remove entries.

/ns admin shop
/ns admin shop list
/ns admin shop add --v BROWN --s 70 --j 65 --h 80 --b 75 --price 2500 --name Royal Steed
/ns admin shop add --v WHITE --s 85 --j 75 --h 70 --b 90 --price DIAMOND:32 --name Frostwind
/ns admin shop remove <shopId>

Shop data is stored in plugins/NobleSteeds/data/shop.yml for local YAML or SQLite installations. MySQL installations save shop entries through the shared database provider. The shop is enabled by default and currently requires Vault and a registered economy provider to open, including for item-priced entries.

Citizens Requirements

Citizens is an optional soft dependency. NobleSteeds continues working normally when Citizens is absent, but NPC registration and NPC access remain unavailable. Install a Citizens build compatible with the server, restart the server, and confirm that NobleSteeds reports its optional noblesteeds Citizens trait as registered.

NobleSteeds does not create or select the NPC's skin, name, entity type, location, or other Citizens behavior. Create and position the NPC through Citizens first, then use NobleSteeds Admin Tools to assign exactly one Storage, Market, or Shop access type.

1. Open /ns admin tools.
2. Select NPC Registration.
3. Choose Storage NPC, Market NPC, or Shop NPC.
4. Enable that access type if it is currently disabled.
5. Select Register NPC.
6. Right-click the intended Citizens NPC.
7. Use Manage Registered NPCs to verify its Citizens ID, name, and assigned type.

Registration is saved in the Citizens registry as a NobleSteeds trait. Starting a registration or deregistration selection can be cancelled by left-clicking the air or a block. Administrators can also deregister by selecting the registered NPC or through the registered-NPC management list.

Storage NPCs

horse-storage:
  enabled: true

storage-npc:
  citizens:
    enabled: false

A registered Storage NPC opens the same Mount Storage menu as /ns storage. The player must have noblesteeds.storage, and the main storage system must be enabled. The horse-storage.command-enabled setting only controls the command, so a server can disable /ns storage and offer storage exclusively through NPCs.

Storage NPCs do not require Vault. Storage capacity, eligible mounts, restoration, market-listing restrictions, and all other storage rules remain unchanged.

Market NPCs

market:
  enabled: true
  command-enabled: true
  npc:
    enabled: false

A registered Market NPC opens the full Player Market hub. The player still needs noblesteeds.market, and the market, Vault, and a compatible economy must be available. Listing, buying, My Listings, item payouts, price limits, and active-slot requirements work exactly as they do through /ns market.

market.command-enabled can be disabled while NPC access remains enabled, allowing a server to make the market location-based. If the market or economy becomes unavailable, right-clicking the NPC does not open a partially working market.

Shop NPCs

shop:
  enabled: true
  command-enabled: true
  npc:
    enabled: false

A registered Shop NPC opens the administrator-created mount catalog. The player still needs noblesteeds.shop, and the shop, Vault, and a compatible economy must be available. Enabled entries, prices, free-slot checks, spawn safety, refunds, and purchase behavior are identical to /ns shop.

Disable shop.command-enabled when players should reach the shop only by visiting its NPC. Deregistering the NPC removes the NobleSteeds trait but does not delete the underlying Citizens NPC.

Command Overview

NobleSteeds uses /noblesteeds as its main command. The aliases /ns, /steed, and /steeds run the same command. Players need noblesteeds.command for the base command, and each feature checks its own permission.

/ns
/ns help 1
/ns help 2
/ns help 3

Help is split across three pages covering core mount actions, ownership tools, and utility systems. Commands that identify a mount generally accept its numbered slot or exact display name. Tab completion suggests available actions, owned mounts, online transfer recipients, and valid states where supported.

Command Reference

Normal feature commands are player-only. Market, Shop, Storage, Auto-Stable, rarity, and revive commands can also be unavailable because of server configuration or a missing optional dependency even when the player has permission.

Admin Menu

Administrators with noblesteeds.admin.tools or the main noblesteeds.admin permission can open the in-game control center with:

/ns admin tools

The menu provides these sections:

• Player Mounts: browse owners and administer active or stored mounts.
• Market Management: inspect and remove player listings when the market and economy are available.
• Shop Management: enable, disable, or remove administrator-created shop entries.
• NPC Registration: enable access types and register or deregister Citizens NPCs.
• Reload Plugin: reload configuration, storage settings and provider, mount data, market data, language files, and integration hooks.

/ns admin and /ns admin help <page> provide four pages of command help. Console can use applicable command-based tools, but inventory menus, targeting, spawning, and mounted editing require an in-game player.

Mount Administration

Player Mounts lists every owner with active or stored profiles. Selecting an owner opens separate active and stored collections with full statistics and management state.

In an owner's active-mount menu:

• Left-click opens a confirmation to remove the NobleSteeds claim.
• Right-click stores the mount for that owner when storage has capacity.
• Shift-right-click starts the mount property editor.
• Add Mounted Mount lets the administrator assign the mount they are riding to the selected owner.

In the stored-mount menu:

• Left-click restores an unlisted mount into the owner's first free active slot and spawns it at the administrator.
• Right-click starts the stored-profile property editor.
• Market-listed stored mounts must be unlisted before restoration or editing.

Direct mount commands

/ns admin spawn
/ns admin spawn --v BROWN --s 70 --j 65 --h 80 --b 75
/ns admin edit --v WHITE --s 85 --j 70 --h 90 --b 80
/ns admin clearclaim

Spawn creates a wild adult supported mount at the administrator with configurable variant and percentage-based statistics. Edit changes the supported mount currently being ridden and refreshes its saved NobleSteeds profile when claimed. Omitted edit tags keep their current values. A type change requires the GUI editor.

Clear Claim targets the mount being ridden or a supported mount within six blocks near the crosshair. It removes any NobleSteeds claim and clears the vanilla owner while leaving the entity tamed. Use it carefully for stale or incorrect ownership records.

Shop Administration

The Admin Tools shop page displays every enabled and disabled catalog entry. Left-click toggles availability, right-click permanently removes the entry, and page controls navigate larger catalogs. The command interface supports listing, creation, and removal by its short or full identifier.

/ns admin shop
/ns admin shop list
/ns admin shop add --v BROWN --s 70 --j 65 --h 80 --b 75 --price 2500 --name Royal Steed
/ns admin shop add --v WHITE --s 85 --j 75 --h 70 --b 90 --price DIAMOND:32 --name Frostwind
/ns admin shop remove <shopId>

Creation values define the variant, speed, jump, health, Breeding Quality, price, and display name of mounts produced by that entry. Item prices require the global item currency system. Price and percentage inputs are validated or clamped to configured limits.

Update and Utility Commands

Player Permissions

These individual player permissions default to true:

noblesteeds.player is a convenience parent containing every normal player node above. It defaults to false because the individual nodes already default to true; servers can use it as one explicit group grant after changing individual defaults through their permissions plugin.

Admin Permissions

Administrator permissions default to server operators. The main noblesteeds.admin node includes all sub-permissions below:

• noblesteeds.admin.tools — administrator GUI tools and their menu actions.
• noblesteeds.admin.storage — storage status and provider conversion.
• noblesteeds.admin.update — update checks, preparation, and confirmation.
• noblesteeds.admin.reload — NobleSteeds-specific reload.
• noblesteeds.admin.spawn — custom administrator mount spawning.
• noblesteeds.admin.edit — live and saved mount property editing.
• noblesteeds.admin.clearclaim — stale NobleSteeds and vanilla ownership cleanup.
• noblesteeds.admin.shop — shop entry listing, creation, toggling, and removal.

Claim Limit Permissions

The configured claim-limits.default value is the baseline, which is 7. Grant noblesteeds.claims.<amount> to increase a player's active mount capacity.

noblesteeds.claims.10
noblesteeds.claims.15
noblesteeds.claims.25

• NobleSteeds uses the highest valid numeric claim-limit permission.
• A value below the configured default does not lower the player's capacity.
• Nonnumeric or invalid suffixes are ignored.
• noblesteeds.claims.* describes the permission pattern but does not supply a numeric amount by itself.
• Changing a limit does not delete existing profiles; restoration and new claims require a free slot inside the effective limit.

Configuration Overview

NobleSteeds creates plugins/NobleSteeds/config.yml on first startup. The bundled file uses config-version: 1 and includes comments explaining each supported setting. Stop the server and make a timestamped backup before editing a production configuration.

plugins/NobleSteeds/config.yml
plugins/NobleSteeds/config.yml.bak-YYYYMMDD-HHMMSS

The top-level sections control:

• Default language and client-locale detection.
• YAML, SQLite, or MySQL storage.
• Breeding Quality, random names, claim limits, and storage capacity.
• Automatic mount snapshots and optional Citizens access.
• Player Market, item currency, administrator shop, calling, stables, and revival.
• Rarity ranges, weights, and tiers.
• The website-powered update checker and release channel.

Values are read during plugin startup and by the NobleSteeds-specific reload process. Unknown enum values, malformed numbers, unavailable providers, or missing dependencies can cause a setting to fall back, a feature to become unavailable, or startup to stop with a protective error. Read the console after every configuration change.

Feature Settings

Complete Default Config

This is the complete default config.yml bundled with NobleSteeds 1.0.0, including every comment and default value. Copy only the settings you intend to change, or compare this block with the generated file after an update.

# ============================================================
# NobleSteeds Configuration
# ============================================================
#
# NobleSteeds is a mount management plugin with claiming,
# storage, rarity, breeding quality, stable management, sharing,
# revive/release tools, item currency, MailboxGUI payouts,
# market, shop, and optional Citizens NPC access.
#
# Storage note:
# - SQLITE is recommended for normal single-server installs.
# - MYSQL is available for servers that prefer database storage.
# - YAML is available for simple flat-file setups.
#
# Economy note:
# Vault is optional for the plugin overall.
# Market, Shop, and paid revive features require Vault unless
# the feature is disabled or using item-currency where supported.
#
# Citizens note:
# Citizens is optional. NPC features only work when Citizens is
# installed and the matching NPC setting is enabled.
#
# MailboxGUI note:
# MailboxGUI is optional. If MailboxGUI payout settings are enabled
# but MailboxGUI is not detected, NobleSteeds disables those settings
# safely and falls back to normal payout behavior.
#
# ============================================================

config-version: 1

# ============================================================
# Locale / Language
# ============================================================
locale:
  # Default language code.
  #
  # This decides which language file is used when player locale
  # detection is disabled or when a player's client language is
  # not supported by NobleSteeds.
  #
  # Example:
  # en = language/messages_en.yml
  default: en

  # If true, NobleSteeds tries to use each player's Minecraft
  # client language.
  #
  # If false, all players use locale.default.
  auto-detect-player-locale: true

# ============================================================
# Storage
# ============================================================
storage:
  # Main storage provider.
  #
  # YAML:
  # Stores data in flat YAML files under the configured folder.
  #
  # SQLITE:
  # Recommended default for single-server installs.
  # Stores data in a local SQLite database file.
  #
  # MYSQL:
  # Stores data in a MySQL/MariaDB database.
  type: "SQLITE"

  yaml:
    # Folder used when storage.type is YAML.
    folder: "data/yaml"

  sqlite:
    # SQLite database file used when storage.type is SQLITE.
    file: "data/data.sql"

  mysql:
    # MySQL/MariaDB connection settings used when storage.type is MYSQL.
    host: "localhost"
    port: 3306
    database: "noblesteeds"
    username: "root"
    password: ""
    use-ssl: false

    # Prefix for NobleSteeds database tables.
    #
    # Useful if multiple plugins or multiple test installs share
    # the same database.
    table-prefix: "noblesteeds_"

# ============================================================
# Breeding Quality
# ============================================================
breeding-quality:
  # Enables NobleSteeds Breeding Quality.
  #
  # Breeding Quality is separate from rarity.
  # It does not directly affect rarity score.
  # It is used to improve breeding outcomes by nudging child
  # vanilla stats upward.
  enabled: true

  generated-range:
    # Random Breeding Quality range for newly claimed/generated mounts.
    min: 0.0
    max: 100.0

  offspring:
    # How much the parents' average Breeding Quality influences
    # the child's Breeding Quality.
    #
    # 70.0 means:
    # - 70% inherited from parents
    # - 30% random from generated-range
    inheritance-weight: 70.0

    # Chance and amount for an extra Breeding Quality bonus.
    high-quality-bonus-chance: 10.0
    high-quality-bonus-amount: 10.0

  outcome-boost:
    # If enabled, high parent Breeding Quality can improve the
    # child's vanilla speed, jump, and health outcomes.
    enabled: true

    # If an unclaimed valid parent is bred, this value is used
    # for that parent's Breeding Quality.
    #
    # Claimed NobleSteeds mounts use their saved Breeding Quality.
    unclaimed-parent-quality: 0.0

    # At 100% average parent Breeding Quality, child stats move
    # this percent of the remaining distance toward the configured
    # max stat range.
    #
    # Example:
    # 20.0 means up to 20% closer to max speed/jump/health.
    max-stat-boost-percent: 20.0

# ============================================================
# Random Mount Names
# ============================================================
random-mount-names:
  # If enabled, newly claimed unnamed mounts can receive a random
  # NobleSteeds display name.
  enabled: true

  # Names used by the random name system.
  names:
    - "Aurelius"
    - "Silvermane"
    - "Stormcrest"
    - "Emberhoof"
    - "Starfall"
    - "Ironstride"
    - "Moonwhisper"
    - "Goldenvalor"
    - "Shadowglen"
    - "Nobleheart"

# ============================================================
# Claim Limits
# ============================================================
claim-limits:
  # Default number of active claimed mounts each player can have.
  #
  # Permission nodes can override this per player:
  # noblesteeds.claims.10
  # noblesteeds.claims.15
  # noblesteeds.claims.20
  #
  # If a player has multiple noblesteeds.claims.<number> permissions,
  # NobleSteeds uses the highest number.
  default: 7

# ============================================================
# Horse Storage
# ============================================================
horse-storage:
  # Enables the player mount storage system.
  enabled: true

  # Enables /ns storage.
  command-enabled: true

  # Enables storage access through the player mount management GUI.
  manage-button-enabled: true

  # Number of stored mount slots available to each player.
  slots: 10

# ============================================================
# Mount Auto Save
# ============================================================
mount-auto-save:
  # Periodically refreshes loaded claimed mounts so saddle, armor,
  # chest inventory, custom Bukkit item metadata, variant, stats,
  # name, and location stay current.
  enabled: true

  # Auto-save interval in minutes.
  #
  # Minimum recommended value is 2.
  interval-minutes: 5

# ============================================================
# Storage NPC
# ============================================================
storage-npc:
  citizens:
    # Optional Citizens NPC support for opening /ns storage.
    #
    # Requires Citizens.
    enabled: false

# ============================================================
# Player Market
# ============================================================
market:
  # Enables the player mount market.
  enabled: true

  # Requires Vault and a Vault-compatible economy plugin for
  # normal money-based market use.
  require-economy: true

  # Enables /ns market.
  command-enabled: true

  npc:
    # Optional Citizens NPC support for opening /ns market.
    #
    # Requires Citizens.
    enabled: false

  # Market listing expiration in hours.
  #
  # 0 = listings never expire.
  # Example: 72 = listings expire after 72 hours.
  listing-expiration-hours: 0

  # Vault money price limits for market listings.
  min-price: 1.0
  max-price: 100000000.0
  default-price: 1000.0

  send-mailboxgui-money:
    # If enabled, money payouts from player market sales are sent
    # through MailboxGUI money mail instead of being deposited
    # directly through Vault.
    #
    # If MailboxGUI is missing or unavailable, NobleSteeds disables
    # this safely and falls back to Vault payouts.
    enabled: false

    # Sender display name shown in MailboxGUI money mail.
    from: "&a&lNobleSteeds Market Payout"

    # Delivery delay in seconds.
    #
    # 0 = deliver immediately.
    delay: 0

# ============================================================
# Item Currency
# ============================================================
item-currency:
  # Enables item-currency pricing for supported systems.
  #
  # Market:
  # Players can list mounts using item prices.
  #
  # Shop:
  # Admins can create shop entries using item prices.
  #
  # Supported format:
  # Diamond:3
  # Diamond:3,Emerald:2,Gold_Nugget:2
  #
  # Up to 3 item entries are supported.
  enabled: false

  # If true, item-currency market payouts are sent through
  # MailboxGUI package mail.
  #
  # If false, sellers claim item payouts through:
  # /ns market receive
  #
  # If MailboxGUI is missing or unavailable, NobleSteeds disables
  # this safely and falls back to /ns market receive.
  send-mailboxgui-package: false

  mailboxgui-package:
    # Sender display name shown in MailboxGUI package mail.
    from: "&a&lNobleSteeds Market Payout"

    # Delivery delay in seconds.
    #
    # 0 = deliver immediately.
    delay: 0

# ============================================================
# Admin Shop
# ============================================================
shop:
  # Enables the admin-created NobleSteeds shop.
  #
  # This is separate from the player market.
  # Players buy shop mounts from /ns shop.
  # Admins manage shop entries from /ns admin shop and admin tools.
  enabled: true

  # Enables /ns shop.
  command-enabled: true

  npc:
    # Optional Citizens NPC support for opening /ns shop.
    #
    # Requires Citizens.
    enabled: false

  # Requires Vault and a Vault-compatible economy plugin for
  # normal money-based shop purchases.
  require-economy: true

  # Vault money price limits for shop entries.
  min-price: 1.0
  max-price: 100000000.0
  default-price: 1000.0

# ============================================================
# Horse Management
# ============================================================
horse-management:
  # Cooldown between player mount calls in seconds.
  #
  # Calling a mount may need to load the mount's last known chunk,
  # find and remove the old entity, load the destination chunk,
  # teleport/spawn the mount, and save the updated location.
  #
  # Paper can load chunks asynchronously, but its API does not
  # guarantee an exact completion time. 4 seconds gives the prior
  # mount call time to finish cleanup before the same player starts
  # another call.
  summon-cooldown-seconds: 4.0

  auto-stable:
    # Enables auto-stable on logout.
    #
    # Disabled by default. When enabled, players can toggle
    # auto-stable per mount from /ns stable auto or the manage GUI.
    #
    # Large servers should use this carefully. On logout,
    # NobleSteeds may load each enabled mount's last known chunk and
    # its stable chunk to safely move the entity. This is queued one
    # mount at a time, but busy servers with many players logging out
    # can still see periodic chunk loads and extra RAM use while those
    # chunks are active.
    enabled: false

    # Delay between queued auto-stable mounts for the same player.
    #
    # 20 ticks = 1 second.
    #
    # The default value is recommended for most servers. Lower values
    # can make logout processing busier because NobleSteeds may load
    # chunks for each auto-stabled mount more quickly.
    #
    # Be especially careful if you give VIP or donor ranks high
    # noblesteeds.claims.* limits such as noblesteeds.claims.15 or
    # noblesteeds.claims.20. More claimed mounts means one logout can
    # queue more chunk loads, entity checks, teleports, and saves.
    queue-delay-ticks: 20

  rename:
    # Maximum length for mount rename input.
    max-length: 32

  revive:
    # Enables the Revive Horse button.
    #
    # Revive creates a replacement mount using the saved vanilla
    # stat snapshot from the dead mount profile.
    enabled: true

    cost:
      # If enabled, reviving a mount requires Vault money.
      #
      # Disabled by default.
      enabled: false

      # Base revive price before rarity and score scaling.
      base-price: 1000.0

      # How strongly the mount's 0-100 overall rarity score affects
      # revive price.
      #
      # 0.0 = score does not affect cost.
      # 1.0 = score adds up to +100% cost.
      # 2.0 = score adds up to +200% cost.
      score-scale: 1.0

      # Optional hard limits after revive cost calculation.
      min-price: 1.0
      max-price: 100000000.0

      # Rarity multipliers applied to revive cost.
      rarity-multipliers:
        common: 1.0
        uncommon: 1.15
        rare: 1.35
        epic: 1.75
        legendary: 2.25
        mythic: 3.0

# ============================================================
# Rarity
# ============================================================
rarity:
  # Enables rarity calculation from vanilla mount stats.
  enabled: true

  # Vanilla horse stat ranges used to convert raw values into
  # 0-100 ratings.
  #
  # These are based around normal Minecraft horse ranges.
  stat-ranges:
    speed:
      min: 0.1125
      max: 0.3375
    jump:
      min: 0.4
      max: 1.0
    health:
      min: 15.0
      max: 30.0

  # Overall score weighting.
  #
  # The weights determine how much each stat contributes to the
  # final rarity score.
  weights:
    speed: 40.0
    jump: 35.0
    health: 25.0

  # Rarity tiers.
  #
  # The highest matching min-score becomes the mount's rarity.
  tiers:
    common:
      display-name: "&7Common"
      min-score: 0.0
    uncommon:
      display-name: "&aUncommon"
      min-score: 21.0
    rare:
      display-name: "&9Rare"
      min-score: 41.0
    epic:
      display-name: "&5Epic"
      min-score: 61.0
    legendary:
      display-name: "&6Legendary"
      min-score: 81.0
    mythic:
      display-name: "&dMythic"
      min-score: 95.0

# ============================================================
# Updates
# ============================================================
updates:
  # Website-powered update checker.
  #
  # No license key is required.
  enabled: true

  # Checks for updates during plugin startup.
  check-on-startup: true

  # Notifies admins when they join if an update is available.
  notify-admins-on-join: true

  # Permission required to receive update notifications.
  notify-permission: "noblesteeds.admin"

  # Release channel passed to the website update system.
  channel: "release"

Safe Configuration Changes

1. Stop the server completely for storage, database, file-path, or provider changes.
2. Create a timestamped copy of plugins/NobleSteeds/config.yml and back up the complete plugins/NobleSteeds/data directory or database.
3. Edit YAML with spaces, preserve indentation, and keep text containing formatting codes or punctuation quoted where the default file does.
4. Do not change config-version manually.
5. Use /ns admin storage convert for provider migration instead of changing storage.type and copying records by hand.
6. Start the server and check the full startup log for YAML, storage, economy, Citizens, MailboxGUI, and update-system warnings.
7. Test claiming, management, storage, and any enabled economy or NPC feature with a non-administrator account.

For ordinary non-storage settings, /ns admin reload reloads NobleSteeds. A clean restart is still safer after dependency, database, or structural changes. Do not use the server-wide /reload command as a substitute.

YAML

YAML is the human-readable flat-file option. Set storage.type to YAML. The default folder is plugins/NobleSteeds/data/yaml and contains:

• horses.yml
• market.yml
• market-item-payouts.yml
• horse-shares.yml
• auto-stable.yml

Local shop entries remain in plugins/NobleSteeds/data/shop.yml. YAML is useful for simple installations and manual inspection, but large datasets cause full files to be parsed and rewritten. Never edit these live data files while the server is running.

SQLite

SQLite is the default and recommended provider for a normal single-server installation. It stores NobleSteeds records in plugins/NobleSteeds/data/data.sql using local database tables for mounts, listings, item payouts, sharing, and Auto-Stable. Local shop entries remain in plugins/NobleSteeds/data/shop.yml.

storage:
  type: "SQLITE"
  sqlite:
    file: "data/data.sql"

No external database server or credentials are required. The server runtime must provide the SQLite JDBC driver. Back up the database file only while the Minecraft server is stopped or by using a database-safe backup method.

MySQL

MySQL supports an external MySQL or MariaDB database. NobleSteeds creates prefixed tables for mounts, listings, item payouts, shares, Auto-Stable, and shop entries. The default prefix is noblesteeds_ and MySQL is the provider that stores shop entries through the shared database rather than local shop.yml.

storage:
  type: "MYSQL"
  mysql:
    host: "localhost"
    port: 3306
    database: "noblesteeds"
    username: "root"
    password: ""
    use-ssl: false
    table-prefix: "noblesteeds_"

Create the database and a dedicated least-privilege database user before startup. Grant the account the permissions required to create, alter, select, insert, update, and delete NobleSteeds tables. Confirm firewall, hostname, port, TLS, and credentials. The server runtime must provide the MySQL Connector/J driver.

Storage Conversion

Administrators with noblesteeds.admin.storage can inspect the current provider and convert supported data:

/ns admin storage current
/ns admin storage convert YAML
/ns admin storage convert SQLITE
/ns admin storage convert MYSQL

Conversion initializes the target, copies mounts, market listings, specific shares, and Auto-Stable selections, then reloads each collection to validate record counts. Shop entries are also written when MySQL is the target. If validation succeeds, NobleSteeds writes the new storage.type, saves the config, and reloads the plugin. A conversion to the already-active provider is rejected.

Included Languages

NobleSteeds 1.0.0 includes 14 language files. They are created in plugins/NobleSteeds/language the first time the plugin loads.

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

With automatic detection enabled, a player's Minecraft client locale is tried first. NobleSteeds checks the full normalized code, such as zh_cn, and then its base language, such as en for en_us. An unsupported locale uses locale.default, then English. Console messages always use the default locale. Set automatic detection to false to make every player use the default.

Editing Messages

1. Stop the server and make a timestamped backup of the language file.
2. Edit the generated file under plugins/NobleSteeds/language, not the copy inside the plugin JAR.
3. Preserve YAML indentation, quotes, list markers, placeholders such as %player%, and color codes such as &a.
4. Start the server, or use /ns admin reload after a safe edit, then test the affected menu and message.

Existing custom values are preserved when NobleSteeds starts. If a plugin update adds a missing key to a bundled locale, that key is copied into the generated file. If a selected player locale lacks a requested string or list, NobleSteeds uses the same key from the configured default language. A completely missing key is displayed as its configuration path, which is a useful sign that the file needs checking.

Vault

Vault connects NobleSteeds to a Vault-compatible economy provider. Both Vault and an economy plugin registered through it are required for money-based player-market activity, money-based admin-shop purchases, and paid mount revival. If no economy provider is found, NobleSteeds logs the condition and those economy actions are unavailable; claiming, mount management, storage, sharing, calling, stables, and other non-economy features continue working.

Citizens

Citizens provides optional NPC access points for NobleSteeds storage, the player market, and the admin shop. When Citizens is detected, NobleSteeds registers the noblesteeds trait and can attach an access type to the selected NPC. Enable the relevant setting under storage-npc.citizens.enabled, market.npc.enabled, or shop.npc.enabled, then use the NPC registration controls in /ns admin and right-click the Citizens NPC requested by the prompt.

Storage NPCs open mount storage; market NPCs open the player market; shop NPCs open the admin-created shop. Market and shop access also require their corresponding feature and the economy support needed by that screen. Without Citizens, NPC registration is disabled and the rest of NobleSteeds continues working through commands and menus.

MailboxGUI

MailboxGUI is an optional delivery method for player-market seller payouts. It is not needed to claim or manage mounts. Two independent settings control the integration:

• market.send-mailboxgui-money.enabled sends money-sale proceeds as MailboxGUI money mail instead of depositing them directly through Vault.
• item-currency.send-mailboxgui-package sends item-currency proceeds as a MailboxGUI package instead of holding them for /ns market receive.

Each delivery type has a configurable from display name and non-negative delay in seconds. NobleSteeds uses MailboxGUI's public API, identifies itself as the source plugin, notifies the recipient, and requires the recipient to be a known MailboxGUI player. Both options are disabled by default.

If MailboxGUI or its API is unavailable while either option is enabled, NobleSteeds turns that option off and saves the configuration. Money payouts fall back to direct Vault deposits; item payouts fall back to the pending payout system and /ns market receive. Check the console warning and fix MailboxGUI compatibility before re-enabling delivery.

Update Checker

NobleSteeds checks the official ImagineCraft website release system asynchronously. It does not require a license key. By default, the checker runs at startup and notifies online administrators with noblesteeds.admin three seconds after they join when a newer version is available.

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

Run /ns admin updatecheck with noblesteeds.admin.update to see the installed and latest versions, release type, title, summary, status, and official release link. Startup connection failures remain quiet; the manual command displays the HTTP or connection error for diagnosis.

Updating In Game

1. Back up plugins/NobleSteeds, its active database, and the current NobleSteeds JAR.
2. Read the release notes and run /ns admin updatecheck.
3. Run /ns admin update to check the latest release and prepare confirmation.
4. Run /ns admin update confirm to download and stage the newer JAR.
5. Perform a full server restart. Do not use /reload to complete an update.
6. Confirm the new version at startup and test storage, mount calling, menus, and integrations.

The confirmed download is written as NobleSteeds.jar in Bukkit's configured update folder, normally plugins/update. The running JAR is not replaced. Before staging, NobleSteeds verifies that the download is a JAR containing a plugin.yml named NobleSteeds with a version newer than the running version. The server installs the staged file during the next restart.

Release Channels

Set updates.channel to release, beta, or alpha. The website returns the newest published, downloadable artifact assigned to that exact channel. A Release-channel server does not install Beta or Alpha builds, and a Beta-channel server checks Beta builds rather than automatically combining Beta and Release. Unknown values are treated as release by the website.

• Release: recommended for production servers.
• Beta: feature-complete testing builds that may still contain defects.
• Alpha: early testing builds intended for controlled environments.

After changing the channel, run /ns admin reload and then /ns admin updatecheck. Always make verified backups before installing a testing build.

Startup Problems

1. Confirm the server is running a supported Paper-compatible Minecraft version and Java 17 or newer.
2. Keep only one active NobleSteeds JAR in plugins; check plugins/update for a staged copy awaiting restart.
3. Read the first NobleSteeds error in the startup log, including its full exception.
4. Validate config.yml indentation and values. Restore the latest working backup if the error began after an edit.
5. Confirm the server account can read and write plugins/NobleSteeds.

NobleSteeds deliberately disables itself when the selected storage provider cannot initialize, protecting mount and market data from running against a broken backend. Fix that underlying storage error rather than repeatedly reloading the plugin.

Mount Problems

• Cannot claim: the player must be riding a supported tamed mount, have noblesteeds.claim, own the mount, and remain below the applicable claim limit.
• Mount will not call: verify calling is enabled, the player has noblesteeds.call, the mount is not dead or stored, the saved world still exists, and the summon cooldown has elapsed.
• Mount appears missing: check My Horses for its saved state and last location. Let the call operation finish loading and reconciling the saved chunk before retrying.
• Storage or restore fails: ensure the player is close enough when required, the mount is not being ridden, and the destination has enough safe space.
• Wrong owner after a transfer: verify the recipient accepted the pending transfer and that no duplicate entity or stale database copy was introduced by a rollback.

Do not manually spawn a replacement with the same identity. Preserve the log and data backup before using admin cleanup or editing tools.

Storage Problems

• SQLite driver missing: the server runtime must provide SQLite JDBC support.
• MySQL driver missing: the runtime must provide MySQL Connector/J.
• MySQL connection fails: verify host, port, database, username, password, TLS setting, firewall, and database grants.
• YAML entries are skipped: stop the server and validate the named record's UUIDs, indentation, and value types against a backup.
• Data differs after conversion: return to the untouched source backup and review the conversion limitations documented under Storage Providers.

Never edit live storage files or switch storage.type as a substitute for the conversion command. Stop player activity, make verified copies of every relevant store, and retain the old provider until record counts and gameplay have been tested.

Integration Problems

• Vault unavailable: install both Vault and a compatible economy provider, then confirm the provider registers successfully during startup.
• Citizens NPC does nothing: confirm Citizens loaded first, enable the matching storage, market, or shop NPC setting, register the NPC through /ns admin, and check that its feature is enabled.
• MailboxGUI payout falls back: NobleSteeds disables the failing delivery option and saves the config when the plugin or API is unavailable. Repair compatibility before turning it back on.
• Update check fails: verify outbound HTTPS and DNS access to imagine-craft.net, the configured channel, and the manual command's HTTP result.

After correcting an integration, prefer a controlled server restart so plugin load order and service registration are rebuilt cleanly.

Is NobleSteeds free?

Yes. NobleSteeds is a completely free plugin; there is no paid or Premium edition.

Which mounts are supported?

Version 1.0.0 supports horses, donkeys, mules, llamas, trader llamas, skeleton horses, and zombie horses.

Do I need Vault, Citizens, or MailboxGUI?

No integration is required for the core plugin. Vault plus an economy provider enables money features, Citizens enables NPC access points, and MailboxGUI can deliver market payouts.

Can players have different languages?

Yes. Keep locale.auto-detect-player-locale enabled. Supported client locales use their matching file, while unsupported locales fall back to the configured default.

Which storage provider should I use?

SQLite is the recommended default for a normal single server. YAML is easy to inspect for small installations. MySQL is appropriate when an external database and its operational requirements are desired.

Can I change storage providers later?

Yes, with /ns admin storage convert <YAML|SQLITE|MYSQL>. Read the conversion limitations and make complete backups first.

Does the updater replace the running JAR immediately?

No. It validates and stages a newer NobleSteeds JAR in the server update folder. A full restart completes installation.

Should I use /reload after installing an update?

No. Use a full server restart. /ns admin reload is intended for supported configuration and language changes, not JAR replacement.

Where should I ask for help?

Use the official ImagineCraft Discord support community. Include the NobleSteeds version, server software and version, Java version, storage provider, relevant configuration with secrets removed, and the complete error from the log.