Set up a contract NPC (Premium)

Hand players a random quest paper when they right-click a Citizens NPC. This guide walks through creating the NPC first, then turning it into a SoapsQuest quest giver.

Need the full settings list? See Contract Request.

---

Before you start

1. SoapsQuest Premium is installed and the server has restarted.
2. Citizens is installed and running (console should show SoapsQuest’s Citizens integration as enabled).
3. You have permission to use Citizens admin commands (usually citizens.admin / OP).
4. Random generation is on in random-generator.yml (enabled: true).
5. If contracts cost money, install Vault and an economy plugin.

---

Steps

1. Create a Citizens NPC

SoapsQuest does not create NPCs. Build one with Citizens first, then point SoapsQuest at it.

1. Stand where you want the NPC (for example in a guild hall).
2. Create it:

/npc create Guild Clerk --type villager

You can use any name and type (player, villager, etc.). If you omit --type, Citizens uses its default.

1. Confirm it is selected (create usually selects it). If not:

/npc select

Or select by id/name later with /npc select <id> / /npc select Guild Clerk.

1. Optional polish while it is selected:

/npc lookclose
/npc skin <playername>

(skin is for player-type NPCs.)

1. Note the NPC’s numeric id (easiest) or exact name. List NPCs with:

/npc list

Example: id 42, name Guild Clerk. You will use one of those in the next step.

The NPC should be spawned and right-clickable before you continue.

2. Make it a contract quest giver

With the Citizens NPC ready, register it in SoapsQuest:

/sq npc broker 42

Or by name:

/sq npc broker Guild Clerk

Optional greeting (shown when a player confirms a contract):

/sq npc broker 42 <green>Here is a job for you.

You should see a success message with how many contract NPCs you have (for example 1/5).

3. Test as a player

1. Use a player account with soapsquest.contract (default: true).
2. Right-click the NPC — the contract board opens.
3. Select a difficulty (cost is shown on each option).
4. Click Confirm to pay and receive a quest paper, or Cancel to leave.

4. Tune the NPC (optional)

Edit plugins/SoapsQuest/contract-request.yml under brokers:, then /sq reload:

brokers:
  "42":
    cooldown-seconds: 600
    cost:
      money: 100
      sigils: 5
    message: "<green>Here is a job for you."
    allowed-difficulties: [normal, hard]
    allowed-types: [single]

Leave brokers empty in the file if you only use /sq npc broker. The command writes entries for you.

5. Check what is registered

/sq npc brokers

Shows every contract NPC and the current count against max-broker-npcs.

6. Remove a contract NPC

/sq npc unbroker 42

The Citizens NPC stays in the world. It just stops handing out random contracts.

---

Fixed quest giver instead of random contracts

If you want the NPC to always give one quest (not a random contract), create the Citizens NPC the same way as in step 1, then link a quest id:

/sq npc link 42 my_quest_id

Optional greeting:

/sq npc link 42 my_quest_id <green>Take this job.

An NPC cannot be both a fixed quest giver and a contract NPC. Unbroker or unlink first if you need to switch.

Command	What the NPC does
/sq npc link <npc> <quest-id>	Always gives that one quest paper
/sq npc broker <npc>	Rolls a new temporary contract each time (with fee and cooldown)

---

Common problems

Problem	What to check
Premium-only message	You need the Premium jar, not Free.
Citizens not available	Install Citizens and leave integrations.citizens enabled (or auto-detect). Restart the server after installing Citizens.
/sq npc broker can’t find the NPC	Create and spawn the Citizens NPC first. Use /npc list and pass the correct id or exact name.
No contract created	Enable the generator in random-generator.yml, then /sq reload.
Already a fixed quest NPC	Unlink the fixed quest, then run broker again.
Broker limit reached	Raise max-broker-npcs, or /sq npc unbroker one NPC.
Need money but no charge works	Install Vault and an economy plugin, or set cost.money to 0.
Inventory full	Free a slot. The paper drops at your feet if inventory is full.

---

Related

• Contract Request — fees, cooldowns, browser button, /sq contract
• Integrations — Citizens objectives and fixed quest links
• Random Quest Generator — what gets rolled into the paper

Version 1.0.5 - Premium