Welcome to the official documentation for Kitsune-Lab’s K4-Seasons project.

A comprehensive Battle Pass plugin for your server, offering extensive configuration options, per-season settings, level-based rewards, personal and community missions, and a host of additional features to enhance player engagement.

Installation

1. Download the project package from the official website.

2. Extract the files and drag them directly to your server. The files are already organized for correct placement, so no manual adjustments are necessary.

3. Restart your server or load the plugin manually.

4. Once the plugin has generated the configuration file at configs/plugins/K4-Seasons, open it and enter your license key. You can also adjust any additional settings.

5. Restart your server or manually reload the plugin to apply the changes.

Update

To update the plugin, simply follow the installation guide. If you’ve customized the translations, be sure to save them before updating to avoid losing your changes, and check if any translation files have been modified.

Permissions

Permissions in K4-Seasons control access to administrative features and commands. Below is a list of available permissions and their purposes.

@k4seasons/admin

• Description: Grants access to administrative commands for managing seasons and rewards.

• Command Access:

  • css_givebp [target]

Commands

1. css_season

• Description: Displays the season menu with all relevant seasonal data for the player.

• Use Case: Allows players to view their progress, available rewards, and other seasonal details.

• Permission Required: None (available to all players).

• Example Usage:

  Copy

  css_season

2. css_prestige

• Description: Attempts to prestige the player, provided they meet the level requirements. Prestiging resets the player's level and grants a prestige multiplier.

• Use Case: Enables players to progress to prestige levels for additional benefits and challenges.

• Permission Required: None (available to all players).

• Example Usage:

  Copy

  css_prestige

3. css_givebp

• Description: Grants a Battle Pass to the specified player.

• Use Case: Used by administrators to manually assign Battle Passes to players.

• Targets: You can use the player's name, userid or you can use the groupping methods such as @all, @t, @ct, @alive, @dead, @me or any other.

• Permission Required: @k4seasons/admin

• Syntax:

  Copy

  css_givebp [target]

• Parameters:

  • [target]: The player identifier (e.g., Name or UserID).

• Example Usage:

  Copy

  css_givebp #{userid}

Method 1: Using the Command

Command: css_givebp

• Description: Grants a Battle Pass to a specified player.

• Permission Required: @k4seasons/admin

• Syntax:

  Copy

  css_givebp [target]

  • [target]: The identifier of the player (e.g., #{userid}, groups, or username).

• Example Usage:

  Copy

  css_givebp #{userid}

• Effect:

  • Immediately assigns the Battle Pass to the specified player.

  • The player gains access to Battle Pass-exclusive rewards and benefits for the current season.

Method 2: Granting via Database Update

Webshops or other external systems can also grant a Battle Pass by updating the player's data in the database.

Steps for Webshop Integration:

1. Update the battle_pass_purchased Field:

   • Locate the player in the database (e.g., by steamid).

   • Set the battle_pass_purchased field to a valid current date and time (e.g., the date of purchase).

   • Example:

     Copy

     UPDATE k4se_players
     SET battle_pass_purchased = NOW()
     WHERE steam_id = 76561198345583467;

2. Automatic Detection by the Plugin:

   • The plugin periodically checks the database for updates (every 1 minute).

   • If it detects that the battle_pass_purchased field has been updated with a valid date:

     • It activates the Battle Pass for the player.

     • The player receives an in-game message, which can be edited in the translations:

       Copy

       [ Battle-Pass ] Congratulations! You have activated the Battle-Pass for this season.

3. Player Access:

   • The player gains immediate access to all Battle Pass-exclusive rewards and benefits for the current season.

Battle Pass Validity

1. Season-Limited:

   • The Battle Pass is only valid for the current season. Once the season ends, the Battle Pass is automatically revoked.

2. Example Scenario:

   • If a player activates their Battle Pass during Season 1, they retain access until the end of Season 1.

   • When Season 2 begins, the plugin revokes their Battle Pass unless they purchase or are granted a new one.

Key Features

Command-Based Activation

• Simple and immediate for administrators.

• Use css_givebp to manually grant a Battle Pass to players.

Database-Driven Activation

• Seamless integration with webshops or external systems.

• Automatically detects Battle Pass purchases and activates them within 1 minute.

• Sends in-game feedback to players upon activation.

Season-Specific Validity

• Ensures that the Battle Pass is only valid for the active season.

• Automatically revokes Battle Pass access at the end of the season, requiring renewal for future seasons.

The easiest way to report issues is by joining our Discord server. There, you'll find a publicly accessible room called "trackers," which functions as a forum where you can create threads for feature requests or issue reports. Be as detailed as possible in your report, and if applicable, attach logs or other relevant files to help us troubleshoot. Give your thread a clear title and assign appropriate labels to make it easier for us to identify the case.

If you prefer not to use Discord, you can also report issues via the ticketing system on our website. To do so, log in to your account where your license key is registered, and navigate to the Tickets section. Here, you can open a ticket. Be sure to select the relevant project for your issue to help us locate the necessary details more quickly.

General Information

The license-key field contains the system's license key, used for unique identification and authentication.

Database Settings

The database-settings section defines the parameters for connecting to the database.

Experience Settings

The experience-settings section defines the amount of experience points (XP) awarded for various in-game actions.

Level Settings

The level-settings section manages how players progress through levels in the system.

Mission Settings

The mission-settings section defines parameters for in-game missions.

Mission Streak Settings

The mission-streak-settings section incentivizes mission completion streaks.

Weekly Bonus Settings

The weekly-bonus-settings section allows for additional bonuses on specific days.

Prime Time Settings

The prime-time-settings section defines bonus periods during specific times.

Anti-Frustration Settings

The anti-frustration-settings section minimizes player frustration through periodic rewards. When they can't complete a mission within the interval, they are offered to abandon the mission and gain xp depending on ther current progress with the mission.

Toplist Settings

The toplist-settings section configures leaderboard bonuses.

Battle Pass Settings

The battle-pass-settings section manages premium content for players.

Menu Settings

The menu-settings section defines the behavior of the in-game menu.

Prestige Settings

The prestige-settings section manages the prestige system for advanced players. When they reach the maximum level, they can do a prestige reset, which sets their rank back to the start and allowing them to start the levelling again with a prestige level based XP multiplier.

Catch-Up Settings

The catch-up-settings section helps players who are behind catch up with others. When someone purchase the battlepass later than the season started, they get a multiplier depending on how many week elapsed to gain XP faster than other, until they reach the avarage battle pass user's level - 10%. So people won't think about the purchase as they cant maximize their rewards from it.

Overview

Each season has an index, starting from 1. So the first season config file will be season_1.jsonc. When the season ends, the plugin load the next config with it's own configurations, which would be season_2.jsonc. Don't forget to create them before the season ends.

The JSON configuration defines the following:

• season_name: The display name of the season.

• duration_days: The number of days the season will last.

• rewards: A mapping of levels to rewards.

Each reward specifies commands to execute, permissions to assign, and whether it is exclusive to Battle Pass owners.

Reward Configuration

Each level in the rewards section defines a reward, and its structure supports additional properties beyond simple commands. Here’s an overview of all fields available in a LevelReward object.

Fields in LevelReward

1. name

   • Description: The name or description of the reward.

   • Type: string

   • Example:

     Copy

     "name": "Operation Bravo Case"

2. commands

   • Description: A list of commands to execute when the reward is granted.

   • Type: array of strings

   • Default Value: [] (empty list)

   • Placeholders:

     • #{steamid}: Player's SteamID64.

     • #{userid}: Player's UserID.

     • #{name}: Player's username.

   • Example:

     Copy

     "commands": [
       "css_givecase #{userid} 4003 1"
     ]

3. permissions

   • Description: A list of permissions granted to the player upon being above that level.

   • Type: array of strings (nullable)

   • Default Value: null

   • Example:

     Copy

     "permissions": [
       "@example/flag",
       "@example/admin"
     ]

4. groups

   • Description: A list of groups the player is added to upon being above that level.

   • Type: array of strings (nullable)

   • Default Value: null

   • Example:

     Copy

     "groups": [
       "#example/vip",
       "#example/premium"
     ]

5. command-access

   • Description: A list of commands the player is allowed to access after reaching the level.

   • Type: array of strings (nullable)

   • Default Value: null

   • Example:

     Copy

     "command-access": [
       "example_flag",
       "admin_access"
     ]

6. battle_pass_only

   • Description: Indicates whether the reward is exclusive to Battle Pass owners.

   • Type: boolean

   • Default Value: false

   • Example:

     Copy

     "battle_pass_only": true

Example JSON Configuration

Here’s an updated example that includes all possible reward types:

{
  "season_name": "The Nine Tailed Fox",
  "duration_days": 90,
  "rewards": {
    "1": {
      "name": "Operation Bravo Case",
      "commands": [
        "css_givecase #{userid} 4003 1"
      ],
      "permissions": [
        "@example/flag"
      ],
      "groups": [
        "#example/vip"
      ],
      "command-access": [
        "example_flag"
      ],
      "battle_pass_only": false
    },
    "2": {
      "name": "eSports 2013 Case",
      "commands": [
        "css_givecase #{userid} 4002 1"
      ],
      "battle_pass_only": false
    },
    "3": {
      "name": "CS:GO Weapon Case + Key",
      "commands": [
        "css_givecase #{userid} 4001 1",
        "css_givekey #{userid} 0 1"
      ],
      "permissions": [
        "@example/admin"
      ],
      "groups": [
        "#example/premium"
      ],
      "command-access": [
        "admin_access"
      ],
      "battle_pass_only": true
    },
    "4": {
      "name": "Winter Offensive Case",
      "commands": [
        "css_givecase #{userid} 4009 1"
      ],
      "groups": [
        "#example/regular"
      ],
      "battle_pass_only": false
    },
    "5": {
      "name": "Winter Offensive Case + Key",
      "commands": [
        "css_givecase #{userid} 4009 1",
        "css_givekey #{userid} 1214 1"
      ],
      "permissions": [
        "@example/special"
      ],
      "command-access": [
        "special_flag"
      ],
      "battle_pass_only": true
    }
  }
}

Usage Notes

1. Mix and Match Rewards: You can combine commands, permissions, groups, and command-access fields for a single reward.

2. Battle Pass Restrictions: Use "battle_pass_only": true to make rewards exclusive to Battle Pass holders.

3. Commands with Placeholders: Replace placeholders (#{steamid}, #{userid}, #{name}) dynamically when commands are executed.

4. The groups, permissions and command acceses are collected and always given to the player as long as the season goes on and they have the level for them.

Mission Object Structure

Example Mission Objects

Personal Mission

{
  "Event": "EventPlayerDeath",
  "Target": "Userid",
  "Map": "de_dust2",
  "Type": "Personal",
  "Name": "Die 3 times on Dust2",
  "AmountToComplete": 3,
  "RewardExperience": 1500,
  "BattlePassOnly": true
}

Community Mission

{
  "Event": "EventPlayerJump",
  "Target": "Userid",
  "Type": "Community",
  "Name": "Jump 500,000 times as a community",
  "AmountToComplete": 500000,
  "RewardExperience": 60000,
}

Special Cases

If EventProperties is specified, the mission is only valid when the event properties match the provided criteria. You can find all property of any event at https://cs2.poggu.me/dumped-data/game-events/

{
    "Event": "EventPlayerDeath",
    "Target": "Attacker",
    "EventProperties": {
      "Weapon": "ak47",
      "Headshot": true
    },
    "Type": "Personal",
    "Name": "Kill 10 with AK47 headshots",
    "AmountToComplete": 10,
    "RewardExperience": 2000,
    "BattlePassOnly": true
  }