Skip to content

Commit bbac93b

Browse files
Copilotxezno
Copilot
and
xezno
committed
Create comprehensive GitHub Copilot instructions for Mocha Engine
Co-authored-by: xezno <[email protected]>
1 parent 6a181b1 commit bbac93b

File tree

1 file changed

+223
-0
lines changed

1 file changed

+223
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Mocha Game Engine Development Instructions
2+
3+
**CRITICAL: Always follow these instructions first and fallback to additional search and context gathering only when the information here is incomplete or found to be in error.**
4+
5+
Mocha is a Windows-only game engine with Vulkan renderer, C# scripting, and hot-loading HTML/CSS UI system. It uses a complex build process that combines C++ native code (with vcpkg dependencies) and .NET 7.0 C# projects with automatic interop code generation.
6+
7+
## Working Effectively
8+
9+
### Prerequisites (Windows Only)
10+
- **Windows 10/11** - Engine is Windows-only and cannot be built on Linux/macOS
11+
- **Visual Studio 2022** - Required for MSBuild and vcproj support
12+
- **.NET 7.0 SDK** - Required for C# projects (though .NET 8.0 can build .NET 7.0 targets)
13+
- **vcpkg** - Package manager for C++ dependencies
14+
- **Vulkan SDK** - Graphics API requirements
15+
- **Git** with submodules support
16+
17+
### Initial Repository Setup
18+
```bash
19+
# Clone repository with all submodules
20+
git clone --recursive https://github.com/mocha-engine/mocha
21+
cd mocha
22+
23+
# If already cloned, update submodules
24+
git submodule update --init --recursive
25+
```
26+
27+
### Build Process (Windows Only)
28+
**NEVER CANCEL BUILDS**: Builds may take 15-45 minutes. Always set timeout to 60+ minutes.
29+
30+
```batch
31+
# Navigate to Source directory
32+
cd Source
33+
34+
# 1. Install vcpkg dependencies (5-15 minutes)
35+
setup_x64.cmd
36+
# OR for 32-bit: setup_x86.cmd
37+
38+
# 2. Build the entire solution (15-45 minutes total)
39+
# NEVER CANCEL: Use MSBuild with long timeout
40+
msbuild Mocha.sln /p:Configuration=Debug /p:Platform=x64
41+
# OR use Visual Studio: Open Source/Mocha.sln and build solution
42+
```
43+
44+
**Build Order Dependencies:**
45+
1. `MochaTool.InteropGen` - Generates C++/C# interop bindings (must build first)
46+
2. `Mocha.Common` - Shared C# library (depends on generated interop code)
47+
3. `Mocha.Engine`, `Mocha.UI`, etc. - Core engine libraries
48+
4. `Mocha.Host` - Native C++ host executable
49+
5. `Mocha` and `MochaDedicatedServer` - Final executables
50+
51+
### Running the Engine
52+
```batch
53+
# After successful build, run the main executable
54+
cd ..\build
55+
Mocha.exe
56+
57+
# Or run with a specific project
58+
Mocha.exe -project ..\Samples\mocha-minimal\project.json
59+
```
60+
61+
### Testing
62+
```batch
63+
# Navigate to Source directory
64+
cd Source
65+
66+
# Run .NET tests (5-10 minutes)
67+
# NEVER CANCEL: Set timeout to 15+ minutes
68+
dotnet test Mocha.Tests/ --configuration Debug
69+
70+
# Run specific test project
71+
dotnet test Mocha.Tests/Mocha.Tests.csproj
72+
```
73+
74+
### Code Formatting and Linting
75+
```batch
76+
# Format .NET code (required before commits)
77+
cd Source
78+
dotnet format
79+
80+
# The CI pipeline (.github/workflows/format.yml) will fail if code is not formatted
81+
# Always run dotnet format before committing changes
82+
```
83+
84+
## Project Structure
85+
86+
### Key Directories
87+
- **`Source/`** - All source code and project files
88+
- **`Mocha.sln`** - Main Visual Studio solution
89+
- **`vcpkg.json`** - C++ dependency manifest
90+
- **`setup_x64.cmd`** / **`setup_x86.cmd`** - Dependency installation scripts
91+
- **`Content/`** - Core engine content and assets
92+
- **`Samples/`** - Example projects
93+
- **`mocha-minimal/`** - Basic sample project
94+
- **`build/`** - Build output directory (created during build)
95+
96+
### C# Projects (.NET 7.0)
97+
- **`Mocha.Engine`** - Core game engine library
98+
- **`Mocha.Common`** - Shared utilities and interop bindings
99+
- **`Mocha.UI`** - HTML/CSS UI system
100+
- **`Mocha.Hotload`** - C# hot-loading system
101+
- **`Mocha.Editor`** - ImGui-based editor
102+
- **`MochaTool.AssetCompiler`** - Asset compilation tool
103+
- **`MochaTool.InteropGen`** - C++/C# interop code generator
104+
- **`Mocha.Tests`** - MSTest unit tests
105+
106+
### C++ Projects (Visual Studio)
107+
- **`Mocha.Host`** - Native C++ host library (Vulkan, SDL2, Jolt Physics)
108+
- **`Mocha`** - Main executable wrapper
109+
- **`MochaDedicatedServer`** - Server executable
110+
111+
## Common Development Tasks
112+
113+
### Building Individual Components
114+
```batch
115+
# Build only .NET projects (faster iteration)
116+
cd Source
117+
dotnet build --configuration Debug
118+
119+
# Build specific project
120+
dotnet build Mocha.Engine/Mocha.Engine.csproj
121+
122+
# Build native components only (requires Visual Studio)
123+
msbuild Mocha.Host/Mocha.Host.vcxproj /p:Configuration=Debug /p:Platform=x64
124+
```
125+
126+
### Asset Compilation
127+
```batch
128+
# Compile assets (after successful build)
129+
build\MochaTool.AssetCompiler.exe --mountpoints "samples/mocha-minimal/content/" "content/core/" -f
130+
```
131+
132+
### Debugging
133+
```batch
134+
# The engine supports both C++ and C# debugging
135+
# Use Visual Studio debugger with "Mocha" profile
136+
# Launch settings are auto-generated in each project's Properties/launchSettings.json
137+
```
138+
139+
## Validation Requirements
140+
141+
### Manual Validation Scenarios
142+
After making changes, always test these core scenarios:
143+
144+
1. **Engine Launch Test**
145+
```batch
146+
cd build
147+
Mocha.exe
148+
# Verify: Engine window opens without crashes
149+
```
150+
151+
2. **Sample Project Test**
152+
```batch
153+
cd build
154+
Mocha.exe -project ..\Samples\mocha-minimal\project.json
155+
# Verify: Sample loads and renders correctly
156+
```
157+
158+
3. **Hot-loading Test**
159+
```batch
160+
# With engine running, modify C# code in sample project
161+
# Verify: Changes reload automatically without restart
162+
```
163+
164+
### Pre-commit Validation
165+
```batch
166+
# ALWAYS run before committing:
167+
cd Source
168+
169+
# 1. Format code
170+
dotnet format
171+
172+
# 2. Build solution (NEVER CANCEL - 15-45 minutes)
173+
msbuild Mocha.sln /p:Configuration=Debug /p:Platform=x64
174+
175+
# 3. Run tests (NEVER CANCEL - 5-10 minutes)
176+
dotnet test
177+
178+
# 4. Test basic functionality
179+
cd ..\build
180+
Mocha.exe -project ..\Samples\mocha-minimal\project.json
181+
```
182+
183+
## Troubleshooting
184+
185+
### Build Issues
186+
- **"Missing Microsoft.Cpp.Default.props"** - Install Visual Studio 2022 with C++ workload
187+
- **"vcpkg packages not found"** - Run `setup_x64.cmd` first
188+
- **"Vulkan not found"** - Install Vulkan SDK
189+
- **"InteropGen.exe not found"** - Build order issue; clean and rebuild entire solution
190+
- **".NET 7.0 not found"** - Install .NET 7.0 SDK (or newer with 7.0 targeting pack)
191+
192+
### Runtime Issues
193+
- **"Vulkan initialization failed"** - Update graphics drivers or install Vulkan runtime
194+
- **"Assembly not found errors"** - Ensure all projects built successfully
195+
- **"Hot-loading not working"** - Check that C# projects are in Debug configuration
196+
197+
### Performance Issues
198+
- **Slow builds** - Normal behavior; builds can take 15-45 minutes
199+
- **Slow vcpkg install** - Normal behavior; first-time setup can take 15+ minutes
200+
201+
## Important Notes
202+
203+
- **Windows Only**: Cannot build or run on Linux/macOS
204+
- **Long Build Times**: NEVER CANCEL builds - they can take 45+ minutes
205+
- **Complex Dependencies**: Build failures often cascade; clean and rebuild entire solution
206+
- **Format Requirements**: Code must be formatted with `dotnet format` or CI will fail
207+
- **Interop Complexity**: Changes to C++ headers may require regenerating interop bindings
208+
- **Visual Studio Dependency**: While some .NET parts work with dotnet CLI, full builds require Visual Studio
209+
210+
## CI/CD Pipeline
211+
212+
### GitHub Actions
213+
- **`.github/workflows/format.yml`** - Validates .NET code formatting
214+
- **`.github/workflows/commit-log.yml`** - Discord notifications
215+
216+
The format workflow will fail if code is not properly formatted. Always run `dotnet format` before committing.
217+
218+
## Getting Help
219+
220+
- **Discord**: [https://discord.gg/SDP4R6Wsza](https://discord.gg/SDP4R6Wsza)
221+
- **Wiki**: [https://wiki.getmocha.org/](https://wiki.getmocha.org/)
222+
- **Issues**: [https://github.com/mocha-engine/mocha/issues](https://github.com/mocha-engine/mocha/issues)
223+
- **Style Guide**: [Mocha Style Guidelines](https://wiki.getmocha.org/index.php/Style_Guidelines)

0 commit comments

Comments
 (0)