Getting Started

Complete setup guide for SteadfastVillagers.

Requirements

Server Software

  • Paper 1.21+ or Paper 26.1+ (recommended)
  • Spigot/Bukkit compatible (Paper recommended for best performance)

Database

  • MySQL 5.7+ or MariaDB 10.3+
  • Database must be created before first run

Optional Plugins

  • GriefPrevention - Claim-based access control
  • Floodgate - Bedrock player detection for display entities

Installation

1

Database Setup

Create a database and user for the plugin:

-- Connect to MySQL as root
mysql -u root -p

-- Create database
CREATE DATABASE steadfastvillagers;

-- Create user (change password!)
CREATE USER 'minecraft'@'localhost' IDENTIFIED BY 'your_secure_password';

-- Grant permissions
GRANT ALL PRIVILEGES ON steadfastvillagers.* TO 'minecraft'@'localhost';
FLUSH PRIVILEGES;
2

Install Plugin

  1. Download the correct JAR for your server version:
    • SteadfastVillagers-1.2.0-mc1.21.jar for Paper 1.21.x
    • SteadfastVillagers-1.2.0-mc26.1.jar for Paper 26.1+
  2. Place the JAR in your plugins/ folder
  3. Start the server once to generate config files
  4. Stop the server
3

Configure Database

Edit plugins/SteadfastVillagers/config.yml:

database:
  host: localhost
  port: 3306
  database: steadfastvillagers
  username: minecraft
  password: your_secure_password
  table-prefix: vb_
4

Start Server

Start your server. Check console for:

[SteadfastVillagers] Connected to database successfully
[SteadfastVillagers] Loaded X villager blocks

If you see database errors, verify your credentials and that the database exists.

First Villager Block

1. Get a Master Villager

Trade with any villager until they reach Master level (level 5):

  • Each trade gives the villager XP
  • Watch the green bar fill up
  • Master villagers have a diamond badge
Tip: Librarians are popular first choices for Mending books.

2. Convert the Villager

  1. Hold an Emerald Block in your main hand
  2. Right-click the Master villager
  3. The villager transforms into a villager head item
  4. The Emerald Block is consumed

3. Place the Block

  1. Place the villager head item like any block
  2. A display entity appears showing the villager head
  3. Right-click to open the GUI

4. Select a Trade

  1. Click any trade item in the GUI to make it active
  2. Active trades have an enchantment glow
  3. The selected trade will process automatically

5. Add Materials

Manual:

  1. Click the "Input" button
  2. Add trade ingredients to the inventory
  3. Click "Back" to return

Automated:

  1. Place a hopper above the villager block
  2. Fill the hopper with ingredients
  3. Items automatically transfer to input buffer

6. Collect Results

Manual:

  1. Click the "Output" button
  2. Take items from the inventory
  3. Shift+click "Output" to take all

Automated:

  1. Place a hopper below the villager block
  2. Results automatically transfer out

Automation Setup

Basic Hopper Farm

[Chest with emeralds] | [Hopper] | v [Villager Block] <-- Right-click to select "Emerald -> Wheat" trade | [Hopper] | v [Chest collects wheat]

Multi-Trade Setup

Each villager block processes one trade at a time. For multiple trades:

[Emerald Chest] --+-- [Hopper] -> [Librarian Block 1] -> [Hopper] -> [Book Chest] | +-- [Hopper] -> [Librarian Block 2] -> [Hopper] -> [Book Chest] | +-- [Hopper] -> [Farmer Block] -> [Hopper] -> [Food Chest]

Restocking (Vanilla Mode)

If using lock-mode: VANILLA:

  1. Open the villager block GUI
  2. Find the "Workstation" slot
  3. Place the correct workstation block:
    • Librarian -> Lectern
    • Farmer -> Composter
    • etc.
  4. Trades restock every 20 minutes (configurable)

Visual Indicators

The villager head's eye color indicates status:

Eye Color Meaning Action
Green Actively trading Working normally
Red Output buffer full Empty output or add hopper below
Yellow Trade locked (restocking) Wait for restock or add workstation
Blue Missing input materials Add ingredients
White Idle / No trade selected Select a trade in GUI

Tips for New Users

Don't Lose Your Villager

  • Always use Silk Touch to pick up villager blocks
  • Without Silk Touch, you cannot break the block (by default)
  • Keep a Silk Touch pickaxe handy

Preserve Discounts

  • Cure zombie villagers before converting for permanent discounts
  • Discounts are captured at conversion time
  • A 5x cured librarian keeps ~80% discount forever

Activation Range

  • Default: Trades only process when a player is within 16 blocks
  • For AFK farms, stand near the villager blocks
  • Or set activation-range: 0 to process whenever the chunk is loaded

XP Collection

  • Trade XP accumulates in the block
  • Click the XP bottle to collect
  • Hold a Mending item while clicking to repair it directly

Troubleshooting

"Database connection failed"

  • Verify MySQL/MariaDB is running
  • Check username and password in config
  • Ensure database exists: SHOW DATABASES;
  • Check user permissions: SHOW GRANTS FOR 'minecraft'@'localhost';

Villager head not appearing

Run /svadmin repair while looking at the block to respawn display entities.

Trades not processing

  1. Check activation range (player must be nearby)
  2. Verify trade is selected (should have enchant glow)
  3. Check input buffer has correct materials
  4. Check output buffer isn't full
  5. For VANILLA mode, verify workstation is placed

"You need Silk Touch"

The block requires a Silk Touch pickaxe to break (by default). This prevents accidental destruction and theft.

Next Steps