BanAPI 1.0.0

Ban system that supports temporarily/permanently banning names, social club names, IP addresses and HWIDs.

 

Installing

1. Put banapi into your server's packages directory
2. Open banapi/database.js and put your MySQL config
3. All done

 

API

/*
    getUnixTimestamp()
    Returns the current Unix timestamp.
*/
mp.bans.getUnixTimestamp()

/*
    formatUnixTimestamp(unixTimestamp)
    Converts a Unix timestamp to "day/month/year hour:minute:second" format. Returns a string.
*/
mp.bans.formatUnixTimestamp(unixTimestamp)

/*
    add(value, banType, reason, endUnixTimestamp)
    Adds a ban to the bans table, the ban will be permanent if endUnixTimestamp is -1.
    You need to provide the value like a player's serial, IP or name.
    endUnixTimestamp must be seconds, NOT milliseconds. Just use the provided getUnixTimestamp()
    This won't terminate the banned player's connection. Can be used for offline banning.
    Returns a promise.
*/
mp.bans.add(value, banType, reason, endUnixTimestamp)

/*
    banPlayer(playerID, banType, reason, endUnixTimestamp)
    Bans the specified player, the ban will be permanent if endUnixTimestamp is -1.
    The script will get the value, you just need to provide a player ID and ban type.
    endUnixTimestamp must be seconds, NOT milliseconds. Just use the provided getUnixTimestamp()
    This will terminate the banned player's connection.
    Returns a promise.
*/
mp.bans.banPlayer(playerID, banType, reason, endUnixTimestamp)

/*
    getInfo(banID)
    Gets information about the specified ban ID. Returns a promise.
*/
mp.bans.getInfo(banID)

/*
    remove(banID)
    Removes the specified ban ID from the bans table. Returns a promise.
*/
mp.bans.remove(banID)

 

Ban Types

• 0 = Name ban, player's current name will be banned. (player.name property)
• 1 = Social Club name ban, player's current social club name will be banned. (player.socialClub property)
• 2 = IP ban, player's current IP address will be banned. (player.ip property)
• 3 = HWID ban, player's current HWID will be banned. (player.serial property)

 

Example Commands

/*
    Usage: /ban 5 0 60 Take a break
    Will nameban the player ID 5 (if there is a player with ID 5) for 60 minutes with the reason "Take a break".  
*/
mp.events.addCommand("ban", (player, _, target, type, minutes, ...reason) => {
    target = Number(target);
    type = Number(type);
    minutes = Number(minutes);
    let fullReason = reason.join(' ');

    let targetPlayer = mp.players.at(target);
    if (targetPlayer) {
        mp.bans.banPlayer(targetPlayer.id, type, fullReason, mp.bans.getUnixTimestamp() + (minutes * 60)).then((banID) => {
            player.outputChatBox(`Banned ${targetPlayer.name} with the reason '${fullReason}' for ${minutes} minutes.`);
            console.log(`${player.name} banned ${targetPlayer.name} for ${minutes} minutes. (${fullReason}) BanID: ${banID}`);
        }).catch((err) => {
            player.outputChatBox(`Error occurred while banning ${targetPlayer.name}.`);
            player.outputChatBox(`Error: ${err.message}`);
        });
    } else {
        player.outputChatBox(`No player with the ID ${target} found.`);
    }
});

/*
    Usage: /baninfo 3
    Will show information about ban ID 3 (if it exists)
*/
mp.events.addCommand("baninfo", (player, banID) => {
    banID = Number(banID);

    mp.bans.getInfo(banID).then((banInfo) => {
        if (banInfo) {
            player.outputChatBox(`Ban Information (BanID ${banInfo.ID})`);
            player.outputChatBox(`Type: ${banInfo.Type}`);
            player.outputChatBox(`Value: ${banInfo.Value}`);
            player.outputChatBox(`Reason: ${banInfo.Reason}`);
            player.outputChatBox(`Is Permanent: ${banInfo.LiftTimestamp == -1}`);
            if (banInfo.LiftTimestamp > -1) player.outputChatBox(`Ends: ${mp.bans.formatUnixTimestamp(banInfo.LiftTimestamp)}`);
        } else {
            player.outputChatBox(`BanID ${banID} expired or doesn't exist.`);
        }
    }).catch((err) => {
        player.outputChatBox(`Error occurred while getting BanID ${banID}.`);
        player.outputChatBox(`Error: ${err.message}`);
    });
});

/*
    Usage: /removeban 5
    Will remove the ban with specified ID (if it exists)
*/
mp.events.addCommand("removeban", (player, banID) => {
    banID = Number(banID);

    mp.bans.remove(banID).then((success) => {
        if (success) {
            player.outputChatBox(`BanID ${banID} is now history...`);
        } else {
            player.outputChatBox(`Couldn't remove BanID ${banID}, probably expired or doesn't exist.`);
        }
    }).catch((err) => {
        player.outputChatBox(`Error occurred while removing BanID ${banID}.`);
        player.outputChatBox(`Error: ${err.message}`);
    });
});

 

Notes

• This script will handle banned players when they join. (kick if they're still banned, remove ban if their ban expired)
• Don't use JS timestamps as they are milliseconds, use the provided mp.bans.getUnixTimestamp()