AwardAPI 1.0.0

 

This script lets you create awards/achievements and give them to players.

 

Installing

1. Put the files you downloaded in their respective places
2. Add require('awards') to client_packages/index.js
3. Open packages/awards/database.js and put your MySQL config
4. All done

 

API - Exported

You need to load awards/api.js in your script with using require() for these.

/*
    awardDefinitions object contains all defined awards.
    
    Keys of this object are valid award IDs.
*/
awardDefinitions

/*
    Defines an award. Awards can be single or multi tier depending on what you send to requiredProgress.

    If you send an array of numbers, it will be a multi tier award. (then tierColor must be an array of numbers too, tierColors length being the same as equiredProgress length)
    
    If you send a single number, it will be a single tier award. (then tierColor must be a single number too)
    
    Check out https://wiki.rage.mp/index.php?title=Fonts_and_Colors#HUD_Colors for tierColors values. (107, 108, 109, 110 are great)
    
    You can search for mpawards in OpenIV/CodeWalker Explorer for txdLib and txdName, or send an empty string to txdLib and txdName if you don't want to use an icon.
    
    This function returns true if award is created, false otherwise.
*/
defineAward(ID, name, description, txdLib, txdName, requiredProgress, tierColor)

/*
    Returns the specified award's tier for the specified progress. You must increase the return value by 1 if you want to display it to players.
    
    Returns:
    -2 if award ID is invalid
    -1 if progress isn't enough for any tier
    0 and above if progress is enough for any tier
*/
calculateAwardTier(awardID, progress)

/*
    Returns the specified award's icon color for the specified tier.
    
    Return value will be -1 if award ID is invalid.
*/
getAwardTierColor(awardID, tier)

 

API - Player

/*
    This property contains the award data and should be used for getting values.
    Keys of this object are the award IDs that player has any progress on.
    
    player.awardData[validAwardID] properties:
    - Progress (number)
    - Tier (number)
    - IsComplete (boolean)
    - CompletionDate (date, null if award isn't complete)
*/
player.awardData

/*
    Sets the specified award's progress to the specified amount.
    Returns false if awardID is invalid, true otherwise.
*/
player.setAwardProgress(awardID, progress)

/*
    Changes the specified award's progress by the specified amount.
    Returns false if awardID is invalid, true otherwise.
*/
player.changeAwardProgress(awardID, progress)

/*
    Resets the specified award's progress.
    Returns false if awardID is invalid or player doesn't have any data about the specified awardID, true otherwise.
*/
player.resetAwardProgress(awardID)

/*
    Resets all award progress.
    Doesn't return anything.
*/
player.resetAllAwardProgress()

/*
    Saves award data.
    You don't need to add this to your script's playerQuit event because AwardAPI will save data when a player disconnects.
*/
player.saveAwards()

 

Serverside Events

/*
    playerAwardTierChange  
    This event is called when a player's award's tier changes.
*/
mp.events.add("playerAwardTierChange", (player, awardID, oldTier, newTier) => {
    // code
});

/*
    playerCompleteAward
    This event is called when a player completes an award.
*/
mp.events.add("playerCompleteAward", (player, awardID) => {
    // code
});

 

Example

This script creates 2 awards (one single tier and one multi tier), progresses them when certain events happen, sends a message to players when one of their awards has a tier change or completion and provides some commands.

const awardAPI = require("../awards/api");

/*
    Multi tier award, will be complete when a player dies 1000 times.
    1 deaths - tier 1 (bronze)
    10 deaths - tier 2 (silver)
    100 deaths - tier 3 (gold)
    1000 deaths - tier 4 (platinum)
*/
awardAPI.defineAward("award_unlucky", "Unlucky", "You keep dying, be careful!", "mpawards5", "killmeleeweapons", [1, 10, 100, 1000], [107, 108, 109, 110]);

/*
    Single tier award, will be complete when a player writes something to the chat.
*/
awardAPI.defineAward("award_chat", "Baby's First Words", "You used the chat.", "", "", 1, 110);

// Events
mp.events.add({
    // Increase player's "award_unlucky" progress by 1 when a player dies.
    "playerDeath": (player) => {
        player.changeAwardProgress("award_unlucky", 1);
    },

    // Set player's "award_chat" progress to 1 (since its max. progress is 1) when a player writes something to chat.
    "playerChat": (player) => {
        player.setAwardProgress("award_chat", 1);
    }
});

// Commands
mp.events.addCommand("howunlucky", (player) => {
    // example: check if player has any progress for award_unlucky, display a message based on completion
    if (player.awardData["award_unlucky"]) {
        if (player.awardData["award_unlucky"].IsComplete) {
            player.outputChatBox("You're extremely unlucky.");
        } else {
            player.outputChatBox(`Not too unlucky, just ${player.awardData["award_unlucky"].Progress} deaths...`);
        }
    } else {
        player.outputChatBox("You're pretty lucky for now.");
    }
});

mp.events.addCommand("setawardprogress", (player, _, awardID, progress) => {
    // example: "/setawardprogress award_unlucky 1000" will complete "unlucky" achievement
    player.setAwardProgress(awardID, Number(progress));
});

mp.events.addCommand("changeawardprogress", (player, _, awardID, progress) => {
    // example: "/changeawardprogress award_unlucky 5" will add 5 progress to "unlucky" achievement
    player.changeAwardProgress(awardID, Number(progress));
});