Home

Leveling

Leveling is a plugin that allows you to add RPG-styled leveling and classes to your server. Leveling works by granting EXP (experience) to players whenever they kill mobs, but it can also be used in tandem with CustomQuests for granting EXP for completing quests.

Config

To generate the configuration file, open the server, and then exit it. The configuration file, leveling/config.json, is currently of the form

{
   "DatabaseConfig" : {
    "DatabaseType" : "mysql",
    "ConnectionString" : "your-connection-string"
},
  "DefaultClass": "ranger",
  "NpcToExpReward": {
    "Blue Slime": 100
  },
  "ExpMultiplier": 1,
  "DeathPenaltyMultiplier": 0.33,
  "DeathPenaltyMinimum": 0,
  "DeathPenaltyPvPMultiplier": 0.1
}

DefaultClass indicates the default class for players, NpcToExpReward is a table that overrides the default EXP given for each mob (by default, each mob gives EXP equal to its HP), and ExpMultiplier is a global EXP multiplier that can be changed freely. The other properties are self-explanatory.

Classes

Under the leveling folder, you can create classes by creating a file with the .class extension. For organization, you may place these files under separate folders. An example class follows:

{
  "Name": "gunsmith",
  "DisplayName": "Gunsmith",
  "ScriptPath" : "scripts/Gunsmith.boo",
  "Levels": [
    {
      "Name": "gunsmith_1",
      "DisplayName": "Level 1",
      "ExpRequired": 1,
      "CurrencyRequired" : "1Copper",
      "Prefix": "[c/00aa00:[Lvl 1 Gunsmith][c/00aa00:]] ",
      "ItemsAllowed": [],
      "PermissionsGranted": [],
      "CommandsOnLevelUp": [],
      "CommandsOnLevelUpOnce": [],
      "CommandsOnLevelDown": [
        "/addhp \"$name\" -100"
      ]
    },
    {
      "Name": "gunsmith_2",
      "DisplayName": "Level 2",
      "ExpRequired": 1000000,
      "Prefix": "[c/00aa00:[Lvl 2 Gunsmith][c/00aa00:]] ",
      "ItemsAllowed": ["Megashark"],
      "PermissionsGranted": [],
      "CommandsOnLevelUp": [
        "/addhp \"$name\" 100"
      ],
      "CommandsOnLevelUpOnce": [
        "/sendto \"$name\" 255,255,0 You have discovered the secrets of the mighty [i:533]!"
      ],
      "CommandsOnLevelDown": [
        "/addhp \"$name\" -1000"
      ]
    },
    {
      "Name": "gunsmith_3",
      "DisplayName": "Level 3",
      "ExpRequired": -1,
      "Prefix": "[c/00aa00:[Lvl 3 Gunsmith][c/00aa00:]] ",
      "ItemsAllowed": ["S.D.M.G.", "Vortex Helmet", "Vortex Breastplate", "Vortex Leggings"],
      "PermissionsGranted": [],
      "CommandsOnLevelUp": [
        "/addhp \"$name\" 1000"
      ],
      "CommandsOnLevelUpOnce": [
        "/sendto \"$name\" 255,255,0 You hold the powerful [i:1553], and stare at its beauty..."
      ],
      "CommandsOnLevelDown": [
      ]
    }
  ],
  "PrerequisiteLevels": ["ranger_2"],
  "PrerequisitePermissions": [],
   "CommandsOnClassChangeOnce" : [],
  "Cost" : "1d",
  "AllowSwitching": true,
  "AllowSwitchingBeforeMastery": true,
  "ExpMultiplierOverride": 0.5,
  "DeathPenaltyMultiplierOverride": null,
    "NpcNameToExpReward" : {}
}

• Name is fairly obvious and is the internal name of the class.

• DisplayName is the name of the class, shown to players.

• ScriptPath is an optional, relative path to a Boo script.

• Levels is an array of levels for the class:

  • Name is the internal name of the level.
  • DisplayName is the name of the level, shown to players.
  • ExpRequired is the amount of EXP required to go through the level. If this is negative, then leveling up cannot be done normally with EXP and must be done by command, if possible.
  • CurrencyRequired is a Currency string value, which will be parsed with the generic raw value stored in ExpRequired. The first currency determined, will be chosen as the class's leveling currency. If no leveling currency is set, users will not be able to level up!
  • Prefix is the prefix for the level, and will show up before the player's group prefix. To hide this, give a group permission leveling.noprefix.
  • ItemsAllowed is an array of item names allowed. These item names must be exact, with proper capitalization. The default value of this is an empty array, so you can leave this out if you want.
  • PermissionsGranted is an array of TShock permissions granted. The default value of this is an empty array, so you can leave this out if you want.
  • CommandsOnLevelUp is an array of commands for the server to execute when the player levels up to this level. Use $name to substitute the player's name. The default value of this is an empty array, so you can leave this out if you want.
  • CommandsOnLevelUpOnce is an array of commands for the server to execute when the player levels up to this level, but only once. Use $name to substitute the player's name. The default value of this is an empty array, so you can leave this out if you want.
  • CommandsOnLevelDown is an array of commands for the server to execute when the player levels down to this level. Use $name to substitute the player's name. The default value of this is an empty array, so you can leave this out if you want.

• CommandsOnClassChangeOnce is an array of commands for the server to execute when the player changes classes. This will only run on the first change to the class.

• PrerequisiteLevels is an array of prerequisite level names for unlocking this class. The default value of this is an empty array, so you can leave this out if you want.

• PrerequisitePermissions is an array of prerequisite permissions for unlocking this class. The default value of this is an empty array, so you can leave this out if you want.

• Cost is the Currency cost of unlocking this class. If invalid, cost will be ignored and players can freely switch to this class.

• AllowSwitching lets you disable switching out of the class.

• AllowSwitchingBeforeMastery lets you disable switching out of the class before mastery.

• ExpMultiplierOverride is an EXP multiplier override over the global EXP multiplier. It will be multiplied with the global. The default value is null, which means there is no change, so you can leave this out if you want.

• DeathPenaltyMultiplierOverride is a death penalty multiplier override over the global death penalty multiplier. It will be multiplied with the global. The default value is null, which means there is no change, so you can leave this out if you want.

• NpcNameToExpReward is an object containing key value pairs matching npc type names to specified experience values that will be awarded on killing.

Items will only be class-restricted if the item name appears in any class. Thus, if, e.g., the S.D.M.G. is not specified in any class, then it will not be restricted to any class.

Classes will be 'mastered' if a player reaches the last level. Thus, the last level must always have negative EXP and should be treated as a terminus.

NOTE: when using these commands in, say, CustomQuests, you must get the player name appropriately. For example, to give everyone in the party 100 EXP, you must do

ForEachPlayer(function(player)
    ExecuteCommand('/giveexp ' .. player.Index .. ' 100')
end)

Script points

Class definitions have a "ScriptPath" property, which can point to a Boo script using a relative path from the .class file(optional).

Leveling supports the following 4 script points:

def OnLevelUp(player, klass, levelIndex):
	Broadcast("Player leveled up!")

def OnLevelDown(player, klass, levelIndex):
	Broadcast("Player leveled down!")

def OnClassChange(player, newClass, oldClass):
	Broadcast("Player changed class to " + newClass.DisplayName)

def OnClassMastered(player, klass):
	Broadcast("Player mastered class!")

Types are TSPlayer, Class, and int for levelIndices. Class is a mostly read-only wrapper-- you will not be able to modify them, or cancel the operation in any way.