Quest catalog administration
Mod version shipped with FlammiCraft: 2.64.0
TDEconomy 2.56.0 provides an optional private HTTP API and a Python 3.11+ tool for reviewing quest definitions together before adding them to a world. Quest content is not bundled in the mod. Imported tasks remain ordinary tasks: operators can edit their titles, descriptions, difficulty, theme, finale flag, material filters, actions, paying account and money/item rewards in the existing in-game editor. Pool selection remains available in game. Delete task requires confirmation.
One-time setup
All credentials belong exclusively in tdeconomy-database.toml, the private file
excluded from pack distribution. The filename remains -database.toml; NeoForge's
COMMON loader type prevents network synchronization and loads it from the global
config directory. It is not a -common.toml file.
Before upgrading an existing installation, stop it manually and preserve the
effective serverconfig/tdeconomy-database.toml from its world in
config/tdeconomy-database.toml. If both files exist, compare and reconcile their
settings locally without printing secrets; do not overwrite one blindly. Keep
the existing database.history and database.daily_quests values; from 2.54.0
the database connection lives in tdlibrary-database.toml. The code performs no automatic file migration or
database operation. A new/default file leaves the API disabled.
The old tdeconomy-common.toml quest section is no longer read. Remove its secret
from files intended for distribution, protect retained backups, and generate a
fresh API key in the private database file instead of reusing a potentially
exposed key. Do not copy that old
file into the new private settings or restore it as a workaround.
Install matching client/server builds manually. Start and stop the updated server
normally to let NeoForge create config/tdeconomy-database.toml. While it is stopped,
set the following existing section:
[database.quest_api]
enabled = true
bind = "127.0.0.1"
port = 18789
token = ""
Generate the token while the server is stopped:
rtk proxy python tools/quest_api.py --config <private-database-config> generate-token
On Windows, token generation uses PowerShell 7 (pwsh) to preserve the private configuration file's access permissions.
The tool writes a 64-character token without printing it. Select the API node
by adding [tdeconomy] with quest_api = true to its server-root
cluster-node.toml. Set this on one backend per cluster. For a standalone
server, create the same file with schema = 1, id = "a" and an empty
owned_dimensions list. The selected node refuses to start with an empty token.
The private database file uses the unsynchronized NeoForge COMMON loader
type and is never sent to players. Exclude it from
distributed packs and limit its filesystem access to administrators. Changing the
key, interface, port or enabled flag takes effect after a full server restart.
Disabling the API or rotating the key leaves all imported quests in place.
Loopback permits access from tools running on that server or through an existing
authenticated tunnel. For administration from another machine, deliberately bind
to the server's specific VPN address and restrict its port to administrators, or
place an authenticated HTTPS reverse proxy in front of the loopback listener.
Use bind = "0.0.0.0" to listen on all IPv4 interfaces and accept connections
from any source IP permitted by the host network. The private bearer key is
still required for every request. Tools connect to the server's actual address
using --url, not to 0.0.0.0. The listener itself uses HTTP; send its
bearer key only over loopback, a trusted encrypted VPN/tunnel, or HTTPS at the proxy.
The key grants quest-catalog administrator access independently of an online
player. It does not expose account transfers, inventories or player progress.
The Python tool reads the private database config internally, including through an authorized UNC path if appropriate. Do not paste its contents into chat. Run the tool from this source repository, or use its absolute path:
rtk proxy python tools/quest_api.py --config <private-database-config> catalog --output catalog.json
rtk proxy python tools/quest_api.py --config <private-database-config> options --output options.json
--url https://<admin-host> or --url http://<specific-vpn-ip>:18789 overrides the
connection address without changing the server binding. Arguments precede the
subcommand. TDECONOMY_QUEST_CONFIG can supply the private config path instead.
Public HTTP addresses, credentials embedded in URLs and redirects are refused;
HTTPS certificate verification remains enabled. No key is accepted as a command
argument or written into catalog/review files. These files contain private quest
definitions and account names/IDs, so keep them with the administration work.
Reviewing an issue together
- Read the issue and identify tasks explicitly approved for insertion. Leave tasks marked for checking, replacement or unresolved item choices out of the submitted change. The tool never converts ambiguous issue prose automatically.
- Read
catalogandoptions. Resolve concrete item IDs, tags, dimensions and an active outgoing system/group account against this running installation. The options response includes identifiers, not account balances. - Discuss the exact definitions and proposed additions/updates/removals. Keep unchanged tasks and unrelated pools outside the change. Missing issue entries do not mean deletion.
- Validate the complete change and read its saved review. Only then apply the exact reviewed file. Read the catalog afterwards when verifying the result.
Use a stable task reference, such as gitlab:241:89:L013, to generate a UUID:
rtk proxy python tools/quest_api.py id --source gitlab:241:89:L013
That command uses Java-compatible name UUIDs over UTF-8
tdeconomy:quest:<source>. Keep the original reference when titles change. Updates
use the same UUID and retain in-game edits unless their replacement is explicitly
reviewed. For an existing manually created task, use its actual catalog UUID;
never guess identity from its title. Recreating a deleted task under its original
reference deliberately reuses its original identity.
Change and review format
The change file uses the revision returned by catalog. Each upsert is a full
task definition, not a partial patch. Copy existing definitions before editing.
This complete example describes issue #89's concrete oak/spruce log task; the
revision and paying account must be taken from the target server:
{
"revision": "<catalog-revision>",
"upsert": [{
"id": "4ee16feb-c496-3780-9d23-47d27705f670",
"title": "Holz für die BRETTERBUDE",
"description": "Liefere 16 Eichenstämme und 16 Fichtenstämme.",
"difficulty": "EASY",
"theme": "wood",
"finale": false,
"materials": [
{"item": "minecraft:oak_log", "count": 16, "hand": "DELIVER", "compare": "DEFAULT", "template": "", "accepted": [], "ignored": [], "ignoreAll": false},
{"item": "minecraft:spruce_log", "count": 16, "hand": "DELIVER", "compare": "DEFAULT", "template": "", "accepted": [], "ignored": [], "ignoreAll": false}
],
"actions": [],
"money": 35,
"account": "<existing-paying-account-uuid>",
"fixed": [],
"pool": null
}],
"delete": [],
"pools": {}
}
pools replaces only named difficulty lists, for example {"EASY": ["<uuid>"]}.
Omitted difficulty lists remain unchanged. Upserting alone adds a task to the
catalog, not to a Daily pool. Include its UUID in the desired pool explicitly.
delete removes only the explicitly listed task definitions and their pool
entries. It rejects missing tasks and changes that would break fixed series
positions or remove a series' last matching random task. Update those series in
the same batch or in game first. Series definitions and active-run counts are included in the catalog response.
Personal quest series
Use upsertSeries for complete series definitions and deleteSeries for explicit
series UUIDs. Omitted lists leave all other series unchanged. Tasks, series and
Daily pools can be changed together in one atomic review. For example, add this
field alongside the task upsert above, replacing both UUID placeholders:
"upsertSeries": [{
"id": "<stable-series-uuid>",
"title": "The workshop",
"positions": [
{"task": "<task-uuid>", "difficulty": null, "theme": "", "finale": false, "duration": 0},
{"task": null, "difficulty": "MEDIUM", "theme": "wood", "finale": false, "duration": 172800000}
],
"defaultDuration": 86400000,
"difficultyDuration": {},
"after": "END",
"follow": null
}]
Each series has 1–365 ordered positions. A position selects either a fixed task
UUID or a random difficulty (EASY, MEDIUM, HARD). Random positions can filter
by theme and finale flag. Durations are integer milliseconds: position duration=0
uses difficultyDuration or defaultDuration; positive durations may not exceed
3,650 days. The title is limited to 80 characters. after is END, REPEAT, or
CONTINUE; only CONTINUE requires follow, the UUID of another series. Missing
follow targets, cycles, missing fixed tasks and invalid random selections are rejected.
Stable IDs use the same id --source command; give series their own source reference,
for example gitlab:241:89:series:workshop, distinct from every task reference.
While active or restorable runs exist, only the series title can change. Series
deletion also rejects completed or failed runs still stored against that series.
It never deletes player history as a workaround. Remove incoming follow references
in the same batch before deleting an unused series. seriesCreated, seriesUpdated,
seriesUnchanged and seriesDeleted in the review describe the resulting changes.
While Daily quests are enabled, their three pools must each retain exactly 60
distinct valid tasks. Replace removed tasks in the same batch, or explicitly add
"dailyEnabled": false before making incomplete pools. This disables new Daily
accepts while retaining personal series and accepted-task completion/collection.
Add "dailyEnabled": true to activate complete pools. Activation follows the
existing Publish action and also reopens the board for new accepts. In-game
deletion explicitly confirms disabling Daily accepts when deleting a pooled task.
Daily content is fully managed with task upsert/delete, the three pools
lists, and dailyEnabled. dailyEnabled=false disables new Daily accepts without
closing personal series. closed=true invokes the existing board closure: both
Daily and series new accepts stop, but accepted work and earned claims remain.
closed=false reopens personal series without enabling incomplete Daily pools.
Closure disables Daily publication, so republish complete pools with
dailyEnabled=true when Daily offers should resume. Requesting both
dailyEnabled=true and closed=true is rejected as contradictory. These flags
do not reset the current cycle, player choices, attempts or rewards.
rtk proxy python tools/quest_api.py --config <private-database-config> validate --change changes.json --review review.json
rtk proxy python tools/quest_api.py --config <private-database-config> apply --review review.json
Validation writes no world data. The new review file contains the exact change, previous catalog, created/updated/unchanged/deleted UUIDs, resulting pool counts, Daily status and a content receipt. Existing output files are not overwritten. Applying checks both the receipt and the current revision and repeats all live validation. An intervening in-game edit, pool edit or publication/closure rejects the stale request with HTTP 409. Read the current catalog, resolve differences together and produce a new review; never silently update a stale revision.
The server applies the entire catalog batch through the existing durable economy save on its owning thread. It does not replace player state, accepted terms, reward claims, reserved funds, inventory recovery or the frozen current 60-day deck. Existing-cycle offers keep their original definitions; valid catalog edits prepare the next cycle. Deleting a task does not cancel previously accepted work or revoke earned rewards. Re-enabling after an incomplete-pool edit does not reshuffle the existing cycle.
HTTP contract and failures
All requests require Authorization: Bearer <private-key>. These are script
endpoints: requests carrying a browser Origin or URL query are rejected. POST
bodies require Content-Type: application/json.
| Method and path | Result |
|---|---|
GET /api/quests/catalog |
Definitions, pools, series references, revision and board flags |
POST /api/quests/catalog/page |
Revision-bound catalog page, without writing |
GET /api/quests/options |
Available item/block/entity IDs and tags, dimensions and paying accounts |
POST /api/quests/validate |
Change object to review receipt and summary, without writing |
POST /api/quests/apply |
{ "review": "<receipt>", "change": { ... } } to durable result |
The catalog returns nonnegative money as a quoted decimal, for example "9.99".
Use the same format for writes. A JSON integer still means whole currency units.
Revalidate saved reviews against the current catalog after upgrading. Unquoted
fractional numbers, values outside the supported range,
unknown fields, duplicate task operations, missing registry entries, invalid
paying accounts and invalid reward capacities are rejected. Maximum request size
is 1 MiB and a batch may contain at most 1,000 task upserts/deletions and 1,000
series upserts/deletions each. Review smaller batches when a request exceeds this
limit; never split and apply a reviewed batch automatically. Each individual task
or series must fit the existing in-game save request (200,000 characters).
The Python tool reads catalogs in pages automatically. It starts with
{"revision":null,"taskOffset":0,"seriesOffset":0,"limit":50} at
POST /api/quests/catalog/page. Responses contain catalog, nextTaskOffset,
nextSeriesOffset, taskCount and seriesCount. Pass the returned revision and
next offsets to subsequent calls. limit is 1–100 per definition type; each page
also has a 524,288-character definition budget. Stop when both offsets equal the
counts. An intervening catalog edit rejects the read with HTTP 409; incomplete
pages are never returned as a complete catalog by the tool. The tool uses the
legacy full GET only when an older server returns HTTP 404 for paging.
The in-game editor receives bounded ordered packets and opens the catalog only after complete assembly. Its logical response budget is 4,194,304 characters, with headroom reserved for player state and feedback. This replaces the former single-response catalog limit; it is still a finite safety limit, not unlimited storage. All imported definitions remain editable in game. Use matching protocol 62 clients and servers. No SavedData schema or migration changes are needed.
HTTP work uses two bounded workers and a bounded server-thread queue; at most one queued operation is adopted per tick. The tick thread never waits for HTTP work. Normal durable saving still has its existing synchronous storage cost. Storage failures use the economy's existing rollback path. In database mode, apply success waits for shared quest-document confirmation on the HTTP worker, never on the server thread. A lease held elsewhere returns HTTP 503; a publication conflict returns HTTP 409. Shutdown closes the listener and cancels queued work; it does not create a database or perform a deployment.
HTTP 401 means the key is missing/wrong; inspect the private config locally. HTTP 400 means validation rejected the request. HTTP 409 means the catalog or review changed. HTTP 413 means the request is too large. HTTP 503 means overload or shutdown. On a timeout, disconnect or HTTP 500/504, the outcome of an apply may be unknown: read the catalog before any retry. The tool does not retry writes automatically. A key with API access must be treated as an administrator secret.
Verification and manual acceptance
The normal clean Gradle build runs the Java suite and all Python tool tests (Python 3.11 or newer must be on PATH):
rtk proxy .\gradlew.bat clean test build --no-daemon
To run only the tool tests, use rtk proxy .\gradlew.bat pythonTests --no-daemon.
After manual installation and a full restart, verify with a fresh log: API off by default; authenticated access over the chosen connection; no key in logs or player configuration; validate-only leaves the world unchanged; import, in-game editing, stale-update rejection, update, pool selection and confirmed deletion. Test a restart with an accepted task and an earned reward, and verify both remain usable after catalog removal. Verify Daily activation requires 60/60/60 and that an already running cycle keeps its frozen offers. Local unit tests do not replace these gameplay and network checks.
Also verify a multi-page catalog read, a batch adding tasks and linked series, active-run structure rejection, safe unused-series deletion, and all Daily board flags. Open and edit an imported catalog larger than the former packet limit, including Unicode titles. In database mode, test confirmation, busy/conflict responses and a restart with existing progress. Local tests do not establish production API reachability or install the new build.