Skip to content

Commit 1ed9fea

Browse files
CopilotRushaway
Copilot
and
Rushaway
authored
chore(ci): coding agent instructions (#4)
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 d43530a commit 1ed9fea

1 file changed

Lines changed: 255 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Copilot Instructions for FixMapFiles SourceMod Plugin
2+
3+
## Repository Overview
4+
5+
This repository contains a SourceMod plugin for Counter-Strike: Source that automatically applies file fixes for specific zombie escape maps. The plugin handles two main types of fixes:
6+
7+
1. **Paranoid Rezurrection fixes** - Custom textures and materials for ze_paranoid_rezurrection_v11_9
8+
2. **Gargantua model fixes** - Fixed model files applied to multiple maps with Gargantua model issues
9+
10+
### Key Files
11+
- `addons/sourcemod/scripting/FixMapsFiles.sp` - Main plugin source code
12+
- `materials/` - Game texture and material files (.vmt, .vtf)
13+
- `models/` - Game model files (.mdl, .vtx, .phy, .vvd)
14+
- `sourceknight.yaml` - Build configuration for SourceKnight build system
15+
- `.github/workflows/ci.yml` - Automated build, test, and release pipeline
16+
17+
## Development Environment
18+
19+
### Language & Platform
20+
- **Language**: SourcePawn (Source engine scripting language)
21+
- **Platform**: SourceMod 1.11+ (minimum required version defined in sourceknight.yaml)
22+
- **Target Game**: Counter-Strike: Source
23+
- **Build Tool**: SourceKnight build system
24+
25+
### Required Headers
26+
All SourcePawn files must include these pragmas at the top:
27+
```sourcepawn
28+
#pragma semicolon 1
29+
#pragma newdecls required
30+
```
31+
32+
## Code Style Standards
33+
34+
### Naming Conventions
35+
- **Functions**: PascalCase (e.g., `ApplyParanoidFix()`)
36+
- **Variables**: camelCase for locals, PascalCase with `g_` prefix for globals
37+
- **Constants**: ALL_CAPS with underscores
38+
- **Stock functions**: Use `stock` keyword for utility functions
39+
40+
### Formatting
41+
- **Indentation**: Use tabs (4 spaces equivalent)
42+
- **Braces**: Opening brace on same line
43+
- **Spacing**: No trailing spaces, consistent spacing around operators
44+
45+
### Example Code Structure
46+
```sourcepawn
47+
#pragma semicolon 1
48+
#pragma newdecls required
49+
50+
#include <sourcemod>
51+
#include <sdktools>
52+
53+
public Plugin myinfo = {
54+
name = "Plugin Name",
55+
author = "Author",
56+
description = "Description",
57+
version = "1.0.0",
58+
url = ""
59+
};
60+
61+
public void OnMapStart() {
62+
// Map detection logic
63+
}
64+
65+
stock void UtilityFunction() {
66+
// Implementation
67+
}
68+
```
69+
70+
## Plugin Architecture
71+
72+
### Core Functionality
73+
The plugin operates on a simple event-driven model:
74+
1. **OnMapStart()** - Triggered when map loads, checks current map name
75+
2. **Map Detection** - Uses string comparison to identify supported maps
76+
3. **Fix Application** - Calls appropriate fix functions based on map
77+
78+
### Supported Maps
79+
- **Paranoid + Gargantua fixes**: `ze_paranoid_rezurrection_v11_9`
80+
- **Gargantua fixes only**: `ze_avalanche_reboot_beta7`, `ze_l0v0l_v1_4`, `ze_mountain_escape_v5_zy`, `ze_Pidaras_v1_4fix3`, `ze_sandstorm_css_v1_5x3`, `ze_tyranny_v5fix`
81+
82+
### Adding New Map Support
83+
To add support for a new map:
84+
85+
1. **Add map to OnMapStart() logic**:
86+
```sourcepawn
87+
else if (strcmp(sCurrentMap, "new_map_name", false) == 0) {
88+
ApplyGargantuaFix(); // or create new fix function
89+
}
90+
```
91+
92+
2. **Create new fix function if needed**:
93+
```sourcepawn
94+
stock void ApplyNewMapFix() {
95+
// Precache models if needed
96+
PrecacheModel("models/new_model.mdl");
97+
98+
// Add files to download table
99+
AddFileToDownloadsTable("materials/path/to/texture.vmt");
100+
AddFileToDownloadsTable("materials/path/to/texture.vtf");
101+
AddFileToDownloadsTable("models/new_model.mdl");
102+
}
103+
```
104+
105+
3. **Add corresponding asset files**:
106+
- Place materials in `materials/` directory structure
107+
- Place models in `models/` directory
108+
- Ensure file paths match exactly what's in the code
109+
110+
## Asset File Management
111+
112+
### File Types and Structure
113+
- **Materials**: `.vmt` (material definition) and `.vtf` (texture) files in `materials/`
114+
- **Models**: `.mdl`, `.vtx`, `.phy`, `.vvd` files in `models/`
115+
- **Directory Structure**: Must match game's expected paths exactly
116+
117+
### Important Notes
118+
- **File Paths**: Must be relative to game root and match exactly in code
119+
- **Case Sensitivity**: Linux servers are case-sensitive, ensure proper casing
120+
- **Download Table**: All custom files must be added via `AddFileToDownloadsTable()`
121+
- **Model Precaching**: Models must be precached with `PrecacheModel()` before use
122+
123+
### Asset Validation
124+
When adding new assets:
125+
1. Verify file paths match between code and actual file locations
126+
2. Test that files download properly on client connection
127+
3. Ensure models load without errors in-game
128+
4. Check that materials display correctly
129+
130+
## Build System
131+
132+
### SourceKnight Configuration
133+
The `sourceknight.yaml` file defines:
134+
- SourceMod version dependency (currently 1.11.0-git6934)
135+
- Build targets and output directories
136+
- Project structure and dependencies
137+
138+
### Build Process
139+
```bash
140+
# Build using SourceKnight (handled by CI)
141+
sourceknight build
142+
143+
# Manual compilation (if needed)
144+
spcomp -i addons/sourcemod/scripting/include addons/sourcemod/scripting/FixMapsFiles.sp
145+
```
146+
147+
### Local Development Setup
148+
1. Install SourceMod compiler (spcomp)
149+
2. Set up include paths for SourceMod headers
150+
3. Use SourceKnight for automated builds
151+
152+
## Testing and Validation
153+
154+
### Plugin Testing
155+
- **Compile Check**: Ensure plugin compiles without errors
156+
- **Map Loading**: Test on supported maps to verify fixes apply
157+
- **File Download**: Verify clients download required files
158+
- **Model Loading**: Check that models load and display correctly
159+
- **Error Handling**: Test with unsupported maps (should do nothing)
160+
161+
### Server Testing Requirements
162+
- Counter-Strike: Source dedicated server
163+
- SourceMod 1.11+ installed
164+
- Test maps available on server
165+
- Client connection testing for file downloads
166+
167+
### Testing Checklist
168+
- [ ] Plugin compiles successfully
169+
- [ ] No console errors on map start
170+
- [ ] Files added to download table correctly
171+
- [ ] Models precache without errors
172+
- [ ] Client downloads complete successfully
173+
- [ ] Materials/models display correctly in-game
174+
175+
## CI/CD Pipeline
176+
177+
### Automated Workflows
178+
- **Build**: Compiles plugin using SourceKnight on Ubuntu 24.04
179+
- **Package**: Creates release package with plugin and asset files
180+
- **Release**: Automatically creates GitHub releases with built artifacts
181+
182+
### Release Process
183+
1. **Push to main/master**: Triggers build and creates "latest" release
184+
2. **Git tag**: Triggers versioned release with tag name
185+
3. **Artifact Upload**: Includes compiled .smx plugin and all asset files
186+
187+
### Package Structure
188+
Release packages include:
189+
- Compiled plugin (.smx file)
190+
- All material files in proper directory structure
191+
- All model files in proper directory structure
192+
- Ready for server deployment
193+
194+
## Common Patterns and Best Practices
195+
196+
### Error Prevention
197+
- Always validate file paths before adding to download table
198+
- Use consistent string comparison with `false` parameter for case-insensitive matching
199+
- Precache models before adding related files to download table
200+
- Test compilation after any changes
201+
202+
### Performance Considerations
203+
- File operations only occur on map start (not performance-critical)
204+
- String comparisons are minimal and only happen once per map load
205+
- Asset file sizes should be reasonable for client downloads
206+
207+
### Maintenance
208+
- Keep supported map list updated in both code and README
209+
- Verify asset file integrity when adding new maps
210+
- Update SourceMod version in sourceknight.yaml as needed
211+
- Monitor for new map versions that may need updated fixes
212+
213+
## Code Examples
214+
215+
### Adding a New Map with Custom Fix
216+
```sourcepawn
217+
// In OnMapStart()
218+
else if (strcmp(sCurrentMap, "ze_newmap_v1", false) == 0) {
219+
ApplyNewMapFix();
220+
}
221+
222+
// New fix function
223+
stock void ApplyNewMapFix() {
224+
// Precache any models
225+
PrecacheModel("models/custom/newmodel.mdl");
226+
227+
// Add materials
228+
AddFileToDownloadsTable("materials/custom/newtexture.vmt");
229+
AddFileToDownloadsTable("materials/custom/newtexture.vtf");
230+
231+
// Add model files
232+
AddFileToDownloadsTable("models/custom/newmodel.mdl");
233+
AddFileToDownloadsTable("models/custom/newmodel.dx80.vtx");
234+
AddFileToDownloadsTable("models/custom/newmodel.dx90.vtx");
235+
AddFileToDownloadsTable("models/custom/newmodel.phy");
236+
AddFileToDownloadsTable("models/custom/newmodel.sw.vtx");
237+
AddFileToDownloadsTable("models/custom/newmodel.vvd");
238+
}
239+
```
240+
241+
## Troubleshooting
242+
243+
### Common Issues
244+
- **File not downloading**: Check file path matches exactly in code and filesystem
245+
- **Model not loading**: Ensure PrecacheModel() is called before AddFileToDownloadsTable()
246+
- **Case sensitivity**: Linux servers require exact case matching
247+
- **Missing dependencies**: Verify all related files (materials for models) are included
248+
249+
### Debugging
250+
- Enable SourceMod logging to see download table additions
251+
- Check server console for file loading errors
252+
- Test with single client connection to verify downloads
253+
- Use `sm_dump_admcache` and related commands for debugging
254+
255+
This plugin is specifically designed for Counter-Strike: Source zombie escape servers and focuses on providing essential file fixes for popular community maps.

0 commit comments

Comments
 (0)