Contract Request (Premium)

Gives players a random quest paper on demand.

Premium config files

File	Role
contract-request.yml	Board settings, costs, channels, broker NPC entries
random-generator.yml	Required — contracts roll quests from the generator
gui.yml → contract-request:	Board layout (shared Free/Premium file; section used by Premium)

Edition: Premium only. Free ignores these files. Defaults: Default contract-request.yml · Default random-generator.yml · Hub: Config Reference.

New here? Start with Set up a contract NPC.

Players open the contract board from:

1. A Citizens NPC set with /sq npc broker <npc-id|name> [message]
2. /sq contract [difficulty] (alias: /sq request)
3. The Get a Contract button in the quest browser

On the board they pick a difficulty (fee shown per option), then Confirm to pay and receive the paper. Cancel closes with no charge.

---

How it works for players

1. Open the board (NPC / command / browser).
2. Select a difficulty — each option shows its cost from cost / cost-by-difficulty.
3. Click Confirm — the plugin checks permission, cooldown, and active-contract limit, charges the fee, rolls a temporary quest for that difficulty, and gives the paper.
4. Click Cancel — nothing is charged.

/sq contract hard opens the board with Hard already selected.

Temporary contracts are removed from the generator file after the reward is claimed. If a quest cannot be created, nothing is charged. If the paper cannot be given after payment, the fee is refunded.

---

Key settings (contract-request.yml)

contract-request:
  enabled: true
  max-broker-npcs: 5
  generated-quest-mode: temporary
  active-contract-limit: 1
  permission: soapsquest.contract
  defaults:
    cooldown-seconds: 300
    cost:
      money: 50
      sigils: 0
    cost-by-difficulty:
      easy: { money: 25 }
      hard: { money: 100, sigils: 5 }
    allowed-types: [single, multi, sequence]
    allowed-difficulties: []
  channels:
    command:
      enabled: true
    gui:
      enabled: true
  brokers: {}

Key	Description
enabled	Master toggle
max-broker-npcs	Cap on Citizens contract NPCs
generated-quest-mode	temporary or session — cleaned up after claim
active-contract-limit	How many of these contracts a player may hold
permission	Required node to take contracts (default soapsquest.contract)
defaults.cooldown-seconds	Wait between contracts from this source
defaults.cost	Base fee (money, sigils, optional items)
defaults.cost-by-difficulty	Per-difficulty fee overrides
defaults.allowed-types	Generator types allowed for contracts
defaults.allowed-difficulties	Empty = any difficulty from the generator pool
channels.command / channels.gui	Enable /sq contract and browser button
brokers	Per-NPC overrides written by /sq npc broker

---

Contract NPCs

/sq npc broker <npc-id|name> [message]
/sq npc brokers
/sq npc unbroker <npc-id|name>

• Cap how many contract NPCs you allow with max-broker-npcs (default 5).
• An NPC cannot be both a fixed quest giver (/sq npc link) and a contract NPC.
• Right-click opens the contract board (not an instant purchase).
• /sq npc brokers lists every registered contract NPC and the current count.

Per-NPC cooldown, cost, difficulty list, and greeting message go under brokers in contract-request.yml. The optional [message] on /sq npc broker is saved there for you.

Full walkthrough: Set up a contract NPC.

---

Permissions

Permission	Default	Purpose
soapsquest.contract	true	Open the board / take contracts
soapsquest.contract.bypass-cooldown	op	Skip the wait between contracts
soapsquest.contract.bypass-cost	op	Skip the fee

---

Notes

• /sq generate is still staff-only. It creates quest definitions and does not hand papers to players. Use optional filters to pin objective, amount, difficulty, tier, or material — see Random Quest Generator.
• To release a contract paper, press Q to drop it (same as any quest). Progress stays on the instance; lock-to-player means only you can pick it back up. Your active-contract limit still counts the instance until it is voided or adopted by another player.
• /sq reload reloads contract-request.yml and keeps saved cooldowns.

Premium only — Version 1.0.5