NexaSpoofer Documentation

Check: Java 21, first console error and /nexaspoofer license.

Fix: replace the placeholder key in config.yml, correct named YAML errors, then restart. Never share the key.

Verify: plugin completes enable and /nexaspoofer status responds. See Installation and License.

Check: /nexaspoofer setup status and Smart Setup → Server & NPC.

Fix: set Player Count and save NPC Spawn in the intended world. Optional integrations can remain NOT_REQUIRED.

Verify: server setup row reads READY. See First Setup.

Check: /nexaspoofer list, /nexaspoofer runtime, route and hooks.

Fix: confirm profile exists, world/location is allowed and NPC Representation is correct. Tab presentation is separate; check TAB/ProtocolLib hook.

Verify: profile is online and NPC appears in allowed world. /nexaspoofer invisible is not ready. See First Fake Player and NPC Locations.

Check: current hour/timezone, override, Auto Join and saved profile count.

Fix: set the target with left-click or reset inherited hour with right-click. Enable Auto Join after spawn is ready and generate enough profiles.

Verify: compare current/target in /nexaspoofer status after an update interval. See Schedule.

Check: /nexaspoofer ai status, AI provider, key, Base URL, Model and mute state.

Fix: correct required fields and run one AI test or Manual Tester AI Reply.

Verify: provider status identifies the selected route; scripted reply is not proof remote AI worked. See AI Chat.

Check: /nexaspoofer intent status, intent inspect <fake> and intent logs.

Fix: follow the displayed reason, check provider/item and use ACTIVE if execution is expected. Repeated force requests do not bypass feasibility.

Verify: evaluate once and read the next trace. See Intent Engine and Simulation Lab.

Check: hooks, setup status, provider capabilities, item master/channel and remaining stock.

Fix: select a capable provider, enable exact channel and review Economy Safety on staging.

Verify: rerun matching scenario and confirm provider state. See Global Commerce and feature guides.

Check: native session is still open and the offer contains a configured item.

Fix: finish/cancel the UI, confirm fake inventory/balance, then read the result after close. Empty offer should be blocked.

Verify: provider transaction and /nexaspoofer audit trade 20. See Trade.

Check: Manual Tester Test Setup → Crate Location/Key, profile Crate Editor and provider hook.

Fix: use a valid test crate/key; check whether prior attempt consumed it.

Verify: provider log and test result. See Crates.

Check: hooks, Practice mode mapping, TrainingBot profile list and bot Validation.

Fix: map each bot-enabled mode to an existing profile; enable Practice Activity and the selected bot.

Verify: Queue Test or Manual Tester shows a native provider session. See Practice and TrainingBot.

Check: claim hook, selected provider, enabled world and test stage detail.

Fix: move the test anchor to an allowed point; review distance, size and provider costs.

Verify: Create → Inspect → Delete on staging. See Claims.

Check: server MSPT/TPS, /nexaspoofer status, latest module and Web Control Center System.

Fix: pause newest activity, reduce online target, compare metrics; do not raise limits before finding the source.

Verify: metrics return toward baseline. See Performance.

Check: /nexaspoofer panel URL and last error.

Fix: inspect web/web-panel.yml, port, token and allowed origins; start with localhost.

Verify: command reports RUNNING and printed URL loads. See Web Control Center.

• languages/en/messages.yml and languages/tr/messages.yml own player-facing messages; language knowledge files supply AI context.
• languages/<language>/scripted.yml owns scripted chat pools and their hook requirements.
• menus/**/*.yml owns GUI titles, slots, icons, lore, visibility rules and configured menu actions.
• plugin.yml declares the command, alias and permission surface bundled in the jar.

AI provider, model, API-key environment-variable and response settings are part of config.yml; there is no separate root ai.yml in the current resource set.

enabled: true
mode: ACTIVE

evaluation:
  idle-min-delay: 3s
  idle-max-delay: 8s

lifecycle:
  enabled: true
  min-wander-before-first-intent: 45s
  min-wander-between-intents: 30s

selection:
  maximum-candidates: 6

Use /nexaspoofer intent mode <DISABLED|SHADOW|ACTIVE> to change the live engine mode, or edit this file for the persisted setting.

Legacy trainingbot.yml and older standalone practice-mapping files are migration inputs. Current provider and TrainingBot mappings are owned by hooks.yml; randomized practice pool membership is stored in fake-profile metadata. The menu file menus/core/safety.yml is a GUI layout, not a separate safety configuration file.

Config and menu reloads merge missing defaults and keep existing values. Restart after changing the jar, license, storage driver/credentials or web-panel bind/port.

prefix: "<gray>[<gold>NexaSpoofer</gold>]</gray> "
missing-message: "<red>Missing message: <key></red>"

no-permission: "<red>You do not have permission.</red>"
player-only: "<red>Only players can use this command.</red>"
unknown-command: "<red>Unknown subcommand. Use <yellow>/nexaspoofer help</yellow>.</red>"
feature-not-ready: "<yellow>That feature is planned but not implemented in this part yet.</yellow>"
command-error: "<red>That command could not be completed. Check console for details.</red>"

%nexaspoofer_online%                 # displayed count; alias: total
%nexaspoofer_fake%                   # active fake-player count
%nexaspoofer_real%                   # real-player count
%nexaspoofer_target%                 # current fluctuation target
%nexaspoofer_max%                    # displayed maximum
%nexaspoofer_tab%                    # active profiles used by tab state
%nexaspoofer_server_list%            # displayed server-list count
%nexaspoofer_profile_count%          # stored profile total
%nexaspoofer_ping%                   # viewed player/fake ping
%nexaspoofer_ai_status%
%nexaspoofer_license%
%nexaspoofer_storage%
%nexaspoofer_runtime_mode%
%nexaspoofer_runtime_provider%
%nexaspoofer_physical_runtime_status%
%nexaspoofer_physical_runtime_available%
%nexaspoofer_physical_active%

%nexaspoofer_simulation_mode%
%nexaspoofer_simulation_status%
%nexaspoofer_nms_npc_world_policy%
%nexaspoofer_anchor_world%
%nexaspoofer_practice_status%
%nexaspoofer_practice_queue%
%nexaspoofer_practice_queue_nodebuff%
%nexaspoofer_practice_queue_nodebuff_ranked%
%nexaspoofer_random_practice_status%
%nexaspoofer_random_practice_queue%
%nexaspoofer_random_practice_matches%
%nexaspoofer_trainingbot_status%
%nexaspoofer_leaderboard_balance_1_name%
%nexaspoofer_leaderboard_balance_1_score%

Per-kit practice placeholders also support _ranked, _unranked, _min and _max. Leaderboard forms are %nexaspoofer_leaderboard_<metric>_<position>_<name|score|position>%.

%nexaspoofer_economy_status%
%nexaspoofer_economy_vault_status%
%nexaspoofer_economy_total_balance%
%nexaspoofer_economy_average_balance%
%nexaspoofer_economy_top_player%
%nexaspoofer_economy_top_balance%
%nexaspoofer_proxy_status%
%nexaspoofer_proxy_local_fake_online%
%nexaspoofer_proxy_network_fake_online%
%nexaspoofer_proxy_network_displayed_online%

Proxy/Redis exposes additional local and network aggregate values. Unknown identifiers return no value. Use the current PlaceholderAPI section in the plugin's feature reference when you need the complete family list.

Purpose: Routes fake chat actors through NexaChat's formatting pipeline via its public fake-actor API.

1. Install NexaChat and restart the server.
2. Configure integrations.nexachat.enabled: true in hooks.yml.
3. Run /nexaspoofer hooks and confirm the adapter reports ready.
4. Test with /nexaspoofer say <name> hello.

If the hook reports DISABLED_BY_CONFIG, check the toggle in hooks.yml. API compatibility is reported by the hook; NexaSpoofer does not reflect into NexaChat internals.

Purpose: Sends fake tablist entries with skin, ping and display-name metadata, with batched packet updates and clean removal on reload/disable. Real players receive replayed entries on join.

Troubleshooting: If tab entries do not appear, confirm ProtocolLib supports your server build, check modules.tablist and tablist.enabled, then run /nexaspoofer hooks for the adapter state.

1. Install a ProtocolLib build matching the server jar.
2. Restart the server.
3. Spawn one fake profile and check the tab list.
4. Toggle tablist.ping.min/max for believable ping values.

Purpose: Registers the %nexaspoofer_*% expansion for scoreboards, TAB, websites and external displays.

1. Install PlaceholderAPI.
2. Restart the server.
3. Run /nexaspoofer hooks and confirm placeholder registration.
4. Use values from the Placeholders section.

Purpose: NexaAuctions provides market scan, buy, bid and cancel through the native AuctionApiProvider. NexaTrade completes fake-seller trades through NexaTradeApi.completeFakeSellerTrade only. Orders use the provider-owned Order service: NOrder exposes native create, own-cancel and query, while FoOrders and BlazeZ Order fail closed when the required safe public lifecycle artifact/capability is unavailable.

Troubleshooting: Confirm the installed provider build exposes the documented API; /nexaspoofer hooks shows per-provider capability detail.

Purpose: Read-only native market scan hooks for item and price context.

Safety: These providers never mutate the market; auction listing/buying/bidding remains disabled unless a verified native mutation provider is selected.

Purpose: Detected through plugin.isEnabled() and included in auction-activity.hook-priority. Native surfaces appear when the providers expose verified APIs.

Safety: Detected-only plugins provide status; they do not mutate markets on their own.

Purpose: Safe practice queue counts, real queue state reading, kit awareness and bot-match activity surfaces. StrikePractice gets a native queue join, kit and queue state reader plus command adapter.

Safety: NexaSpoofer avoids blind private queue mutation. Placeholder-only and command-safe paths are preferred unless a target API is verified in your environment.

Troubleshooting: If queue counts look wrong, check per-kit min/max values, queue type and whether the target hook runs in placeholder, command or native mode.

Purpose: Spawns mapped TrainingBot-backed opponents from fake profiles, applies rating tiers, saves match results and cleans up after testing or match end.

Troubleshooting: Confirm TrainingBot is installed, the selected provider/mode mapping is configured in hooks.yml, and the referenced global profile exists in TrainingBot. Combat behavior and movement belong inside that plugin's own profile config.

Purpose: Fake crate opening activity through native openCrate APIs, feeding crate chat categories and invisible crate traces.

Setup:

1. Install ExcellentCrates or CrazyCrates and create at least one crate inside the crate plugin (ExcellentCrates: plugins/ExcellentCrates/crates/, CrazyCrates: plugins/CrazyCrates/crates/).
2. Restart the server. NexaSpoofer detects the plugin automatically; confirm with /nexaspoofer hooks.
3. Native crate opens need a physical fake player online (runtime.mode: "PHYSICAL"). Spawn one with /nexaspoofer spawn <name> before testing.
4. Add the optional crate-hooks section to config.yml when you want to change defaults:

crate-hooks:
  enabled: true
  priority:
    - "ExcellentCrates"
    - "CrazyCrates"
  ExcellentCrates:
    enabled: true
    native-api: true
    ignore-restrictions: true   # bypass key/permission requirements for fake players
    ignore-animation: false     # skip the opening animation for faster fake opens
  CrazyCrates:
    enabled: true
    native-api: true
    key-type: "free_key"
    event-type: "event_crate_force_opened"
  crate-id-aliases:             # map display names to real crate ids
    "Vote Crate": "vote"
  command-fallback:             # only used when no native provider is available
    enabled: true
    hooks:
      generic:
        enabled: false
        command: "crate givekey %player% vote 1"
        run-as: "CONSOLE"       # CONSOLE or PLAYER
        require-target-plugin: true
        plugin: "ExcellentCrates"

Usage: When the activity scheduler runs a crate action, NexaSpoofer reads the provider's crate list, picks the profile's preferred crate (set it in the profile editor's Crate GUI by cycling available crates) or a random one, opens it through the native API and chats a line from activity.actions.crate.messages. Test with the Crate editor Test Crate Open button or /nexaspoofer event crate.

Command fallback placeholders: %player%, %player_uuid%, %crate%, %crate_id%, %reward%. Dangerous commands (op, deop, stop, restart, reload) are always blocked.

Troubleshooting: If the GUI shows No Crates Available, no crates are defined in the crate plugin. If a test open fails silently, the fake player is not spawned as a physical entity.

Full guide: docs/integrations-setup.md.

Purpose: Routes fake vote activity through the selected vote provider's supported native API so the reward plugin receives its normal vote path.

Configuration: Provider selection, service-name allowlist and adapter toggles live under providers.vote in hooks.yml. Command fallback is provider-specific, empty and disabled by default; do not use the retired vote-hooks or fake-votes config blocks.

Usage: Enable vote activity for the profile in the Vote editor, confirm the selected adapter with /nexaspoofer hooks, then test through the Vote editor or /nexaspoofer event vote. The native vote path updates the profile counter and emits NexaVirtualVoteEvent.

Troubleshooting: If the provider is unavailable, check its installation, hook selection and API capability. If the event arrives but rewards do not, verify the reward plugin accepts the service identity and named/offline vote source configured by the server.

MythicMobs: reads active boss data only - no synthetic boss data is generated. Configure mythicmobs-hook.max-active-bosses and boss-identifiers when bosses do not use boss bars.

LuckPerms: resolves prefix/suffix for fake ranks and tab display names.

AuthMe: physical runtime auto-login bridge; keep disabled unless physical mode is actually used.

Purpose: Relays configured combat or practice feed lines when the detected DiscordSRV adapter has a usable API or command path. The integration is disabled by default.

All integration settings belong in hooks.yml, under integrations.discordsrv. Current defaults leave the toggle off, relay command blank and feed flags disabled.

integrations:
  discordsrv:
    enabled: false
    relay-command: ""
    relay-combat-feed: false
    relay-practice-feed: false

Enable only the feed you use, set the exact server-tested console relay command when needed, then confirm capability state with /nexaspoofer hooks. Keep Discord credentials in DiscordSRV's own configuration. Feed relay follows supported activity; /nexaspoofer invisible is not implemented.

Purpose: Chat-format compatibility, tablist compatibility, economy writes, region queries for movement/spawn filters.

Missing hooks are shown in status output and should never stop startup.

Purpose: Optional packet interception and island-activity placeholders. These surfaces report status and participate where configured; none is required to boot.

provider-specific native APIs, capability adapters and detection-only hooks. Hook-related exceptions are logged but never disable the plugin.

license-key: "YOUR-KEY-HERE"
debug: false
color-format: "legacy"

safety:
  require-admin-confirmation-for-real-economy: true
  real-economy-confirmed: false
  max-money-injected-per-day: 500000
  max-real-player-purchases-per-day: 25
  audit-log:
    enabled: true

These settings are in config.yml. Real-economy actions remain confirmation-gated, caps bound exposure and allowed or blocked actions are recorded in the audit log. Auction/order provider operations still use their verified native APIs.

Lifecycle events cover fake profile creation, join, quit, removal and the physical runtime path. NexaActivityPreEvent provides the cancellable gate before supported activity execution, while NexaActivityPostEvent reports the result. AI response and count-change events are emitted by their corresponding service paths.

The NexaVirtual* event classes are addon contracts. They are not all emitted automatically: only an implemented module path that explicitly calls an event emits it. The native virtual vote event and delivered fake-chat paths are examples of active event sources. Check the event's source path before relying on it as a complete record of provider activity.

• Call methods that access Bukkit players, entities, worlds or inventories on the server thread.
• AI HTTP and storage work run asynchronously inside the plugin; callbacks return through the server scheduler.
• Stored history, memory and web observation surfaces use immutable snapshots.
• Public contracts live under net.ritomasss.nexaSpoofer.api; avoid internal package dependencies.