Skip to content

README_sakaSTATS.md

Latest commit

 

History

History
263 lines (203 loc) · 9.52 KB

README_sakaSTATS.md

File metadata and controls

263 lines (203 loc) · 9.52 KB
Raw

sakaSTATS Include File Documentation

The sakaSTATS.inc include file provides a comprehensive API for interacting with the sakaSTATS plugin from other SourceMod plugins. This allows developers to access player statistics, rankings, and seasonal data across the entire saka ecosystem.

Installation

  1. Place sakaSTATS.inc in your sourcemod/scripting/include/ directory
  2. Include it in your plugin: #include <sakaSTATS>
  3. Ensure the sakaSTATS plugin is loaded on your server

Constants

Statistics Types

#define SAKASTATS_STAT_POINTS           "points"
#define SAKASTATS_STAT_KILLS            "kills"
#define SAKASTATS_STAT_DEATHS           "deaths"
#define SAKASTATS_STAT_PLAYTIME         "playtime"
#define SAKASTATS_STAT_TOPSPEED         "topspeed"
#define SAKASTATS_STAT_DEFLECTIONS      "deflections"

Other Constants

#define SAKASTATS_MAX_NAME_LENGTH       128
#define SAKASTATS_MAX_STEAMID_LENGTH    64
#define SAKASTATS_INVALID_RANK          -1
#define SAKASTATS_CURRENT_SEASON        0

Native Functions

The legacy scalar reads are compatibility shims: they read confirmed local state and fail closed on a cache miss. They never wait for MySQL. Consumers that require an authoritative remote result should use the asynchronous request natives below.

Player Statistics

SakaStats_GetPlayerStat(steamid, statistic)

Gets a player's statistic value for the current season.

  • Parameters:
    • steamid - Player's SteamID (Steam3 format: [U:1:XXXXXXX])
    • statistic - Statistic name (use SAKASTATS_STAT_* constants)
  • Returns: Statistic value, -1 on error

SakaStats_GetPlayerStatSeason(steamid, statistic, season)

Gets a player's statistic value for a specific season.

  • Parameters:
    • steamid - Player's SteamID
    • statistic - Statistic name
    • season - Season number (0 for current season)
  • Returns: Statistic value, -1 on error

Player Rankings

SakaStats_GetPlayerRank(steamid, statistic)

Gets a player's ranking for a statistic in the current season.

  • Parameters:
    • steamid - Player's SteamID
    • statistic - Statistic name
  • Returns: Player's rank (1-based), SAKASTATS_INVALID_RANK on error

SakaStats_GetPlayerRankSeason(steamid, statistic, season)

Gets a player's ranking for a statistic in a specific season.

  • Parameters:
    • steamid - Player's SteamID
    • statistic - Statistic name
    • season - Season number (0 for current season)
  • Returns: Player's rank (1-based), SAKASTATS_INVALID_RANK on error

SakaStats_RequestPlayerRank(steamid, statistic, season, callback, data)

Queues an authoritative competition-rank query. Returns a positive request ID when accepted and invokes the callback exactly once with a SakaStatsAsyncResult, rank, and caller data.

SakaStats_RequestPlayerProfile(steamid, callback, data)

Queues an authoritative live-profile query. Returns a positive request ID when accepted and invokes the callback exactly once with the display name, remaining name changes, result status, and caller data.

SakaStats_RequestPlayerExists(steamid, callback, data)

Queues an authoritative existence query and completes once with the SteamID, existence flag, result status, and caller data.

SakaStats_RequestPlayerStat(steamid, statistic, season, callback, data)

Queues an authoritative statistic query and completes once with the typed result, value, request identity, and caller data.

SakaStats_RequestSeasonPlayerCount(season, callback, data)

Queues an authoritative season count. The live season returns active players from the last 30 days; archived seasons return their total row count.

Season System

SakaStats_GetCurrentSeason()

Gets the current season number.

  • Returns: Current season number

SakaStats_IsSeasonSystemEnabled()

Checks if the season system is enabled.

  • Returns: True if season system is enabled, false otherwise

Player Information

SakaStats_GetPlayerDisplayName(steamid, name, maxlen)

Gets a player's display name (custom name if set, otherwise Steam name).

  • Parameters:
    • steamid - Player's SteamID
    • name - Buffer to store the name
    • maxlen - Maximum length of buffer
  • Returns: True on success, false on error

SakaStats_GetPlayerNameChanges(steamid)

Gets a player's remaining name changes.

  • Parameters:
    • steamid - Player's SteamID
  • Returns: Number of remaining name changes, -1 on error

Utility Functions

SakaStats_CalculateKillsPerHour(kills, playtime)

Calculates Kills per Hour for given stats.

  • Parameters:
    • kills - Number of kills
    • playtime - Playtime in seconds
  • Returns: Kills per hour

SakaStats_GetTotalPlayerCount()

Gets the total number of players in the database.

  • Returns: Total player count, -1 on error

SakaStats_PlayerExists(steamid)

Checks if a player exists in the database.

  • Parameters:
    • steamid - Player's SteamID
  • Returns: True if player exists, false otherwise

SakaStats_GetPlayerRocketsStolen(client)

Gets the tracked rockets-stolen count for a connected client.

  • Parameters:
    • client - Client index
  • Returns: Rockets stolen count, 0 on error

Stock Functions (Client-based Wrappers)

The following immediate reads have stock wrappers accepting client indices. Async requests still take SteamIDs; capture a userid or serial in caller data and revalidate the recipient before displaying a callback result:

  • SakaStats_GetClientStat(client, statistic)
  • SakaStats_GetClientStatSeason(client, statistic, season)
  • SakaStats_GetClientRank(client, statistic)
  • SakaStats_GetClientRankSeason(client, statistic, season)
  • SakaStats_GetClientDisplayName(client, name, maxlen)
  • SakaStats_GetClientNameChanges(client)
  • SakaStats_ClientExists(client)
  • SakaStats_GetClientRocketsStolen(client)

Utility Stock Functions

SakaStats_IsValidClient(client)

Validates a client index.

  • Returns: True if client is valid, false otherwise

SakaStats_GetClientSteamID(client, steamid, maxlen)

Gets a client's SteamID in Steam3 format.

  • Returns: True on success, false on failure

SakaStats_FormatPlaytime(seconds, buffer, maxlen)

Formats playtime from seconds to readable string.

  • Example: 3661 seconds → "1h1m1s"

SakaStats_CalculateKDR(kills, deaths)

Calculates K/D ratio with proper handling of zero deaths.

  • Returns: K/D ratio

SakaStats_FormatKillsPerHour(kills, playtime, buffer, maxlen)

Formats Kills per Hour for display.

Usage Examples

These fragments demonstrate cache-only reads. Handle unavailable values before displaying them; a prior existence check does not guarantee that rank or other fields are cached. Use asynchronous requests for authoritative results.

Basic Statistics Display

#include <sakaSTATS>

public Action Command_MyStats(int client, int args) {
    if (!SakaStats_ClientExists(client)) {
        PrintToChat(client, "No statistics found!");
        return Plugin_Handled;
    }
    
    int points = SakaStats_GetClientStat(client, SAKASTATS_STAT_POINTS);
    int rank = SakaStats_GetClientRank(client, SAKASTATS_STAT_POINTS);
    
    PrintToChat(client, "Points: %d (Rank #%d)", points, rank);
    return Plugin_Handled;
}

Season-Specific Data

public Action Command_SeasonStats(int client, int args) {
    if (!SakaStats_IsSeasonSystemEnabled()) {
        PrintToChat(client, "Season system is disabled!");
        return Plugin_Handled;
    }
    
    int currentSeason = SakaStats_GetCurrentSeason();
    int seasonPoints = SakaStats_GetClientStatSeason(client, SAKASTATS_STAT_POINTS, currentSeason);
    
    PrintToChat(client, "Season %d Points: %d", currentSeason, seasonPoints);
    return Plugin_Handled;
}

Player Comparison

public void ComparePlayersStats(int client1, int client2) {
    int points1 = SakaStats_GetClientStat(client1, SAKASTATS_STAT_POINTS);
    int points2 = SakaStats_GetClientStat(client2, SAKASTATS_STAT_POINTS);
    
    char name1[SAKASTATS_MAX_NAME_LENGTH], name2[SAKASTATS_MAX_NAME_LENGTH];
    SakaStats_GetClientDisplayName(client1, name1, sizeof(name1));
    SakaStats_GetClientDisplayName(client2, name2, sizeof(name2));
    
    PrintToChatAll("%s (%d) vs %s (%d)", name1, points1, name2, points2);
}

Integration with Other Plugins

There are currently no in-repository plugin consumers of this public API. External consumers should use the contract reference and the signatures in sakaSTATS.inc. The older references to sakaBOT, sakaROBOT, and sakaCOLORSv2 are not current integration examples.

Error Handling

Always check each native's documented return value:

  • Legacy stat/rank/name-change reads use -1 for unavailable data.
  • Async requests return 0 when not accepted; inspect SakaStatsAsyncResult in callbacks for accepted requests.
  • Rockets-stolen reads return 0 on invalid input.
  • A false cache-only existence result can mean unconfirmed data, not necessarily an absent database row. Use SakaStats_RequestPlayerExists when that distinction matters.

Performance Considerations

  • Use the async request natives for authoritative database reads.
  • Immediate legacy calls are safe in gameplay callbacks because they never execute network SQL; always handle their fail-closed sentinel.

Example Plugin

See the compiled API consumer fixture for signature coverage. It is a compile-time fixture, not a deployable gameplay example; the previously referenced examples/sakaSTATS_example.sp is not present.