Skip to main content

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

  1. 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.
  2. Read catalog and options. 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.
  3. 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.
  4. 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.