Troubleshooting & FAQ

Common issues, debugging tips, and frequently asked questions for beginners.

My NPC doesn't show the quest menu

Problem: You right-click the NPC, the dialogue opens, but there's no option to get quests — or the quest list is empty.

Check these:

• Quest ID mismatch — The quest ID in the NPC's quests array must exactly match the id field in the quest JSON file. Compare them character by character.

``` // NPC config — note the colon "quests": ["yourmod:elder-quest"]

// Quest file — must match "id": "yourmod:elder-quest" ```

• Missing quest file — Is the quest file in the right folder? It should be at assets/yourmod/config/quests/elder-quest.json.

• Wrong file extension — The framework reads .json files. Double-check the extension.

• Server restart needed — After adding new quest files, run /avq reload or restart the server.

Dialogue doesn't open when I right-click

Problem: Right-clicking the NPC does nothing, or you get a "Not conversable" message.

Check these:

• Missing conversable behavior — The NPC entity must have "code": "conversable" in its behaviors array.

• Wrong dialogue path — The dialogue value in the conversable behavior must match the file path (minus .json):

```json // Entity config { "code": "conversable", "dialogue": "config/dialogue/villager-elder" }

// Actual file location assets/yourmod/config/dialogue/villager-elder.json ```

• Dialogue file has syntax errors — Use a JSON validator (e.g., jsonlint.com) to check your file.

My quest doesn't complete

Problem: The player did everything the quest asked, but it doesn't complete.

Check these:

• Missing translation keys — The quest needs a title and description in your lang file. Check that these keys exist:

`` yourmod:quest-id-title yourmod:quest-id-desc ``

• Objective still in progress — Use /avq qcheck <playername> to see the current objective progress. This shows exactly what's done and what's missing.

• Per-player vs global — If perPlayer is false, progress is shared across all players. This can confuse testing.

No sound / wrong sound

Problem: Sounds don't play, or you get an error in the log.

Sound paths are relative to the assets/ folder of the mod that provides them:

• Framework sounds — Reference as sounds/... (e.g., sounds/effect/writing)
• Vanilla game sounds — Prefix with game: (e.g., game:sounds/effect/receptionbell)
• Your own sounds — Place them in assets/yourmod/sounds/ and reference as sounds/yourfile

// Framework sound
{ "id": "playsound", "args": ["sounds/effect/writing", "0.5"] }

// Vanilla sound
{ "id": "playsound", "args": ["game:sounds/effect/receptionbell", "0.8"] }

"/avq reload" doesn't work

Problem: The command gives a "permission denied" or "unknown command" error.

• All /avq commands require give privilege (except /promo which only needs chat)
• Grant it: /grant <playername> give
• Commands are case-sensitive — use lowercase: /avq reload, not /AVQ reload

I see "null" as quest text

Problem: Quest title, description, or dialogue text shows as "null" in the UI.

This means a translation key is missing from your lang file. Check:

• Is the key present in assets/yourmod/lang/en.json?
• Does the key match exactly what's in the quest/dialogue file (case-sensitive)?
• Did you restart or reload after editing the lang file?

For quests, the framework looks for these keys by convention:

yourmod:quest-id-title
yourmod:quest-id-desc

Quest appears only once and never again

If a quest has "cooldown": -1, it's one-time only — once completed, it never appears again.

To make a repeatable quest, use a positive number — the cooldown in hours:

// Available again after 48 hours
"cooldown": 48

// Available after 7 days
"cooldown": 168

Use /avq qforgive <questId> <playername> to reset a quest for testing.

Mod not loading / not detected

Check these:

• modinfo.json — Is it in the root of your mod folder (not inside assets/)?
• Dependencies — Does your modinfo.json include "alegacyvsquest": "3.0.0" in dependencies?
• Folder structure — The framework looks for assets/yourmod/config/quests/. If the path is wrong, nothing loads.
• Server log — Check the server log for errors. Search for "alegacy", "quest", or "error" messages.

Run /avq qlist in-game. If your quests appear in the list, they're loaded. If not, the framework isn't finding them.

My multi-stage quest doesn't advance

• Each stage must have all its objectives completed before the next stage activates
• Use /avq qcheck <playername> to see which objectives are done
• Make sure each stage has at least one objective — an empty stage will block progression
• Stage transitions are automatic — you don't need to do anything except complete the objectives

How do I test quests without doing all the work?

Use these admin commands to skip ahead:

# Force-start a quest
/avq qstart yourmod:quest-id PlayerName

# Force-complete
/avq qcomplete yourmod:quest-id PlayerName

# Complete the currently active quest
/avq qcompleteactive PlayerName

# Check progress
/avq qcheck PlayerName

I'm getting JSON errors in the console

Use a JSON validator before deploying. Common mistakes:

• Trailing comma after last array element — JSON doesn't allow this
• Missing comma between objects
• Extra comma in objects
• Unquoted keys — JSON requires double quotes around keys: "key": "value", not key: "value"
• Comments — JSON doesn't support // or /* */. Remove all comments

How do I enable debug logging?

In alegacy-vsquest-config.json, set "Debug": true. This prints verbose information to the server console:

{
  "Debug": true
}

The config file is auto-generated in your server's config folder on first run.

Quick Reference