PLUGIN Expression Parser

Expression Parser

Create dynamic NPC behavior using mathematical expressions with variables, functions, and boolean logic. Use expressions in click actions, goal conditions, and variable calculations.

Operator Precedence

Expressions are evaluated in this order (highest to lowest):

1. Parentheses: () - Grouping and function calls
2. Functions: sin(), cos(), sqrt(), etc.
3. Power: ^ - Exponentiation
4. Unary Operators: +, - (prefix), ! (NOT)
5. Multiplication/Division: *, /
6. Addition/Subtraction: +, -
7. Comparisons: ==, !=, <, >, <=, >=
8. Boolean AND: &&
9. Boolean OR: ||

Supported Elements

Numeric Literals

123          // Integer
45.67        // Decimal
1.23e-4      // Scientific notation
-5.5         // Negative number

Mathematical Constants

PI           // 3.141592653589793...
E            // 2.718281828459045...

Mathematical Functions

Trigonometric

• sin(x) - Sine
• cos(x) - Cosine
• tan(x) - Tangent

Algebraic

• sqrt(x) - Square root
• log(x) - Natural logarithm
• exp(x) - Exponential function

Rounding

• ceil(x) - Round up to nearest integer
• floor(x) - Round down to nearest integer
• round(x) - Round to nearest integer
• trunc(x) - Truncate decimal part
• abs(x) - Absolute value

Boolean Operations

Logical Operators

• && - Logical AND
• || - Logical OR
• ! - Logical NOT

Comparison Operators

• == - Equal to
• != - Not equal to
• < - Less than
• > - Greater than
• <= - Less than or equal to
• >= - Greater than or equal to

Variable References

Syntax Patterns

$varName                    // Auto-resolve scope (local → instance → global)
$global.varName             // Explicit global variable
$instance.varName           // Explicit instance variable
$local.varName              // Explicit local variable
$self.varName               // Self/player scoped variable
$loop.index                 // Loop-specific variable (only 'index' supported)

Special Variables (Player Context)

$self.rightClick            // 1 if right-click, 0 otherwise
$self.right_click          // Alternative syntax (snake_case)
$self.leftClick             // 1 if left-click, 0 otherwise
$self.left_click            // Alternative syntax (snake_case)
$self.sneaking              // 1 if player is sneaking, 0 otherwise
$self.flying                // 1 if player is flying, 0 otherwise
$self.op                    // 1 if player is operator, 0 otherwise
$loop.index                 // Current loop iteration index

Command Execution

Commands can be executed in two ways:

Parenthesized Commands (inside expressions)

2 + (/count players)         // Execute command, use result in calculation
sin(PI) + (/scoreboard players get @p score)

Standalone Commands (full expression)

/count players               // Returns command success count
/scoreboard players get @p score

Commands execute with maximum permissions (admin level). Failed commands return 0.

Expression Examples

Basic Arithmetic

2 + 3 * 4                   // 14
(10 - 5) * 2               // 10
15 / 3                     // 5
2 ^ 8                      // 256

Mathematical Functions

sin(PI / 2)                // 1.0
sqrt(16) + 4               // 8.0
log(E)                     // 1.0
ceil(3.7)                  // 4
floor(3.7)                 // 3
round(3.5)                 // 4
abs(-5)                    // 5

Boolean Logic

1 && 1                     // 1 (true - both non-zero)
1 || 0                     // 1 (true - first is non-zero)
!0                         // 1 (true - negation of zero)
5 > 3 && 2 < 4             // 1 (true)

Boolean Values:

• True: Any non-zero value (typically 1)
• False: Zero (0)
• Comparison operators return 1.0 for true, 0.0 for false
• Logical operators treat non-zero as true, zero as false

Comparisons

5 == 5                     // 1 (true)
5 != 3                     // 1 (true)
10 > 5                     // 1 (true)
3 <= 3                     // 1 (true)
7 >= 8                     // 0 (false)

Variable Operations

$global.score + 1         // Global score + 1
$local.health * 0.5       // Half local health
$instance.cooldown - 1     // Decrease cooldown

Validation Examples

Valid Expressions

2 + 3 * 4
$global.score + 1
sin(PI / 2) + cos(0)

Invalid Expressions

2 + * 3                    // Invalid operator sequence
$global.123var             // Invalid variable name
sin(                       // Missing closing parenthesis
unknown_function(5)       // Unknown function

Error Handling

Common Errors

Error	Cause	Solution
Unexpected character	Invalid symbol in expression	Check for typos
Missing ')'	Unclosed parenthesis	Add closing parenthesis
Unknown function	Function not recognized	Use supported functions only
Invalid variable name	Name starts with number	Start with letter or _
Division by zero	Dividing by 0	Check values before division

Error messages show the exact position with a visual pointer:

2 + * 3
    ^
Unexpected character at position 4

Advanced Usage

Complex Expressions

Combine multiple features for sophisticated logic:

// Health-based conditional damage
($entity.health < 10) * 5 + ($entity.health >= 10) * 2

// Distance-weighted scoring
(10 - $distance) * $self.rightClick

// Command-integrated calculations
(/scoreboard players get @p kills) * 100 + $global.bonus

// Boolean logic with variables
$self.op || ($global.level > 50 && $self.sneaking)

// Nested function calls
round(sqrt($distance) * 10) + abs($entity.health - 20)

Command Integration Patterns

Using Command Results:

// Check if players are online
(/execute if entity @p) * 1

// Get scoreboard values
(/scoreboard players get @p myScore)

// Conditional execution
(/execute if score @p myScore matches 10.. run say HighScore) * 1

Variable Scope Resolution

When using $varName without a scope prefix, the parser searches:

1. Local (player-specific) variables first
2. Instance (NPC-specific) variables second
3. Global (server-wide) variables last

Returns 0 if variable is not found in any scope.