Weight system

Introduction

The probability system of the entire plugin is controlled by weights. What are weights? A weight represents the relative chance of obtaining a particular item. For instance, if item A has a weight of 10 and item B has a weight of 30, the probability of getting A is 25%, while the chance of getting B is 75%. This is the most scientific method for calculating probabilities.

Where can weights be used?

Where can weights be used? In fact, weights are applied in many parts of the plugin. For instance, adjusting weights based on conditions for loot, weights in mini-games, and item effects (like fishing rods) that offer weight modification features. They are typically configured in a list format and adhere to this specific configuration format.

With weight modifications, we can achieve features that many other fishing plugins can't. For example, there's less trash in the ocean but it frequently appears in rivers. Players using a golden fishing rod have a higher chance to catch gold-quality loot. Or perhaps, to catch a ferocious shark, players must use shark bait. All these features can be realized through the weight system.

Weight Operations

Weight operations include + (addition), - (subtraction), * (multiplication), / (division), % (modulus), and = (custom expression).

Basic Operations

Let's first take a look at some basic weight operation expressions. For the operators +, -, *, /, and %, simply write the corresponding operator after the colon and then specify the corresponding value after it. This value can either be a registered placeholder or a fixed number.

rubbish:+10
rubbish:-5.5
rubbish:/2
rubbish:%6
rubbish:*{placeholder}

Custom Operations

For the = operator, the plugin provides a more advanced expression system.

You can freely use the expressions provided by the plugin. For example, this simple mathematical formula:

rubbish:=100+sin(pi)

Built-in functions:
    abs: absolute value
    acos: arc cosine
    asin: arc sine
    atan: arc tangent
    cbrt: cubic root
    ceil: nearest upper integer
    cos: cosine
    cosh: hyperbolic cosine
    exp: euler's number raised to the power (e^x)
    floor: nearest lower integer
    log: logarithmus naturalis (base e)
    log10: logarithm (base 10)
    log2: logarithm (base 2)
    sin: sine
    sinh: hyperbolic sine
    sqrt: square root
    tan: tangent
    tanh: hyperbolic tangent
    signum: signum function

You can also use {0} to represent the weight of the current entry at the time this expression is evaluated, or {1} to represent the sum of the weights of all entries (excluding those with weights less than or equal to 0) when this expression is evaluated.

In this example, the weight of "rubbish" will be doubled compared to its previous value.

rubbish:={0}*2

In this example, the weight of "rubbish" will become 1% of the total weight of all loot.

rubbish:={1}*0.01

Configure loot-conditions.yml & game-conditions.yml

Some users may feel very confused after coming into this file. Custom Fishing is using a configuration file format that other plugins have never attempted before. Unlike other fishing plugins, Custom Fishing provides a tree like probability pool that can be freely modified in weight based on conditions. Now we will take you through the default configuration file to understand how this system works.

Groups

Please note: The "group" here has no relation to the group in the items. This "group" is simply a random name used to help users organize the file structure.

Firstly, we saw a section name called 'global group'

global-group:
  list: []
  conditions: {}
  sub-groups: {}

global-group is just a random name that you can freely modify and add any group you want for instance:

river-group:
  list: []
  conditions: {}
  sub-groups: {}
ocean-group:
  list: []
  conditions: {}
  sub-groups: {}
nether-group:
  list: []
  conditions: {}
  sub-groups: {}
the-end-group:
  list: []
  conditions: {}
  sub-groups: {}

Upon careful observation, you will find that a group consists of three parts: list, conditions, and sub-groups.

Add Entry to List

If you want a certain loot to appear, you just need to add it to the list with =or + If the file is loot-conditions.yml, you can put any id of the loots from item/entity/block folder If the file is game-conditions.yml, you can only put the id of the games from minigame folder

global-group:
  list:
    - my_fish:+1 # Add my_fish to the loot table
  conditions: {}
  sub-groups: {}

In this strange configuration, the final weight of my_fish is ((0+6-4)*10/5)%3=1. Okay, it's funny that its weight has returned to 1 after circling around for a long time.

global-group:
  list:
    - my_fish:=0   # set the weight 
    - my_fish:+6   # plus
    - my_fish:-4   # minus
    - my_fish:*10  # multiply
    - my_fish:/5   # divide
    - my_fish:%3   # modular
  conditions: {}
  sub-groups: {}

Conditions

Now let's continue to look at the conditions section. This section affects whether the weight operator of the list is executed. You can use most of the conditions provided by the conditional system. If you still don't know what the conditional system is, please read

Condition

For example, if I want this fish to appear in my custom biome now, I can configure it like this

global-group:
  list:
    - my_fish:+1
  conditions: 
    in-water: true
    biome:
      - my_namespace:my_custom_biome
  sub-groups: {}

Very good! You now know how the conditional system works, let's continue to look at how sub groups work.

In this example, I created two subgroups, one of which cannot be executed because it violates an important principle: The conditions of the subgroup cannot conflict with the conditions of the parent group If a player is cute, then at last he can only get cute_fish because I set the weight of my_fish to 0

global-group:
  list:
    - my_fish:+1
  conditions: 
    in-water: true
    biome:
      - my_namespace:my_custom_biome
  sub-groups:
    impossible_group:  # This group would not work because the biome has to be 
      list:            # my_namespace:my_custom_biome before going into the inner
        - my_fish:+1   # sub-groups section
      conditions:
        biome:
          - minecraft:plains 
    possible_group:
      list:
        - cute_fish:+1
        - my_fish:=0   
      conditions:
        equals:
          value1: '%cute_player%'  # This is just a fabricated placeholder
          value2: 'true'

Suppose you have a requirement where the probability of obtaining a chest should always be around 2%, regardless of how the loot list changes. In that case, you can configure it as follows:

global-group:
  list: []
  conditions:  {}
  sub-groups: 
    fishs:
      list: 
       - a:+5
       - b:+7
       - c:+19
      conditions:  {}
      sub-groups: {}
    chest:
      list: 
       - chest:={1}*0.02
      conditions:  {}
      sub-groups: {}

Remember, the loot-conditions.yml is parsed from top to bottom, and from outside to inside. Therefore, you need to place the chest condition at the end.

The example here is unrealistic because the fishing gear a player holds will often influence the weight of other items afterward, which could cause the 2% probability to become ineffective. Therefore, you can use global-effects and apply weight adjustments to individual loot items, as global-effects are always processed last.

However, it provides enough insight and can be useful in certain scenarios.

Debug the Loot Table

Weights aren't very intuitive to me. How can I convert the weights into a percentage form? The plugin has already thought of this. You simply need to use the command /customfishing debug loot <surroundings>. It will calculate the probabilities of all potential loots based on the fishing rod, bait, and other factors you currently hold that can affect the fishing results.

Advanced Tutorial

Additional Weight Functions

In addition to the basic id:operation format, the plugin also provides many other operation qualifiers. Next, I will explain each function one by one according to the examples.

group_for_each

The group_for_each operation will apply a weight operation to each member within the group.

global-group:
  list:
    - group_for_each:river:+10
  conditions:  {}
  sub-groups: {}

In addition to using a single group like river, you can also combine groups. For example, river&silver_star represents loot that is in both the river and silver_star groups. Similarly, river|ocean represents loot that is in either the river or ocean group.

global-group:
  list:
    - 'group_for_each:river&silver_star:+10'
  conditions:  {}
  sub-groups: {}

group_available_for_each

Unlike group_for_each, the objects affected by group_available_for_each must have already appeared earlier.

global-group:
  list:
    - gold_fish:=10
    - group_available_for_each:river:+10
  conditions:  {}
  sub-groups: {}

group_total

The group_total operation will evenly distribute the weight among each member within the group to ensure that the total weight of the group remains consistent.

global-group:
  list:
    - group_total:ocean:+10
  conditions:  {}
  sub-groups: {}

global-group:
  list:
    - 'group_total:ocean&golden_star:+10'
  conditions:  {}
  sub-groups: {}

group_available_total

The difference between group_available_total and group_total is that group_available_total only affects entries that have already appeared earlier.

Due to the limitations of the 2.x architecture and performance considerations, the plugin does not dynamically track or calculate entries that have already appeared. This can lead to discrepancies in the total weight when using group_available_total. This issue will be resolved in the 3.0 refactor.

global-group:
  list:
    - tuna_fish:+10
    - group_available_total:ocean:+10
  conditions:  {}
  sub-groups: {}

loot_available

Unlike regular weight operations, this one only targets entries that have already appeared earlier.

global-group:
  list:
    - tuna_fish:+10
    - loot_available:tuna_fish:+10
  conditions:  {}
  sub-groups: {}

global-group:
  list:
    - gold_fish:+10
    - loot_available:tuna_fish:+10
  conditions:  {}
  sub-groups: {}

Additional Placeholders

In the = expression, you can use {entry_xxx} to retrieve the weight of a specific entry that has appeared earlier, and use {group_xxx} to get the sum of the weights of all entries that meet the group conditions.

In this example, I first added a +10 weight to all river fish, and then evenly distributed the total weight of the river fish across all ocean fish.

global-group:
  list:
    - group_for_each:ocean:+10
    - group_total:river:={group_ocean}
  conditions:  {}
  sub-groups: {}

In this example, I set the weight of the golden_star and silver_star to 10% and 30% of their weight without a star status.

global-group:
  list:
    - tuna_fish:+10
    - 'tuna_fish_silver_star:={entry_tuna_fish}*0.3'
    - 'tuna_fish_golden_star:={entry_tuna_fish}*0.1'
  conditions:  {}
  sub-groups: {}

For groups, you can also use the previously mentioned & and | operators. The & operator represents the intersection of groups (items that belong to both groups), while the | operator represents the union of groups (items that belong to either group).

global-group:
  list:
    - group_for_each:ocean:+10
    - 'rainbow_fish:={group_ocean&silver_star}*0.3'
  conditions:  {}
  sub-groups: {}