Conditions - BetterHud

Conditions allow you to show or hide HUD elements based on dynamic criteria using placeholder values.

Basic Conditions

Conditions use boolean placeholders to determine visibility:

my_popup:
  condition: "<boolean:is_sneaking>" # Only show when sneaking
  triggers:
    1:
      class: player_join
  layouts:
    # ... layout configuration

Condition Syntax

Boolean Placeholders

Use boolean placeholders directly:

condition: "<boolean:is_sneaking>"
condition: "<boolean:is_flying>"
condition: "<boolean:is_in_combat>"

Negation

Invert conditions with !:

condition: "!<boolean:is_sneaking>" # Show when NOT sneaking
condition: "!<boolean:is_flying>" # Show when NOT flying

Comparison Operators

Compare numeric placeholders:

# Greater than
condition: "<number:player_health> > 10"

# Less than
condition: "<number:player_health> < 5"

# Greater than or equal
condition: "<number:player_level> >= 20"

# Less than or equal
condition: "<number:food_level> <= 6"

# Equal
condition: "<number:player_level> == 50"

# Not equal
condition: "<number:armor_value> != 0"

String Comparisons

Compare string placeholders:

# Equality
condition: "<string:world_name> == 'world_nether'"

# Inequality
condition: "<string:biome> != 'plains'"

Logical Operators

AND

Multiple conditions must all be true:

condition: "<boolean:is_sneaking> && <number:player_health> < 5"

OR

At least one condition must be true:

condition: "<boolean:is_flying> || <boolean:is_in_water>"

Complex Logic

Combine operators with parentheses:

condition: "(<boolean:is_sneaking> && <number:health> < 10) || <boolean:in_combat>"

Always Check Condition

By default, conditions are only checked when a popup is triggered. Enable continuous checking:

my_popup:
  always-check-condition: true
  condition: "<boolean:is_in_combat>"
  triggers:
    1:
      class: entity_attack

With always-check-condition: true:

The popup will hide automatically when the condition becomes false
Useful for status indicators that should disappear when conditions change

Conditional Layouts

Show different layouts based on conditions:

my_hud:
  layouts:
    1:
      name: full_health_bar
      condition: "<number:player_health> >= 15"
    2:
      name: low_health_bar
      condition: "<number:player_health> < 15"

Conditional Text

Display different text based on conditions:

my_text:
  text:
    - condition: "<number:player_health> > 15"
      value: "Health: <number:player_health> (Healthy)"
    - condition: "<number:player_health> <= 15"
      value: "Health: <number:player_health> (Low!)"

Creating Conditional Placeholders

Create boolean placeholders for use in conditions:

import kr.toxicity.hud.api.BetterHudAPI;
import kr.toxicity.hud.api.placeholder.HudPlaceholder;
import kr.toxicity.hud.api.placeholder.PlaceholderContainer;

public class CustomConditions {
    public void registerConditions() {
        PlaceholderContainer<Boolean> booleanContainer = BetterHudAPI.inst()
            .getPlaceholderManager()
            .getBooleanContainer();
        
        // Low health check
        HudPlaceholder.<Boolean>builder()
            .function((args, event) -> player -> {
                return player.getHealth() < 5.0;
            })
            .build()
            .add("is_low_health", booleanContainer);
        
        // High level check
        HudPlaceholder.<Boolean>builder()
            .function((args, event) -> player -> {
                return player.getLevel() >= 30;
            })
            .build()
            .add("is_high_level", booleanContainer);
        
        // In combat check (requires custom tracking)
        HudPlaceholder.<Boolean>builder()
            .function((args, event) -> player -> {
                return CombatTracker.isInCombat(player.getUUID());
            })
            .build()
            .add("is_in_combat", booleanContainer);
    }
}

Common Condition Patterns

Health Warnings

low_health_warning:
  condition: "<number:player_health> < 6"
  always-check-condition: true
  triggers:
    1:
      class: health

Status Effects

poison_indicator:
  condition: "<boolean:has_poison>"
  always-check-condition: true

Environment-Based

nether_hud:
  condition: "<string:world_name> == 'world_nether'"
  triggers:
    1:
      class: player_join

Permission-Based

admin_hud:
  condition: "<boolean:has_permission:admin>"
  triggers:
    1:
      class: player_join

Time-Based

night_indicator:
  condition: "<number:world_time> > 13000 && <number:world_time> < 23000"
  always-check-condition: true

Advanced Conditional Logic

Range Checks

# Health in specific range
condition: "<number:player_health> > 5 && <number:player_health> <= 15"

# Level tiers
condition: "<number:player_level> >= 20 && <number:player_level> < 40"

Multi-State Conditions

health_display:
  layouts:
    1:
      name: critical_health # Red
      condition: "<number:player_health> < 4"
    2:
      name: low_health # Yellow  
      condition: "<number:player_health> >= 4 && <number:player_health> < 10"
    3:
      name: normal_health # Green
      condition: "<number:player_health> >= 10"

Combination States

stealth_mode:
  condition: "<boolean:is_sneaking> && !<boolean:is_in_combat> && <number:light_level> < 5"
  always-check-condition: true

Performance Considerations

Expensive Conditions

Avoid complex calculations in frequently-checked conditions:

# Good - Simple check
condition: "<boolean:is_sneaking>"

# Avoid - Complex calculation every frame
condition: "<number:distance_to_spawn> > 1000 && <number:nearby_players> > 3"

Always Check Condition

Use always-check-condition sparingly:

# Good - Only check on trigger
my_popup:
  condition: "<number:player_level> > 10"
  triggers:
    1:
      class: player_join

# Use carefully - Checks every tick
my_status:
  always-check-condition: true
  condition: "<boolean:is_in_combat>"

Condition Caching

Placeholder values are cached per update cycle, so multiple conditions using the same placeholder are efficient:

# Both conditions use cached health value
layout_1:
  condition: "<number:player_health> < 10"
layout_2:
  condition: "<number:player_health> >= 10"

Debugging Conditions

Enable Debug Mode

# config.yml
debug: true
debug-level: all

Test Placeholders

Verify placeholder values:

test_text:
  text:
    - "Health: <number:player_health>"
    - "Sneaking: <boolean:is_sneaking>"
    - "World: <string:world_name>"

Common Issues

Condition always true/false
- Check placeholder registration
- Verify placeholder type matches usage
- Test placeholder values independently
Condition not updating
- Enable always-check-condition: true
- Verify trigger is firing
- Check placeholder updates on the right events
Syntax errors
- Verify operator syntax (&&, ||, !)
- Check parentheses are balanced
- Ensure string comparisons use quotes

Examples

Combat HUD

combat_hud:
  condition: "<boolean:is_in_combat>"
  always-check-condition: true
  triggers:
    1:
      class: entity_attack
    2:
      class: entity_damage
  layouts:
    1:
      name: combat_indicators

Low Resource Warning

resource_warning:
  condition: "<number:player_health> < 6 || <number:food_level> < 4"
  always-check-condition: true
  layouts:
    1:
      name: warning_icon

Achievement Unlock

achievement_popup:
  condition: "<number:player_level> >= 30 && !<boolean:has_seen_achievement>"
  triggers:
    1:
      class: level_up
  duration: 100
  layouts:
    1:
      name: achievement_display

Dimension-Specific HUD

nether_hud:
  condition: "<string:world_type> == 'nether'"
  triggers:
    1:
      class: player_join
  layouts:
    1:
      name: nether_compass
    2:
      name: nether_temperature

end_hud:
  condition: "<string:world_type> == 'the_end'"
  triggers:
    1:
      class: player_join
  layouts:
    1:
      name: end_indicators

Next Steps

Placeholders

Create custom placeholders

Triggers

Control when conditions are checked

Popups

Use conditions in popups

Layouts

Conditional layout display

Get Started

Core Concepts

Configuration

Platform Guides

Advanced

Documentation Index

​Basic Conditions

​Condition Syntax

​Boolean Placeholders

​Negation

​Comparison Operators

​String Comparisons

​Logical Operators

​AND

​OR

​Complex Logic

​Always Check Condition

​Conditional Layouts

​Conditional Text

​Creating Conditional Placeholders

​Common Condition Patterns

​Health Warnings

​Status Effects

​Environment-Based

​Permission-Based

​Time-Based

​Advanced Conditional Logic

​Range Checks

​Multi-State Conditions

​Combination States

​Performance Considerations

​Expensive Conditions

​Always Check Condition

​Condition Caching

​Debugging Conditions

​Enable Debug Mode

​Test Placeholders

​Common Issues

​Examples

​Combat HUD

​Low Resource Warning

​Achievement Unlock

​Dimension-Specific HUD

​Next Steps

Placeholders

Triggers

Popups

Layouts

Build docs developers (and LLMs) love

Basic Conditions

Condition Syntax

Boolean Placeholders

Negation

Comparison Operators

String Comparisons

Logical Operators

AND

OR

Complex Logic

Always Check Condition

Conditional Layouts

Conditional Text

Creating Conditional Placeholders

Common Condition Patterns

Health Warnings

Status Effects

Environment-Based

Permission-Based

Time-Based

Advanced Conditional Logic

Range Checks

Multi-State Conditions

Combination States

Performance Considerations

Expensive Conditions

Always Check Condition

Condition Caching

Debugging Conditions

Enable Debug Mode

Test Placeholders

Common Issues

Examples

Combat HUD

Low Resource Warning

Achievement Unlock

Dimension-Specific HUD

Next Steps