checks.md

checks.yml is the rule file for all checks of Matrix.

TIP

Before reading this, make sure you have read the Core Concepts of Matrix.

You can:

• Enable/Disable checks / subchecks
• Change the punishment of checks
• Change the threshold of checks
• Change the magic value of checks

Getting started

Open checks.yml, you will see something like this:

# Check A
check-name-a:
  enable: true

  other-settings: ...

  decay:
    interval: 15
    amount: 5

  commands:
    10: '...'
    20: '...'

# Check B
check-name-b:
  enable: true

  other-settings: ...

  decay:
    interval: 15
    amount: 5

  commands:
    10: '...'
    20: '...'

# Check C
check-name-c:
...

Let me explain to you, in checks.yml, the root node is the check type, and after the colon is a series of its settings.

• enable represents whether to enable this type of check
• other-settings represents other settings of this type of check, Usually, you can define some settings of sub-checks (modules) or switch them here
• decay represents the decay settings of the violation level of this type of check
• commands represents the commands to be executed when the violation level of this type of check reaches a certain value

Take the KillAura check as an example

killaura:
  # Enable KillAura check?
  enable: true

  # List of the various KillAura check modules of Matrix
  modules:
    # Check if the player exhibits flaw in the combat
    flaw:
      type_a:
        enable: true
        vl: 3
      type_b:
        enable: true
        vl: 10
      type_c:
        enable: true
        vl: 10
      type_d:
        enable: true
        vl: 10
      type_e:
        enable: true
        vl: 5
    # Check if the player has correct rotation when attacking
    rotation:
      type_a:
        enable: true
        vl: 2
      type_b:
        enable: true
        vl: 2
    # Check if the player shows aiming characteristics similar to aimbot
    aimbot:
      vl_weight: 7
      cancel_hit: true

      check_aimbot_sync: true
      check_aimbot_shake: true
      check_aimbot_snap: true
      check_aimbot_sensitivity: true
      check_aimbot_acceleration: true
      check_aimbot_bad_rotation: true

    # KillAura NPC check, it will generate a fake player behind the player to detect
    # if the player is using KillAura, and don't worry, the player can only see his own NPC
    npc:
      enable: true
      vl_weight: 5

      # Should the position calculation of the NPC run asynchronously, as this may consume some resources
      async: true

      # Should NPCs use real entity IDs instead of randomly generating them?
      # Some cheating clients can bypass random entity ID
      real_entity_id: true

      # Has the NPC been generated by command only? If set to false, the NPC will be automatically
      # generated when the player fights. If set to true, you can only generate an NPC for a player
      # via the "matrix npc" command. (default: true)
      only_command_trigger: true

      # Should the player see this NPC? (true = visible)
      visible: true

      # Force random name (default: false)
      # If this option is turned on, the NPC generated by Matrix will force the use of a random name
      # instead of the random name of the online player, which can solve the problem of some clients
      # bypassing the "duplicate" name NPC. But Matrix will NOT apply teams to the NPC with random name
      # you may need to use the API to apply the NPC team by yourself, Otherwise, some clients will
      # bypass based on whether the NPC name has color
      force_random_name: false

      # NPC existence time setting (ticks)
      check_ticks:
        base: 100
        attack_add: 20
        hit_bot_add: 50

      # NPC motion settings
      movement:
        distance_base: 3.2
        distance_random_size: 0.75
        distance_attack_base: 3.0
        move_up_after_attack: false

    # Critical Hit check, Prevent players from making abnormal crit attacks
    critical:
      # Enable this module?
      enable: true

      # How much VL should the player get after being flagged by this module?
      vl_weight: 5

      # Should Matrix cancel the player's attack after detecting the player's cheating?
      cancel_attack: true

    # Strafe Check
    strafe:
      enable: true
      vl_weight: 3
      cancel_move: true

    # Combine check
    combine:
      aimbot_with_reach:
        time: 5000
        condition:
          - 'ka.abt.magic'
          - 'hb.reach'
          - 'hb.reach'
        action: 5 # +5 VL

  # Custom vl decay interval(seconds) and vl decay step size
  decay:
    interval: 15
    amount: 5

  # Violation Thresholds
  # number_of_violations: '<command>'
  commands:
    10: 'matrix npc %player% 100'
    20: 'matrix notify %player% might be using combat hacks (KillAura)'
    35: 'matrix notify %player% is using combat hacks (KillAura) #2'
    45: 'matrix delay 5 matrix kick %player% KillAura'

The decay section is particularly important as it controls how the violation level (VL) of a player decreases over time. The interval setting determines the time in seconds between each decay operation, and the amount setting determines how much the VL decreases by each time. This allows the VL of a player to gradually decrease if they stop cheating, preventing permanent high VLs for temporary cheating behavior.

The commands section is used to define what actions should be taken when a player's VL reaches certain thresholds. The numbers on the left represent the VL thresholds, and the strings on the right are the commands to be executed when these thresholds are reached.

For example, when a player's VL reaches 10, the command matrix npc %player% 100 is executed. This command generates a non-player character (NPC) for 100 ticks to further check if the player is using KillAura.

When the VL reaches 20 and 35, notifications are sent to the server administrators, alerting them that the player might be using combat hacks.

Finally, when the VL reaches 45, the player is kicked from the server after a delay of 5 seconds with the reason being " KillAura".

This configuration file allows server administrators to customize the KillAura check to suit their needs, adjusting the sensitivity of the check and the severity of the punishments.

Placeholders

• %player%: The name of the player who triggered the check.
• %message%: The message of the detection detail.
• %tooltips%: The tooltip message of the detection detail.
• %add_vl%: The number of VL points to be added to the player's total VL.
• %vl%: The total VL points of the player.
• %ping%: The ping of the player.
• %tps%: The TPS of the server.
• %component%: The component of the check.
• %version%: The version of the the player.
• %world: The world of the player.

You also can install PlaceholderAPI to get more placeholders.