Module: Distributor

The distributor module allows you to distribute credits to all of the online players in your server every X seconds. The distributor is highly configurable, and we'll overview that in this documentation.

Overview

The amount of credits distributed between players is affected by a few factors. The distributor allows you to configure a base amount of credits, and then allows your to alter that per player, based on the current map, player count or player flags using Filters. Filters can do that by adding to or multiplying the base amount of credits.

The base amount of credits isn't a scalar value, it's a range. You configure that by setting a minimum and a maximum value. Distributor chooses a random value between this range. Filters can add to and/or multiply the minimum value, the maximum value, or both.

Configuration

The config file for distributor is available at configs/store/distributor.cfg. It is based on the standard KeyValues format.

Let's take a look on the default distributor.cfg that comes with the store package:

"Distributor"
{
	"time_per_distribute"				"180"
	"enable_message_per_distribute"		"1"

	"distribution"
	{
		"base_minimum"			"1"
		"base_maximum"			"3"
	}
}

The time_per_distribute property allows you to define the time between each credits distribute, in seconds.

The enable_message_per_distribute property allows you to define whether or not the store should print a message such as:

[Store] You have just received 13 credits.

Then we have the distribution section. There are two properties in there right now: base_minimum, and base_maximum. The distributor module will pick a random value between that range (1 to 3, in our example) and give that amount of credits to all players.

Filters

Sometimes, you don't want to give all players the same amount of credits. You want to give more credits to VIP and Admins, or you want to give more credits to all players in a specific map, or you want to give more credits to VIP and Admins in a specific map when player count is above 15, etc. All of these configurations can be easily done using Filters.

Note: Filters require Distributor 1.1+.

Each filter has 2 parts:

• Conditions: When the filter should take effect. For example: when map is ctf_2fort, when player count > 10, when the player has the "a" flag, or when map is ctf_2fort and player count > 10 and the player has the "a" flag.
• Factors: What should the filter do if it satisfies its condition. You can multiply and/or add to the base credits amount (minimum, maximum or both). The calculation here is based on the standard arithmetic order of operations (multiplication comes first, then addition).

You can currently add up to 128 filters.

Let's start from a standard, non-filters example of a constant distribution:

"Distributor"
{
	"time_per_distribute"				"180"
	"distribution"
	{
		"base_minimum"			"1"
		"base_maximum"			"1"
	}
}

In this example, all players except spectators get a credit every 3 minutes. Let's decide that when there are 10 players or more all players will get 5 credits instead of 1. To do that, we will utilize filters:

"Distributor"
{
	"time_per_distribute"				"180"
	"distribution"
	{
		"base_minimum"			"1"
		"base_maximum"			"1"
		
		"filters"
		{
			"1"
			{
				"player_count"			"10"
				"multiplier"			"5"
			}
		}
	}
}

We used the multiplier property here in the filter, which multiplies both minimum and maximum. You can use min_multiplier to multiply the minimum value and max_multiplier to multiply the maximum value.

Now, let's decide than when there are 15 players or more and the map is pl_badwater, players will get between 7 and 10 credits:

"Distributor"
{
	"time_per_distribute"				"180"
	"distribution"
	{
		"base_minimum"			"1"
		"base_maximum"			"1"
		
		"filters"
		{
			"1"
			{
				"player_count"			"10"
				"multiplier"			"5"
			}

			"2"
			{
				"player_count"			"15"
				"map"					"pl_badwater"
				"min_addend"			"2"
				"max_addend"			"5"
			}
		}
	}
}

We used here min_addend to add 2 to the minimum value (so it's now 7 - it started from 1, we multiplied it by 5 and now we're adding 2) and max_addend to add 5 to the maximum value (so it's now 10, for the same reason).

Important: If we changed the 1st filter's player count condition to 25, for example, instead of 10, it wouldn't apply when player count < 25. That means that the minimum value would be 3 (1 from the base + 2 from the 2nd filter) and the maximum value would be 6.

Next, let's do that any player with the "ab" flags always gets double credits than usual players (even if the map isn't pl_badwater or player count < 10):

"Distributor"
{
	"time_per_distribute"				"180"
	"distribution"
	{
		"base_minimum"			"1"
		"base_maximum"			"1"
		
		"filters"
		{
			"1"
			{
				"player_count"			"10"
				"multiplier"			"5"
			}

			"2"
			{
				"player_count"			"15"
				"map"					"pl_badwater"
				"min_addend"			"2"
				"max_addend"			"5"
			}

			"3"
			{
				"flags"					"ab"
				"multiplier"			"2.0"
			}
		}
	}
}