Upgrade Scripts Docs

#Leveling & XP

Reward points and leveling XP are two separate currencies and always have been:

  • Reward points are what players spend in the shops. They come from the playtime timer, referrals, loot cases and admins. Configured with Config.GivePeriodPoints, Config.ReferreeReward and Config.ReferrerReward.
  • XP only moves the level bar. It cannot be spent. Configured entirely inside Config.LevelSystem.

Changing one never affects the other. The most common setup mistake is expecting Config.GivePeriodPoints to control leveling - it does not.

#Choosing the curve

Config.LevelSystem = {
    Mode = 'scaling',

    XPPerLevel = 2000,   -- 'static' mode
    BaseXP     = 100,    -- 'scaling' mode
    Multiplier = 1.5,    -- 'scaling' mode

    CustomXP = {         -- 'custom' mode
        [1] = 500,
        [2] = 1000,
        [3] = 1500,
        [4] = 2000,
    },

    MaxLevel = 100,
}

Set Mode first. Only the values belonging to the mode you choose are read, so editing XPPerLevel does nothing while Mode is still 'scaling'.

  • 'static' - every level costs XPPerLevel. Set XPPerLevel = 2000 and every single level needs 2,000 XP.
  • 'scaling' - level 1 needs BaseXP, and each level after costs Multiplier times the one before it. With the defaults that is 100, 150, 225, 337, 506 and so on. A Multiplier of 1.0 behaves like static mode.
  • 'custom' - each level's cost is read from CustomXP. Levels past the last entry reuse the highest one you defined.

The threshold is calculated from this config every time it is needed, so changing the curve applies to every existing player immediately. Nothing is cached in the database that could disagree with what the level bar shows.

#Where XP comes from

XP = {
    Playtime         = 10,
    ReferralReferee  = 50,
    ReferralReferrer = 100,
    AdminPointsRatio = 0,
},

These are the only four sources of XP. Set any of them to 0 to switch that source off.

  • Playtime - granted each time the playtime reward pays out, which is every Config.PlayTimeMinutes.
  • ReferralReferee - to the player who redeems a referral code.
  • ReferralReferrer - to the player whose code was redeemed. With Config.ReferralSystem.MaturityHours set, this is granted when the referral matures rather than immediately.
  • AdminPointsRatio - XP granted alongside points credited from the admin panel, as XP per point. 0.1 would be 1 XP for every 10 points. It defaults to 0 because the panel has its own "Grant XP" button.

#Working out hours per level

XP per hour is Playtime * 60 / Config.PlayTimeMinutes. With the default 60-minute period, Playtime is your XP per hour.

For 2,000 XP per level at roughly 10 hours a level:

Config.PlayTimeMinutes = 60

Config.LevelSystem.Mode       = 'static'
Config.LevelSystem.XPPerLevel = 2000
Config.LevelSystem.XP.Playtime = 200

The console prints the result on every start, so you can check it without logging in:

[Upgrade-Rewards] Level system: mode static | XP needed 1->2: 2000, 2->3: 2000, 5->6: 2000, 10->11: 2000 | XP per playtime reward: 200 (every 60 min), referral: 50 / 100

If a single playtime reward is enough to reach level 2, the resource prints a warning as well - that almost always means XPPerLevel was edited while Mode was left on 'scaling'.

#Level-up rewards

NotifyOnLevelUp = true,

Rewards = {
    [5]  = { points = 250 },
    [10] = { points = 500, cash = 10000, items = { { name = 'armor', count = 1, label = 'Armor' } } },
    [25] = { points = 1500, items = { { name = 'weapon_pistol', count = 1, label = 'Pistol' } } },
},

Keyed by the level being reached. Every key is optional - points, cash and items can each be used on their own. If a player crosses several levels at once, they receive the rewards for every level they passed.

Points are always granted. Cash and items need the player to be online at the moment they level, which in practice they are, since XP comes from playing. Anything skipped is noted in the server console.

With NotifyOnLevelUp on, the player is told the moment they level, and the rewards they earned are named in the notification. They also get the level-up celebration in the menu next time they open it. Level changes made by an admin with "Set Level" deliberately do not grant these rewards.

Every level-up can also post to Discord - see the LevelUp event in Discord Webhooks.

#Rank titles

Titles = {
    [1] = "Newbie",
    [5] = "Rookie",
    [10] = "Amateur",
    -- ...
    [100] = "Los Santos Legend"
}

A title is assigned every five levels and shown next to the player's level in the menu and in the admin panel. Add or rename entries freely; a level with no entry of its own keeps the last title below it.

#The points bonus

PointMultiplier = 0.1,

Each level adds this fraction to every playtime points payout. At 0.1, a level 10 player earns double points and a level 20 player triple. It applies to the playtime reward only, and the bonus percentage is written into the player's points history so they can see where it came from.

#Adjusting a player directly

Admins can grant XP or set a level outright from /rewards-admin. Setting a level resets that player's XP to 0 for the new level and does not grant level rewards. Other resources can award XP through the AddXP export - see Server Exports.