# Docs

- Documentation: Install, build and write plugins
  - [Introduction](/docs): Source2Mod is a plugin platform for Counter-Strike 2 servers on Metamod:Source — plugins in C++ or SourcePawn, on one API.
  - [Installation](/docs/installation): Install Metamod:Source and Source2Mod on a Counter-Strike 2 server, and check that both are running.
  - Development
    - [Your first C++ plugin](/docs/development/first-plugin): A minimal Source2Mod plugin, from the plugin class to a built .smx on the server — with a command, a game event and logging.
    - [SourcePawn plugins](/docs/development/sourcepawn): The same API as C++, as a SourcePawn script — .smx files compiled with spcomp, loaded next to native plugins.
    - [Coming from CounterStrikeSharp](/docs/development/coming-from-counterstrikesharp): What a CounterStrikeSharp plugin turns into on Source2Mod — the same concepts side by side, a full plugin ported, and what you get for switching.
    - [C++ for C# developers](/docs/development/cpp-for-csharp-developers): The part of C++ a plugin actually needs, explained from C# — pointers and lifetimes, strings, lambdas, collections, casting, headers, and what a crash tells you.
    - [Plugin Lifecycle](/docs/development/plugin-lifecycle): When plugins are loaded and unloaded, what the listener callbacks tell you, what Source2Mod cleans up for you, and how hot reload works.
    - [Compatibility](/docs/development/compatibility): What a core update means for a plugin — the stable and raw tiers, interface revisions and the compat adapters, the plugin API version, the KHook check, and what s2m info shows.
    - [SDK & Building](/docs/development/building): Get the Source2Mod SDK, set up its dependencies and build a plugin into a .smx with CMake.
    - [SDK Dependencies](/docs/development/sdk-dependencies): Where the SDK gets s2sdk, how tools/deps.py sets it up, keeps KHook on the core's commit, and how the build finds it.
    - [Gamedata](/docs/development/gamedata): The gamedata folder, its JSON format, how files are merged, and how a plugin ships and reads signatures and offsets of its own.
    - [Contributing](/docs/development/contributing): Fork, branch off main, open a pull request against main — how to get a change into the core or the SDK.
  - Guides
    - [Permissions](/docs/guides/permissions): Admins, groups and permissions — permission-gated commands, permissions.json, granting at runtime from your own database, and which SteamID a player is checked under.
    - [Clients and targeting](/docs/guides/clients-and-targeting): Player state by slot — in game, bot, Steam-validated, SteamIDs in every form, latency, client cvars, kicking — and turning command text like @ct,
    - [Translations](/docs/guides/translations): Phrases per plugin in each player's language — phrase files, phrases pushed at runtime from JSON or code, formatting them for a player, and how a player's language is chosen.
    - [Menus](/docs/guides/menus): Menus with numbered options, paging, per-player instances and cleanup on unload — in the center panel (CenterHtmlMenu) or on the Panorama HUD (HudMenu).
    - [Scheduler](/docs/guides/scheduler): Run code on the next frame, after a delay or on a repeat — on the main thread, and cleaned up with your plugin.
    - [Sounds](/docs/guides/sounds): Play sound events for exactly the players you pick, stop or change them by guid, give players volume channels, and rewrite the game's own sounds.
    - [Transmit](/docs/guides/transmit): Decide per viewer which entities a player receives — hide players, personal entities, owner-following, and the raw CheckTransmit hook.
    - [Scripts](/docs/guides/scripts): Run cs_script (the game's server-side JavaScript) from a plugin — compiled assets, raw source, hot-reloaded files, inputs into a script and messages back out.
    - [Tracing](/docs/guides/tracing): Line and hull traces against the world and entities — what a player is looking at, line of sight, and whether a box fits.

    - **Services**
    - [HTTP](/docs/guides/http): Asynchronous HTTP requests through Steam's HTTP client — no curl, queued until Steam is up, callbacks on the main thread.
    - [JSON](/docs/guides/json): Parse and read JSON through Source2Mod, without vendoring a JSON library or agreeing on its ABI.
    - [SQL](/docs/guides/sql): Asynchronous SQL on MySQL or SQLite — one-off serverless queries with placeholders, or a persistent connection with queries and transactions.
    - [Client preferences](/docs/guides/client-preferences): Per-player settings that survive reconnects and map changes — registering a cookie, reading and writing it, knowing when a player's values are loaded.
    - [Files and KeyValues](/docs/guides/files-and-keyvalues): Reading and writing files and folders, KeyValues trees and the streaming KeyValues parser, and the text, time, regex and logging helpers in ISource2ModUtils.
    - [Maps, GeoIP and features](/docs/guides/maps-geoip-features): The current and next map, map changes, map history and map lists; where a player or an IP address is from; and checking for optional features before using them.
    - [Paths](/docs/guides/paths): Where Source2Mod keeps configs, gamedata, plugins and shared data — ask instead of hard-coding paths.

    - **Low level**
    - [Game Systems](/docs/guides/game-systems): Register your own IGameSystem with the engine — for precaching in BuildGameSessionManifest and the rest of the game system events.
    - [Memory and Modules](/docs/guides/memory-and-modules): Find functions and vtables in game binaries — pattern scanning, vtables by name, offset or base class, and address arithmetic.
    - [Crash Handler](/docs/guides/crash-handler): Minidumps processed on the server itself, symbolized plugin frames, a suspected culprit and a Discord report.
  - Resources
    - [FAQ](/docs/resources/faq): Licensing, platform support, how Source2Mod relates to Metamod:Source and CounterStrikeSharp, and what to do when something does not load.
    - [Links](/docs/resources/links): Repositories, downloads, community and machine-readable versions of these docs.
    - [Credits](/docs/resources/credits): The people and projects Source2Mod is built on.
- API: Interfaces, types and macros of the SDK
  - [API reference](/docs/core-api): Every interface, type and macro a plugin gets from the Source2Mod SDK, generated from the SDK headers.

  - **Plugin**
  - [ISource2ModPlugin](/docs/core-api/ISource2ModPlugin): Plugin interface and integration layer for Source2Mod.
  - [ISource2ModApi](/docs/core-api/ISource2ModApi): Main entry point for Source2Mod API.
  - [ISource2ModTypes](/docs/core-api/ISource2ModTypes): Types shared by every source2mod callback.
  - [ISource2ModNatives](/docs/core-api/ISource2ModNatives): Natives for SourcePawn plugins, from a native (C++) plugin.

  - **Gameplay**
  - [ISource2ModCommands](/docs/core-api/ISource2ModCommands): Command and chat handling interface for Source2Mod.
  - [ISource2ModPermissions](/docs/core-api/ISource2ModPermissions): Admins, groups and permissions, and the commands they gate.
  - [ISource2ModConVars](/docs/core-api/ISource2ModConVars): Interface for managing and interacting with console variables (ConVars).
  - [ISource2ModEvents](/docs/core-api/ISource2ModEvents): Interface for registering and handling game events.
  - [ISource2ModEntities](/docs/core-api/ISource2ModEntities): Interface for entity lookup and Source2 Entity I/O system.
  - [ISource2ModClients](/docs/core-api/ISource2ModClients): Player helpers the controller classes do not have: SteamIDs in every form, connection details, client cvars, kicking with a message.
  - [ISource2ModTargeting](/docs/core-api/ISource2ModTargeting): Command text to players: "@ct", "#12", "STEAM_1:0:123", "bob".
  - [ISource2ModMenus](/docs/core-api/ISource2ModMenus): Interface and base implementation for menu system.
  - [ISource2ModCustomHud](/docs/core-api/ISource2ModCustomHud): Interface for the panorama custom HUD layouts.
  - [ISource2ModTranslations](/docs/core-api/ISource2ModTranslations): Translated text: phrases per plugin, each player's language.
  - [ISource2ModNetworkMessages](/docs/core-api/ISource2ModNetworkMessages): Interface for manipulating and sending Source2 network (protobuf) messages.
  - [ISource2ModSounds](/docs/core-api/ISource2ModSounds): Interface for playing, stopping and rewriting sound events.
  - [ISource2ModTransmit](/docs/core-api/ISource2ModTransmit): Interface for deciding which entities each player receives.
  - [ISource2ModTrace](/docs/core-api/ISource2ModTrace): Interface and utilities for ray tracing and collision queries.
  - [ISource2ModScheduler](/docs/core-api/ISource2ModScheduler): Interface for scheduling tasks and managing timers.
  - [ISource2ModScripts](/docs/core-api/ISource2ModScripts): Interface for running cs_script (the game's server-side JavaScript).
  - [ISource2ModMaps](/docs/core-api/ISource2ModMaps): The current map, the next one, map changes and map lists.
  - [ISource2ModFeatures](/docs/core-api/ISource2ModFeatures): Asking whether something optional is there before using it.

  - **Engine**
  - [ISource2ModHooks](/docs/core-api/ISource2ModHooks): One way to hook anything, the same from C++ and SourcePawn:
  - [ISource2ModHookContexts](/docs/core-api/ISource2ModHookContexts): What the handlers of the typed hook points get (ISource2ModHooks.h).
  - [ISource2ModFunctions](/docs/core-api/ISource2ModFunctions)
  - [ISource2ModAddresses](/docs/core-api/ISource2ModAddresses): Resolved engine-function accessors for Source2Mod.
  - [ISource2ModKHook](/docs/core-api/ISource2ModKHook): KHook's virtual hook, with the one thing Source2Mod needs to see that KHook keeps protected: the slot the hook is on.
  - [ISource2ModGameConfig](/docs/core-api/ISource2ModGameConfig): Interface for accessing game configuration (gamedata).
  - [ISource2ModGameSystems](/docs/core-api/ISource2ModGameSystems): Interface for registering game systems with the engine.
  - [ISource2ModMemory](/docs/core-api/ISource2ModMemory): Source2Mod-facing memory address wrapper (mirrors DynLibUtils::CMemory).
  - [ISource2ModModule](/docs/core-api/ISource2ModModule): Source2Mod-facing module interface (mirrors DynLibUtils::CModule).
  - [ISource2ModSchemaMethods](/docs/core-api/ISource2ModSchemaMethods): The SDK's schema helpers, served by the core.
  - [Schema](/docs/core-api/Schema): Schema system utilities for accessing and modifying entity fields.
  - [consts](/docs/core-api/consts)

  - **Services**
  - [ISource2ModHTTP](/docs/core-api/ISource2ModHTTP): Interface for HTTP requests.
  - [ISource2ModJSON](/docs/core-api/ISource2ModJSON): Reading JSON without the plugin owning a JSON library.
  - [ISource2ModSQL](/docs/core-api/ISource2ModSQL): Interfaces and utilities for SQL database access: MySQL and SQLite behind one interface.
  - [ISource2ModCookies](/docs/core-api/ISource2ModCookies): Client preferences: per-player settings that outlive the session.
  - [ISource2ModGeoIP](/docs/core-api/ISource2ModGeoIP): Country, city and the rest of where an IP address is.
  - [ISource2ModFiles](/docs/core-api/ISource2ModFiles): Files, directories, KeyValues (Valve's KV1 text) and a streaming KeyValues reader.
  - [ISource2ModPaths](/docs/core-api/ISource2ModPaths): Where Source2Mod keeps things on disk.
  - [ISource2ModUtils](/docs/core-api/ISource2ModUtils): Text, time, regex, profiling and file logging helpers.
  - Utilities
    - [utils/plat.h](/docs/core-api/utils/Plat): Platform abstraction utilities and module helpers.
    - [utils/virtual.h](/docs/core-api/utils/Virtual): Virtual method table (VMT) utilities for calling virtual functions.
- Schema: Engine structures; the schema classes are in the game data viewer
  - [Schema](/docs/schema): Entity classes, enums and engine structures, generated from the game's own schema and the SDK headers.

  - **Structures**
  - [AttackerInfo_t](/docs/schema/Attackerinfo): Engine structures the SDK declares by hand: AttackerInfo_t.
  - [Entity I/O](/docs/schema/Entityio): Entity I/O system (inputs/outputs) for Source2Mod.
  - [CMoveData](/docs/schema/Movedata): Engine structures the SDK declares by hand: SubtickMove, TouchList_t, CMoveDataBase, CMoveData.
  - [Navigation mesh](/docs/schema/Navarea): Engine structures the SDK declares by hand: CCSNavArea.
  - [Net message types](/docs/schema/Netmessages): Network message wrappers for Source2 networking system.
  - [Recipient filters](/docs/schema/Recipientfilter): Engine structures the SDK declares by hand: CRecipientFilter, CSingleRecipientFilter.
  - [CTakeDamageInfo](/docs/schema/Takedamageinfo): Engine structures the SDK declares by hand: CTakeDamageInfo.
  - [CTakeDamageResult](/docs/schema/Takedamageresult): Engine structures the SDK declares by hand: CTakeDamageResult.
- SourcePawn: The script API, natives, entity handles and function hooks
  - [SourcePawn](/docs/sourcepawn): The script API — how the C++ interfaces, schema classes and hooks look from a .sp, and where scripts work differently.
  - [Coming from SourceMod](/docs/sourcepawn/from-sourcemod): For SourceMod plugin authors — what carries over unchanged, what Source2Mod does differently, and the Source2Mod calls for common SourceMod ones.
  - [Entity handles](/docs/sourcepawn/entity-handles): Entities in scripts are entity handles, not indexes — NULL_ENTITY, IsValid, why an entity is a negative number, converting to and from indexes and slots, and what happens to a handle whose entity is gone.
  - [Natives and forwards](/docs/sourcepawn/natives-and-forwards): Sharing code between plugins — natives a C++ plugin or a script provides, libraries and optional natives, global and private forwards, calling functions of other plugins, and a script's natives and forwards from C++.
  - [Function hooks](/docs/sourcepawn/raw-hooks): Source2ModHooks.HookFunction — hooking any game function from a script through a Source2ModFunction; where the function comes from, parameter types, this, pre and post, actions and return values, and when a hook point or a listener is the better choice.
- ConVars & Commands: Console variables, console and chat commands
  - [ConVars & Commands](/docs/convars-commands): Console and chat commands, listening in on other commands, and console variables — what Source2Mod gives you and where each piece lives.
  - [Commands](/docs/convars-commands/commands): Registering console and chat commands, reading their arguments and caller, and taking them down again.
  - [Command Listeners](/docs/convars-commands/command-listeners): Running code before or after commands the game, the engine or other plugins own — and blocking them.
  - [ConVars](/docs/convars-commands/convars): Declaring your own console variables, reading and writing the game's, and reacting when any of them changes.
  - [Replication](/docs/convars-commands/replication): Sending one player a ConVar value of their own with ReplicateConVar, keeping it there, and reading ConVars from the client.
- Entities: Finding, creating and changing entities
  - [Entities](/docs/entities): How CS2 models players and other entities, and how the SDK exposes them as typed schema classes you read, write and call helpers on.
  - [Finding Entities](/docs/entities/finding-entities): Getting a player controller from a slot, userid, SteamID or pawn, and finding other entities by index, classname, name or crosshair.
  - [Schema Fields](/docs/entities/schema-fields): Reading and writing entity fields, when a change reaches clients on its own and when you call NetworkStateChanged, embedded objects, pointers, arrays and vectors, and extending the classes.
  - [Creating Entities](/docs/entities/creating-entities): Creating and spawning entities with New and DispatchSpawn, keyvalues, moving and modelling them, removing them, particles and live grenades.
  - [Players](/docs/entities/players): The everyday player helpers — respawning, teams, killing and damaging, items and weapons, attributes, messages, kicking — and the HookChain argument they take.
  - [Entity I/O](/docs/entities/entity-io): Sending inputs to entities, queueing delayed ones, and listening to — or blocking — outputs and inputs, for one entity, a designer name or every entity.
  - [Damage](/docs/entities/damage): CTakeDamageInfo and CTakeDamageResult, hooking CBaseEntity::TakeDamageOld to change or block damage, and dealing damage yourself.
- Protobuf: Network and user messages
  - [Net Messages](/docs/protobuf): What network and user messages are in Source 2, how they are identified by id and by name, and how Source2Mod lets you send and hook them.
  - [Sending Messages](/docs/protobuf/sending): Allocating a net message by id or name, filling its protobuf fields, and sending it to one player, a set of players or everyone.
  - [Hooking Messages](/docs/protobuf/hooking): Reading, changing, redirecting and blocking outgoing and incoming net messages with Source2Mod's hooks, and the raw PostEventAbstract alternative.
  - [Common Messages](/docs/protobuf/common-messages): Useful CS2 user and net messages — their ids, protobuf class names and fields, checked against the game's .proto files.
- Events: Game events and Source2Mod listeners
  - [Events](/docs/events): The kinds of events a plugin can react to — game events, Source2Mod listener callbacks, engine hooks, entity outputs and net messages — and where each one is documented.
  - [Game Events](/docs/events/game-events): Hooking game events before and after the engine, reading and changing their fields, keeping them from clients, cancelling them, and firing your own.
  - [Listeners](/docs/events/listeners): The ISource2ModListener callbacks — plugin lifecycle, map start and end, Steam authorisation, permissions, interface queries — what each one reports and exactly when it fires.
  - [Event Reference](/docs/events/event-reference): The CS2 game events plugins use most, with their fields and types as the game defines them.
- Panorama: Custom HUD layouts and menus on screen
  - [Panorama HUD](/docs/panorama): Server-driven Panorama layouts with custom_hud_layout — what the server controls, what the client needs, and how a click gets back to your plugin.
  - [HUD Menus, Texts and Prompts](/docs/panorama/hud): Menus, on-screen text and HUD elements drawn by Panorama through the CustomhudManager_s2t plugin — HudMenu, ICustomhudManager, the reference layouts and the addon that ships them.
  - [ICustomhudManager](/docs/panorama/hud-api): On-screen text, prompts, toasts, announcements, countdowns, status chips, progress bars, hit feedback, an event feed and overlays on the Panorama HUD.
  - [Layouts](/docs/panorama/layouts): Creating a custom_hud_layout with CCSCustomHudLayout, global and per-player state, toggling CSS classes, setting dialog variables and capturing the mouse.
  - [Click Callbacks](/docs/panorama/click-callbacks): Getting a callback when a player clicks a button in a custom HUD layout — HookClick, the panel id, and the ISource2ModCustomHud registry behind it.
  - [Authoring Layouts](/docs/panorama/authoring): Writing the layout and stylesheet a custom_hud_layout loads — the narrow XML subset it accepts, Panorama CSS versus web CSS, compiling, and the state of shipping layouts to players.
- Hooks: Hook points, function hooks, addresses and gamedata
  - [Hooking](/docs/hooks): ISource2ModHooks — one call to hook a game function, an engine callback or any function by gamedata, signature or vtable slot, the same from C++ and SourcePawn.
  - [Hook Points](/docs/hooks/game-hooks): The typed points of ISource2ModHooks — the game functions plugins hook most and the engine callbacks, each with its own context, detoured once by the core from its gamedata.
  - [Virtual Functions](/docs/hooks/virtual-hooks): Hooking a vtable slot with ISource2ModHooks — on one object, on every object of a class, or on an engine interface — and the vtable caveats that come with it.
  - [Function Hooks](/docs/hooks/function-hooks): HookPoint::Function — hooking any game function by gamedata entry, address, signature, symbol or vtable slot through ISource2ModFunctions; SourceMod's DHooks.
  - [Writing Handlers](/docs/hooks/handlers): Handler signatures, contexts, HookReturn and the three actions, calling the original, changing arguments and return values, ids, owners and recursion.

  - **Engine functions**
  - [Calling Game Functions](/docs/hooks/calling-functions): Functions described once in gamedata and called by name from C++ and SourcePawn — Source2Mod's SDKCall.
  - [Addresses](/docs/hooks/addresses): ISource2ModAddresses and the ADDR_* macros — calling and hooking the engine functions Source2Mod resolves, SOURCE2MOD_ORIGINAL, and HookChain on schema helpers.
  - [Gamedata for Hooks](/docs/hooks/gamedata): Signatures and vtable offsets from a hooking point of view — writing them, Windows vs Linux differences, and verifying them.

  - **Advanced**
  - [Raw KHook](/docs/hooks/raw-khook): KHOOK_VIRTUAL, KHOOK_MEMBER and KHOOK_FUNCTION from ISource2ModKHook.h, KHook handlers, KHOOK_INIT / KHOOK_DESTRUCT, KHook objects and the C-style API underneath — for C++ hooks ISource2ModHooks does not cover.