Skip to content

Commit da9aec1

Browse files
CopilotRushaway
Copilot
and
Rushaway
authored
chore(ci): coding agent instructions (#16)
Co-authored-by: Rushaway <11679883+Rushaway@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent d714d99 commit da9aec1

1 file changed

Lines changed: 188 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Copilot Instructions for VIP SourceMod Flags Plugin
2+
3+
## Repository Overview
4+
5+
This repository contains a SourceMod plugin written in SourcePawn that manages VIP user flags and permissions in Source engine game servers. The plugin integrates with VIP-Core to automatically assign admin flags and groups to VIP users, providing them with appropriate permissions and immunity levels.
6+
7+
**Key Features:**
8+
- Automatic admin flag assignment for VIP users
9+
- Dynamic group creation and management
10+
- Integration with SourceBans++ for admin cache management
11+
- Support for Custom Chat Colors (CCC) integration
12+
- Configurable VIP group names and immunity levels
13+
14+
## Technical Environment
15+
16+
**Language**: SourcePawn (.sp files)
17+
**Platform**: SourceMod 1.11+ (as per sourceknight.yaml dependency)
18+
**Build System**: SourceKnight (Python-based build tool for SourceMod plugins)
19+
**Compiler**: SourceMod compiler (spcomp) - handled automatically by SourceKnight
20+
21+
### Dependencies
22+
- **sourcemod**: Core SourceMod framework (version 1.11.0-git6917)
23+
- **vip_core**: VIP system core functionality
24+
- **multicolors**: Color chat message support
25+
- **utilshelper**: Utility functions
26+
- **ccc** (optional): Custom Chat Colors integration
27+
- **sourcebanspp** (optional): SourceBans++ integration
28+
29+
## Build System
30+
31+
### SourceKnight Configuration
32+
The project uses SourceKnight as defined in `sourceknight.yaml`:
33+
- Dependencies are automatically downloaded and configured
34+
- Output directory: `/addons/sourcemod/plugins`
35+
- Target plugin: `VIP_SourcemodFlags`
36+
37+
### Building the Plugin
38+
```bash
39+
# Install SourceKnight (if not already installed)
40+
pip install sourceknight
41+
42+
# Build the plugin
43+
sourceknight build
44+
```
45+
46+
### CI/CD Pipeline
47+
The repository uses GitHub Actions (`.github/workflows/ci.yml`):
48+
- Automatically builds on push/PR to any branch
49+
- Creates releases for tagged versions and latest builds
50+
- Uses `maxime1907/action-sourceknight@v1` action
51+
52+
## Code Style & Standards
53+
54+
### SourcePawn Conventions
55+
- **Indentation**: Use tabs (equivalent to 4 spaces)
56+
- **Variables**:
57+
- Local variables and parameters: `camelCase`
58+
- Global variables: `PascalCase` with `g_` prefix (e.g., `g_cvVIPGroupName`)
59+
- Functions: `PascalCase`
60+
- **Pragmas**: Always include `#pragma semicolon 1` and `#pragma newdecls required`
61+
- **Memory Management**: Use `delete` for cleanup, avoid `.Clear()` on StringMap/ArrayList
62+
63+
### File Structure
64+
```
65+
addons/sourcemod/scripting/
66+
├── VIP_SourcemodFlags.sp # Main plugin file
67+
└── include/ # Include files (dependencies)
68+
```
69+
70+
## Plugin Architecture
71+
72+
### Core Components
73+
1. **VIP Integration**: Hooks into VIP-Core events for user status changes
74+
2. **Admin Management**: Dynamic creation/removal of admin entries
75+
3. **Group Management**: Automatic VIP group creation with proper flags
76+
4. **Optional Integrations**: SourceBans++ and Custom Chat Colors support
77+
78+
### Key Functions
79+
- `LoadVIPClient(client)`: Assigns admin flags to VIP users
80+
- `UnloadVIPClient(client)`: Removes admin flags from non-VIP users
81+
- `LoadClient(client)`: Core logic for admin flag assignment
82+
- `RemoveClient(client)`: Core logic for admin flag removal
83+
84+
### Configuration Variables
85+
- `sm_vip_group_name`: VIP group name (default: "VIP")
86+
- `sm_vip_group_immunity`: Immunity level for VIP users (default: 5, range: 0-100)
87+
88+
## Development Guidelines
89+
90+
### Adding New Features
91+
1. **Follow existing patterns**: Use the same event handling structure
92+
2. **Memory management**: Always use `delete` for cleanup, never check for null before delete
93+
3. **Error handling**: Validate client indices and states before operations
94+
4. **Integration**: Use optional includes for external dependencies (`#tryinclude`)
95+
96+
### Common Modifications
97+
- **Adding new VIP flags**: Modify the group creation logic in `LoadClient()`
98+
- **Changing immunity logic**: Update `SetAdmGroupImmunityLevel()` calls
99+
- **Adding integrations**: Follow the CCC/SourceBans++ pattern with library checks
100+
101+
### Testing Procedures
102+
1. **Build validation**: Ensure plugin compiles without warnings
103+
2. **Server testing**: Test on a development server with VIP-Core installed
104+
3. **Integration testing**: Verify compatibility with optional dependencies
105+
4. **Memory testing**: Check for memory leaks using SourceMod's profiler
106+
107+
## Working with Dependencies
108+
109+
### Required Dependencies
110+
All required dependencies are managed through `sourceknight.yaml`. When adding new dependencies:
111+
1. Add to the `dependencies` section in `sourceknight.yaml`
112+
2. Update the include statements in the plugin file
113+
3. Test the build process
114+
115+
### Optional Dependencies
116+
Optional dependencies use conditional compilation:
117+
```sourcepawn
118+
#undef REQUIRE_PLUGIN
119+
#tryinclude <optional_plugin>
120+
#define REQUIRE_PLUGIN
121+
122+
// Later in code:
123+
#if defined _optional_plugin_included
124+
// Optional functionality
125+
#endif
126+
```
127+
128+
## Common Tasks
129+
130+
### Adding a New ConVar
131+
```sourcepawn
132+
// In OnPluginStart()
133+
ConVar g_cvNewSetting = CreateConVar("sm_vip_new_setting", "default", "Description");
134+
```
135+
136+
### Adding Admin Commands
137+
```sourcepawn
138+
// In OnPluginStart()
139+
RegAdminCmd("sm_newcommand", Command_NewCommand, ADMFLAG_BAN);
140+
141+
public Action Command_NewCommand(int client, int args)
142+
{
143+
// Command implementation
144+
return Plugin_Handled;
145+
}
146+
```
147+
148+
### Debugging Tips
149+
- Use `CPrintToChat()` for colored debug messages
150+
- Check `IsValidClient()` before client operations
151+
- Monitor server logs for compilation and runtime errors
152+
- Use the `sm_adminimmunity` command to verify immunity levels
153+
154+
## File Locations
155+
156+
- **Plugin source**: `addons/sourcemod/scripting/VIP_SourcemodFlags.sp`
157+
- **Build config**: `sourceknight.yaml`
158+
- **CI/CD**: `.github/workflows/ci.yml`
159+
- **Compiled output**: `.sourceknight/package/addons/sourcemod/plugins/VIP_SourcemodFlags.smx`
160+
161+
## Best Practices
162+
163+
1. **Always validate client indices** before performing operations
164+
2. **Use meaningful variable names** that reflect their purpose
165+
3. **Document complex logic** with inline comments
166+
4. **Test with multiple scenarios**: VIP addition, removal, server restart, plugin reload
167+
5. **Handle edge cases**: Client disconnection during admin operations
168+
6. **Optimize performance**: Avoid unnecessary loops in frequently called functions
169+
7. **Memory safety**: Always clean up StringMaps and ArrayLists with `delete`
170+
8. **Version compatibility**: Ensure changes work with minimum SourceMod version (1.11+)
171+
172+
## Troubleshooting
173+
174+
### Build Issues
175+
- Verify all dependencies are listed in `sourceknight.yaml`
176+
- Check for syntax errors using SourceMod compiler warnings
177+
- Ensure proper include file placement
178+
179+
### Runtime Issues
180+
- Check SourceMod error logs for detailed error messages
181+
- Verify VIP-Core is properly installed and functioning
182+
- Test admin cache rebuilding with `sm_reloadadmins`
183+
- Use `sm_reloadvips` command to refresh VIP admin assignments
184+
185+
### Integration Issues
186+
- Verify optional dependencies are properly detected with library checks
187+
- Test with and without optional plugins loaded
188+
- Check for proper event handling order with other plugins

0 commit comments

Comments
 (0)