CS2DrawShared 1.0.0

CS2Draw

CS2Draw is a centralized world-space shape rendering service for CS2 plugins using CParticleSystems. CS2Draw handles the particles, lifetime, and cleanup. Particles Must be created using an addon. For help feel free to reach out to me on discord or chekc the examples.

This package was built for use on EdgeGamers servers and is shared as a demonstration of what's possible with CS2 particles. It isn't intended for wide use, but if it gains traction I'll look into expanding it — including CEnvBeam support and growing it into a more fully-featured drawing utility.

CS2Draw.Shared

The shared contracts library for CS2Draw. This is the only project your plugin needs to reference.

Setup

In your plugin, declare the capability reference using the same key CS2Draw registers under:

using CS2Draw.Contracts;
using CounterStrikeSharp.API.Core.Capabilities;

public sealed class ConsumerPlugin : BasePlugin
{
    private static readonly PluginCapability<IDrawService> DrawCapability = new("cs2draw:service");

    public override void OnAllPluginsLoaded(bool hotReload)
    {
        var draw = DrawCapability.Get();
        if (draw == null)
        {
            Console.WriteLine("[MyPlugin] CS2Draw not loaded.");
            return;
        }

        // you're ready to draw
    }
}

CS2Draw must be loaded before your plugin calls .Get(). Use OnAllPluginsLoaded not Load.

Drawing Built-in Shapes

Every draw call follows the same pattern:

service.Shape(origin, ...geometry params...)
    .ChainOptions()
    .Draw();

.Draw() returns an IDrawHandle. It is safe to discard if you don't need early cancellation.

Circle

draw.Circle(origin, radius);

Shape-specific options

Examples

// minimal
draw.Circle(origin, 100f).Draw();

// fully configured
draw.Circle(origin, 100f)
    .WithSegments(64)
    .Color(Color.Red)
    .WithLifetime(10f)
    .Particles(30)
    .Draw();

// permanent until cancelled
var handle = draw.Circle(origin, 100f)
    .Color(Color.White)
    .Infinite()
    .Draw();

handle.Cancel(); // remove it early

Rectangle

draw.Rectangle(origin, width, height);

Examples

// minimal
draw.Rectangle(origin, 200f, 100f).Draw();

// fully configured
draw.Rectangle(origin, 200f, 100f)
    .Color(Color.Blue)
    .WithLifetime(5f)
    .Draw();

Base Options

All shapes share these options. They can be chained in any order.

Handles

Every .Draw() call returns an IDrawHandle. You can discard it for fire-and-forget, or hold it for control.

public interface IDrawHandle
{
    Guid Id      { get; }
    bool IsAlive { get; }
    void Cancel();
}

Examples

// fire and forget
draw.Circle(origin, 50f).Color(Color.Green).Draw();

// hold and cancel
var handle = draw.Rectangle(origin, 200f, 100f)
    .Infinite()
    .Draw();

// later...
if (handle.IsAlive)
    handle.Cancel();

Bulk Cancellation

Cancel all active drawings at once:

draw.CancelAll();

Useful for round end cleanup, player disconnect, or any event where all visuals should be cleared.

Custom Shapes

If you need a shape CS2Draw doesn't provide, you can register your own. CS2Draw still owns the spawn sequence — you only define the control points.

Step 1 — Add your effect name to cs2draw.json

{
  "custom": {
    "my_star": "particles/myaddon/star.vpcf"
  }
}

Step 2 — Implement IShapeSetup

using CS2Draw.Contracts;

public sealed class StarSetup : IShapeSetup
{
    private readonly int   _points;
    private readonly float _outerRadius;
    private readonly float _innerRadius;

    public string EffectKey => "my_star";

    public StarSetup(int points, float outerRadius, float innerRadius)
    {
        _points      = points;
        _outerRadius = outerRadius;
        _innerRadius = innerRadius;
    }

    public void Configure(IParticleConfigurator cp)
    {
        // set whatever control points your particle file expects
        cp.SetCP(4, _points, 0, 0);
        cp.SetCP(5, _outerRadius, 0, 0);
        cp.SetCP(6, _innerRadius, 0, 0);
    }
}

Step 3 — Register and draw

public override void Load(bool hotReload)
{
    var draw = DrawCapability.Get();

    // register once
    draw.RegisterShape(new StarSetup(5, 100f, 50f));

    // draw it — gets the full builder chain
    draw.Custom(origin, new StarSetup(5, 100f, 50f))
        .Color(Color.Yellow)
        .WithLifetime(8f)
        .Draw();
}

Configure() is called after the particle is created and teleported, before DispatchSpawn and Start. You only set control points — CS2Draw handles everything else.

Color and Control Points

CS2 particles apply tint via a specific control point (TintCP) on the CParticleSystem. By default CS2Draw applies color to CP 1. If your particle file expects the tint on a different CP, pass it explicitly:

draw.Circle(origin, 100f)
    .Color(Color.Red, controlPoint: 3)
    .Draw();

If you don't call .Color() at all, no tint is applied and the particle renders with its baked-in color. If particles are alwasy rendering with a particular color its likely that you've not got your colors setup right. Check the example or feel free to reach out to me on discord.