Skip to content

Config Options

Jump to bottom
BallOfEnergy edited this page Dec 23, 2025 · 9 revisions

API

B:"Allow statistics gathering (other mods)?"

  • Default: true
  • Performance impact: Low
  • Compatibility impact: Low

This option controls whether or not other mods are allowed to receive statistics data from Spool itself. Spool has several built-in systems to allow for statistics and general performance data to be gathered and sent to other mods, though it can sometimes be an expensive set of operations if the receiving mod is not properly programmed. Disabling this causes other mods to not receive any data from Spool.

Compatibility

B:"Enable ASM checks?"

  • Default: true
  • Performance impact: Low
  • Compatibility impact: High

This option enables Spool to perform certain ASM checks on mod code (vanilla and other mods) to increase compatibility with Spool. This option potentially causes problems with other mods due to its abrasive changes via ASM, though overall it increases compatibility. More information can be found on the implementation wiki page.

B:"Enable FQCN compatibility checks?"

  • Default: true
  • Performance impact: Low
  • Compatibility impact: Moderate

This option enables Spool to perform FQCN (Fully-Qualified Class Name) checks during compatibility detection. Most mods work with this option, however some advanced/corrosive mods fail when this type of compatibility detection is used (classloader changes), causing a crash. This shouldn't be disabled unless absolutely necessary.

S:"Force-loaded modIDs"

  • Default: {}
  • Performance impact: Low
  • Compatibility impact: Low

Mod IDs inserted into this string array will be loaded into Spool's compatibility system, even if they aren't detected during Spool's checks. This can fix some issues with some mods (especially when used with B:"Enable FQCN compatibility checks?").

Concurrency

B:"Enable concurrent world?"

  • Default: true
  • Performance impact: High
  • Compatibility impact: High

This option enables Spool's specialized concurrent world transformers. Concurrent world is something that was generally thought impractical, however after months of work, Spool is able to replace needed classes inside Minecraft itself with its own, allowing for fully concurrent world access. Many parts of Spool rely on this option being true in order for threading to operate properly, so it should only be disabled if you know fully what you are doing going into it! More information can be found on the implementation wiki page.

I:"Chunk blobbing radius"

  • Default: 5
  • Range: 1 ~ 512
  • Performance impact: High
  • Compatibility impact: Low

This option controls the radius (in chunks) in which Spool should "blob" chunks together. Chunk blobbing is where multiple chunks are combined together into a single data object, reducing expensive map calls when a lot of updates are occurring in one area. Lower values decrease memory usage, however they do less to reduce the unwanted calls. Higher values reduce the calls exponentially, however, the memory usage also scales exponentially, as each blob has to cover more chunks (allocate more room for potential chunks).

Debug

B:"Allow SDB connections?"

  • Default: false
  • Performance impact: Low
  • Compatibility impact: None

This option enables connections to Spool's primitive SDB (Spool Database) system via a socket on localhost:7655. It can only be connected to via the client socket program inside the Spool jar at FQCN:com/gamma/spool/db/SpoolDBManager. This socket is insecure and does not contain any form of password/authentication/verification checks, so if it is enabled, make sure to lock down this port. More information can be found on the implementation wiki page.

B:"Enable ASM debug mode (console logging)?"

  • Default: false
  • Performance impact: Low
  • Compatibility impact: None

This option changes the way Spool logs ASM transformations. This is especially important when Spool's concurrent world is enabled, as it utilizes many ASM transformations. Generally, this option will not impact performance, though it may cause unwanted log spam.

B:"Enable compatibility debug mode (console logging)?"

  • Default: false
  • Performance impact: Low
  • Compatibility impact: None

This option toggles Spool's compatibility debug logging. This can be useful when tracking down compatibility issues and doesn't harm performance, though it can cause log spam.

B:"Enable debug mode (GUI)?"

  • Default: false
  • Performance impact: Moderate
  • Compatibility impact: None

This option enables the debug information inside the Spool GUI (accessible via the Home key, or another keybind set by the user), including time statistics and thread manager information. This does reduce performance when enabled, so it should be kept disabled when running on a server.

B:"Enable debug mode (console logging)?"

  • Default: false
  • Performance impact: Low
  • Compatibility impact: None

This option enables the debug information inside the F3 menu, including time statistics and thread manager information. This does reduce performance when enabled, so it should be kept disabled when running on a server.

B:"Enable full compatibility debug mode (complete SDB logging)?"

  • Default: false
  • Performance impact: Low
  • Compatibility impact: None

This option toggles Spool's full compatibility debug logging. This logs all compatibility interactions (Early/late Mixins, ASM, compatibility detection, etc.) into Spool's SDB (Spool Database) system for verbose compatibility debugging. This SDB file is stored under save/spool/debug.sdb, and contains no system/user information, making it safe to share. More information can be found on the implementation wiki page.

I:"Max # of SDB connections"

  • Default: 2
  • Range: 1 ~ 16
  • Performance impact: Moderate
  • Compatibility impact: None

This option controls the maximum amount of connections to the SDB (Spool Database) server before connections are denied. High values can lead to performance drops, as system/JVM threads can get used up by the SDB system.

Distance Threading

I:"Chunk distance limit"

  • Default: 0
  • Range: 0 ~ 2147483647
  • Performance impact: High
  • Compatibility impact: Low

This option changes how the distance manager allocates executors to different players. Players will have to be 2 * valueOfThisOption + 1 chunks away from each-other for them to be assigned the same executor (synchronized). This can be increased if this option is causing issues with synchronization or concurrent access. If this value is not set (set to 0), it will be the same as the view distance (on servers; render distance on singleplayer; render distance of host on LAN). If this option is lower than the view distance, the game will crash.

B:"Resolve conflicts?"

  • Default: true
  • Performance impact: Low
  • Compatibility impact: Low

This option determines if the distance thread manager should resolve internal conflicts, or if it should crash the game. Sometimes crashing the game is desired, as conflicts can cause data loss of potential issues with tick order/ticking. Spool should be able to handle conflicts on its own with this option enabled, however conflicts can be severe enough to the point where Spool will give up and crash, even when this option enabled. This only attempts to prevent crashes with distance threading; it does not protect any other mode of threading.

I:"Stream parallelization level"

  • Default: 0
  • Range: 0 ~ 2
  • Performance impact: Moderate
  • Compatibility impact: Low

This option is used to determine how aggressively streams should be parallelized, primarily when calculating the chunk flood-fill algorithm that Spool uses for force-loaded chunks. A value of 0 disables stream parallelization entirely, a value of 1 enables larger stream parallelization (unlikely to cause much overhead), and a value of 2 enables all stream parallelization. Level 2 parallelization has the potential to introduce massive overhead to smaller servers, so it should only be enabled with very large servers (very large amounts of force-loaded chunks).

General

I:"# Block threads"

  • Default: 4
  • Range: 1 ~ 16
  • Performance impact: High
  • Compatibility impact: High

This option changes the amount of threads that Spool will allocate to the thread manager responsible for processing blocks and chunks when B:"Enable experimental threading?" is true.

I:"# Chunk loading threads"

  • Default: 1
  • Range: 1 ~ 8
  • Performance impact: High
  • Compatibility impact: High

This option controls the maximum amount of threads that the threaded chunk loading manager may utilize for loading/generating chunks asynchronously. This option only applies when B:"Enable threaded chunk loading?" is true. This option should NOT be changed, as the system is currently heavily work-in-progress.

I:"# Dimension threads"

  • Default: 4
  • Range: 1 ~ 64
  • Performance impact: Moderate
  • Compatibility impact: Low

This option changes the amount of threads that Spool will allocate to the thread manager responsible for updating dimensions when B:"Enable dimension threading?" is true.

I:"# Distance-based threads"

  • Default: 8
  • Range: 1 ~ 64
  • Performance impact: High
  • Compatibility impact: Moderate

This option changes the amount of threads that Spool will allocate to the thread manager responsible for dimension-based processing of blocks, entities, and chunks when B:"Enable distance-based threading?" is true.

I:"# Entity AI threads"

  • Default: 4
  • Range: 1 ~ 16
  • Performance impact: High
  • Compatibility impact: High

This option changes the amount of threads that Spool will allocate to the thread manager responsible for processing entity AI when B:"Enable threaded entity AI?" is true.

I:"# Entity threads"

  • Default: 4
  • Range: 1 ~ 16
  • Performance impact: High
  • Compatibility impact: High

This option changes the amount of threads that Spool will allocate to the thread manager responsible for processing entities when B:"Enable experimental threading?" is true.

B:"Enable dimension-based threading?"

  • Default: true
  • Performance impact: Moderate
  • Compatibility impact: Low

This option enables or disables the threading of different dimensions in parallel. It is compatible with both B:"Enable distance-based threading?" and B:"Enable experimental threading?". The value of this config option should be set to the maximum amount of loaded dimensions or the number of cores on the processor, whichever is lesser. More information can be found on the implementation wiki page.

B:"Enable distance-based threading?"

  • Default: true
  • Performance impact: High
  • Compatibility impact: Moderate

This option enables or disables the threading of entities, blocks, and chunk updates based on their distance from an online player. This option is compatible with B:"Enable distance-based threading?", however it is incompatible with B:"Enable experimental threading?", and will this option will be force disabled when they are both enabled. This option will also be force-disabled if the option is enabled on a single player world. More information can be found on the implementation wiki page.

B:"Enable experimental threading?"

  • Default: false
  • Performance impact: High
  • Compatibility impact: High

This option enables or disables Spool's experimental threading function. This option is incredibly incompatible, and breaks a lot of mods/in-game features. This option is compatible with B:"Enable dimension-based threading?", however it is incompatible with B:"Enable distance-based threading?". Distance threading will be disabled if both options are enabled. More information can be found on the implementation wiki page.

B:"Enable threaded chunk loading?"

  • Default: false
  • Performance impact: High
  • Compatibility impact: High

This option enables or disables Spool's threaded chunk loading system. As of now, this system is extremely unstable, and should generally not be used. More information will come following a commit fixing/finishing this.

B:"Enable threaded entity AI?"

  • Default: true
  • Performance impact: High
  • Compatibility impact: Moderate

This option enables or disables Spool's threaded entity AI system. This includes running path-finding, target-finding, and other AI tasks inside a dedicated thread pool, potentially increasing performance with many entities (especially with squids on servers). This is currently experimental and can potentially cause compatibility issues between mods.

Implementation

B:"Use compact implementations?"

  • Default: false
  • Performance impact: Moderate
  • Compatibility impact: None

This option is used when Spool is deciding what implementations of various structures (bit sets, byte arrays, etc.) to use. Enabling this option makes Spool prioritize memory efficiency over speed, sometimes sacrificing performance for a large reduction in RAM usage by using "compact" implementations.

B:"Use Java 8 Unsafe?"

  • Default: true
  • Performance impact: Moderate
  • Compatibility impact: None

This option allows Spool to use Java 8's Unsafe class for improved performance with atomic classes and operations, especially under thread contention. This class, however, is unsafe and has since been removed in favor of VarHandle in later Java versions, leading to incompatibilities with Spool. This option, when disabled, prevents Unsafe from ever being loaded, allowing for compatibility on later Java versions.

B:"Use Java 9+ features?"

  • Default: false
  • Performance impact: High
  • Compatibility impact: None

This option allows Spool to use Java 9+ features (such as VarHandle) to greatly improve performance with atomic classes/structures, especially under thread contention. This is not present on Java 8, which makes it incompatible with Spool. Using LWJGL3ify, however, allows Minecraft to run on later Java versions, allowing for compatibility with Java 9+ libraries. Currently, this option is unused, however it will be used in the future.

Thread Managers

B:"Allow automatically disabling non-performant managers?"

  • Default: true
  • Performance impact: Moderate
  • Compatibility impact: None

This option determines if Spool is allowed to disable thread managers if they're detected to be negatively impacting performance. This can be seen, for example, on smaller servers using distance threading and entity AI threading at the same time. Disabled thread managers will be re-enabled after 10 seconds via. a timed thread manager. This, due to the fact that the system needs performance statistics, is only partly operational when B:"Enable debug mode (GUI)?" is disabled.

B:"Allow processing during sleep?"

  • Default: false
  • Performance impact: High
  • Compatibility impact: Moderate

This option determines if threads should be allowed to process while the server is sleeping (after the FML Post-Tick event). This is generally a somewhat incompatible option, however it can let some low-load servers run at much lower MSPTs. This also leads to Spool (unintentionally) spoofing the debug time statistics, meaning they are less accurate and may report much higher time savings.

B:"Drop tasks on timeout?"

  • Default: false
  • Performance impact: Low
  • Compatibility impact: Low

This option determines if tasks should be dropped whenever a thread manager "times out". A manager "times out" whenever the tasks inside the pool (entity/block/chunk updates) takes longer than the allowed time (determined by I:"Running single thread timeout (ms)"). This can be enabled to effectively "force" the server's MSPT to be ~50ms, however it can lead to dropping updates (meaning they never get processed). This should only be enabled if absolutely necessary.

B:"Enable Spool Watchdog?"

  • Default: true
  • Performance impact: Moderate
  • Compatibility impact: None

This option enables or disabled Spool's Watchdog systems. The Watchdog is a thread (separated from the main game threads) that watches over the other threads both inside Spool and inside Minecraft. This ensures that, if an incompatible mod is paired with Spool, and if a deadlock occurs (when two or more threads are waiting on the other thread; a circular dependency), the game will be safely terminated instead of hanging indefinitely. The overhead from having a separate thread for this is nearly negligible, and it is highly recommended to leave enabled.

I:"Load balanced pool frequency"

  • Default: 5
  • Range: 1 ~ 2147483647
  • Performance impact: Moderate
  • Compatibility impact: Low

This option controls how often the load-balancing thread manager refreshes the load map and recalculates the thread mappings. Lower values can increase the pool's reaction time (when load changes); however, it increases the overall overhead of the manager. Higher values can reduce the overhead of the manager, though it may be slower to react to load changes, potentially causing lag spikes.

I:"Non-performant manager check frequency"

  • Default: 5
  • Range: 1 ~ 2147483647
  • Performance impact: Moderate
  • Compatibility impact: Low

This option controls how often Spool checks all managers for performance. Lower values can increase Spool's reaction time (when load changes); however, it increases overhead. Higher values can reduce overhead, though it may be slower to react to load changes, potentially causing lag spikes.

I:"Running single thread timeout (ms)"

  • Default: 2000
  • Range: 0 ~ 2147483647
  • Performance impact: Moderate
  • Compatibility impact: Low

This option is used to determine how long the thread managers will wait for tasks to be processed before timing out (while running). If Spool is constantly logging that pools are timing out, then this option may need to be increased. The total time that the manager waits is dependent on this option and the amount of threads in the pool, where the total time can be found by dividing the value of this option by the amount of threads in the pool.

I:"Spool Watchdog frequency (ms)"

  • Default: 1000
  • Range: 0 ~ 2147483647
  • Performance impact: Moderate
  • Compatibility impact: None

This option is used to determine the rate at which the Spool Watchdog will query the system for deadlocks. This number is the number of milliseconds between queries, so to find the frequency (in Hz), you would do 1 / frequency (default leading to 1 Hz, or 1 query per second). The lower this value is (more queries per second), the faster Spool will respond to a deadlock situation, however it also leads to higher overhead. The opposite is true however, where the higher this value is (less queries per second), the slower Spool will react to a deadlock scenario (and the less overhead there will be).

I:"Terminating single thread timeout (ms)"

  • Default: 50000
  • Range: 0 ~ 2147483647
  • Performance impact: Low
  • Compatibility impact: Low

This option is used to determine how long the thread managers will wait for tasks to be processed before timing out (while terminating). If the game crashes due to Spool's managers not finishing in time (while closing the game, shutting down the server, etc.), this value should be increased. The total time that the manager waits is dependent on this option and the amount of threads in the pool, where the total time can be found by dividing the value of this option by the amount of threads in the pool. This option exists to allow the game to crash if a thread locks up or otherwise becomes inoperable and stops executing its task.

B:"Use better task profiling?"

  • Default: false
  • Performance impact: Moderate
  • Compatibility impact: Low

This option enables or disables Spool's task profiling system. This generally lightly impacts performance (negatively), however it can be used during profiling (using the built-in /debug command from Minecraft) to get extra information into the thread task times. More information can be found on the implementation wiki page.

B:"Use lambda optimization?"

  • Default: true
  • Performance impact: Moderate
  • Compatibility impact: Low

This option enables or disables Spool's lambda optimization process. This attempts to remove as many lambda instantiations as possible, potentially increasing performance. This can cause some unforeseen problems with states however, and sometimes leads to additional lambda creations when debug is enabled. This should be kept on unless disabling it is required. More information can be found on the implementation wiki page.

B:"Use load-balancing dimension thread manager?"

  • Default: true
  • Performance impact: Moderate
  • Compatibility impact: Low

This option determines if the load-balancing thread manager implementation should be used for certain pools. Currently, this option affects the dimension threading manager, however it may be expanded in the future. This generally improves performance when enabled, as thread keys with more "relative load" will be prioritized when giving keys threads.

Clone this wiki locally