mirror of
https://github.com/creazy231/cs2-css-flashlight.git
synced 2026-10-18 05:17:04 +02:00
🔦 Modernize flashlight for CSS/.NET 10
Bump to CounterStrikeSharp 1.0.371 and .NET 10, replace per-tick light spawns with a parented light_barn, add plugin config, real unit tests, and refresh CI plus docs. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Tobias Thiele
parent
081278a8ae
commit
a0ef6311ee
13 changed files with 847 additions and 434 deletions
|
|
@ -0,0 +1,148 @@
|
|||
# Flashlight Plugin Modernization Design
|
||||
|
||||
**Date:** 2026-07-21
|
||||
**Status:** Approved
|
||||
**Version target:** 0.1.0
|
||||
|
||||
## Goal
|
||||
|
||||
Modernize the CounterStrikeSharp flashlight plugin to the latest CSS/.NET stack, replace the per-tick spawn/teleport light path with a parented `light_barn` implementation, add `IPluginConfig` for admin tuning, improve testability, and update the README.
|
||||
|
||||
## Background
|
||||
|
||||
The current plugin (`Flashlight` v0.0.7) targets CounterStrikeSharp.API `1.0.363` on .NET 8. While the flashlight is on, `OnTick` creates a `light_omni2` and calls `DispatchSpawn` every server frame. That is the dominant performance problem. Existing tests only exercise inlined dictionary/bool logic and do not cover extractable plugin helpers. CI still installs .NET 7.
|
||||
|
||||
Latest CounterStrikeSharp.API is `1.0.371` and targets .NET 10. CS2Fixes demonstrates the preferred flashlight pattern: spawn `light_barn` once, set a flashlight lightcookie via entity keyvalues, parent to the player pawn attachment, and toggle enablement rather than teleporting every tick.
|
||||
|
||||
## Decisions
|
||||
|
||||
| Topic | Decision |
|
||||
| --- | --- |
|
||||
| Runtime | .NET 10 + CounterStrikeSharp.API 1.0.371 |
|
||||
| Light entity | `light_barn` (`CBarnLight`), parented once |
|
||||
| Position updates | Engine parenting; no per-tick teleport |
|
||||
| Config | `IPluginConfig<FlashlightConfig>` with JSON config |
|
||||
| Logging | Prefer `BasePlugin.Logger` |
|
||||
| README | Fully updated for new runtime, behavior, config, build/test |
|
||||
| Module version | 0.1.0 |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
FlashlightPlugin (BasePlugin, IPluginConfig)
|
||||
├── FlashlightConfig // JSON-backed settings + clamps
|
||||
├── PlayerFlashlightState // per-player flags + entity handle
|
||||
├── FlashlightService // create / parent / enable / destroy
|
||||
└── FlashlightLogic // pure helpers (toggle, cooldown, offsets)
|
||||
```
|
||||
|
||||
### Runtime flow
|
||||
|
||||
1. `OnConfigParsed` validates/clamps config.
|
||||
2. `Load` registers `OnTick` (Use-key edge + cooldown only), game event handlers, and command `css_fl_toggle`.
|
||||
3. When a player turns the light on:
|
||||
- Create `CBarnLight` via `Utilities.CreateEntityByName<CBarnLight>("light_barn")`.
|
||||
- Apply config (brightness, range, color, temperature, soft/skirt/size, cast shadows, direct light).
|
||||
- Compute initial origin: pawn origin + eye Z offset + forward * `ForwardDistance`.
|
||||
- `Teleport` once using `System.Numerics.Vector3` overloads (avoid legacy `Vector` allocs).
|
||||
- `DispatchSpawn(CEntityKeyValues)` with `lightcookie` = configured path (default flashlight vtex).
|
||||
- `AcceptInput("SetParent", pawn, …)` then `AcceptInput("SetParentAttachmentMaintainOffset", …, AttachmentName)`.
|
||||
- Set `Enabled = true`.
|
||||
4. When turned off: set `Enabled = false` and remove the entity (or disable and keep — prefer remove to avoid orphaned entities across pawn changes).
|
||||
5. Cleanup on death, team change, disconnect, and plugin unload.
|
||||
|
||||
### Why not keep tick teleport?
|
||||
|
||||
Parenting follows view/attachment with far less managed work and no entity churn. Tick work is limited to scanning connected humans for Use-button edges and cooldown expiry.
|
||||
|
||||
## Config surface
|
||||
|
||||
File written/loaded by CSS config system (standard plugin config JSON).
|
||||
|
||||
| Key | Type | Default | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `Enabled` | bool | `true` | Master switch |
|
||||
| `AllowUseKey` | bool | `true` | Toggle via Use (`E`) |
|
||||
| `ToggleCooldownSeconds` | float | `0.25` | Clamp ≥ 0 |
|
||||
| `Brightness` | float | `1.0` | |
|
||||
| `Range` | float | `2048` | Match CS2Fixes-style defaults |
|
||||
| `ColorR` / `ColorG` / `ColorB` | byte | `255` | White |
|
||||
| `ColorTemperature` | float | `6500` | |
|
||||
| `CastShadows` | bool | `true` | Maps to `CastShadows` int |
|
||||
| `SoftX` / `SoftY` | float | `1.0` | |
|
||||
| `Skirt` | float | `0.5` | |
|
||||
| `SkirtNear` | float | `1.0` | |
|
||||
| `SizeX` / `SizeY` / `SizeZ` | float | `45` / `45` / `0.03` | `SizeParams` |
|
||||
| `ForwardDistance` | float | `54` | Avoid AWP blocking beam |
|
||||
| `StandEyeOffsetZ` | float | `64` | |
|
||||
| `CrouchEyeOffsetZ` | float | `46` | Used at spawn time only |
|
||||
| `AttachmentName` | string | `axis_of_intent` | Parent attachment |
|
||||
| `LightCookie` | string | `materials/effects/lightcookies/flashlight.vtex` | |
|
||||
|
||||
Invalid values are clamped or rejected in `OnConfigParsed` with log warnings; plugin remains loadable when possible.
|
||||
|
||||
## Player state
|
||||
|
||||
Replace multiple `Dictionary<CCSPlayerController, …>` maps with one structure keyed by player slot (or controller), holding:
|
||||
|
||||
- `IsOn`
|
||||
- `CanToggle`
|
||||
- `Light` (`CBarnLight?`)
|
||||
|
||||
Crouch tracking for continuous Z updates is unnecessary once the light is parented; crouch offset is only applied at creation time. Optional: read duck state at spawn for initial Z only.
|
||||
|
||||
## Event / command behavior (unchanged UX)
|
||||
|
||||
- Use key toggles when `AllowUseKey` is true and cooldown allows.
|
||||
- `css_fl_toggle` remains client-only command alternative.
|
||||
- Flashlight turns off on death and spawn; entity cleaned on team change and disconnect.
|
||||
- Bots ignored.
|
||||
|
||||
## Testing strategy
|
||||
|
||||
Full CSS entity lifecycle cannot be unit-tested without a game server. Extract and test pure logic:
|
||||
|
||||
1. Toggle state transitions and cooldown gating.
|
||||
2. Config clamp helpers (range, cooldown, color channels).
|
||||
3. Initial position offset calculation (stand/crouch Z + forward distance given basis vectors).
|
||||
4. Enable/disable policy: when entity should be created vs destroyed.
|
||||
|
||||
Use xUnit on .NET 10. Keep Moq only if needed; prefer plain helpers over mocking CSS types.
|
||||
|
||||
## CI / packaging
|
||||
|
||||
- GitHub Actions: .NET 10 SDK, `dotnet restore`, `dotnet test`, release build on tags.
|
||||
- Remove stale .NET 7 setup.
|
||||
- Publish zip layout unchanged: `plugins/Flashlight/`.
|
||||
|
||||
## README updates
|
||||
|
||||
- Prerequisites: .NET 10, CSS 1.0.371+.
|
||||
- Behavior: parented `light_barn`, Use + command.
|
||||
- Config table with defaults.
|
||||
- Build / test instructions.
|
||||
- Changelog entry for 0.1.0 (API bump, performance rewrite, config, tests, CI).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Particle flashlight mode (CS2Fixes mode 2).
|
||||
- Admin permissions / VIP-only flashlight.
|
||||
- Client-side HUD indicators.
|
||||
- Migrating to CounterStrikeSharp 2.0 alpha.
|
||||
|
||||
## Risks / mitigations
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| Attachment name missing on some models | Configurable `AttachmentName`; fall back to parent-only if attachment input fails |
|
||||
| `CEntityKeyValues` lightcookie path differs | Use CS2Fixes-proven path; document override |
|
||||
| .NET 10 server prerequisite | Document clearly; MinimumApiVersion 371 |
|
||||
| Parenting breaks on pawn swap | Recreate light on spawn; destroy on death/team |
|
||||
|
||||
## Success criteria
|
||||
|
||||
- Builds against CounterStrikeSharp.API 1.0.371 on net10.0.
|
||||
- No entity create/spawn/teleport in the steady-state OnTick path.
|
||||
- Config file generated and honored.
|
||||
- Unit tests cover pure helpers and pass in CI.
|
||||
- README matches shipped behavior and versions.
|
||||
Loading…
Add table
Add a link
Reference in a new issue