SwiftlyS2-Toolkit

# SwiftlyS2-Toolkit

This is a general-purpose toolkit entry for **SwiftlyS2 C# / .NET plugin development**.

Its goal is not to bind itself to any specific workspace, but to provide a **publicly reusable** workflow, rule set, template collection, and reference navigation system.

## Public reference allowlist

The public docs, prompts, agents, and templates in this toolkit should, by default, reference only the following public sources:

1. SwiftlyS2 official documentation: `https://swiftlys2.net/docs/`
2. sw2-mdwiki: `https://github.com/himenekocn/sw2-mdwiki`
3. SwiftlyS2 official repository: `https://github.com/swiftly-solution/swiftlys2`

If the current workspace has workspace-specific mappings, local reference repositories, historical reference projects, or special rules, that information **may only be recorded in**:

- `./copilot-instructions.md`
- `./knowledge-base.md`

- If the workspace includes a local `sw2-mdwiki` checkout, it is strongly recommended to use it as a local reference repository to improve agent retrieval efficiency and accuracy.

## What this skill should produce

When using this skill, the preferred output should be one of the following:

- An implementation plan for a new plugin or new module
- A direct modification plan for an existing plugin
- A gap analysis for historical behavior alignment
- An audit of lifecycle, thread safety, high-frequency hooks, Schema, or Protobuf usage
- A method-level implementation plan

## When to use it

Use this skill when the task involves:

- SwiftlyS2 plugin development
- `Commands`, `Events`, `Hooks`, `Modules`, `Workers`, `Services`
- High-frequency runtime loops and state synchronization
- `Schema`, `NetMessages`, `Protobuf`, or `IPlayer` lifecycle handling
- High-frequency hooks, async workers, main-thread-sensitive APIs, or entity lifecycle handling
- Plugin migration, behavior alignment, structural audits, or method-level planning

## When not to use it

- Regular C# work unrelated to SwiftlyS2
- Pure frontend UI work
- A one-off tiny change that does not require architecture, lifecycle, or thread-boundary judgment

## Toolkit structure

### Entry documents

- `./SKILL.md`
- `./README.md`

### Reference documents

- `./references/swiftlys2-plugin-playbook.md`
- `./references/swiftlys2-kb-index.md`
- `./references/swiftlys2-official-docs-map.md`
- `./references/swiftlys2-asset-inventory.md`

### Templates and checklists

- `./assets/README.md`
- `./assets/development/getting-started/partial-plugin-template.cs.md`
- `./assets/development/using-attributes/attribute-registration-checklist.md`
- `./assets/development/swiftly-core/core-service-entrypoints.md`
- `./assets/development/commands/command-attribute-template.cs.md`
- `./assets/development/commands/command-service-template.cs.md`
- `./assets/development/commands/client-command-hook-template.cs.md`
- `./assets/development/menus/menu-template.cs.md`
- `./assets/development/netmessages/protobuf-handler-template.cs.md`
- `./assets/development/native-functions-and-hooks/hook-handler-template.cs.md`
- `./assets/development/configuration/config-hot-reload-template.cs.md`
- `./assets/development/convars/convar-template.cs.md`
- `./assets/development/core-events/lifecycle-checklist.md`
- `./assets/development/core-events/precache-resource-template.cs.md`
- `./assets/development/game-events/game-events-usage-notes.md`
- `./assets/development/shared-api/shared-interface-template.cs.md`
- `./assets/development/thread-safety/thread-sensitivity-checklist.md`
- `./assets/development/profiler/hotpath-gc-checklist.md`
- `./assets/development/entity/schema-write-checklist.md`
- `./assets/development/scheduler/scheduler-vs-worker-guide.md`
- `./assets/guides/dependency-injection/di-service-plugin-template.cs.md`
- `./assets/guides/dependency-injection/service-template.cs.md`
- `./assets/patterns/background-workers/worker-template.cs.md`
- `./assets/patterns/per-player-state/player-state-management-guide.md`
- `./assets/patterns/async-patterns/async-safety-guide.md`
- `./assets/patterns/service-factory/service-factory-template.cs.md`
- `./assets/workflows/planning/method-level-plan-template.md`
- `./assets/workflows/audit/audit-report-template.md`

### Paired prompts

- `../../prompts/SwiftlyS2-Toolkit-Plan.prompt.md`
- `../../prompts/SwiftlyS2-Toolkit-Audit.prompt.md`
- `../../prompts/SwiftlyS2-Toolkit-Edit.prompt.md`

## Task routing

### If the task is mainly “should we do this / how should this be broken down”

Open these first:

- `./references/swiftlys2-plugin-playbook.md`
- `../../prompts/SwiftlyS2-Toolkit-Plan.prompt.md`

### If the task is mainly “systematically find risks first”

Open these first:

- `./references/swiftlys2-plugin-playbook.md`
- `../../prompts/SwiftlyS2-Toolkit-Audit.prompt.md`
- `./assets/workflows/audit/audit-report-template.md`

### If the task is mainly “edit code directly”

Open these first:

- `../../prompts/SwiftlyS2-Toolkit-Edit.prompt.md`
- `./assets/README.md`
- The template or checklist closest to the relevant subsystem

### If the task is mainly “find reference entry points”

Open these first:

- `./references/swiftlys2-kb-index.md`
- `./references/swiftlys2-official-docs-map.md`
- `./README.md`

## Architecture categories

### 1. Modular gameplay plugins

Suitable when:

- A single plugin contains a large amount of gameplay logic
- It needs `Commands + Events + Hooks + Modules + Workers + Models`
- It needs per-player runtime state, state synchronization, persistence, and multi-module coordination

### 2. DI / service-oriented plugins

Suitable when:

- The plugin is medium or large in size
- It needs clear interface / implementation / install / uninstall lifecycles
- It needs `ServiceCollection`, dependency injection, self-owned listeners, and command registration inside services

### 3. Hybrid architecture

Suitable when:

- The plugin is mainly gameplay-module-oriented, but some subsystems fit services better
- The modular core needs to be augmented with a small number of installable and uninstallable services

## Core operating rules

### 1. Historical implementations are only temporary experience sources

- If the task requires behavior alignment, historical implementations may be referenced.
- But historical implementations must not become long-term dependencies of the future solution.

### 2. Silent drift is forbidden

- If the user explicitly requires historical alignment, legacy compatibility, or player-visible consistency, every difference must be explicitly explained or explicitly fixed.

### 3. Lifecycle closure is a hard requirement

At minimum, explicitly check:

- map load / unload
- player connect / disconnect

### 4. Main-thread / async boundaries must be explicit

According to the official SwiftlyS2 `Thread Safety` documentation, the following operations should be treated as main-thread-sensitive by default:

- Many message and entity operations on `IPlayer`
- `ICommandContext.Reply`
- `IGameEventService.Fire*`
- `IEngineService.ExecuteCommand*`
- `CEntityInstance.AcceptInput / DispatchSpawn / Despawn`
- `CBaseModelEntity.SetModel / SetBodygroupByName`
- `CCSPlayerController.Respawn`
- `CPlayer_ItemServices.*`
- `CPlayer_WeaponServices.*`

When in an async context, prefer the corresponding `Async` APIs instead of mechanically wrapping everything in `NextTick` / `NextWorldUpdate`.

### 5. For high-frequency hooks, prioritize safety before speed

- Filter irrelevant objects as early as possible
- Control allocations and logging
- Avoid JSON, IO, blocking waits, and unbounded lock contention
- Prefer a producer / consumer separation mindset
- Keep a 64-tick frame-budget mindset

### 6. `IPlayer` lifecycle has extremely high priority

- `IPlayer` objects may be destroyed after disconnect
- Delayed tasks, async callbacks, menu callbacks, and background worker writebacks must revalidate or reacquire the object
- Do not assume bots / fakeclients can reuse the same identity-key strategy as real players
- When bots and real players are stored together, prefer `SessionId` as the runtime lookup key
- Bot `SteamID` values are not reliable and should, in practice, be treated as fixed `0`; do not use them as stable bot lookup keys

### 7. For long-lived entity tracking, think in handles first

- Across frames, delays, or maps, do not hold raw entity wrappers long-term
- Prefer storing entities as `CHandle<T>` and validate before access

### 8. `Span` / `stackalloc` / `ref` should only be used when there is evidence

- Suitable for synchronous hot paths and small data transfers
- Must not cross `await`
- Must not cross threads
- Must not be captured by closures or escape the synchronous stack frame
- Do not introduce dangling references or shared-buffer risks just to avoid one copy

### 9. Treat menu callbacks as async contexts

- Review `Click`, `ValueChanged`, and `Submenu` callbacks as async-context code by default
- Prefer `BindingText` for dynamic display text

### 10. JSON and synchronous blocking are high-risk by default

- `.Wait()`, `.Result`, synchronous joins, and blocking IO should be treated as high-risk by default
- JSON serialization / deserialization should, by default, run in the background rather than inside hooks, runtime loops, menu callbacks, or main-thread periodic tasks

## Recommended reading order

### For planning

1. `./SKILL.md`
2. `./references/swiftlys2-plugin-playbook.md`
3. `../../prompts/SwiftlyS2-Toolkit-Plan.prompt.md`
4. `./assets/workflows/planning/method-level-plan-template.md`

### For auditing

1. `./SKILL.md`
2. `./references/swiftlys2-kb-index.md`
3. `../../prompts/SwiftlyS2-Toolkit-Audit.prompt.md`
4. `./assets/workflows/audit/audit-report-template.md`

### For direct code edits

1. `./SKILL.md`
2. `../../prompts/SwiftlyS2-Toolkit-Edit.prompt.md`
3. Relevant subsystem templates / checklists

## Output requirements

### If the user wants a plan

The output must include at least:

- Task classification
- Target plugin / subsystem
- Whether historical behavior alignment is involved
- A method-level plan
- Thread / lifecycle boundaries
- A regression matrix

### If the user wants an audit

The output must include at least:

- Risk levels
- File / method-level locations
- Evidence
- Repair directions
- Regression recommendations

### If the user requests direct editing

The output must include at least:

- Files and methods changed
- Why the change was made this way
- Validation results
- Which requirements were directly validated and which still need additional validation

## Examples

- “Add a DI-based state synchronization module for a SwiftlyS2 plugin.”
- “Audit a plugin’s RuntimeLoop and hook hot paths.”
- “Migrate player-visible behavior from a historical SwiftlyS2 plugin into the current architecture.”
- “Fix thread-sensitive calls inside menu callbacks and land the code directly.”