Documentation for SimpleCalculator
This documentation provides detailed guidance on using the SimpleCalculator, a high-performance calculator plugin for Minecraft Spigot servers (versions 1.21, 1.21.1, 1.21.3, and 1.21.5). It covers command usage, configuration options, permissions, and troubleshooting tips to help players and server administrators make the most of the plugin.

Using the SimpleCalculator
The SimpleCalculator allows players to perform mathematical calculations directly in-game using commands. It supports basic arithmetic operations and provides a user-friendly interface with tab completion.

Commands
The plugin offers three commands, each with the same functionality but different names for convenience:

• /calculate <expression>
• /calc <expression>
• /c <expression>

Command Format:
The expected format for the expression is <number> <operator> <number>. For example:

• /c 5 + 3 → Calculates 5 + 3 and returns the result.
• /calc 10 * 2 → Calculates 10 * 2.
• /calculate 7 - 4 → Calculates 7 - 4.

Supported Operators

• + (Addition)
• - (Subtraction)
• * (Multiplication)
• / (Division)
• ^ (Exponentiation, e.g., 2 ^ 3 calculates 2 raised to the power of 3)
• Advanced functions (via JavaScript engine): sin, cos, tan, pow (e.g., pow(2, 3) for 2^3).

Note: sqrt and cbrt are not supported in this version of the plugin.

Tab Completion
The plugin provides structured tab completion to guide users through the input process:

1. First Argument: Suggests a number (e.g., "1", "2", "3").
   Example: Type /c and press Tab → Suggests "1", "2", "3".
2. Second Argument: Suggests an operator (+, -, *, /, ^).
   Example: Type /c 5 and press Tab → Suggests "+", "-", "*", "/", "^".
3. Third Argument: Suggests another number (e.g., "1", "2", "3").
   Example: Type /c 5 + and press Tab → Suggests "1", "2", "3".

Example Usage

• Command: /c 4 + 6
  Output: [Calculator] 4 + 6 = 10.00
• Command: /calc 8 * 3
  Output: [Calculator] 8 * 3 = 24.00
• Command: /calculate 5 ^ 2
  Output: [Calculator] 5 ^ 2 = 25.00

If an invalid expression is entered, an error message is displayed:

• Command: /c 5 / 0
  Output: [Calculator] Invalid expression: Division by zero

When using /c with no arguments, a specific usage message is shown:

• Command: /c
  Output: [Calculator] usage: /c <number> <operator> <number>

For /calc or /calculate, the usage message is configurable in the config.yml.

Configuration Options
The plugin generates a config.yml file in the plugins/CalculatorPlugin directory upon first load. Below are the configurable options:

• use-script-engine:
  • Default: true
  • Description: Enables the JavaScript engine for complex calculations. Set to false to use basic parsing (only supports +, -, *, /, ^).
• calculation-timeout:
  • Default: 1000 (milliseconds)
  • Description: Maximum time allowed for a calculation to prevent server lag.
• messages:
  • prefix: Default: &6[Calculator]
    The prefix for all plugin messages (supports color codes with &).
  • error-color: Default: &c
    Color for error messages.
  • result-color: Default: &a
    Color for result messages.
  • operation-color: Default: &e
    Color for the operation display in the result.
  • no-permission: Default: You don't have permission to use this command!
    Message shown when a player lacks the calculator.use permission.
  • usage: Default: Usage: /%command% <expression>
    Usage message for /calc and /calculate (not /c).
  • error: Default: Invalid expression:
    Prefix for error messages.
• format.decimal-places:
  • enabled: Default: true
    Whether to format results to a specific number of decimal places.
  • count: Default: 2
    Number of decimal places to display (e.g., 2 formats 5 as 5.00).

Example Configuration Change:
To change the prefix to a blue color and limit decimal places to 1:

yaml
messages: prefix: "&9[Calc] " format: decimal-places: count: 1


After editing, reload the plugin with /reload or restart the server.

Permissions

• calculator.use
  • Default: true
  • Description: Allows players to use the calculator commands.
  • Usage: Deny this permission in a permissions plugin (e.g., LuckPerms) to restrict access:
    /lp user <player> permission set calculator.use false

Troubleshooting

• Command Not Working:
  • Ensure the plugin loaded correctly by checking the server console for errors.
  • Verify the player has the calculator.use permission.
  • Check if the command is registered in plugin.yml and matches the command you're typing.
• Invalid Expression Errors:
  • Ensure the expression follows the <number> <operator> <number> format (e.g., 5 + 3).
  • Avoid using unsupported operators or functions (e.g., sqrt is not supported).
  • If using the JavaScript engine, ensure use-script-engine is set to true in config.yml.
• No Output or Server Lag:
  • If a calculation takes too long, it may hit the calculation-timeout limit. Adjust this value in config.yml or simplify the expression.
  • Check the server console for logged errors (e.g., JavaScript engine issues).
• Tab Completion Not Working:
  • Ensure you’re following the correct format. Tab completion only suggests numbers and operators in the correct order.
  • Verify the CalculatorTabCompleter is registered in the plugin code.

Advanced Usage (JavaScript Engine)
If use-script-engine is enabled, you can use advanced mathematical functions:

• sin, cos, tan: Trigonometric functions (e.g., /c sin(0) returns 0.00).
• pow: Power function (e.g., /c pow(2, 3) calculates 2^3, same as 2 ^ 3).

Note: These functions require the JavaScript engine to be available on your server’s Java runtime. If unavailable, set use-script-engine to false to fall back to basic operations.

Support and Feedback
For issues or feature requests, check the server console logs for detailed error messages. As of June 11, 2025, this plugin is designed to be lightweight and efficient, but future updates may add more features based on user feedback. Ensure your server is running a compatible Minecraft version (1.21 to 1.21.5) to avoid compatibility issues.

This plugin is a practical tool for players and educators on Minecraft servers, blending utility with ease of use.