AwardAPI 1.0.0

   (2 reviews)
Sign in to follow this  

4 Screenshots

About This File

MEwRQis.jpg

xb81ksL.jpg

 

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));
});

 

XgBXKT6.jpg




User Feedback

Create an account or sign in to leave a review

You need to be a member in order to leave a review

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Protocole

Report ·

  

Such great!

Share this review


Link to review
ragempdev

Report ·

  

approved 

image.png

Share this review


Link to review