System

System

A NeoForge mod that brings the “System” from web novels into Minecraft. The Agent runs on the server and handles data
queries, quests, daily check-ins and shop interactions. The client provides a full workspace, a minimal dialogue view
and HUD notifications that keep gameplay uninterrupted, with optional speech output.

Features

• Player and item queries: view your own status and public online-player names, or search for items by name or
  registry ID.
• FTB Quests integration: browse visible, unlocked, actionable and unfinished quests in a compact list. Open details
  by number or name, then explicitly select and claim rewards. Quest completion and newly unlocked quests appear as
  queued System notifications.
• Explicit web research: use /system search <question> or the Web search page to request a lookup. Ordinary
  questions do not trigger automatic browsing. Search shares the DeepSeek key by default, has a separately configurable
  loop budget, and meters Search and Fetch requests separately.
• AI daily check-in: the model selects rewards from a server-approved pool. Rewards enter an inbox for manual
  collection; the model cannot invent items or change quantities.
• System shop: browse offers, review quotes and confirm payment through Saturn Costs, including item exchanges,
  resources and registered extensions. There is no built-in currency economy.
• Data-driven lottery: browse pools, review prize weights and single-draw costs, then confirm one draw. Rewards
  enter the inbox. Data packs configure Saturn Costs or free draws.
• Configurable content and workflows: data packs define system names, descriptions, enabled modules, check-in
  rewards, shop offers and lottery pools. Modules support IDs, tags and conditions. Server rules can trigger bounded
  workflows when players complete advancements.
• HUD notifications and speech: notifications do not take control of the mouse or keyboard. Optional Aliyun
  streaming TTS reads message bodies; closing a view, dismissing a notification or switching messages ends the corresponding
  speech session.
• Usage and privacy controls: server AI and web usage by player, private local TTS / ASR usage, history management,
  external-AI opt-out, UUID-isolated data and limits on model and tool execution.

Quick Start

1. Install this mod and its required dependencies. Add FTB Quests and its dependencies if you want quest integration.
2. Start the server or open a single-player world once to generate the server configuration files under
   config/system/.
3. To use AI, set SYSTEM_DEEPSEEK_API_KEY in the server process’s startup environment, then restart. In single-player,
   the Minecraft process must inherit the variable. Configuration stores the environment-variable name, not the key.
4. Install a server data pack defining a system, then an administrator binds it with
   /system grant <system ID> [player], for example /system grant example:daily Steve. Omit the player to bind
   yourself. Players start unbound and can currently bind at most one system. The release JAR includes no default
   system definition or default module tag; development defaults live only in src/test-mod/.
5. Run /system, /system full or /system simple, then use the controls or type a request.

For example, set the variable in PowerShell, then launch the server from the same environment:

$env:SYSTEM_DEEPSEEK_API_KEY = "<your-api-key>"

Explicit queries, shop browsing and item exchanges do not require a model key. AI check-in and model-based routing
fallback do. /system usage does not require a binding.

Model Configuration

Model settings live in config/system/system-model.json. The default fields are shown below; restart the server after
changes.

{
  "providerType": "auto",
  "baseUrl": "https://api.deepseek.com",
  "model": "deepseek-chat",
  "apiKeyEnvironment": "SYSTEM_DEEPSEEK_API_KEY",
  "apiKeyRequired": true,
  "jsonMode": true,
  "outputTokenParameter": "max_tokens",
  "thinkingEnabled": false
}

Set baseUrl to the API prefix without /chat/completions; the adapter appends that path automatically. To use another
compatible service, change the URL, model ID and key environment-variable name, and explicitly set
providerType: "openai" if needed. auto enables DeepSeek-specific parameters only for the official DeepSeek domain;
when using a proxy for DeepSeek, explicitly select deepseek.

Commands and Interaction

The following commands run in Minecraft chat:

System IDs, players and module arguments support completion. Granting the same system again does not reset player
data; revoke the current binding before switching to another system. Manual module overrides take precedence over
data-pack conditions and persist until revoked or reset. Required modules, including core, binding and usage, cannot
be removed manually.

Notifications appear at the bottom of the HUD. Open vanilla chat with its configured key (T by default) to click
“Confirm” or an action button. Consecutive notifications keep the panel expanded while the content fades out, changes
and fades in. Confirming, timing out or switching notifications immediately cuts off the old speech, so the next message
does not wait for it to finish. Closing an assistant view also ends its speech session.

Optional Speech

All speech features run on the client and use paid APIs.

All speech features currently use Aliyun APIs. Support for more providers is planned.

Voice Input

Requires a separate Aliyun NLS project AppKey and AccessKey ID / Secret. Temporary Tokens are acquired, cached and
refreshed automatically on demand.

Installing Simple Voice Chat is recommended for a better experience.

Voice input is disabled by default. Use /system settings, or enter /settings in the assistant’s input box, then
select Voice input and enable it. Changes are saved automatically. Hold F8 to record and release to finish;
the key opens the assistant during gameplay. /listen and the Voice input button are also available. Final
recognition fills the draft, then Enter sends it; enable Send after recognition to send it immediately. Recording
lasts at most 60 seconds and is cancelled when the view closes.

While a notification is visible, recognized speech first attempts to match its confirmation or action buttons;
unmatched text goes to the main chat. Simple Voice Chat is optional; Java Sound records audio when it is not installed.

Speech Output

Requires a separate Aliyun Model Studio API key and the matching region.

Open Settings → Speech output in the full workspace, or use /system settings or the assistant’s /settings
command and select the tab.

1. Enter an Aliyun Model Studio API key and select its region, or set DASHSCOPE_API_KEY for the client process.
2. Set the model, voice, language and volume. Defaults are qwen3-tts-flash, Cherry and the game language.
3. Preview, then enable automatic speech. Changes are saved automatically. Custom voice IDs must match the model they
   were created for.

Enter exported voice parameters directly in the settings fields. TTS does not support JSON import or a settings reload
button. Local settings are saved in config/system/system-speech.json. The notification sound has its own switch,
enabled by default, and does not require a TTS request.

The Python 3.10+ utility tools/voice_design.py supports voice design, cloning, test synthesis and temporary uploads.
It uses the standard library.

python tools/voice_design.py --lang en --help

Content and Extensions

System definitions live at data/<namespace>/system/system/<path>.json. Names and descriptions use client translation
keys. For example, create data/example/system/system/daily.json:

{
  "name": "system.definition.default.name",
  "description": "system.definition.default.description",
  "modules": [
    "#example:basic",
    "system:web_search"
  ]
}

Place the corresponding module tag at data/example/tags/system/server_module/basic.json:

{
  "replace": false,
  "values": [
    "system:player",
    "system:items",
    "system:signin",
    "system:inbox",
    "system:shop",
    "system:lottery"
  ]
}

Module lists also accept objects with a condition; id can name a single module or a #tag. If several entries match
the same module, any satisfied condition enables it. Module availability controls workspace entries, commands and
execution permissions. FTB features also require their dependencies. See system definitions and module tags.

Check-in rewards, shop offers and lottery pools are defined entirely by data packs, including the bundled defaults:

data/<namespace>/system/signin_rewards/<path>.json
data/<namespace>/system/shop_offers/<path>.json
data/<namespace>/system/lottery_pools/<path>.json

See the examples in this GitHub repository for details.

Data and Privacy

Configuration Files

Configuration files are not synchronized directly between the client and server. System definitions and available
modules are synchronized through Minecraft networking. Player data files in the world folder are managed by the
server; clients cannot modify them directly.

API Usage

AI usage comes from server-side model responses. The server gateway tracks Search / Fetch request counts and estimated
costs separately. The all-player view contains server AI and web records only. TTS and ASR totals stay on the client,
per local account; they are never uploaded to the Minecraft server, and administrators cannot view other players’
voice usage records.

Search / Fetch rates are configured on the server and can be reloaded with /reload after initialization. Voice rates
are configured on the client; reload resources with F3+T or restart after editing them. ASR defaults to an estimate of
CNY 3.5 per 1,000 successful recognitions. TTS uses the character or token usage returned by the selected model; the two
are not charged together.

Empty search results receive no cost estimate. Unknown outcomes, such as timeouts or network interruptions, are recorded
separately and do not prove that the provider charged nothing. Rate changes do not recalculate historical totals;
provider billing is authoritative. See usage and billing and the external API request list.