diff options
Diffstat (limited to '.github/copilot-instructions.md')
| -rw-r--r-- | .github/copilot-instructions.md | 736 |
1 files changed, 736 insertions, 0 deletions
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..2249ade --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,736 @@ +# GitHub Copilot Instructions for OpenMB + +This document provides context and instructions for GitHub Copilot and other AI coding assistants when working on the OpenMB project. + +## Project Overview + +OpenMB is a C++20 game engine project that follows strict coding standards and conventions. When generating code or suggestions, always adhere to the guidelines outlined in this document. + +## Core Principles + +1. **Consistency over personal preference** - Follow existing patterns in the codebase +2. **Modern C++20** - Use modern C++ features appropriately +3. **Cross-platform compatibility** - Code must work on Windows, Linux, and macOS +4. **Clear documentation** - All public APIs should have Doxygen comments +5. **Memory safety** - Prefer RAII and smart pointers over manual memory management + +## Code Style Requirements + +### Formatting + +**CRITICAL: All code must follow these formatting rules:** + +```cpp +// Braces - ALWAYS on their own line (Allman/BSD style) +void myFunction() +{ + if (condition) + { + doSomething(); + } + else + { + doSomethingElse(); + } +} + +// NOT this: +void myFunction() { + if (condition) { + doSomething(); + } else { + doSomethingElse(); + } +} +``` + +- **Indentation**: 4 spaces (NEVER tabs) +- **Line length**: Maximum 120 columns +- **Pointer alignment**: Left-aligned with type (`Ptr* ptr`, not `Ptr *ptr`) +- **Spacing**: Space after control keywords (`if (`, `for (`, `while (`), no space after function names + +### Naming Conventions + +**CRITICAL: Follow these naming rules exactly:** + +```cpp +// Classes and Structs - PascalCase +class PlayerManager { }; +struct GameState { }; + +// Functions and Methods - camelCase +void processInput(); +bool isGameRunning() const; + +// Member Variables - 'm' prefix + PascalCase +class MyClass +{ +private: + int mHealthPoints; + std::string mPlayerName; + bool mIsActive; +}; + +// Local Variables and Parameters - camelBack +void updatePlayer(const Ptr& playerPtr, int deltaTime) +{ + int currentHealth = getHealth(playerPtr); + float movementSpeed = calculateSpeed(); +} + +// Namespaces - PascalCase with MB prefix for project namespaces +namespace MBWorld { } +namespace MBMechanics { } +namespace MBBase { } + +// Constants and Enums - PascalCase +enum class GameState +{ + Loading, + Running, + Paused +}; + +constexpr int MaxPlayers = 64; +``` + +### Include Guards + +**ALWAYS use this format for include guards:** + +```cpp +#ifndef OPENMB_<PATH_TO_FILE>_H +#define OPENMB_<PATH_TO_FILE>_H + +// Header content + +#endif +``` + +Example: For file `apps/openmb/mbworld/player.hpp` +```cpp +#ifndef OPENMB_APPS_OPENMB_MBWORLD_PLAYER_H +#define OPENMB_APPS_OPENMB_MBWORLD_PLAYER_H +``` + +### Include Order + +**ALWAYS organize includes in this order:** + +```cpp +#include "relatedheader.hpp" // Related header first (for .cpp files) + +#include <cstdint> // C system headers +#include <cmath> + +#include <string> // C++ standard library +#include <vector> +#include <memory> + +#include <osg/Vec3f> // External libraries +#include <MyGUI_Widget.h> + +#include <components/esm/refid.hpp> // Project headers +#include "../mbbase/environment.hpp" +``` + +### Namespace Structure + +```cpp +namespace MBWorld +{ + // All namespace content indented + class MyClass + { + public: // Access modifiers outdented by 4 spaces + MyClass(); + + private: + int mData; + }; + + void freeFunction(); +} +``` + +## Code Generation Guidelines + +### When Creating New Classes + +**ALWAYS generate headers like this:** + +```cpp +#ifndef OPENMB_APPS_OPENMB_MBWORLD_MYCLASS_H +#define OPENMB_APPS_OPENMB_MBWORLD_MYCLASS_H + +#include <string> +#include <vector> + +namespace MBWorld +{ + /// Brief description of what this class does + class MyClass + { + public: + MyClass(); + ~MyClass() = default; + + /// Brief description of method + /// \param input Description of parameter + /// \return Description of return value + bool processData(int input); + + /// Get the current value + int getValue() const; + + private: + int mValue; + std::string mName; + std::vector<int> mData; + }; +} + +#endif +``` + +**And implementations like this:** + +```cpp +#include "myclass.hpp" + +#include <algorithm> +#include <stdexcept> + +namespace MBWorld +{ + MyClass::MyClass() + : mValue(0) + , mName() + , mData() + { + } + + bool MyClass::processData(int input) + { + if (input < 0) + { + throw std::runtime_error("Invalid input"); + } + + mValue = input; + return true; + } + + int MyClass::getValue() const + { + return mValue; + } +} +``` + +### Modern C++ Patterns to Use + +```cpp +// Smart pointers instead of raw pointers +std::unique_ptr<Dialog> mDialog; +std::shared_ptr<Resource> mResource; + +// Range-based for loops +for (const auto& item : container) +{ + process(item); +} + +// Auto for complex types +auto iterator = myMap.find(key); +auto result = complexFunction(); + +// nullptr instead of NULL +Ptr* ptr = nullptr; + +// override keyword for virtual functions +void myMethod() override; + +// constexpr for compile-time constants +constexpr int BufferSize = 1024; + +// Const correctness +void processData(const std::string& input) const; + +// Structured bindings (C++17) +for (const auto& [key, value] : myMap) +{ + // ... +} +``` + +### Patterns to AVOID + +```cpp +// DON'T use manual memory management +MyClass* obj = new MyClass(); // BAD +delete obj; // BAD + +// DO use smart pointers or stack allocation +auto obj = std::make_unique<MyClass>(); // GOOD +MyClass obj; // GOOD (when appropriate) + +// DON'T omit braces for single-line blocks +if (condition) + doSomething(); // BAD + +// DO always use braces +if (condition) +{ + doSomething(); // GOOD +} + +// DON'T use raw pointers for ownership +void takeOwnership(MyClass* ptr); // BAD + +// DO use smart pointers +void takeOwnership(std::unique_ptr<MyClass> ptr); // GOOD + +// DON'T ignore const correctness +void getData(Ptr& ptr); // BAD if not modifying + +// DO use const when appropriate +void getData(const Ptr& ptr) const; // GOOD +``` + +### Virtual Functions and Inheritance + +```cpp +class Base +{ +public: + virtual ~Base() = default; + + /// Pure virtual function + virtual void mustImplement() = 0; + + /// Virtual function with default implementation + virtual void canOverride(); +}; + +class Derived : public Base +{ +public: + // Always use override keyword + void mustImplement() override; + void canOverride() override; + + // Use final to prevent further overriding + void finalMethod() final; +}; +``` + +### Exception Handling + +```cpp +// Throw exceptions for error conditions +void MyClass::validate() +{ + if (!isValid()) + { + throw std::runtime_error("Invalid state detected"); + } + + if (mData.empty()) + { + throw std::logic_error("Data cannot be empty"); + } +} + +// Use specific exception types +void processFile(const std::string& filename) +{ + if (!fileExists(filename)) + { + throw std::invalid_argument("File does not exist: " + filename); + } +} +``` + +### Documentation Comments + +**ALWAYS add Doxygen comments for:** +- All public classes +- All public methods +- All public member variables +- Complex private methods + +```cpp +/// Manages the game's resource loading and caching +/// +/// This class handles asynchronous loading of game resources +/// and maintains a cache to avoid redundant disk access. +class ResourceManager +{ +public: + /// Load a resource by its identifier + /// + /// \param resourceId The unique identifier of the resource + /// \param async If true, load asynchronously + /// \return Pointer to the loaded resource, or nullptr if failed + /// \throws std::runtime_error if resource format is invalid + Resource* loadResource(const ESM::RefId& resourceId, bool async = false); + + int mCacheSize; ///< Maximum number of cached resources +}; +``` + +## Common OpenMB Patterns + +### Using Project Types + +```cpp +// ESM::RefId for game object identifiers +ESM::RefId mItemId; +ESM::RefId mSpellId; + +// Ptr and ConstPtr for game object references +void processObject(const MBWorld::ConstPtr& ptr); +void modifyObject(MBWorld::Ptr& ptr); + +// Common project classes +MBWorld::CellStore* cell; +MBBase::Environment& env = MBBase::Environment::get(); +``` + +### Initialization Lists + +**ALWAYS use initialization lists for constructors:** + +```cpp +MyClass::MyClass(int value, const std::string& name) + : mValue(value) + , mName(name) + , mCounter(0) + , mIsActive(false) +{ + // Constructor body for additional logic only +} +``` + +### Const Correctness + +```cpp +class DataManager +{ +public: + // Non-const methods for modification + void addData(int value); + void clearData(); + + // Const methods for reading only + int getDataCount() const; + bool hasData() const; + const std::vector<int>& getData() const; + + // Return const reference when not modifying + const std::string& getName() const { return mName; } + +private: + std::vector<int> mData; + std::string mName; +}; +``` + +### Error Handling in Base Classes + +```cpp +// Use exceptions for unsupported operations in base classes +class GameObjectBase +{ +public: + virtual InventoryStore& getInventoryStore(const Ptr& ptr) const + { + throw std::runtime_error("This object type does not have an inventory"); + } + + virtual float getWeight(const Ptr& ptr) const + { + throw std::runtime_error("This object type does not have weight"); + } +}; +``` + +## File Organization + +### Header File Template + +```cpp +#ifndef OPENMB_<PATH>_H +#define OPENMB_<PATH>_H + +// Includes in proper order +#include <standard/library> + +#include <external/library> + +#include <components/project/header.hpp> + +// Forward declarations +namespace MBWorld +{ + class Ptr; +} + +namespace <YourNamespace> +{ + /// Class documentation + class ClassName + { + public: + // Public interface + + protected: + // Protected members + + private: + // Private members + // All member variables with 'm' prefix + }; +} + +#endif +``` + +### Implementation File Template + +```cpp +#include "classname.hpp" + +#include <algorithm> +#include <stdexcept> + +#include "../other/project/headers.hpp" + +namespace <YourNamespace> +{ + ClassName::ClassName() + : mMember1() + , mMember2(0) + { + } + + void ClassName::method() + { + // Implementation + } +} +``` + +## Platform Considerations + +```cpp +// Avoid platform-specific code when possible +// If necessary, use clear preprocessor guards + +#ifdef _WIN32 + // Windows-specific code +#elif defined(__linux__) + // Linux-specific code +#elif defined(__APPLE__) + // macOS-specific code +#else + #error "Unsupported platform" +#endif + +// Prefer cross-platform solutions +#include <filesystem> // C++17 cross-platform filesystem +namespace fs = std::filesystem; +``` + +## Testing and Validation + +When generating code, consider: + +1. **Is the code cross-platform compatible?** +2. **Are all member variables initialized?** +3. **Is const correctness maintained?** +4. **Are there proper Doxygen comments?** +5. **Does it follow the naming conventions?** +6. **Is memory managed safely (RAII/smart pointers)?** +7. **Are exceptions used appropriately?** +8. **Does it follow the brace style (Allman)?** + +## Quick Reference Checklist + +Before generating code, verify: + +- [ ] Braces on their own line (Allman style) +- [ ] 4 space indentation (no tabs) +- [ ] Member variables have 'm' prefix +- [ ] Functions use camelCase +- [ ] Classes use PascalCase +- [ ] Include guards follow OPENMB_<PATH>_H format +- [ ] Includes are in correct order +- [ ] Const correctness is maintained +- [ ] Smart pointers used instead of raw pointers for ownership +- [ ] Override keyword used for virtual functions +- [ ] Doxygen comments on public APIs +- [ ] Initialization lists used in constructors +- [ ] Namespaces properly indented +- [ ] Line length under 120 columns +- [ ] Exception handling for error conditions + +## Example: Complete Class Generation + +When asked to create a new class, generate both header and implementation following this pattern: + +**Header (playermanager.hpp):** +```cpp +#ifndef OPENMB_APPS_OPENMB_MBWORLD_PLAYERMANAGER_H +#define OPENMB_APPS_OPENMB_MBWORLD_PLAYERMANAGER_H + +#include <memory> +#include <string> +#include <vector> + +#include <components/esm/refid.hpp> + +namespace MBWorld +{ + class Ptr; + class CellStore; + + /// Manages player state and interactions + /// + /// This class handles player initialization, state updates, + /// and interactions with the game world. + class PlayerManager + { + public: + PlayerManager(); + ~PlayerManager() = default; + + /// Initialize the player in the game world + /// \param playerId The unique identifier for the player + /// \param startCell The starting cell for the player + /// \return True if initialization succeeded + bool initialize(const ESM::RefId& playerId, CellStore* startCell); + + /// Update player state + /// \param deltaTime Time elapsed since last update in seconds + void update(float deltaTime); + + /// Get the current player pointer + /// \return Const reference to the player pointer + const Ptr& getPlayer() const; + + /// Check if player is initialized + bool isInitialized() const; + + private: + /// Load player data from save + void loadPlayerData(const ESM::RefId& playerId); + + /// Validate player state + bool validateState() const; + + Ptr mPlayer; + ESM::RefId mPlayerId; + bool mIsInitialized; + float mTimeSinceLastUpdate; + }; +} + +#endif +``` + +**Implementation (playermanager.cpp):** +```cpp +#include "playermanager.hpp" + +#include <stdexcept> + +#include "../mbbase/environment.hpp" +#include "cellstore.hpp" +#include "ptr.hpp" + +namespace MBWorld +{ + PlayerManager::PlayerManager() + : mPlayer() + , mPlayerId() + , mIsInitialized(false) + , mTimeSinceLastUpdate(0.0f) + { + } + + bool PlayerManager::initialize(const ESM::RefId& playerId, CellStore* startCell) + { + if (!startCell) + { + throw std::invalid_argument("Start cell cannot be null"); + } + + if (playerId.empty()) + { + throw std::invalid_argument("Player ID cannot be empty"); + } + + mPlayerId = playerId; + loadPlayerData(playerId); + + // Additional initialization logic here + + mIsInitialized = validateState(); + return mIsInitialized; + } + + void PlayerManager::update(float deltaTime) + { + if (!mIsInitialized) + { + throw std::runtime_error("Cannot update uninitialized player"); + } + + mTimeSinceLastUpdate += deltaTime; + + // Update logic here + } + + const Ptr& PlayerManager::getPlayer() const + { + if (!mIsInitialized) + { + throw std::runtime_error("Player not initialized"); + } + + return mPlayer; + } + + bool PlayerManager::isInitialized() const + { + return mIsInitialized; + } + + void PlayerManager::loadPlayerData(const ESM::RefId& playerId) + { + // Load implementation + } + + bool PlayerManager::validateState() const + { + // Validation implementation + return true; + } +} +``` + +## Summary + +When generating code for OpenMB: +1. Follow Allman brace style (braces on own lines) +2. Use proper naming (mMemberVars, camelCaseFunctions, PascalCaseClasses) +3. Include Doxygen documentation +4. Use modern C++20 features +5. Maintain const correctness +6. Use smart pointers and RAII +7. Follow include order and guards +8. Keep code cross-platform + +**Remember: Consistency with existing code is paramount. When in doubt, follow the patterns already established in the codebase.** |