## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Commands](#commands)
- [Permissions](#permissions)
- [Forge System](#forge-system)
- [Leveling System](#leveling-system)
- [Recipe System](#recipe-system)
- [Fuel System](#fuel-system)
- [ItemsAdder Integration](#itemsadder-integration)
- [Configuration](#configuration)
- [Frequently Asked Questions](#frequently-asked-questions)

---

## Features

### Core Features
- **Time-Based Forging** - Recipes take real time to complete, continuing even when offline
- **Progressive Leveling** - Unlock more forge slots and time bonuses as you level up
- **Multiple Forge Slots** - Up to 5 concurrent forging slots (unlocked through leveling)
- **Fuel System** - Lava-based fuel system required to power the forge
- **Custom Recipes** - Fully configurable recipes via config or in-game commands
- **Category Organization** - Organize recipes into custom categories
- **Progress Tracking** - Visual progress bars and time remaining displays
- **Auto-Claim Notification** - Players are notified when items are ready

### Integration Features
- **ItemsAdder Support** - Full compatibility with ItemsAdder custom items
- **Custom Model Data** - Support for resource pack custom model data
- **Persistent Data** - All progress saved and persists through restarts

### Quality of Life
- **Batch Claiming** - Claim all completed items at once
- **Ingredient Checking** - Visual feedback showing if you have required materials
- **Time Formatting** - Human-readable time displays (1h 30m 45s)
- **Tab Completion** - Full tab completion for all commands
- **Hot Reload** - Reload configuration without server restart

---

## Installation

1. Download the Forging999 plugin JAR file
2. Place it in your server's `plugins` folder
3. Start or restart your server
4. The plugin will generate default configuration files
5. (Optional) Install ItemsAdder for custom item support

---

## Commands

### Player Commands

| Command | Description |
|---------|-------------|
| `/forge` | Opens the main forge GUI |
| `/forge help` | Displays the help menu with all available commands |

### Admin Commands

| Command | Description |
|---------|-------------|
| `/forge reload` | Reloads the plugin configuration |
| `/forge settime <player> <seconds>` | Sets a player's total forging time |
| `/forge setlevel <player> <level>` | Sets a player's forge level (1-5) |

### Recipe Management Commands

| Command | Description |
|---------|-------------|
| `/forge recipe add <category> <item> <lava_cost> <time> <materials>` | Adds a new recipe |
| `/forge recipe remove <category> <recipe_name>` | Removes a recipe from a category |
| `/forge recipe list` | Lists all recipe categories |
| `/forge recipe list <category>` | Lists all recipes in a specific category |

### Category Management Commands

| Command | Description |
|---------|-------------|
| `/forge category add <name> [display_name] [icon]` | Creates a new recipe category |
| `/forge category remove <name>` | Deletes a recipe category |
| `/forge category list` | Lists all available categories |

### Recipe Add Command Detailed Usage
/forge recipe add <category> <hand|item_id> <lava_cost> <forge_time> <materials>

**Parameters:**
- `category` - The category to add the recipe to (must exist)
- `hand|item_id` - Use "hand" to use held item, or specify item ID
- `lava_cost` - Fuel cost in millibuckets (mb)
- `forge_time` - Time in seconds or formatted (1h, 30m, 1h30m)
- `materials` - Required ingredients (comma-separated)

**Examples:**
/forge recipe add ores hand 500 3600 RAW_IRON:1
/forge recipe add parts DIAMOND_SWORD 800 1h30m DIAMOND:2,STICK:1
/forge recipe add custom ia:myitems:sword 600 2h IRON_INGOT:4,DIAMOND:2

---

## Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `forging999.use` | Allows access to the forge GUI | All players |
| `forging999.admin` | Allows access to admin commands | Operators |

---

## Forge System

### Main Interface

The forge interface is a 54-slot GUI containing:

- **Forge Slots (5 max)** - Central slots where forging takes place
- **Timer Display** - Shows remaining time for each active recipe
- **Fuel Indicator** - Displays current lava fuel amount
- **Upgrade Button** - Shows level progress and upgrade requirements
- **Recipe Browser** - Access to all available recipes by category
- **Claim Button** - Quickly claim all completed items

### Forge Slot States

1. **Locked** - Slot not yet unlocked (requires higher forge level)
2. **Empty** - Available for a new recipe
3. **Active** - Currently forging (shows progress bar and time remaining)
4. **Complete** - Ready to claim (highlighted with completion indicator)

### Forging Process

1. Click an empty forge slot
2. Select a recipe category
3. Choose a recipe (must have ingredients and fuel)
4. Ingredients and fuel are consumed
5. Wait for the timer to complete
6. Claim your forged item

---

## Leveling System

### Overview

The forge leveling system rewards players for using the forge. As players spend more time forging, they unlock additional slots and time reduction bonuses.

### Level Progression

| Level | Forge Slots | Time Reduction | Required Forging Time |
|-------|-------------|----------------|----------------------|
| 1 | 1 slot | 0% | Starting level |
| 2 | 2 slots | 10% | 20 minutes total |
| 3 | 3 slots | 20% | 40 minutes total |
| 4 | 4 slots | 30% | 60 minutes total |
| 5 | 5 slots | 40% | 120 minutes total |

### How Leveling Works

- Forging time is accumulated as recipes complete
- The total time of each completed recipe adds to your progress
- Upgrades happen automatically when requirements are met
- Progress is shown on the upgrade button in the GUI
- Time reduction applies to all future recipes

### Time Reduction Bonus

The time reduction bonus stacks with each level:
- Level 1: Recipes take 100% of base time
- Level 2: Recipes take 90% of base time
- Level 3: Recipes take 80% of base time
- Level 4: Recipes take 70% of base time
- Level 5: Recipes take 60% of base time

---

## Recipe System

### Recipe Components

Each recipe consists of:
- **Result Item** - The item produced when forging completes
- **Ingredients** - Required materials consumed when starting
- **Forge Time** - Base time required (affected by level bonus)
- **Fuel Cost** - Lava fuel consumed in millibuckets (mb)

### Recipe Categories

Recipes are organized into categories for easy browsing:
- Default categories: Parts, Ores, Armor
- Custom categories can be added via commands or config
- Each category has a display name and icon

### Adding Recipes In-Game

**Using held item:**
/forge recipe add ores hand 500 1h RAW_GOLD:2,COAL:4

**Using material name:**
/forge recipe add parts IRON_PICKAXE 800 2h IRON_INGOT:3,STICK:2

**Using ItemsAdder item:**

### Material Format

**Vanilla Items:**
- Format: `MATERIAL_NAME:AMOUNT`
- Example: `IRON_INGOT:3`

**ItemsAdder Items:**
- Format: `ia:namespace:item_id:amount`
- Example: `ia:myitems:custom_ore:2`

**Multiple Materials:**
- Separate with commas
- Example: `IRON_INGOT:3,DIAMOND:2,STICK:1`

### Time Format

Recipes support multiple time formats:
- Seconds: `3600` (1 hour)
- Hours: `1h` or `2h`
- Minutes: `30m` or `45m`
- Combined: `1h30m` or `2h15m30s`

---

## Fuel System

### Overview

The forge requires lava fuel to operate. Each recipe consumes a specific amount of fuel measured in millibuckets (mb).

### Adding Fuel

- Hold a lava bucket and click the fuel slot
- Or drag a lava bucket onto the fuel slot
- Each lava bucket adds 1000mb of fuel
- Empty bucket is returned after adding fuel

### Fuel Consumption

- Fuel is consumed when starting a recipe
- Different recipes require different fuel amounts
- If insufficient fuel, the recipe cannot be started
- Fuel amount is displayed in the GUI

### Fuel Costs

Fuel costs are configurable per recipe. Default examples:
- Simple smelting: 100-200 mb
- Standard forging: 300-600 mb
- Advanced forging: 800-1000+ mb

---

## ItemsAdder Integration

### Overview

Forging999 fully supports ItemsAdder custom items for:
- Recipe results (forged items)
- Recipe ingredients (required materials)
- Category icons

### Using ItemsAdder Items

**In Commands:**
ia:namespace:item_id or itemsadder:namespace:item_id

**Examples:**
/forge recipe add weapons ia:myweapons:fire_sword 1000 2h ia:myores:fire_crystal:3
/forge category add gems Gems ia:myitems:gem_icon

**In Config:**
```yaml
result:
itemsadder_id: "namespace:item_id"
amount: 1

```
Automatic Detection
The plugin automatically detects if ItemsAdder is installed
Custom items are recognized and handled appropriately
Items maintain all custom properties (name, lore, model data)
Configuration
File Locations
plugins/Forging999/config.yml - Main configuration
plugins/Forging999/data.yml - Player data (auto-managed)
forge_settings:
# Slots available at each level
slots_per_level:
1: 1
2: 2
3: 3
4: 4
5: 5

# Time reduction percentage per level above 1
time_reduction_per_level: 10

# Forging time (seconds) required for each level
upgrade_requirements:
2: 1200 # 20 minutes
3: 2400 # 40 minutes
4: 3600 # 60 minutes
5: 7200 # 120 minutes
recipe_categories:
category_name:
display_name: "Display Name"
icon:
material: "MATERIAL_NAME"
name: "&7Icon Name"
recipes:
recipe_name:
result:
material: "RESULT_MATERIAL"
name: "&fItem Name"
amount: 1
lore:
- "&7Description line"
custom_model_data: 12345
time_in_seconds: 3600
fuel_cost: 500
ingredients:
ingredient_1:
material: "MATERIAL_NAME"
amount: 3
recipes:
custom_sword:
result:
itemsadder_id: "mynamespace:epic_sword"
amount: 1
time_in_seconds: 7200
fuel_cost: 1000
ingredients:
custom_ingot:
itemsadder_id: "mynamespace:magic_ingot"
amount: 4
diamond:
material: "DIAMOND"
amount: 2
Frequently Asked Questions
Does forging continue when I'm offline?
Yes! Forging continues in real-time even when you're offline. Your items will be ready to claim when you return.

What happens if my inventory is full when claiming?
You'll receive a message that your inventory is full. The item remains in the forge slot until you have space to claim it.

Can I cancel a recipe in progress?
No, once a recipe starts, it cannot be cancelled. Ingredients and fuel have already been consumed.

Do I lose progress if the server restarts?
No, all progress is saved automatically and persists through server restarts.

How do I add custom items from ItemsAdder?
Use the ia:namespace:item_id format in commands or itemsadder_id in config files.

Can I have more than 5 forge slots?
The default maximum is 5 slots, but this can be modified in the configuration.

Does the time reduction apply to recipes already in progress?
No, time reduction only applies to newly started recipes after leveling up.

How do I remove the default recipes?
Use /forge recipe remove <category> <recipe_name> or delete them from the config file.

Can I create recipes with no ingredients?
Yes, set ingredient amounts to 0 or omit the ingredients section (still requires fuel).

What happens to active recipes if I remove them from config?
Active recipes will complete normally, but the recipe won't be available for new forging.
Support
For issues, suggestions, or contributions, please join my discord