Skip to main content

Usage and configuration

Choose offline, standard (default), extended or free mode to the left of the send box; the menu shows each name and description, and options disallowed by an administrator are greyed out. Switching is saved automatically, and administrator permissions are independent of personal preferences. The current world save's defaultMode sets both the initial mode and the ceiling selectable by ordinary players, and administrators change it with /system ai default <mode>; single-player players and LAN hosts get all modes by default, and player-level /system ai overrides still take priority. See AI modes and administrator permissions.

When the server model requires an API key but none is configured, only offline mode is allowed, and the menu and settings page show the reason; local commands and matching still work. The server syncs only whether it is ready and never sends the key. Keyless model endpoints with apiKeyRequired=false are not limited by this; once the configuration is restored, the original mode preferences and administrator permissions are applied again.

Config directory​

All runtime configuration of this mod lives in config/system/ of each game instance, split by responsibility:

config/system/
├── system-agent.json           # Server execution budget, concurrency and time zone
├── system-storage.json         # Server player file capacity budget
├── system-model.json           # Server model connection and provider options
├── system-search.json          # Server search connection, shares DeepSeek environment variables by default
├── system-search-pricing.json  # Server Search / Fetch prices
├── system-semantic.json        # Server local routing, thresholds and cache
├── system-advancements.json    # Server advancement rules
├── system-speech-pricing.json  # Client TTS / ASR prices
├── system-client.json          # Client interface mode and theme
├── system-speech.json          # Client speech settings
└── system-asr.json             # Client speech recognition settings

When a configuration is loaded for the first time, ConfigInstance copies defaults/<file name>.json from inside the JAR to the missing path and then reads it with the corresponding Codec. Existing files are not overwritten, and on broken syntax or a read failure an error is logged while the defaults are used in memory, without regenerating or overwriting the bad file; there is no migration from the old directories or the old aggregated config. Edits on the settings page save automatically: local configs are marked dirty and written to disk immediately through INSTANCE.set(next), and a failed save shows an error and keeps the mark for a later retry; server preferences are saved through the existing request and wait for confirmation. A resource reload re-reads the files, while the server engine, model connection and advancement rules still require a full restart of the application. TTS parameters are filled in directly in settings, with no JSON import or in-page reload button. The client and the server each operate on their own configuration, and player business files and the world save usage ledger stay at their original world save paths.

Installation and entry points​

In the in-game chat bar type /system settings, or click "Settings" in the top-right corner of full mode, or type /settings in any assistant input box, to open the unified multi-tab settings page:

  • General: interface mode, theme, saving history and the administrator AI permission description. The interface mode is saved on this machine and history is saved through the server preference interface; the AI execution mode is selected to the left of the send box.
  • Speech narration: Bailian key, region, model, voice, language and volume, plus preview and stop.
  • Voice input: NLS credentials, region, the recognition switch, "send immediately after recognition" and the optional microphone backend status.

All switches, drop-downs, region and text parameters of every tab save automatically after a change, with no save button; switching tabs or closing the page keeps the saved changes. Speech credentials may be filled in item by item, and the complete parameters are validated only on preview or actual use; a blank, non-integer or out-of-range volume reports an error and keeps the previous volume without blocking the saving of other parameters. The interface mode is applied when returning to the assistant and keeps the chat draft. Leaving the speech narration tab or closing settings stops the preview on this page. The assistant settings command is /settings, and pressing F8 while recognition is not enabled still opens the voice input tab. Server model and billing configuration continues to be managed by server files and is not edited in the client settings.

The assistant input box /settings opens the unified settings; select "Voice input", fill in the NLS AppKey and the Alibaba Cloud AccessKey ID / Secret and enable it, and the temporary token is issued automatically and refreshed on demand; /listen or "Voice input" next to the input box starts recording, the result is filled into the draft after it ends, and Enter sends it. "Send immediately after recognition" can also be enabled, so that the final recognition result is sent automatically together with the existing draft; it is off by default. Changes are saved automatically in the client-side config/system/system-asr.json. For operation, permissions and the separate per-attempt billing, see Voice input.

The "Speech narration" tab of the unified settings configures the client-side Alibaba Cloud TTS. It is off by default; after filling in the Bailian key, choose a voice and preview it, and all changes save automatically. The default model is qwen3-tts-flash and the default voice is Cherry; a designed voice has to match the model it is bound to, and its parameters exported by the Python tool are filled in by hand instead of importing JSON. The key and the switch are saved in the client-side config/system/system-speech.json. For details, see Speech synthesis and voices.

The "Notification sound" option on the same page is on by default, needs no key and is independent of auto narration. Turning it off saves immediately and no longer plays the cue when a notification expands, while the body still plays according to the auto narration setting; when it is on, the cue plays only on the first expansion and does not repeat for consecutive messages, and the volume is still 75% of the narration volume.

Minecraft 26.1.2 / NeoForge 26.1.2.114. Install System on both the server and the client; on the client, also install ApricityUI 1.2.9 and its dependencies. FTB Quests is an optional integration; see the development documentation for the exact versions.

  • /system grant <system ID> [player]: an administrator grants a system defined by a data pack; /system grant <system ID> alone acts on yourself. The system ID is completed and validated from the system:system registry of the current world save, for example /system grant system:default Steve. After the first success the HUD shows "Host detection → Link established → Binding succeeded" without opening an interface; granting the same system again only shows an already-bound notice, and another system is rejected and has to be revoked first.
  • /system revoke [player]: an administrator revokes the system and clears that player's business records, keeping the accumulated AI / TTS / ASR usage; omitting the player acts on yourself.
  • /system module add <player> <module ID>, /system module remove <player> <module ID>: an administrator manually enables or disables modules for an already bound online player, overriding the data pack defaults and conditions, and this survives relogging; required modules such as core, binding and usage cannot be changed manually. Player and mutable module IDs support completion.
  • /system module list [player]: an administrator views the module list; without a player it lists every registered module on the server, and with a player it lists the modules that player actually has enabled. It can run from the console; a new module only enters the player list after initialization finishes.
  • /system ai <player> enable|disable: an administrator allows or denies AI for the specified online player; /system ai <player> freechat enable|disable controls free chat only. status shows permissions, limit <count> sets the daily quota, and reset removes that player's administrator overrides. Completion is supported, changes take effect immediately and are saved automatically, the player receives a chat notice and the interface explains the reason for the restriction; personal settings and used quota are kept. See AI modes and administrator permissions for details.
  • /system: opens the bound system with the interface last selected on this machine.
  • /system simple, /system full: open the simple interface and the full workbench respectively.
  • /system settings: the client opens the unified settings page directly, entering "General" by default, and requires no administrator permission or binding; going back returns to the game. /settings inside the assistant keeps the original page and draft.
  • The "System" category in the controls settings gains an "Open/close system interface" key, unbound by default; players can assign it themselves, pressing it opens the interface of the current mode and pressing it again closes the system page.
  • /system routing: administrators / the console view the semantic service state, scores and margins and the in-process counters.
  • /system ftb reload: administrators / the console re-ingest FTB's currently loaded guide quests and rebuild the local index; it does not require a bound system and does not change quest progress or rewards. When the native disk files are edited by hand, FTB has to load them first.
  • /system usage: opens the personal AI / TTS / ASR usage ledger; administrators can switch to "All players" or use /system usage all to view the whole server directly. The statistics are independent of binding and remain viewable after a revoke.
  • /system ask <content>: submits a natural-language request; the reply goes to the current speaking area or the workbench, and a HUD summary is shown while the interface is closed without opening a window proactively.
  • /system help, /system player, /system item <query>, /system quests [query], /system submittable [query], /system view <number or name>, /system claimable, /system signin, /system inbox, /system shop [query], /system buy <offer ID>: deterministic command entry points.
  • /system question <question>: queries local knowledge and answers from the material without allowing web access; /question <question> works inside the assistant.
  • /system search <question>: queries locally first and allows paid web access only when there is no result; the search module still has to be enabled. /search <question> or "search the web for me…" works inside the assistant.
  • /system lottery [query]: lists or searches lottery pools; /system draw <pool ID>: shows the prizes, chances and cost, and draws once only after the separate confirm button is chosen.

Unbound by default. grant/revoke require game master permission (COMMANDS_GAMEMASTER); a target can only be one online player and the console has to provide it explicitly. Each player can currently bind at most one system; the world save uses a separate SystemBindings collection to reserve multi-system expansion, while the current commands, transactions and Codec all limit it to one entry. While unbound, the assistant interface, business requests and advancement rewards are all unavailable, and the independent usage ledger is still viewable; errors of entry points such as /system are shown in the vanilla chat bar and neither pop up a system notification nor trigger system narration. Granting keeps the player's existing records, and only a revoke clears business records.

The released JAR does not ship a default system or a default module tag, so the server has to provide system definitions through a data pack; the development default example system:default only lives in src/test-mod/resources and does not enter the released JAR. Fill system names and introductions with translation keys, and the client resource pack provides the text for each language. The system ID a player binds is persisted; binding notifications, the assistant title, the welcome area, module conditions and entries use the definition selected by that player, see System definition. Reopen the world or restart the server after changing a definition; when a definition is removed, the binding is not switched to the default system automatically.

revoke deletes the server player file of that UUID — binding, conversation, preferences, the sign-in uniqueness marker, the inbox, orders, the daily model quota, business receipts, event quests and advancement baselines — and clears the current client system session. Old quotes and FTB claim references become invalid, and in-flight tasks must not write back after the cleanup; a failed deletion returns a failure instead of reporting that the cleanup succeeded. After a new grant the player starts from a fresh system state, and advancements already completed at binding time do not pay out rewards retroactively. Items already placed in the MC inventory, MC/FTB progress of their own and external payments that already happened are not rolled back; this group of management commands is therefore usable for a test reset and also clears unclaimed entitlements and orders awaiting manual verification.

The old /system give is no longer used, and entitlements of the old architecture are not migrated automatically.

Server-accumulated AI / web usage is saved in the separate <world save>/data/system/token_usage.dat; it does not use player attachments and is not affected by revoke, forget, turning memory off or rebinding. The same page shows the actual AI tokens, Search / Fetch counts and the estimate, plus the TTS / ASR usage that is kept only on this machine for the current account; unknown usage is counted separately and no estimated value is used to fill in real units. It can be opened from "Usage statistics" in the top-right corner of the full workbench or /usage in simple mode; see AI / TTS / ASR usage statistics for details.

TTS billing rates are read from the client-side config/system/system-speech-pricing.json; when the file is missing, defaults/system-speech-pricing.json from inside the JAR is copied first and then loaded. An existing configuration is not overwritten; changes take effect through a client resource reload or a restart and do not recalculate historical cost. For the config format and the behavior on a read failure, see Pricing configuration.

Model endpoint (DeepSeek by default)​

Configuration is generated on first use of the feature it belongs to. The model connection and environment variable names are configured in system-model.json, and the budget in system-agent.json. The server process reads the key from the SYSTEM_DEEPSEEK_API_KEY environment variable; the configuration stores only the environment variable name, never the key, and it is not synced to the client.

Mod-managed data inside the world save is uniformly GZIP-compressed NBT, in the directories below; vanilla SavedData still stays in data/system/. The old system-agent/ and system-database/ are not migrated or deleted automatically, and binding, business records and chat use the new directories directly.

<world save>/system/
├── store.lock                 # Process file lock
├── players/<UUID>.dat         # Binding, preferences, module business and pinned cards
├── chat/<UUID>.dat            # Conversation and request replay cache
└── database/
    ├── shared.dat             # Shared knowledge, quest guides and background cache
    └── players/<UUID>.dat     # Per-player database

Set the key in the server's startup environment first, then start the server normally. The engine and the model client use the configuration snapshot taken at startup, so a normal restart is still required after adjusting the model JSON. baseUrl accepts a fixed HTTPS API prefix and HTTP on loopback addresses, appends /chat/completions automatically, and rejects redirects and arbitrary model-specified URLs.

By default it uses deepseek-chat, JSON output and thinking turned off, and does not retry or repair model responses automatically. Each player gets at most 100 model requests per day by default, and the whole server runs at most 4 concurrent model requests. The fast default is 4 seconds per request and 14.5 seconds per task, and endpoint latency above that may cause frequent timeouts; both can be adjusted in the corresponding module policy, and the values are not a measured SLA.

Other services use the OpenAI Chat Completions format by default; changing baseUrl, model and apiKeyEnvironment is enough to connect. providerType=auto enables the dedicated parameters only for DeepSeek's official domain; a DeepSeek proxy can set deepseek explicitly and an ordinary compatible service can set openai. For jsonMode, the output token parameter name, keyless local services and the DeepSeek thinking switch, see Model connection.

Lightweight local intent routing​

A single operation is still handled by a command, local matching or one model routing step that selects the corresponding workflow; when a request needs to combine several reads such as quests and items, type /reason <request> in the assistant, or let model routing choose the combined analysis. By default it runs at most 3 rounds including the final answer, and web search still queries the database first and is authorized separately, with at most 6 rounds by default. The upper limits are set through reactIterations in the workflow policy of system-agent.json; for the complete fields and examples, see Generic ReAct.

system-semantic.json defaults to mode=ENFORCE: pure Java domain synonyms and TF-IDF matching; when the high score, the score margin and the input coverage all meet the thresholds and the arguments are complete, the request goes straight to a read-only module, and everything else is still decided by the configured model service. Successfully validated partial AI read-only intents can be cached exactly per player for a short time, and the result data is queried again every time. No model download, inference engine or JVM arguments are needed.

Similarity is not a probability. Sign-in, claiming and purchasing never go straight through local matching or the cache; the sign-in reward is still chosen by the AI. It can be changed to SHADOW to observe candidates, or OFF to disable the local layer. The switches of the old configuration are kept, and the old ONNX thresholds are not reused. For the description and examples, see Local semantic routing.

Two interfaces​

Bindings, advancement completion, server notifications and replies that arrive after the interface is closed all enter the client message queue and are rendered as a HUD, by default centered at the bottom, 6vh from the bottom edge. Use Saturn's own HUD editor (right Shift by default, or /saturn hud open) to drag the "System notifications" preview box and adjust the position; the checkbox in the top-right corner controls visibility, and changes are saved immediately to the local config/saturn/hud.json. Use /saturn hud system.notification reset to restore the default position. Close the editor to return to the game. A prompt that arrives suddenly does not release the mouse, capture the keyboard or IME, or pause the game. After opening the chat bar with the vanilla chat key (T by default) you can click "Confirm" with the mouse to close the current message, or choose "Open System", "View details" and the business buttons carried by the message; the hint shows the actually bound chat key.

The notification panel first expands from the center to the left and right within 240ms and then fades the text and buttons in over 160ms; on close it fades out first and then collapses towards the center. Consecutive notifications keep the panel expanded, and the old content fades out before it is replaced and the new content fades in. A notification received during the collapse expands in reverse and then fades in; entering or leaving the chat bar does not replay the open/close animation, and buttons are disabled during animation.

Messages are shown one after another; each notification stays until an explicit action such as "Confirm" or "Close", or until the server updates and ends the current item, and neither the end of narration nor the passage of time collapses it or skips to the next one. Esc only closes the chat bar and resumes play, and the notification keeps showing. The inventory, other system screens or F1 temporarily hide the prompt, and the current item is restored when you return to the game. Notifications provide business actions and "Confirm"; business actions still use the trusted action returned by the server and are disabled while the assistant is busy. The queue waits for at most 32 items and drops the earliest waiting item when full; the full reply is still viewable in the system workbench. The message queue lives only in the current connection and is cleared on logout or a successful revoke; the revoke-completion notification is queued again after the clearing.

Quest notifications are used as interactive small windows: the list holds at most 10 quests per page, and the previous / next page controls sit in the content area, separate from the bottom "Confirm". Paging happens entirely on the client and does not replace the notification or switch to the next one; clicking a quest still queries the current details from the server, and "Back to list" above the details restores the original page number. The bottom "Confirm" ends the whole current window. Newly unlocked ordinary quests show their details directly when there is only one, and are merged into the list above when there are several; a completed quest is always one notification per item. Notifications keep their original width and height limit, and long content scrolls inside.

The full workbench keeps the module sidebar, result cards, history and privacy buttons, and always shows the conversation; the top-right corner holds "Usage statistics" and "Settings". The module toolbar sits below the conversation log and above the message input box, and clicking the same entry again collapses it. A short conversation is shown near the input area and a long log scrolls normally; while you are reading history, a new reply does not force a jump to the bottom. Switch to the simple interface through settings or /mode simple; the view choice is saved in the local config/system/system-client.json and does not affect the server gameplay configuration.

The "General" page of settings provides AUI's native theme switcher. Click the button on the right to choose a theme, which saves automatically and syncs to the full workbench, the simple interface, settings, usage statistics and HUD notifications; pages opened later and the game after a restart also use that choice. The default theme is t09-arwes-transparent, saved in the theme field of system-client.json. The theme affects only this mod's interfaces and the current client; the area outside the HUD panel is always transparent.

The message input of both interfaces is a single line, Enter sends, and Enter during IME composition confirms the candidate. Typing /, a command prefix or a Chinese alias shows local completion; the up and down keys select, Tab or a click fills it in, Enter executes and Esc collapses it. Parameters such as /memory on|off and /mode simple|full are supported, as are /select <number> for the current reply and /view <number|name> for the quest list. Completion does not call the AI and works in offline mode too; free mode does not show command completion. The item and shop search boxes likewise support Enter to query.

The simple interface has only the current speaking area and the input area, without a sidebar, history list, history loading or business buttons. A new request replaces the previous display; the current reply can be scrolled to read the full result, and event notifications do not push out the current options. Explicit phrases such as "sign in", "shop" and "quests" work, and natural language can be typed as well. Queries, paging, quest optional rewards, sign-in delivery and shop confirmation are all done through text: the system numbers the trusted actions in the current reply consecutively, and typing /select 1, Select1, /select 1 or the corresponding number continues. A new reply rebuilds the numbers, so an old number cannot be used to pick an action in an old reply.

For example: type Shop → type the number of a "View redemption details" option → check the current price → type the number of "Confirm payment and redeem" → type the number of the claim option. Each stage performs one request. The model cannot replace the final payment confirmation.

Simple mode is only a way of displaying; it does not change the server-side memory saving policy automatically. /memory off turns saving off and clears the conversation; selecting offline mode to the left of the send box turns off the external model. /forget clears conversation memory, /help shows every input method, /mode full switches back to the full interface, and /close or Esc returns to the game. The simple interface does not perform history viewing, and using /history prompts to switch modes.

Pinned quests and persistent cards​

Click the pin in the top-right corner of the quest list or details to pin a quest on the left side of the screen. The card shows the quest title, chapter, at most three objectives and a progress bar; a colored tick / cross indicates completion, and a completed quest stays until it is unpinned manually. Press the chat key (T by default) to interact, scroll the persistent area and click the pin again to unpin. Normal gameplay does not capture the mouse, and by default the card is temporarily hidden on other screens such as the inventory and with F1.

"Settings → General → Persistent cards" separately controls the entry and exit animations (on by default) and showing on other screens (off by default). After showing on other screens is enabled you can compare quests with items on pages such as the inventory, and the card is still interactive only in the chat bar; the HUD editor uses the preview, and F1 still hides it. With animations off the card appears or disappears directly. Both options take effect immediately and are saved automatically to the client-side config/system/system-client.json, without affecting other players.

Pinned records use Saturn's DataStorage and are saved in the player data of the current world save, isolated by server / world save and player; they are restored after relogging and restarts, and quest progress refreshes every second. Quests that are invisible or whose module is disabled are hidden temporarily and shown again once restored. Revoking the system or resetting deletes the pinned records together, while merely clearing conversation memory does not. This area is independent of notifications, does not take up the message queue, does not close automatically and does not trigger narration. Position and visibility are adjusted in the "Persistent cards" entry of Saturn's own HUD editor, by default right Shift or /saturn hud open.

Workbench​

  • Conversation: explicit phrases and commands are dispatched directly; ordinary natural language first tries the enabled local semantic routing and then a single model routing step as needed. Each request currently handles only one capability, and when the model returns a clarification a read-only entry is offered to choose from.
  • Player overview: your own model on the left and Saturn's standard player information rows on the right (health, hunger, experience, dimension, game mode, effects, resources, abilities and so on). Name / health / level / dimension are no longer repeated separately, and the online player list is no longer shown; when the information cannot be obtained, placeholder text is shown. The model preview has no border by default and can be restored in the card template.
  • Item lookup: searches by the server-side display name or registry ID and shows the results in a shop-style paginated grid; click an item to see how it is obtained, and hovering shows the item details, registry ID and stack size. The vanilla server's name language may differ from the client's, so the registry ID is more reliable.
  • Item sources: /system recipe <item ID> [scope], the "View source" button shown when an item search has exactly one match, or simply asking "how do I get a diamond pickaxe" — semantic routing resolves the name into a registry ID with the local display-name table and routes directly (subject to the system-semantic.json thresholds), without looking up the ID first. Results are grouped into "recipe / loot / tag", and the buttons show the count of each group; by default a recipe page holds 4 entries (at most 2 in simple / notification), a loot page 12 and a tag page 24, and each group remembers its own page. Recipes show ingredient slots, the output count and the crafting station, items support tooltips, and several candidates show substitutable examples; loot and tags use compact lists. Group switching and paging happen inside the card body and do not request the AI. The scope is optionally all (default), recipe, loot or tag, and omitting the second word means a complete query. Sources such as item repair and brewing that are not in the server recipe table cannot be found; see Module lifecycle.
  • Quest manual: by default it lists only visible, unlocked, advanceable and incomplete quests; a locked team does not show in-progress quests. All matching quests go into one scrollable list that shows only the number, quest name, chapter and progress, without expanding objectives, description or rewards. /quests <keyword> or /quests [keyword] keeps filtering; /view 1, /view <quest name>, /view <number or name> or clicking a list row expands the details, and /system view <number or name> also works. The details page shows the full description, quest objectives, ordinary rewards and optional rewards page by page as needed. When FTB is not installed, the details module is not registered and no quest entry is shown.
  • AI sign-in: the model chooses on the spot from the candidate bundles approved by the server, and the daily unique entitlement is recorded only after a legal response; there is no random guarantee.
  • Reward inbox: credited rewards are saved independently of the conversation and can be claimed into the inventory manually.
  • System shop: search offers, view prices and confirm redemption. The default offer is 16 cobblestone for 4 torches; administrators can configure it or replace it with a data pack. It is still usable from the sidebar or through deterministic commands without a key and with external AI turned off.
  • System lottery: browse data pack lottery pools from the sidebar, /lottery or "lottery", and /draw <pool ID> previews the chances and cost. After confirmation it draws once according to the weights and stores the result in the inbox; confirming again does not draw again or charge again. The default system:supplies costs 1 emerald, each draw is independent and there is no guarantee. The simple interface uses /select <number> to finish preview, confirmation and claiming; none of these steps calls the AI, and the lottery settlement narration reads only the result and the prize names.

Non-item objectives / rewards in quest details, submission results and notifications use FTB's native type icons with the count or progress next to them; hover to see the title, type, concrete content and claim state, and HUD notifications require pressing T first. Items still use the real item preview and the vanilla tooltip, and this also applies to optional rewards and the experience rewards of a gift.

Quest names, chapters and descriptions are read in the current player's game language; when a translation is missing, the fallback language of the FTB quest file is used, and name lookup and display share the same title.

Quest numbers correspond to the current player's most recent complete quest list, numbered consecutively from 1 and no longer limited by the former 8-entry paging; expanding details does not replace this numbered list. The number mapping is kept for 10 minutes and isolated by UUID, team, binding generation and memory generation, so after a revoke, clearing memory, changing teams or reloading quests it has to be queried again. Viewing by name prefers an exact title or quest ID match and falls back to a title-contains match when nothing matches exactly; several results show only a short candidate list without expanding anything on its own. An explicit name or ID query can view other currently visible quests, including completed ones, while still obeying FTB's hidden chapters and the "hide details until startable" setting.

/claimable or "claimable rewards" separately lists completed quests that have rewards waiting to be claimed; the list stage does not create a claim reference, and a claim action valid for two minutes is generated only after the details are expanded. Natural-language claiming likewise needs a valid reference returned by the details; without one it first lists the quests with pending rewards and views their details, and it currently does not freely search and then batch-claim automatically. None of the explicit query and view commands above calls the AI.

/submittable [keyword], "submittable quests" or "checkable quests" lists the quests the system can currently submit, and the quest page of full mode also has a "Submittable / check" entry. It lists only quests that are visible, unlocked, incomplete, not paused by the player and have at least one supported, incomplete manual objective whose order allows it; manual objectives that are already complete and objectives that can only be submitted in the FTB interface do not make a quest enter this list. The numbers are shared with the ordinary quest list, so /view 1 or /submit 1 can follow. Submittable means the native submission entry may be called; it does not guarantee that the inventory has enough materials, that a custom check passes or that the quest completes in one go. FTB allows partial submission, and the actual progress is decided by the native interface. The query itself does not consume items or experience.

Quests that need manual submission are judged by FTB objective type and configuration: one such objective in a quest is enough, and it is not limited to consuming items. In the assistant input box you can send /submit 1, /submit <quest name>, /submit <number or name>, or use /system submit <number or name> in the vanilla chat bar. The numbers are shared with the most recent quest list used by "View", and with duplicate names you query first and then choose; an explicit submission handles the native item consumption, checkboxes, experience and manual custom-button objectives supported by the selected quest, and does not trigger automatic detection objectives such as kill or observe. Item, fluid, energy and other unsupported resource objectives of the quest interface still have to be handled in FTB. Pausing, quest order and prerequisites are kept by the original interface, and one command does not enter the next round of a repeatable quest. Queries, notifications and narration never submit on their own; the submission tool does not enter automatic model routing.

Quest notifications and details share the QuestSubmission selected by the server: when only native checkbox objectives remain, "Complete this quest" is shown; when there are other currently submittable supported manual objectives, "Submit quest" is shown; otherwise no submit button is shown. Only pressing T and clicking, or saying the corresponding button text in a notification, calls the native submission; "Submit quest" also recognizes aliases such as "submit materials". Submission may consume items or experience; the checkbox-only action carries checkmarkOnly=true and does not consume resources. The server rechecks prerequisites, team lock, player pause, objective order and remaining objectives when executing, so an old checkbox button cannot turn into a resource submission. A quest that is genuinely still locked behind prerequisites does not skip its dependencies, and guide quest filtering and the starter gift claiming flow keep their original rules.

The "Speech narration" settings provide toggles for quest details, rewards and background, with details and rewards on and background off by default. With details off only the name and rewards are read; with it on the requirements are appended. Background extracts only real narrative from FTB's original description, and blank, operational explanations or content that cannot be determined are omitted. Common objectives are formatted directly, and model-organized fragments of special objectives and rewards are cached in server memory; the background verdict is saved by unique quest ID and language in the system:quest_backgrounds table of the world save's system/database/shared.dat (GZIP-compressed NBT), including results judged to have no background, and it is regenerated after the content or the prompt changes. With external AI off there is no web access and the cache can still be reused; uncached objectives use the original text and an uncached background is omitted. See Speech synthesis and voices for details.

After FTB Quests is installed, completing a quest automatically emits a "Ding— Quest complete" system message; when the ordinary quests unlocked by the same batch of progress changes contain only one item, its details are shown directly, and when there are several they are merged into one "Ding! N new quests unlocked" list notification. The completed items of the batch are shown one by one first, then the gift summary (if any) and the unlock notification; the list shows name, chapter and progress in chapter / quest order, 10 items per page, and after pressing the chat key (T by default) you can page in the content area, click any row to view details and return to the original page. The unlock list does not take up or overwrite the numbers of the most recent active query and opens details by quest ID; ordinary queries still support /view 1. The notification itself does not call the AI, submit or claim automatically, or overwrite the current conversation options.

Only on a successful new binding does the system show, in order through the same notification queue: binding message → claimable starter gifts → overview of currently advanceable quests (the total and the first three). All claimable gifts are merged into one scrollable list that shows only rewards and claim state, not the source quest name; experience points and experience levels are summed separately, so for example six lots of 100 experience show a single "+600" icon and the tooltip is summed as well. Stacks of the same item with the same components are merged, and items carrying the native only_one condition stay separate. Clicking "View gifts" reads the full list and clicking "Claim gifts" claims them in a batch. "Confirm" only closes the notification; within the same connection the gift can still be claimed from the card in the chat history, and the gift reference does not expire by waiting two minutes; logging out, revoking or disabling the quest module clears the reference, and the history after reconnecting is read-only. On success it refreshes silently and removes the claimed items without appending a success notification, and failed items keep their actual hint. When there are no gifts or quests the corresponding notification is skipped. Relogging of an already bound player, a repeated grant and opening or closing the system interface do not resend the guide; a rebind after a revoke triggers it again. If an ordinary quest is explicitly submitted and completes, only the quest completion notification is shown, without repeating a submission success or progress update.

The rewards area of gifts, quest details and quest notifications shows the "Rewards" heading only once, with items and other reward icons arranged compactly side by side and wrapping automatically beyond the width; hover to see details. Optional rewards keep their own options and buttons, and a failed gift claim keeps the corresponding error hint.

After clicking "View quests" in a notification, all matching quests are shown directly in the same scrollable list, each row containing the name, chapter and progress; press T and click the corresponding row to view quest details. With many quests you scroll directly, without a "Next page" button; you can also click "View details" to enter the system interface. Quest rows are not truncated by the number of bottom action buttons.

A pure guide quest (no quest objectives or only native checkbox objectives, and no rewards) does not enter system queries, details or notifications. Only quests with native checkbox objectives only, that are not repeatable and have at least one non-empty item reward — optionally with native experience / level rewards — are shown as a starter gift: the card shows the items and the attached experience directly, and only clicking "Claim gifts" submits the checkboxes and claims FTB's original rewards. Claiming keeps FTB's prerequisites, quest order, pause, team and repeat-claim limits, and does not complete guide quests automatically to skip dependencies. Experience-only quests, quests with other rewards such as commands / optional / random, hidden rewards, third-party quest types and repeatable quests still go through the ordinary quest flow. After the quest definition or team changes you can click "View gifts" to refresh; already claimed or currently unclaimable gifts show their actual state.

Guide retrieval is independent of the in-progress queries above: only quests that are checkbox-based or have no objectives, carry body text and are not gifts can enter the local index. The quest page accepts a question query, and /system guide <keyword> or /guide <keyword> and /guide <keyword> inside the assistant also work. Relevant paragraphs and the expandable original text are returned, and guide quests are not completed automatically; completed guides can still be read, and hidden content and content that does not meet the text unlock condition are not returned. The original text is saved by language in the system:ftb_guides table of the world save's system/database/shared.dat (GZIP-compressed NBT), and administrators can use /system ftb reload to re-ingest it and rebuild the index. Explicit queries do not request an embedding or chat API; vague natural language may still go through the existing model routing. See FTB guide index and Shared and per-player databases for details.

Quest completion notifies online team members who have a system bound, sharing progress by FTB team; the unlock decision uses the same visible, advanceable and incomplete conditions as the in-progress list, and does not treat quests that already existed at the first binding, on relogging or when joining a team as newly unlocked. Hidden chapters are not notified. FTB has no separate unlock event, so the state change is checked after a progress event and locked, reset and repeatable-cooldown changes are rechecked once per second. Reloading quest files rebuilds the baseline; while offline notifications are not accumulated and historical completions are not replayed. FTB's native completion hint is kept.

Claiming and failure states​

The sign-in business day is computed from timeZone in the server's system-agent.json, defaulting to Asia/Shanghai; the same world save, player and date have only one daily entitlement. Decisions returned across a day boundary are not recorded. Do not change the time zone casually after deployment; there is currently no time zone migration tool.

Rewards enter the inbox first. The delivery state is reserved before claiming; enough free inventory slots are required, each reward entry reserves one slot, and the entitlement is kept when there are not enough slots. A disconnect, a model failure or insufficient free inventory space is never disguised as success by client-side text.

DELIVERY_UNKNOWN or DELIVERING turns into unknown after relogging: the interruption may have happened between the game write and the ledger flush. The system does not resend automatically, and an administrator has to check the world save together with the logs manually. There is currently no automatic repair or administrator re-delivery command. The database / player files are not one transaction, so strict exactly-once item delivery after any crash cannot be guaranteed, and there may also be a loss window for a world save that has not been saved yet.

An FTB receipt only proves that FTB validation passed and the corresponding reward handler ran; it does not prove that the item of every third-party reward has reached the inventory. The reference has to be queried again after a quest reset, a team change, a reload or expiry, and optional rewards must be chosen explicitly.

System shop​

Enter the shop from the sidebar, choose "View redemption details" and check the price before choosing "Confirm payment and redeem"; click the button in the full interface and type the current number in the simple interface. Each confirmation buys one offer; the quote is bound to the current player, offer and catalog version and expires after two minutes. Natural language can browse offers and generate a preview, but the actual payment needs a separate confirmation action. /buy also only generates a preview and does not pay directly.

The shop and the lottery both pay through Saturn Cost. Item costs use Saturn's item / tag matching rules and the player's Inventory; an ordinary item ID matches by type, so similarly named, enchanted, damaged or component-carrying items may also be consumed. The different slot ranges and complex matching are decided by Saturn, and this mod's original exact-component deducter on the main inventory is no longer used. Offers enter the inbox first, and with a full inventory you can also redeem first and claim later.

Prices can combine items, Saturn resources and extension Costs; a system currency can be defined as a Saturn resource and no longer needs a separate payment interface. There is still no built-in currency issuance, transfer or top-up feature. A dynamic cost is fixed when the confirmation quote is generated, and the payment conditions are rechecked on confirmation; after changing the player entity or after the quote expires a new preview is needed. System and Saturn have to be installed on both the client and the server. For the data pack configuration, see Extension configuration.

Sign-in rewards, shop offers and lottery pools come from separate server-side native Data Pack Registries; content changes require reopening the world or restarting the server. A module's rewards / offers / pools can restrict the selectable content with a single ID, a #tag or a mixed array, and the built-in modules use #system:default of each table; newly added entries also have to be added to the corresponding tag or module selection. The allowances of the same kind enabled by the same player are unioned, and the restriction applies to lists, sign-in selection, quotes and confirmation charging alike. Tag members are updated through a vanilla reload; see Module catalog options for details.

An order is first persisted as PREPARED while reserving a non-claimable inbox slot for the offer; after charging succeeds, the order completion and the entitlement unlock are written in the same player file transaction. Confirming the same quote again does not charge again. A confirmed failure with no charge deletes the reserved entitlement and a new quote can be generated; an order interrupted between charging and the ledger shows PAYMENT_UNKNOWN, the reserved entitlement stays locked, and after relogging it does not charge, resend or refund automatically — an administrator has to check it against the order snapshot and the player file. The world save and the order file are not one transaction, so a crash or separate rollbacks may still leave materials / entitlements inconsistent, and strict exactly-once settlement is not guaranteed.

Conversation and privacy​

The server isolates history, results, quests and rewards by world save directory and player UUID. The original text is kept for at most 30 days and at most 256 events; the model context selects only bounded recent events and compressed historical results and does not call an extra summarization model.

The interface provides history, clearing memory, turning history saving off and the offline / standard / extended / free mode choice. Turning saving off clears the local history and result cache; after external AI is turned off, deterministic queries and the enabled local high-confidence read-only direct paths are still available, while routing fallbacks that need the model service and AI sign-in are denied. Turning history saving off also disables the exact intent cache; clearing memory, changing preferences, revoking or disconnecting clears the cache. The first open syncs the actual preferences. The simple interface manages preferences through the text commands above; the local interface choice is kept as a device setting, and revoking a player does not rewrite that file.

Clearing memory does not delete the sign-in uniqueness marker, the inbox, event deduplication or business receipts. The model and the history text have no right to change the player identity, extend the tool catalog or execute arbitrary commands; the necessary text sent to the configured model service is still subject to the provider's policy, and clearing locally does not mean deletion on the remote side.

Optional features and the sidebar​

The left side of full mode directly arranges the entries provided by each module, without group headings; usage statistics and settings move to the top-right corner. Disabled modules hide their entries, the current toolbar collapses when it loses permission, and the conversation log keeps showing. A server data pack's system definition can decide by player condition whether a module is enabled; see System definition and module switches for details. Manual add/remove overrides survive relogging and are cleared on revoke or reset; the independent usage ledger and client settings are not affected by business module switches. The default released definition includes the FTB quest module, and quest features are only assembled when FTB Quests is installed; without it the definition and existing data are kept, no quest entry is shown and it cannot be enabled manually.

Every knowledge question queries the local player / shared knowledge and the readable guides of enabled FTB modules first. When material exists it answers according to the source and shows the collapsible original text, and it does not search even when the material is incomplete or organizing the material fails; a database error is reported as an error. /question <question>, /system question <question> and ordinary questions do not allow web access and return a hint when the result is empty.

Only when an administrator has explicitly enabled the search module and web access is allowed for this request do empty results fall back to search. The development default does not grant that module either; /system module add <player> system:web_search adds it manually, and a released environment has to provide the corresponding data pack entry first. The search page of full mode allows the fallback after the question is filled in and Enter / the button is pressed, and opening the tab does not query; /search and an explicit web expression mean the same thing. Other natural expressions are judged by the routing model, and the authorization is not carried over from history.

By default it reuses the server's SYSTEM_DEEPSEEK_API_KEY, and the connection is configured in system-search.json; after switching to another chat model, DeepSeek search can still be used separately. Search / Fetch cost CNY 5 per 1,000 successful requests that returned results (CNY 0.005 each), and model tokens are charged separately; the prices are in system-search-pricing.json. Turning "External AI" off also disables search. This Q&A allows at most 6 model calls, 9 tool calls, 20 steps and 90 seconds by default, with a single model call capped at 20 seconds, and database queries and internal FTB queries also count as tool calls; adjust it separately with policies["system:question"]. Web results contain the answer and collapsible sources, and narration reads only the answer. See Search configuration, authorization and budget for details.