Add-ons/Player Quest System Engine (PQS)/Quest libraries

Lua add-on documentation: Player Quest System Engine (PQS) overview · Add-on hub · Contribute or update documentation

Quest libraries

A PQS quest library is a separate add-on that owns one decoded quest definition and announces it to PQS through SES. Keeping content separate lets the engine and individual stories update independently.^[1]

Verified integration contract

A library package should depend on sota-event-system-ses-addon and pqs. After SES is ready, announce:

SES.invoke("PQS.onLoadQuestLibrary",
  LibraryKey, ScriptName, Version,
  CreatorName, Description, QuestData)

On disable, remove it with:

SES.invoke("PQS.onUnloadQuestLibrary", LibraryKey)

LibraryKey must exactly equal QuestData.id. PQS uses that ID to register, persist, and later remove the quest. Its subscription uses replayLastPerSender, so several libraries that announce before PQS finishes starting are replayed independently.^[1]

Quest model

The engine supports definitions containing quest metadata, events, criteria trees, actions, journal entries, conversations, virtual quest items, and optionally embedded sound assets. Criteria may be nested with AND/OR logic. Actions include quest-variable and item changes, journal/task changes, timers and cooldowns, dialogs, completion, console text, and supported sound behavior.

The designated start_event is special: PQS applies its actions when a new or reset quest starts without testing that event's own criteria. Put unconditional initialization there and place location- or state-gated work in an ordinary event.^[1]

Authoring status

The approved 1.10.0 source refers to PQS_JSON_SCHEMA.md and quest_library_template.lua, but neither file is included in the approved package manifest. This page therefore documents the verified load boundary, not a guessed JSON schema. Obtain the matching template/schema from the author or the PQS support thread before publishing a library.

Do not copy an old test quest and assume it represents the current schema. Validate unique IDs, reset behavior, every dialog branch, completion/failure paths, and a clean install with only SES, PQS, and the candidate library enabled.

Library checklist

Use a stable package slug and make LibraryKey exactly match the quest ID.
Declare SES and PQS dependencies and no permissions that the content does not need.
Supply creator, version, description, supported language, and a support route.
Test first start, disable/re-enable, PQS reload, reset, completion, and saved progress.
Make virtual rewards unmistakably different from real game items or currency.
Avoid implying that client-side text changes the official game world or another player's state.

References

↑ ^1.0 ^1.1 ^1.2 Community Addons: approved PQS 1.10.0 package, reviewed October 13, 2026.