ShadowQuests

On update your files (this one, quests/, lang/, menus/ and the others below) are moved to the new version automatically: every value you changed or added stays, new options arrive with their comments, and what you deleted stays deleted. The old copies are in backup/<date>/; if something needs your attention you will find PORTING-<version>.txt in the plugin folder.

A wrong value never stops anything: it is replaced by the factory one and reported in the console at startup, with the path and what was expected.

LANGUAGE. Everything you configure is written in English - keys, sections, values, and these notes - because this file is read by server owners all over the world. What a PLAYER reads is a different matter and stays translatable: see lang/ below, which ships in English and in Italian, and messages.default-locale a few sections down.

Where things live:

config.yml        this file: storage, rules, messages, integrations
quests/*.yml      the quests, one file per group
rewards.yml       reusable reward bundles
npcs.yml          which NPC hands out which quest
lang/*.yml        the messages players read
menus/*.yml       the layout of the windows
license.yml       the licence (created on first start, kept apart on
                  purpose: a "send me your config" must never arrive
                  with somebody's licence inside it)

Which NPC hands out which quest.

The NPCs themselves come from ShadowEssentials: this file only says, for each of them, what they have to offer. Without ShadowEssentials the file does nothing and raises no error.

There are two ways to tie a quest to an NPC, and both are fine:

1. inside the quest, with "npc: blacksmith" - the right place for
   anyone writing YAML by hand, because it keeps the binding next to
   the rest of the quest;
2. here - the place the in-game editor writes to, and the only way to
   have one NPC offer more than one quest.

The two sources add up.

ORDER MATTERS: the NPC offers the first quest in the list that the player can still take. That is how one character tells a story a chapter at a time instead of dumping six offers at once.

It can also be done from a command:

/sqa npc bind <npc> <quest>
/sqa npc unbind <npc> <quest>
/sqa npc list

Reusable reward bundles.

A bundle is defined here once and called from any quest with "bundle: <name>". Changing it here changes every quest that uses it, without touching a single quest file: that is the difference between retuning a server's rewards in a minute and reopening thirty files.

Inside a bundle you write exactly what you would write inside a quest, so there is no second syntax to learn.

THE LADDER, AND WHY THE NUMBERS ARE THESE

They are priced against ShadowEconomy's shop.yml, where a diamond sells for 10 and costs 1000, an iron ingot sells for 4 and a log for 2. A quest that pays a thousand times what it asks for breaks the economy on the first day, so the whole ladder is written down here in one place and every quest picks a rung instead of inventing a number:

starter-reward      400     the first chapter of a chain
small-reward        500     an ordinary daily
medium-reward     5.000     a weekly
weekly-reward     7.500     a hard weekly, with a crate key
big-reward       25.000     the end of a chain, or a monthly
monthly-reward   35.000     a monthly that took the whole month
legend-reward    60.000     the last chapter of a long chain

Sixty thousand is four netherite ingots at shop price. That is the ceiling on purpose: a reward that buys more than a player could ever mine turns the shop into scenery.

THE CRATE KEYS are the ones ShadowCrazyChest ships with - basic, vote, daily, magic, epic. On a server without a crate plugin the key is not delivered and the console says so once: every bundle that carries one also carries money, so nobody is left with nothing.

Names, keys and values are English, and so is what a player sees - "display": change it, it is yours. An Italian version of this file is in esempi/it_IT/rewards.yml. It is not loaded: copy it over this one to use it.

MiniMessage format. Placeholders are written <like_this>.

THREE PLACEHOLDERS ARE ALWAYS AVAILABLE, EVERYWHERE:

<prefix>      the prefix below
<label>       the label the player command was ACTUALLY registered
              under on this server
<adminlabel>  the same thing for the staff command

Commands are never written by hand in a message. A short alias such as /sq may already belong to another plugin, and whoever asks second does not get it: an in-chat help that names a command which does not answer here sends people to type something that does not work, and it looks like the plugin's fault. With <label> that cannot happen.

On update this file is moved to the new version automatically: the lines you rewrote stay as you wrote them, the new keys are added, and the old copy is kept in backup/<date>/. If something needs your attention you will find PORTING-<version>.txt in the plugin folder.

The chains: stories made of quests, one after the other.

For each chain you see how far it has got and which chapter comes next - not the ones after that, because a story told all at once inside a menu is not a story.

Keys and slots are English. THE WORDS: a title or a name written "lang:<key>" comes from the language files in lang/, so every player reads it in their own language. Write a text instead - for example name: "<yellow>Back to the quests" - and that text is shown as it is, to everybody: what you write here wins over the language file.

Every screen of the in-game editor, in a single file.

One block per screen:

editor          the list of quests
quest-edit      the desk of one quest
objectives      the objectives of a quest
types           picking an objective type
objective-edit  one objective in detail
rewards         the rewards of a quest
reward-types    picking a reward type
reward-edit     one reward in detail

THE LABELS are not here: they live in the language files, under editor.field, editor.obj and editor.rew. This file only says where the buttons go and what they are made of, so one can be moved without touching a single translation.

The titles and the few names below point to the language files too: "lang:<key>" is read in the language of whoever opens the editor. Write a text instead and that text is shown as it is, to everybody: what you write here wins over the language file.

One quest, looked at closely.

Slot 4        the header: name, description, bar, requirements
Row 1         the objectives, one per slot
Row 2         the rewards
Row 3         the button that makes sense right now

The middle button changes on its own: accept when the quest has not been taken yet, claim when it is finished, give up while it is in progress. That is why all three share the same slot.

Keys and slots are English. THE WORDS: a title or a name written "lang:<key>" comes from the language files in lang/, so every player reads it in their own language. Write a text instead - for example name: "<green><bold>Take it" - and that text is shown as it is, to everybody: what you write here wins over the language file.

The main quest screen.

Row 0         one tab per group
Middle        the quests of the selected group
Last row      claim all, chains, pages, close

Every slot, material and text can be changed here without recompiling anything. A deleted key does not break the menu: it simply falls back to the value the code carries.

Slots are counted from 0, top left. Expressions accept lists and ranges: "10-16,19-25".

On update this file is moved to the new version automatically: what you changed stays, the rest takes the new layout, and the old copy is kept in backup/<date>/.

Keys and slots are English. THE WORDS: a title or a name written "lang:<key>" comes from the language files in lang/, so every player reads it in their own language. Write a text instead - for example name: "<red>Leave" - and that text is shown as it is, to everybody: what you write here wins over the language file.