Machine Spirit

A configurable log-triage and diagnostic assistant for modded Minecraft.

Modded Minecraft logs can be intimidating. A harmless compatibility warning can look catastrophic, while a genuinely important threading, recipe, or performance problem may be buried under hundreds of unrelated messages.

MachineSpirit watches the log and adds useful context when something noteworthy happens.

It does not replace, hide, or modify the original warning or error. Instead, it adds a second message explaining what MachineSpirit knows about it, whether it matches a known issue, and—when possible—where a server owner or modpack author should start investigating.

With an appropriate amount of Mechanicus-approved heresy.

What does it do?

MachineSpirit can:

• Recognize known warnings and errors using configurable rules.
• Preserve the original log message, so developers still receive the real diagnostic information.
• Inspect exception stack traces and identify the mod or library most likely involved.
• Show a probable cause pointer and relevant call path when enough evidence is available.
• Give server operators a place to start troubleshooting instead of simply saying “an error occurred.”
• Distinguish common categories such as compatibility problems, threading/lifecycle violations, recipe/data errors, missing classes, networking problems, memory failures, and performance warnings.
• Rate-limit repeated commentary, preventing MachineSpirit from becoming another source of log spam.
• Keep more detailed diagnostic information in logs/machinespirit-triage.log.
• Allow modpack authors to create their own rules for problems specific to their pack.
• Reload rules without restarting using /machinespirit reload.
• Generate test warnings/errors with /machinespirit test <level>.
  
  

  Example

  A normal modded log might say:

   

  ERROR: A mod is calling registerReloadListener at the wrong time.

   

  MachineSpirit can add context such as:

   

  [MachineSpirit] Actual thread heresy detected.
  ModernFix is containing it.
  
  [MachineSpirit] Cause pointer:
  likely source ProjectRed Integration;
  call path also includes CodeChickenLib.
  
  Server operator: start there, preserve the original stack trace,
  and retest after any version/config change.
  
  Attribution is probable, not proven.

   

  MachineSpirit performs diagnostic triage. A stack trace can show which mods were involved without proving which one is ultimately responsible. MachineSpirit deliberately uses language such as “likely source” rather than falsely declaring a mod guilty.

  Known problems vs. unknown problems

  MachineSpirit has two layers of analysis.

  Known issues can have carefully written rules with specific explanations. These are the highest-confidence responses and are ideal for modpacks that have known compatibility quirks.

  For other errors, MachineSpirit can inspect available evidence such as the exception type, logger, thread and stack trace to provide a cautious first-pass classification and point operators toward the most relevant code or mod.

  It is rule-based and deterministic. MachineSpirit is not an AI chatbot and does not send your log somewhere to have it guessed at.

  For modpack authors

  One of this mod's main goals is allowing pack authors encode knowledge they would otherwise have to explain repeatedly.

  If your pack intentionally produces a scary-looking but understood warning, MachineSpirit can explain that.

  If a particular message means players should report an issue, MachineSpirit can say that.

  If a warning means the server should be profiled immediately, MachineSpirit can say that too.

  Rules can be customized through:

   

  config/machinespirit-rules.json

   

  This allows the same diagnostic engine to behave differently depending on the pack it is installed in.

  For server owners

  MachineSpirit is intended to make logs more useful to the person who is actually operating the server.

  Instead of:

   

  ERROR
  [large stack trace]

   

  the goal is closer to:

   

  ERROR
  [original stack trace]
  
  MachineSpirit:
  Likely subsystem: threading
  Likely source: Mod A
  Call path also contains: Library B
  
  Start your investigation here.
  Keep the original stack trace when reporting the problem.

   

  It will not automatically repair broken mods, remove incompatibilities, or replace proper profiling and debugging tools.

  It will try to make the first few minutes of troubleshooting much less painful.

  The personality

  MachineSpirit's diagnostics are wrapped in a deliberately overdramatic machine-cult personality.

  Expect words like heresy, Magos, and occasional concern for the spiritual condition of your JVM.

  Underneath that is a serious diagnostic tool.

  If Minecraft reports:

   

  Can't keep up!

   

  MachineSpirit may respond:

   

  THE MACHINE SPIRIT IS ACTUALLY SUFFERING.
  Check MSPT and profile this workload.

   

  MachineSpirit is in an early development phase, so features, rules, output formatting, and behavior may change between releases. While it is designed to preserve original log messages and avoid interfering with normal operation, please report any incorrect classifications, crashes, or unexpected behavior.