Server Functions Documentation

This document explains the server-side Lua code for the admin menu, focusing on the ADMINMENU table, exported functions, and how to customize the XP system. The code initializes key data structures, provides utility functions, and integrates with the VORP Core framework. Below, we break down the code and explain how to adapt it, especially for the XP functionality, which currently uses the cas-metabolism script.

Code Overview

The provided Lua code defines the ADMINMENU table, global variables, and exported functions for managing admin panel features. Here's the structure with explanations:

ADMINMENU = {
    Dashboard = {
        serverStartTime = os.time() -- Stores the server start time
    },
    Players = {}, -- Tracks online players
    DatabaseItems = {}, -- Stores database items (e.g., inventory or resources)
    WeaponItems = {}, -- Stores weapon-related data
    FUNCTIONS = {}, -- Holds custom admin functions
    Admins = {}, -- Tracks online admins
    MySQLPerms = {}, -- Stores MySQL permission data
    Whitelist = {}, -- Manages whitelist data
    Leaderboard = {}, -- Stores leaderboard data
    closedForPlayers = false, -- Indicates if the server is closed to new players
}
Core = exports["vorp_core"]:GetCore() -- Initializes VORP Core for player and character data
freezeCache = {} -- Cache for frozen players
PlayerSessions = {} -- Tracks active player sessions

Key Components

• ADMINMENU Table: A global table storing server state and data:

  • Dashboard.serverStartTime: Records when the server started using os.time().

  • Players: Stores data for online players (e.g., IDs, names).

  • DatabaseItems, WeaponItems: Hold items and weapons data from the database.

  • FUNCTIONS: Reserved for custom admin functions.

  • Admins: Lists active admins.

  • MySQLPerms: Stores permission data from the database.

  • Whitelist: Manages whitelisted players.

  • Leaderboard: Tracks leaderboard data (e.g., top players).

  • closedForPlayers: Boolean to control server access (true prevents new players from joining).

• Core: Connects to the VORP Core framework to access player and character data.

• freezeCache: Stores data for players who are frozen by admins.

• PlayerSessions: Tracks active player sessions for session management.

Exported Functions

The script exports several functions for use by other scripts or the admin menu:

1. AdminMenuData

   exports("AdminMenuData", function()
       return ADMINMENU
   end)

   • Purpose: Returns the entire ADMINMENU table.

   • Usage: Allows other scripts to access admin menu data (e.g., players, whitelist, leaderboard).

2. AdminList

   exports("AdminList", function()
       return getOnlineAdmins()
   end)
   function getOnlineAdmins()
       return ADMINMENU.Admins
   end

   • Purpose: Returns the list of online admins.

   • Usage: Useful for checking which admins are active on the server.

3. WhitelistData

   exports("WhitelistData", function()
       return Config.UseWhitelist, ADMINMENU.Whitelist
   end)

   • Purpose: Returns the whitelist status (Config.UseWhitelist) and the Whitelist table.

   • Usage: Allows scripts to check if the whitelist is enabled and access whitelisted players.

4. isServerClosedForPlayers

   exports("isServerClosedForPlayers", function()
       return ADMINMENU.closedForPlayers
   end)

   • Purpose: Returns whether the server is closed to new players.

   • Usage: Used to check if closedForPlayers is true (server closed) or false (server open).

5. getActivePlayers

   exports("getActivePlayers", function()
       return ADMINMENU.Players
   end)

   • Purpose: Returns the list of active players.

   • Usage: Provides access to online player data for admin tools or scripts.

XP Functions

The AddXP and RemoveXP functions manage player XP, currently integrated with the cas-metabolism script. These functions need customization if you’re using a different XP system.

AddXP

function AddXP(source, xpToAdd)
    local user = Core.getUser(source) --[[@as User]]
    if not user then return end -- is player in session?
    local character = user.getUsedCharacter --[[@as Character]]
    local identifier = character.charIdentifier -- unique character identifier
    exports["cas-metabolism"]:addXP(xpToAdd, identifier, source)
    return {
        success = true,
        message = "xp added successfully"
    }
end

• Purpose: Adds XP to a player.

• Parameters:

  • source: The player’s server ID.

  • xpToAdd: The amount of XP to add (integer).

• Current Integration: Uses cas-metabolism to add XP via exports["cas-metabolism"]:addXP.

• Customization:

  • If you’re not using cas-metabolism, replace the export call with your own XP system’s function. For example:

    exports["your_xp_system"]:addXP(xpToAdd, identifier, source)

  • Ensure your XP system accepts the same parameters (xpToAdd, identifier, source) or adjust the function accordingly.

  • If your system doesn’t use identifier, you may need to modify how the player is identified (e.g., use source or another unique ID).

RemoveXP

function RemoveXP(source, xpToRemove)
    local user = Core.getUser(source) --[[@as User]]
    if not user then return end -- is player in session?
    local character = user.getUsedCharacter --[[@as Character]]
    local identifier = character.charIdentifier -- unique character identifier
    local xpToRemove = 30 -- Hardcoded value, should be dynamic
    exports["cas-metabolism"]:removeXP(xpToRemove, identifier, source)
    return {
        success = true,
        message = "xp removed successfully"
    }
end

• Purpose: Removes XP from a player.

• Parameters:

  • source: The player’s server ID.

  • xpToRemove: The amount of XP to remove (currently hardcoded to 30).

• Current Integration: Uses cas-metabolism to remove XP via exports["cas-metabolism"]:removeXP.

• Issues:

  • The xpToRemove parameter is hardcoded to 30, ignoring the passed value. This should be fixed to use the xpToRemove parameter dynamically:

    exports["cas-metabolism"]:removeXP(xpToRemove, identifier, source)

• Customization:

  • Replace the cas-metabolism export with your own XP system’s function, similar to AddXP.

  • Example:

    exports["your_xp_system"]:removeXP(xpToRemove, identifier, source)

  • Update the function to match your system’s API and parameters.

  • Ensure xpToRemove is passed dynamically instead of hardcoded.

Customizing the XP System

To adapt the XP functions for your server:

1. Identify Your XP System:

   • Determine which script handles XP (e.g., vorp_core, a custom script, or another framework).

   • Check its API for adding and removing XP (e.g., function names, parameters).

2. Update AddXP and RemoveXP:

   • Replace exports["cas-metabolism"] with your script’s export name.

   • Example for a custom XP system:

     function AddXP(source, xpToAdd)
         local user = Core.getUser(source)
         if not user then return end
         local character = user.getUsedCharacter
         local identifier = character.charIdentifier
         exports["my_xp_system"]:addExperience(identifier, xpToAdd) -- Replace with your function
         return {
             success = true,
             message = "xp added successfully"
         }
     end

   • Adjust RemoveXP similarly.

3. Test Changes:

   • Test the modified functions by triggering them via the admin menu (e.g., using the add.xp or remove.xp permissions).

   • Verify that XP is added or removed correctly and that no errors occur.

4. Handle Edge Cases:

   • Ensure the player is online (Core.getUser(source) check).

   • Validate xpToAdd and xpToRemove to prevent negative values or invalid inputs, if your system requires it.

Additional Notes

• VORP Core Dependency: The script relies on vorp_core for player data (Core.getUser, getUsedCharacter). Ensure VORP Core is running and properly configured.

• Error Handling: The XP functions return a success message, but you may want to add error handling for cases like invalid players or failed XP updates.

• Extending Functionality: Add new functions to ADMINMENU.FUNCTIONS for custom admin actions (e.g., managing currency, teleporting).

• Database Integration: The DatabaseItems and WeaponItems tables suggest database-driven item management. Ensure your database is set up to populate these tables.

• Whitelist and Leaderboard: Use WhitelistData and Leaderboard for whitelist and leaderboard features, respectively. Populate these tables via your database or scripts.

Tips for Developers

• Backup Before Changes: Save a copy of the script before modifying to avoid losing functionality.

• Test Exports: Use the exported functions in other scripts to ensure they return the expected data.

• Check VORP Core Docs: Refer to VORP Core’s documentation for details on getUser and getUsedCharacter methods.

• Debugging: Enable Config.DebugMode (in config/main.lua) to troubleshoot issues during development.

By customizing the XP functions and understanding the ADMINMENU structure, you can fully integrate the admin menu with your server’s systems. If you don’t use cas-metabolism, ensure you replace the XP-related exports with your own system’s equivalents.