hubmc_essentionals/CONFIG_EXAMPLE.md

# Configuration Example

This file shows an example configuration for HubMC Essentials mod.

The actual configuration file is located at: `config/hubmc_essentials-common.toml`

## Example Configuration File

```toml
# HubGW API Configuration
# Base URL for HubGW API (without trailing slash)
apiBaseUrl = "http://localhost:8000/api/v1"

# API key for authentication with HubGW
apiKey = "your-api-key-here"

# Connection timeout in seconds
# Range: 1 ~ 30
connectionTimeout = 2

# Read timeout in seconds
# Range: 1 ~ 60
readTimeout = 5

# Maximum number of retries for failed API requests (429/5xx errors)
# Range: 0 ~ 10
maxRetries = 2

# Enable debug logging for API requests and responses
enableDebugLogging = false

# Command cooldowns in seconds
[cooldowns]
    # Cooldown for /clear command
    # Range: 0 ~ 3600
    clear = 300

    # Cooldown for /ec command
    # Range: 0 ~ 3600
    ec = 180

    # Cooldown for /hat command
    # Range: 0 ~ 3600
    hat = 120

    # Cooldown for /heal command
    # Range: 0 ~ 3600
    heal = 300

    # Cooldown for /feed command
    # Range: 0 ~ 3600
    feed = 180

    # Cooldown for /repair command
    # Range: 0 ~ 7200
    repair = 600

    # Cooldown for /near command
    # Range: 0 ~ 3600
    near = 60

    # Cooldown for /back command
    # Range: 0 ~ 3600
    back = 120

    # Cooldown for /rtp command
    # Range: 0 ~ 7200
    rtp = 600

    # Cooldown for /repair all command
    # Range: 0 ~ 7200
    repairAll = 1800

    # Cooldown for /top command
    # Range: 0 ~ 3600
    top = 300

    # Cooldown for /pot command
    # Range: 0 ~ 3600
    pot = 120

    # Cooldown for /day, /night, /morning, /evening commands
    # Range: 0 ~ 3600
    time = 60

    # Cooldown for /goto command
    # Range: 0 ~ 3600
    goto = 60
```

## Configuration Notes

### API Configuration

- **apiBaseUrl**: Set this to your HubGW API server URL. Must not include trailing slash.
  - Example: `http://localhost:8000/api/v1`
  - Example: `https://api.yourdomain.com/api/v1`

- **apiKey**: Your API authentication key. Get this from your HubGW server administrator.
  - **Security Note**: Keep this key secret! Do not commit it to version control.

- **connectionTimeout**: Time to wait for initial connection (2 seconds recommended)

- **readTimeout**: Time to wait for response from server (5 seconds recommended)

- **maxRetries**: Number of automatic retries on server errors (2 recommended)
  - Set to 0 to disable retries
  - Applies only to 429 (rate limit) and 5xx (server error) responses

- **enableDebugLogging**: Enable detailed logging for troubleshooting
  - Set to `true` only when debugging API issues
  - Generates verbose logs with request/response details

### Cooldown Configuration

All cooldowns are in **seconds**. Set to `0` to disable cooldown for a specific command.

**Default cooldown times:**
- Quick actions (1-2 min): `/near`, `/time`, `/goto`, `/hat`, `/pot`
- Medium actions (3-5 min): `/ec`, `/feed`, `/heal`, `/top`, `/clear`
- Long actions (10 min): `/repair`, `/rtp`
- Very long actions (30 min): `/repair all`

**Adjusting cooldowns:**
- Lower cooldowns for casual/creative servers
- Higher cooldowns for survival/competitive servers
- Set to 0 for staff/VIP groups (handled via LuckPerms permissions)

### Permission Bypass

Players with operator status or specific permissions can bypass cooldowns:
- Configure in LuckPerms to grant cooldown-free access to specific groups
- Use tier permissions (`hubmc.tier.vip`, `hubmc.tier.premium`, `hubmc.tier.deluxe`) for tiered access

## First-Time Setup

1. Start your server with the mod installed
2. Server will generate `config/hubmc_essentials-common.toml`
3. Stop the server
4. Edit the config file:
   - Set your `apiBaseUrl` to your HubGW API server
   - Set your `apiKey` from your HubGW administrator
   - Adjust cooldowns as needed for your server
5. Save the file and start your server

## Troubleshooting

### API Connection Issues

If you see errors about API unavailable:
1. Check `apiBaseUrl` is correct and accessible
2. Verify `apiKey` is valid
3. Enable `enableDebugLogging = true` to see detailed error messages
4. Check firewall/network connectivity to API server
5. Increase `connectionTimeout` and `readTimeout` if network is slow

### Cooldown Not Working

1. Verify HubGW API server is running
2. Check server logs for API errors
3. Enable debug logging to see cooldown check/create requests
4. Verify player has correct permissions in LuckPerms

## Example Production Configuration

```toml
# Production server example
apiBaseUrl = "https://api.yourserver.com/api/v1"
apiKey = "prod-api-key-abc123def456"
connectionTimeout = 3
readTimeout = 10
maxRetries = 3
enableDebugLogging = false

[cooldowns]
    clear = 600      # 10 minutes (survival)
    ec = 300         # 5 minutes
    hat = 180        # 3 minutes
    heal = 600       # 10 minutes (survival)
    feed = 300       # 5 minutes (survival)
    repair = 1200    # 20 minutes (survival)
    near = 120       # 2 minutes
    back = 180       # 3 minutes (survival)
    rtp = 900        # 15 minutes (survival)
    repairAll = 3600 # 60 minutes (rare command)
    top = 300        # 5 minutes
    pot = 180        # 3 minutes
    time = 300       # 5 minutes (restricted)
    goto = 120       # 2 minutes
```

## Example Creative Server Configuration

```toml
# Creative/test server example
apiBaseUrl = "http://localhost:8000/api/v1"
apiKey = "dev-api-key-test"
connectionTimeout = 2
readTimeout = 5
maxRetries = 2
enableDebugLogging = true

[cooldowns]
    clear = 10       # Minimal cooldowns for testing
    ec = 10
    hat = 10
    heal = 30
    feed = 30
    repair = 60
    near = 10
    back = 30
    rtp = 60
    repairAll = 120
    top = 30
    pot = 30
    time = 10
    goto = 10
```