feat(窗口图标): 添加窗口图标支持并完善相关资源处理
添加窗口图标功能，包括： 1. 支持通过配置文件设置窗口图标 2. 添加Windows资源文件处理 3. 更新各平台构建脚本以处理图标资源 4. 添加图标使用文档说明 5. 优化Application类结构 同时修复了Switch平台构建脚本中的团队名称错误
This commit is contained in:
216
AGENTS.md
Normal file
216
AGENTS.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Frostbite2D Agent Guide
|
||||
|
||||
This guide helps agentic coding agents work effectively with the Frostbite2D 2D game engine codebase.
|
||||
|
||||
## Build Commands
|
||||
|
||||
### Basic Build
|
||||
```bash
|
||||
xmake build
|
||||
```
|
||||
|
||||
### Clean Build
|
||||
```bash
|
||||
xmake clean
|
||||
xmake build
|
||||
```
|
||||
|
||||
### Debug Build
|
||||
```bash
|
||||
xmake build -m debug
|
||||
```
|
||||
|
||||
### Release Build
|
||||
```bash
|
||||
xmake build -m release
|
||||
```
|
||||
|
||||
### Platform-Specific Build
|
||||
```bash
|
||||
xmake build -p windows
|
||||
xmake build -p linux
|
||||
xmake build -p switch
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```bash
|
||||
xmake f -c # Show current configuration
|
||||
xmake f # Interactive configuration
|
||||
```
|
||||
|
||||
## Testing
|
||||
Currently no automated test framework is configured. Manual testing is performed by running the built binary.
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
Frostbite2D/
|
||||
├── include/frostbite2D/ # Public headers
|
||||
│ ├── core/ # Core engine classes
|
||||
│ ├── types/ # Type definitions
|
||||
│ ├── utils/ # Utility classes
|
||||
│ └── platform/ # Platform-specific code
|
||||
└── src/frostbite2D/ # Implementation files
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Naming Conventions
|
||||
- **Classes/Structs**: PascalCase (`Application`, `Window`, `Vec2`)
|
||||
- **Methods/Functions**: camelCase (`readTextFile`, `getFileName`)
|
||||
- **Member Variables**: camelCase with trailing underscore (`width_`, `height_`, `running_`)
|
||||
- **Constants**: UPPER_CASE (`PI_F`, `DEG_TO_RAD`) or PascalCase static methods (`Vec2::Zero()`)
|
||||
- **Namespaces**: lowercase (`frostbite2D`, `math`)
|
||||
- **Template Parameters**: PascalCase (`T`, `Args`, `Sig`)
|
||||
- **Type Aliases**: using keyword with PascalCase (`using int8 = std::int8_t;`)
|
||||
|
||||
### Imports and Includes
|
||||
- **Engine headers**: Use path relative to frostbite2D root
|
||||
```cpp
|
||||
#include <frostbite2D/core/application.h>
|
||||
#include <frostbite2D/utils/asset.h>
|
||||
```
|
||||
- **Third-party libraries**: Use vendor prefixes
|
||||
```cpp
|
||||
#include <SDL2/SDL.h>
|
||||
#include <glm/gtc/matrix_transform.hpp>
|
||||
#include <glad/glad.h>
|
||||
```
|
||||
- **Standard library**: Use angle brackets
|
||||
```cpp
|
||||
#include <string>
|
||||
#include <functional>
|
||||
#include <optional>
|
||||
```
|
||||
|
||||
### Formatting
|
||||
- **Indentation**: 2 spaces
|
||||
- **Brace Style**: K&R (opening brace on same line)
|
||||
```cpp
|
||||
void myFunction() {
|
||||
// body
|
||||
}
|
||||
```
|
||||
- **Pointer/Reference Style**: Type on left, not centered
|
||||
```cpp
|
||||
void func(T* ptr); // Good
|
||||
void func(T *ptr); // Avoid
|
||||
void func(T& ref); // Good
|
||||
```
|
||||
- **Const Placement**: After type
|
||||
```cpp
|
||||
const std::string& str; // Good
|
||||
std::string const& str; // Avoid
|
||||
```
|
||||
|
||||
### Types
|
||||
- **Use custom type aliases**: `int8`, `int32`, `uint8`, `uint64`, `Ptr<T>`, `SharedPtr<T>`
|
||||
- **Smart pointers**: Prefer `Ptr<T>` alias over `std::shared_ptr<T>`
|
||||
- **constexpr**: Use for compile-time constants
|
||||
- **Struct vs Class**:
|
||||
- Use `struct` for POD types, configurations, and data-only types
|
||||
- Use `class` for objects with methods/encapsulation
|
||||
- **Default member initialization**: Initialize at declaration
|
||||
```cpp
|
||||
bool running_ = false;
|
||||
int width_ = 1280;
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
- **Return bool for success/failure operations** (especially I/O)
|
||||
- **Use SDL_Log/SDL_LogError for logging**
|
||||
- **Use std::optional for optional returns**
|
||||
- **Avoid exceptions** (not observed in codebase)
|
||||
- **Return early on failure**: Check conditions and return false immediately
|
||||
|
||||
### Singletons
|
||||
- Use static instance pattern with private constructor:
|
||||
```cpp
|
||||
static Application& get();
|
||||
private:
|
||||
Application() = default;
|
||||
```
|
||||
|
||||
### Const Correctness
|
||||
- Mark methods `const` if they don't modify state
|
||||
- Pass by const reference for large types: `const std::string&`
|
||||
- Return const references to member data when appropriate
|
||||
|
||||
### Documentation
|
||||
- **Doxygen-style comments** with `@brief` tag
|
||||
- **Use `///` for single-line comments in headers**
|
||||
- **Section separators** use `// ---------------------------------------------------------------------------`
|
||||
- **Chinese comments** are present and should be preserved/maintained
|
||||
```cpp
|
||||
/**
|
||||
* @brief 读取文本文件
|
||||
* @param path 文件路径
|
||||
* @param outContent 输出文件内容
|
||||
* @return 读取成功返回 true
|
||||
*/
|
||||
bool readTextFile(const std::string& path, std::string& outContent);
|
||||
```
|
||||
|
||||
### Platform Handling
|
||||
- Use `#ifdef` guards for platform-specific code:
|
||||
```cpp
|
||||
#ifdef __SWITCH__
|
||||
switchInit();
|
||||
#endif
|
||||
```
|
||||
- Supported platforms: Windows, Linux, macOS, Switch
|
||||
- Platform configs in `platform/` directory
|
||||
|
||||
### STL Usage
|
||||
- Prefer STL algorithms over manual loops
|
||||
- Use `std::filesystem` for file operations (already wrapped in Asset class)
|
||||
- Use `std::optional` for nullable returns
|
||||
- Use `std::function` for callbacks
|
||||
- Use `std::vector` for dynamic arrays
|
||||
- Use `std::string` for text
|
||||
|
||||
### OpenGL/Graphics
|
||||
- GLM library for math operations
|
||||
- Glad for OpenGL function loading
|
||||
- Keep OpenGL-specific code minimal and well-encapsulated
|
||||
|
||||
## Dependencies
|
||||
- **SDL2**: Windowing, input, platform abstraction
|
||||
- **GLM**: Math library (vectors, matrices)
|
||||
- **Glad**: OpenGL loader
|
||||
- **STB**: Image/text utilities (single-header libs)
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Module Pattern
|
||||
```cpp
|
||||
void Application::use(Module& m) {
|
||||
modules_.push_back(&m);
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration Pattern
|
||||
Use configuration structs with default values:
|
||||
```cpp
|
||||
struct WindowConfig {
|
||||
uint32_t width = 640;
|
||||
uint32_t height = 480;
|
||||
std::string title = "Frostbite2D Game";
|
||||
};
|
||||
```
|
||||
|
||||
### Path Handling
|
||||
Always use the Asset singleton for file operations - it handles platform-specific path issues:
|
||||
```cpp
|
||||
Asset& asset = Asset::get();
|
||||
asset.setWorkingDirectory("path/to/assets");
|
||||
std::string content;
|
||||
if (asset.readTextFile("file.txt", content)) {
|
||||
// success
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
- **Path separators**: Use Asset class, it handles platform differences
|
||||
- **Encoding**: Project uses UTF-8, Asset handles Windows UTF-8 paths
|
||||
- **Memory leaks**: Use smart pointers, ensure proper cleanup in destructors
|
||||
- **OpenGL context**: Initialize only after window creation
|
||||
Reference in New Issue
Block a user