==========
Properties
==========

Sponge has some properties you can set on the command-line that can assist with debugging and other tasks. These 
properties provide useful information in the logs when submitting issues.

Usage
=====

The properties are set on the command line in the server launch command using the ``-Dkey=value`` syntax. For example, 
the launch command may look like this: ``java -Dsponge.shouldFireAll=true -Dsponge.filter.debug=true -jar forge.jar`` .

.. note::
   The example above is a simple launch command. Your launch command can, and probably will, have other options.

Properties Available
====================

+------------------------------------+---------------------------------------------------------------------------------+
| Property                           | Description                                                                     |
+====================================+=================================================================================+
|                                    | Prints out a very verbose log entry for every block captured that is processed, |
|                                    | information about what ``BlockStates`` are proxied, what ``BlockStates`` exist  |
| **sponge.debugBlockTransactions**  | on the ``Chunk`` during processing, and potentially what ``BlockStates``        |
|                                    | existed prior to a future transaction changing positions. Likewise applies to   |
| (boolean, default: false)          | tracking ``TileEntity`` instances. Useful for debugging purposes for the        |
|                                    | implementation, and potentially plugins, when dealing with                      |
|                                    | ``ChangeBlockEvents`` and their processing.                                     |
+------------------------------------+---------------------------------------------------------------------------------+
|                                    | Adds a StackTrace to each ``StackFrame`` for when either the Sponge             |
| **sponge.debugcauseframes**        | implementation or a plugin potentially corrupts the ``CauseStackManager`` 's    |
|                                    | ``StackFrame`` s, whether it's a frame being popped out of order, or popping    |
| (boolean, default: false)          | an already popped frame. This is useful to find out where the frame was         | 
|                                    | created.                                                                        |
+------------------------------------+---------------------------------------------------------------------------------+
|                                    | Similar to the ``StackFrame`` exception creation, this tracks the stack trace   |
|                                    | for each ``BlockTransaction`` that is captured for a block being changed, a     | 
| **sponge.debugProxyChanges**       | neighbor notification request, or a ``TileEntity`` change. Useful to find out   |
|                                    | where each transaction is created, potentially adding more information if there |
| (boolean, default: false)          | is an exception thrown during the processing of said transactions. Should       |
|                                    | always be included for logs when reporting issues involving these sort of       |
|                                    | transactions.                                                                   |
+------------------------------------+---------------------------------------------------------------------------------+
| **sponge.debugShouldFire**         | Logs changes to the ``ShouldFire`` flags when event listeners are               |  
|                                    | registered/unregistered causing one of the boolean flags to be flipped (whether |
| (boolean, default: false)          | it's going from ``true`` to ``false`` or ``false`` to ``true``).                |
+------------------------------------+---------------------------------------------------------------------------------+
| **sponge.filter.debug**            | Writes out classes that are generated by the filter generator to the            |
|                                    | ``.sponge.debug.out`` folder, named after the class they are altering.          |
| (boolean, default: false)          |                                                                                 |
+------------------------------------+---------------------------------------------------------------------------------+
| **sponge.print_all_catalog_types** | Prints out all Sponge provided ``CatalogType`` s and their ``String`` id's      |
|                                    | before preInit, which is useful for finding out what id's are registered from   |
| (boolean, default: false)          | vanilla, mods, and plugins for all created ``CatalogType`` s.                   |
+------------------------------------+---------------------------------------------------------------------------------+
|                                    | Forces all boolean "performance" checks for common SpongeAPI events to be       |  
| **sponge.shouldFireAll**           | forcibly created and fired, regardless whether there is a registered event      |
|                                    | listener for the desired event (Sponge will normally not construct and throw a  |
| (boolean, default:false)           | ``ChangeBlockEvent`` if there are no listeners for that event or its sub        |
|                                    | events).                                                                        |
+------------------------------------+---------------------------------------------------------------------------------+
| **sponge.world.migrate_old**       | World migration is disabled when this is set to false.                          |
|                                    | The migration process is described in :doc:`/server/getting-started/migrating`. |
| (boolean, default: true)           |                                                                                 |
+------------------------------------+---------------------------------------------------------------------------------+
| **timings.bypassMax**              | Allows for bypassing the max number of frames to send to the Aikar's timing     |
|                                    | API. Setting this will not permit bypassing the limit unless the API is         |
| (any value that exists)            | configured to permit it.                                                        |
+------------------------------------+---------------------------------------------------------------------------------+

.. warning::
   **sponge.debugcauseframes** has the potential to increase performance costs due to the stack trace creation for
   every frame in the duration of the game's lifecycle.

   **sponge.debugProxyChanges** has the same potential to increase performance costs in potentially intensive 
   environments due to exception creation for every potential ``Entity`` / ``TileEntity`` / ``Block`` being ticked in 
   the game.