# SteadfastVillagers Plugin Documentation
# For AI/LLM consumption - plain text summary of plugin documentation

## Plugin Overview
SteadfastVillagers is a Minecraft Paper/Spigot plugin that converts villagers into portable trading blocks.

### Key Features
- Converts villagers to placeable trading blocks (no pathfinding AI = no lag)
- Full hopper automation support (input above, output below)
- Permanent cure discounts (captured at conversion, never decay)
- Silk Touch pickup and placement anywhere
- 100 villager blocks perform better than 20 actual villagers
- Players can sell villager blocks to create a villager economy

### Requirements
- Paper 1.21+ or Paper 26.1+ (Spigot/Bukkit compatible)
- MySQL 5.7+ or MariaDB 10.3+ (required for persistence)
- Optional: GriefPrevention (claim protection), Floodgate (Bedrock support)

## Installation
1. Create MySQL database: CREATE DATABASE steadfastvillagers;
2. Download correct JAR from Modrinth (mc1.21 or mc26.1 version)
3. Place in plugins/ folder, start server to generate config
4. Edit config.yml with database credentials
5. Restart server

## How to Convert a Villager
1. Trade with villager until Master level (level 5)
2. Hold Emerald Block in main hand
3. Right-click the villager
4. Villager becomes a head item, place anywhere
5. Right-click to open GUI and select trades

## Configuration Options

### Trade Lock Modes
- VANILLA: Trades lock after use, require workstation for restock (default)
- INFINITE: Unlimited trades, no restocking needed

### Key Settings
- conversion.item: EMERALD_BLOCK (what converts villagers)
- conversion.min-level: 5 (minimum villager level, 1-5)
- trades.activation-range: 16 (blocks from player, 0 for always active)
- trades.cooldown-ticks: 200 (10 seconds between trades)
- discount.max-percent: 80 (cap on cure discounts)
- block.require-silk-touch: true (Silk Touch needed to pick up)

## Commands

### Player Commands
- /sv - Plugin info

### Admin Commands
- /svadmin inspect [id] - View block details
- /svadmin list [player|world] - List all blocks
- /svadmin repair [id] - Respawn display entities
- /svadmin restock [id] - Force restock trades
- /svadmin clearbuffers [id] [input|output|all] - Clear buffers
- /svadmin export [id] - Export to JSON
- /svadmin transfer <player> [id] - Change ownership
- /svadmin delete [id] - Remove permanently
- /svadmin cleanup - Remove orphaned entries
- /svadmin stats - Server statistics

## Permissions
- steadfastvillagers.convert (default: true) - Convert villagers
- steadfastvillagers.use (default: true) - Use villager blocks
- steadfastvillagers.admin (default: op) - Admin commands
- steadfastvillagers.bypass (default: op) - Bypass claim checks

## Workstation Requirements (VANILLA mode)
- Armorer: Blast Furnace
- Butcher: Smoker
- Cartographer: Cartography Table
- Cleric: Brewing Stand
- Farmer: Composter
- Fisherman: Barrel
- Fletcher: Fletching Table
- Leatherworker: Cauldron
- Librarian: Lectern
- Mason: Stonecutter
- Shepherd: Loom
- Toolsmith: Smithing Table
- Weaponsmith: Grindstone

## API Integration

### Maven
```xml
<repository>
    <id>steadfastsmp</id>
    <url>https://repo.steadfastsmp.com/releases</url>
</repository>
<dependency>
    <groupId>com.steadfastsmp</groupId>
    <artifactId>steadfastvillagers-api</artifactId>
    <version>1.2.0</version>
    <scope>provided</scope>
</dependency>
```

### Gradle
```kotlin
repositories {
    maven("https://repo.steadfastsmp.com/releases")
}
dependencies {
    compileOnly("com.steadfastsmp:steadfastvillagers-api:1.2.0")
}
```

### Events
- VillagerBlockConvertEvent - Villager converted to block
- VillagerBlockPlaceEvent - Block placed
- VillagerBlockBreakEvent - Block broken (Silk Touch)
- VillagerBlockTradeEvent - Trade executed (async)
- VillagerBlockUnconvertEvent - Block reverted to villager

### Service Classes
- VillagerBlockManager: getBlockAt(), getAllBlocks(), getBlocksByOwner()
- DatabaseManager: saveBlock(), deleteBlock(), loadAllBlocks()
- ConfigManager: getConversionItem(), getTradeLockMode(), getActivationRange()

## Troubleshooting

### Database connection failed
- Verify MySQL/MariaDB is running
- Check credentials in config.yml
- Ensure database exists

### Display entity missing
- Run /svadmin repair while looking at block

### Trades not processing
1. Check player is within activation-range
2. Verify trade is selected (enchant glow)
3. Check input buffer has materials
4. Check output buffer not full
5. For VANILLA mode, verify workstation placed

### Trades not restocking
1. Verify lock-mode: VANILLA in config
2. Check workstation in GUI matches profession
3. Wait for restock interval (default 20 min)

## Links
- Documentation: https://steadfastsmp.com/docs/steadfast-villagers/
- Modrinth: https://modrinth.com/plugin/steadfastvillagers
- GitHub: https://github.com/steadfastsmp/steadfastvillagers
- Support: https://discord.gg/steadfastsmp

## Version
Current: 1.2.0
Supports: Paper 1.21+, Paper 26.1+, Spigot, Bukkit