repository·main·Indexed 20 days ago
https://github.com/roflmuffin/counterstrikesharpA .NET 8 scripting layer for Counter-Strike 2 that runs on top of a Metamod Source Plugin, enabling developers to create high-performance server-side plugins using C#. The framework provides APIs for console and chat commands, game event handlers, dependency injection via IPluginServiceCollection, semi-automatic configuration parsing with IPluginConfig, and localization using IStringLocalizer. It supports shared APIs, entity output hooks, and integration with Dapper and SQLite for data persistence.
Subclasses of GameEvent provide strongly typed properties corresponding to the event definition (e.g., long for time limits, CCSPlayerController for user IDs).
Important Lifecycle Warning:
GameEvent instances and their properties are transient. They cease to exist once the event listener function returns. Do not attempt to access event properties inside asynchronous tasks, timers, or functions like Server.NextFrame(). Instead, capture the required values into local variables before the listener function completes.
IPluginConfig interface within your plugin. This allows the framework to handle the loading and mapping of configuration data for your plugin automatically.Inter-plugin communication in CounterStrikeSharp is achieved through a Shared Plugin API (Capabilities). This pattern allows one plugin to expose functionality (an API) that other plugins can consume without direct project references.
To implement this, you follow a three-part pattern:
.Get().There are two types of capabilities:
PlayerCapability<T>: Provides functionality scoped to a specific player (e.g., a player's balance).PluginCapability<T>: Provides generic functionality scoped to the plugin instance (e.g., a global service).// 1. The Contract (in a shared library)
public interface IBalanceHandler
{
decimal Balance { get; }
public decimal Add(decimal amount);
public decimal Subtract(decimal amount);
}
// 2. The Declaration (in your plugin class)
public static PlayerCapability<IBalanceHandler> BalanceCapability { get; } = new("myplugin:balance");
// 3. The Registration (by the provider plugin)
Capabilities.RegisterPlayerCapability(BalanceCapability, player => new BalanceHandler(player));
// 4. The Usage (by the consumer plugin)
var balance = BalanceCapability.Get(player);
if (balance != null)
{
balance.Add(500);
}CounterStrikeSharp does not automatically enforce immunity checks for all actions. Plugin developers must manually implement immunity logic when a player targets another player.
Use the following AdminManager methods to handle immunity:
AdminManager.CanPlayerTarget: Check if a player is allowed to target another player based on their immunity levels.AdminManager.SetPlayerImmunity: Programmatically set a player's immunity value.CounterStrikeSharp utilizes a standard IServiceCollection to support dependency injection (DI) within plugins.
To register your own services (scoped or singleton), you must implement the IPluginServiceCollection<T> interface, where T is your plugin class.
Lifecycle and Discovery:
IPlugin and IPluginServiceCollection<T>.ConfigureServices implementation.Load method is called.public class TestPluginServiceCollection : IPluginServiceCollection<TestPlugin>
{
public void ConfigureServices(IServiceCollection serviceCollection)
{
serviceCollection.AddScoped<ExampleInjectedClass>();
}
}In CS2, player data is split into two distinct entities:
CCSPlayerController): Represents the player on the server. Use this to access persistent data like SteamIDs.CCSPlayerPawn): Represents the player's physical character in the game world. Use this to modify gameplay attributes like health.Every controller has a PlayerPawn property (which is a CHandle), and every pawn has a Controller property (also a CHandle). To access the underlying object from a handle, you must use the .Value property.
CounterStrikeSharp supports automatic hot reloading. If you replace the .dll file in your plugin folder while the server is running, the framework will automatically trigger a reload.
During a hot reload:
Unload function (if implemented).Load function with the hotReload parameter set to true.Note on Event Handlers: The framework automatically deregisters event handlers and listeners during unload. You can safely re-register them in your Load method without manually checking the hotReload flag, though you may use the flag to perform specific logic unique to a reload scenario.
When the NuGet resolver is enabled, CounterStrikeSharp searches for assemblies in the following order:
shared/ folder: Existing shared assemblies mechanism (manual).You can register commands that function both as console commands and chat commands.
To ensure a command is automatically registered as a chat command (accessible via ! or / prefixes), prefix the command name with css_. For example, a command named css_ping will be automatically available in chat as !ping or /ping.
This example demonstrates the pattern for registering these types of commands within CounterStrikeSharp.
To provide localized strings in your Counter-Strike Sharp plugin, follow these steps:
lang folder within your plugin directory. Add a .json file for every language you wish to support, naming the files after their locale codes (e.g., en.json, fr.json).lang folder is included in your plugin's output directory. You can automate this in your .csproj file.IStringLocalizer to your services.Localizer property provided directly on the plugin instance.IStringLocalizer instance to retrieve the appropriate string based on the current locale.To upgrade CounterStrikeSharp, download the latest release and copy the files to your server using the same method as the original installation.
CounterStrikeSharp is designed to prevent your configuration files from being overwritten during an upgrade.
Note on builds: If CounterStrikeSharp is already installed, you may use the non with-runtime build, but you are responsible for ensuring your server's .NET runtime is up-to-date.