Skip to content

AGENTS.md

Latest commit

 

History

History
155 lines (121 loc) · 6.32 KB

AGENTS.md

File metadata and controls

155 lines (121 loc) · 6.32 KB
Raw

Agent Guide

SourceMod plugin collection for the saka-gg Team Fortress 2 Dodgeball ecosystem. This repo is both a source archive and a build/release repo that produces deployable .smx bundles.

For full project orientation, read README.md. This file is the short version for AI agents and contributors who need to act, not browse.

Repo Layout

  • sakaBASE/, sakaCOLORS/, sakaDONATE/, sakaMAPVOTE/, sakaNER/, sakaSESSION/, sakaSOLO/, sakaSTATS/, sakaGameDescription/, sakaMapDelete/ — plugin source trees
  • include/ — project-specific and third-party non-SourceMod headers
  • vendor/sourcemod-current/include/ — vendored official SourceMod headers, kept separate on purpose
  • scripts/ — build and packaging scripts
  • .github/workflows/ — CI and release automation
  • spcomp — vendored SourcePawn compiler (1.13.0.7246, macOS arm64)

Typical plugin layout:

  • PLUGIN/scripting/*.sp — plugin entrypoint
  • PLUGIN/scripting/PLUGIN/*.inc — local split modules (when modularized)
  • PLUGIN/translations/*.txt — phrase files
  • PLUGIN/configs/*.cfg, PLUGIN/cfg/*.cfg — runtime configs

Build

Full repo:

./scripts/build-all.sh

Compiled .smx files land in .build/plugins/.

Package a release:

./scripts/package-release.sh v2026.04.30

Manual single-plugin compile must use this include order:

  1. matching official SourceMod 1.13.0-git7246 headers
  2. repo include/
  3. plugin-local PLUGIN/scripting

Cross-Plugin Contracts

Some plugins expose libraries other plugins compile against. Before changing any public API, check CROSS_PLUGIN_CONTRACTS.md and the relevant include/saka*.inc.

Provider summary:

  • sakaDONATE → sakaDONATE library, SD_* natives
  • sakaSOLO → sakaSOLO library, SakaSolo_* natives
  • sakaSTATS (seasonal) → sakaSTATS library, SakaStats_* natives
  • sakaMAPVOTE → preserves the mapchooser library contract
  • sakaWeightedVoting → shared include used by sakaMAPVOTE and sakaNER

Rules For Agents

If you are editing this repo, follow these to avoid breaking things:

  • treat include/ as project-specific and non-SourceMod support headers only
  • do not put official SourceMod headers back into include/
  • do not assume every plugin is standalone — check whether it exposes a library or depends on another saka include first
  • before changing a plugin API, inspect its public include file in include/
  • before changing build behavior, inspect scripts/build-all.sh and the GitHub workflow
  • for split plugins, prefer editing the focused local module rather than adding more top-level monolith code

When exploring a plugin, look for:

  • public Plugin myinfo — plugin metadata and version string
  • AskPluginLoad2 — registers libraries and natives for cross-plugin use
  • local #include "PLUGIN/*.inc" — module boundaries in split plugins

Coding Style

Conventions used across the codebase. Follow these in new code; minor drift exists in older files and gets cleaned up in dedicated passes.

  • Globals: g_<type><Name> Hungarian prefix. g_b for bool, g_i for int, g_f for float, g_h for Handle, g_cv for ConVar, g_s for char[] arrays. Example: g_bRoundStarted, g_cvNERVotingTimeout, g_iLastDeadTeam.
  • Constants and #define: UPPER_SNAKE_CASE. Example: SAKA_MAX_MESSAGE_LENGTH, STATS_MAX_NAME_LENGTH.
  • Public natives (cross-plugin API surface):
    • New providers: <Plugin>_<Function> — e.g. SakaSolo_PlayerIsInSolo, SakaStats_GetPlayerStat.
    • sakaDONATE's SD_* short prefix is grandfathered for compatibility; do not introduce new SD_*-style short prefixes elsewhere.
  • Commands: lowercase sm_<verb> — e.g. sm_solo, sm_rtv.
  • ConVars: lowercase <plugin>_<feature> — e.g. sakasolo_debug, sakaner_voting_timeout. sakaBASE's legacy sakambrs_* / sakafov_* / sakarobot_* are slated for a follow-up consolidation pass and should not be expanded.
  • Pragmas: every plugin starts with #pragma semicolon 1 and #pragma newdecls required.
  • Logging: use the Saka_LogInfo / Saka_LogError helpers from <sakaLogging> rather than raw LogMessage / LogError. Set SAKA_LOG_DEFAULT_COMPONENT and SAKA_LOG_INTERCEPT_LEGACY before including.
  • Shared helpers: prefer <sakaClientValidation>, <sakaConstants>, <sakaColors>, <sakaMessageFormatting> over redefining the same helpers per plugin.

Good Entry Points

Plugin Notes

  • sakaGameDescription requires the SteamWorks extension and sets the server browser Game field to saka Dodgeball. Extension binaries are not bundled.

  • sakaMapDelete preserves sm_mapdeleter_regex and the console-only sm_deletemaps command. Loading it never initiates cleanup.

  • sakaMAPVOTE is a compatibility-preserving consolidation of older map vote plugins.

  • sakaBASE is a compatibility-preserving consolidation of several smaller gameplay/QoL plugins.

  • sakaSTATS runs the season system by default; set enableSeasonSystem=0 in sakaSTATS/configs/sakastats.cfg to disable it at runtime. The retired sakaSTATS_w-o_seasons.sp build is no longer shipped — see sakaSTATS/README.md for the upgrade path.

  • sakaCOLORS and sakaSTATS are good examples of the split-module style.

Related Docs