Contributing to Adastrea

March 8, 2026 · View on GitHub

First off, thank you for considering contributing to Adastrea! It's people like you that make Adastrea such a great project.

Code of Conduct
Getting Started
Development Workflow
Coding Standards
Submitting Changes
Reporting Bugs
Feature Requests

Before You Start

📍 Check the Project Roadmap: Before contributing, review our ROADMAP.md to understand:

Current development priorities and phases
Planned features and systems
Timeline and milestones
How your contribution fits into the bigger picture

Code of Conduct

This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. Please be respectful and constructive in all interactions.

Getting Started

Prerequisites

Unreal Engine 5.6 (check the .uproject file for the exact version)
Visual Studio 2022 (Windows) or Xcode (Mac) for C++ development
Git for version control
Basic knowledge of Unreal Engine, C++, and Blueprint scripting

Setting Up Your Development Environment

Fork and Clone

git clone https://github.com/YOUR_USERNAME/Adastrea.git
cd Adastrea

Validate Environment (Recommended)
```
# Use the automated setup validation scripts
./SetupCheck.sh              # Linux/Mac/WSL
# or
python SetupCheck.py         # Cross-platform
```
These scripts verify:
- Unreal Engine version compatibility
- C++ compiler availability
- Required project folders and files
- Optional: Static code analysis with cppcheck
See README.md for detailed usage.
Generate Project Files
- Right-click on the .uproject file and select "Generate Visual Studio project files"
Build the Project
- Open the generated .sln file in Visual Studio
- Build the project in Development Editor configuration
- Or open the .uproject file directly in Unreal Engine and let it compile
Verify Setup
- Launch the editor and ensure all systems load correctly
- Check that all example Blueprints and Data Assets work
- Refer to Assets/PlaytestingChecklist.md for comprehensive verification

Using Custom Agents

Adastrea provides custom AI agents for GitHub Copilot that have deep knowledge of the project:

Adastrea Developer Expert - Available in .github/agents/adastrea-developer.md

This agent has expertise in:

All core game systems (Spaceships, Factions, Personnel, AI, Trading, etc.)
Unreal Engine 5.6 and C++ best practices specific to Adastrea
Data Asset architecture and Blueprint integration patterns
Project coding standards and conventions

How to use:

@workspace /agent adastrea-developer How do I implement a new faction trait?

See .github/agents/README.md for more information about custom agents.

Development Workflow

Branching Strategy

main - Stable, production-ready code
develop - Integration branch for features
feature/* - New features (e.g., feature/new-ship-system)
bugfix/* - Bug fixes (e.g., bugfix/faction-relationship-crash)
docs/* - Documentation updates

Making Changes

Create a Branch

git checkout -b feature/your-feature-name

Make Your Changes
- Write clean, well-documented code
- Follow the coding standards below
- Add or update tests as needed
- Update documentation
Test Your Changes
- Build the project without errors
- Test in-editor functionality
- Verify Blueprint integration works
- Check that example Data Assets still work
Commit Your Changes
```
git add .
git commit -m "feat: Add detailed description of your changes"
```
Use conventional commit messages:
- feat: - New feature
- fix: - Bug fix
- docs: - Documentation changes
- refactor: - Code refactoring
- test: - Adding tests
- chore: - Maintenance tasks

Coding Standards

C++ Code

Header Files (.h)

#pragma once

#include "CoreMinimal.h"
#include "Engine/DataAsset.h"
#include "YourClassName.generated.h"

/**
 * Brief description of the class.
 * Detailed explanation of what this class does and when to use it.
 */
UCLASS(BlueprintType)
class ADASTREA_API UYourClassName : public UDataAsset
{
    GENERATED_BODY()

public:
    // Properties with clear descriptions
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category="Your Category")
    float SomeValue;

    /**
     * Function description explaining what it does
     * @param ParamName Description of parameter
     * @return Description of return value
     */
    UFUNCTION(BlueprintCallable, Category="Your Category")
    bool YourFunction(int32 ParamName);
};

Best Practices

Use UPROPERTY macros properly:
- EditAnywhere, BlueprintReadWrite for designer-editable values
- BlueprintReadOnly for values that shouldn't be changed in Blueprints
- Always specify a Category
- Use meta= for constraints (ClampMin, ClampMax, MultiLine, etc.)
Use UFUNCTION for Blueprint exposure:
- Mark functions BlueprintCallable if Blueprints should call them
- Mark functions BlueprintPure for getter functions with no side effects
- Add clear parameter and return value documentation
Naming Conventions:
- Classes: UClassName (U for UObject-derived), AClassName (A for Actor-derived), FClassName (F for structs)
- Member variables: CamelCase (e.g., MaxHealth)
- Boolean properties: Prefix with b (e.g., bIsEnabled)
- Functions: CamelCase (e.g., CalculateDamage())
- Constants: ALL_CAPS or kConstantName
Comments:
- Document all public APIs with /** */ Doxygen-style comments
- Explain WHY, not WHAT (code should be self-documenting)
- Add inline comments for complex logic

Blueprint Organization

Naming Convention: BP_SystemName_Purpose (e.g., BP_Faction_TradeStation)
Folder Structure: Organize by system (Ships, Stations, UI, etc.)
Comments: Add comment boxes in complex Blueprint graphs
Functions: Keep Blueprint functions small and focused (max 20-30 nodes)
Variables: Use descriptive names and categories

Data Assets

Naming: Use descriptive names indicating the asset type (e.g., DA_Ship_Pathfinder, DA_Faction_SolarisUnion)
Organization: Group by system in Content Browser
Documentation: Add descriptions to all properties
Templates: Use YAML templates from Assets/ folder as reference

Submitting Changes

Pull Request Process

Update Documentation
- Update README.md if you add/change features
- Add/update guides in Assets/ folder
- Include code comments and docstrings
- Update ROADMAP.md if your changes affect project milestones, phases, or system status
  - Update required for: system completion, phase transitions, new major features, timeline changes
  - Not required for: minor bug fixes, documentation-only changes, small incremental work
Ensure Quality
- Code compiles without errors or warnings
- All systems work in-editor
- Blueprint integration is tested
- No crashes or critical bugs
Create Pull Request
- Push your branch to your fork
- Open a PR against the develop branch (not main)
- Use a clear, descriptive title
- Fill out the PR template completely
- Reference any related issues
- Check the ROADMAP.md update box if applicable
PR Description Should Include:
- Summary of changes
- Motivation and context
- Type of change (bug fix, new feature, breaking change, etc.)
- Testing performed
- Screenshots (if UI changes)
- Checklist of completed items
- Note if ROADMAP.md was updated and why
Review Process
- Respond to feedback promptly
- Make requested changes in new commits
- Be open to suggestions and discussion
- Reviewers may request ROADMAP.md updates if not included