Contributing

Welcome Contributors

Thank you for your interest in contributing to Hydra! This guide will help you get started with contributing code, reporting issues, and collaborating with the community.

Getting Started

Prerequisites

Before contributing, make sure you:

Build Hydra from source - See Building
Understand the architecture - Read Architecture
Join the Discord - Hydra Discord Server for real-time discussion
Review existing issues - Check GitHub Issues

Setting Up Your Development Environment

Fork the repository

Create a fork of the Hydra repository on GitHub:

# Click 'Fork' on https://github.com/SamoZ256/hydra

Clone your fork

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/hydra.git
cd hydra
git submodule update --init --recursive

Add upstream remote

Add the original repository as upstream:

git remote add upstream https://github.com/SamoZ256/hydra.git

Build and test

Ensure you can build successfully:

cmake . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DMACOS_BUNDLE=ON
ninja -C build

Code Style Guidelines

Hydra follows strict code style guidelines to maintain consistency across the codebase.

C++ Code Style

Formatting

Hydra uses clang-format for automatic code formatting. The configuration is defined in .clang-format:

DerivePointerAlignment: false
PointerAlignment: Left
TabWidth: 4
IndentWidth: 4
AlwaysBreakTemplateDeclarations: Yes

Format your code before committing:

clang-format -i src/**/*.cpp src/**/*.hpp

Naming Conventions

// Use PascalCase for classes and structs
class EmulationContext {
    // ...
};

struct GuestThread {
    // ...
};

Pointer and Reference Alignment

// Pointers and references aligned LEFT
void* pointer;      // Correct
int& reference;     // Correct

void *pointer;      // Incorrect
int &reference;     // Incorrect

Headers and Includes

// Order: Standard library -> Third-party -> Project headers
#include <vector>
#include <string>

#include <fmt/format.h>

#include "core/emulation_context.hpp"
#include "hw/tegra_x1/gpu/gpu.hpp"

Swift Code Style (SwiftUI Frontend)

// Use Swift standard naming conventions
class GameListView: View {
    @State private var selectedGame: Game?
    
    var body: some View {
        // ...
    }
    
    func loadGames() {
        // ...
    }
}

CMake Style

# Use lowercase for commands
set(CMAKE_CXX_STANDARD 20)
add_library(hydra-core ...)
target_link_libraries(hydra-core PRIVATE fmt)

# Use descriptive variable names
set(FRONTEND "SDL3" CACHE STRING "Frontend to use")

Compilation Requirements

Compiler Warnings

Hydra treats all warnings as errors via -Werror. Ensure your code compiles without warnings:

# Enabled warning flags:
-Wall -Wextra -Wconversion -Wsign-conversion -Wno-vla-cxx-extension

C++ Standards

Required: C++20
Features used: Concepts, ranges, designated initializers, modules (future)

// C++20 features are encouraged
auto process_data(std::span<const uint8_t> data) -> void {
    // ...
}

Development Workflow

Creating a Feature Branch

Sync with upstream

git fetch upstream
git checkout main
git merge upstream/main

Create feature branch

Use descriptive branch names:

# Feature branches
git checkout -b feature/implement-audio-filter

# Bug fix branches
git checkout -b fix/texture-cache-crash

# Service implementation
git checkout -b service/implement-caps-service

Make your changes

Edit code, following style guidelines

Test your changes

Build and test thoroughly:

ninja -C build
# Test with actual games/homebrew

Commit Messages

Write clear, descriptive commit messages:

git commit -m "gpu: Implement texture border color support"
git commit -m "service/am: Fix application exit handling"
git commit -m "frontend/swiftui: Add game icon caching"
git commit -m "docs: Update build instructions for Xcode 15"

Commit Guidelines

One logical change per commit
Prefix with component area (gpu, cpu, service/xxx, frontend, build, docs)
Use imperative mood (“Add feature” not “Added feature”)
Keep first line under 72 characters
Add detailed explanation for complex changes

Pull Request Process

Before Submitting

Code quality checks

Code compiles without warnings
clang-format applied
No debug code or commented-out sections
All new code follows style guidelines

Testing

Test with multiple games/homebrew
Verify no regressions
Check both Debug and Release builds

Documentation

Update relevant documentation
Add code comments for complex logic
Document new CMake options

Submitting a Pull Request

Push your branch

git push origin feature/your-feature-name

Create pull request

Go to https://github.com/SamoZ256/hydra/pulls and click “New Pull Request”

Fill out PR template

Title: Descriptive summaryDescription:

## Summary
Brief description of changes

## Changes
- Implemented X feature
- Fixed Y bug
- Improved Z performance

## Testing
- Tested with Game A: Works correctly
- Tested with Homebrew B: No regressions

## Screenshots (if UI changes)
[Add screenshots]

Respond to reviews

Address reviewer feedback promptly
Push additional commits if needed
Discuss design decisions in comments

PR Review Criteria

Your PR will be reviewed for:

Code quality: Follows style guidelines, well-structured
Correctness: Implements feature correctly, no bugs introduced
Performance: No unnecessary performance regressions
Compatibility: Works on all supported macOS versions
Documentation: Code is well-commented and documented

Areas for Contribution

High Priority

Service implementations: Many system services need implementation
GPU accuracy: Improve Maxwell emulation accuracy
Performance: Optimize hot paths
Game compatibility: Fix issues with specific games

Service Implementation

To implement a new service:

Check src/core/horizon/services/ for existing patterns
Create service class inheriting from Service
Implement IPC command handlers
Register service in service manager
Test with games that use the service

GPU Features

To add GPU features:

Study Maxwell architecture documentation
Locate relevant engine code (src/core/hw/tegra_x1/gpu/engines/)
Implement in Metal renderer (src/core/hw/tegra_x1/gpu/renderer/metal/)
Update shader decompiler if needed

Frontend Improvements

SDL3: Improve controller support, add hotkeys
SwiftUI: Enhance UI/UX, add features

Testing Guidelines

Manual Testing

Test your changes with:

Homebrew apps: Simple test cases
Commercial games: Real-world testing
Edge cases: Unusual configurations

Regression Testing

Verify previously working games still work
Test both frontends (SDL3 and SwiftUI)
Test Debug and Release builds

Performance Testing

# Profile with Instruments
open -a Instruments build/bin/Hydra.app

# Check for memory leaks
leaks -atExit -- build/bin/Hydra.app

Debugging

GDB Debugger

Hydra includes a built-in GDB server:

# Enable in config.toml
[debugger]
enabled = true
port = 1234

# Connect with LLDB
lldb
(lldb) gdb-remote localhost:1234

Xcode Debugging

# Generate Xcode project
cmake . -B build -G Xcode
open build/hydra.xcodeproj

Logging

Use fmt::print for debug logging:

#ifdef HYDRA_DEBUG
    fmt::print("[GPU] Texture format: {}\n", format);
#endif

Communication

Discord Server

Join the Hydra Discord for:

Development discussion
Technical questions
Coordination on features
Community support

GitHub Discussions

Use GitHub Discussions for:

Feature proposals
Architecture discussions
Long-form technical topics

Issue Tracker

Use GitHub Issues for:

Bug reports
Feature requests
Tracking work

Reporting Issues

When reporting bugs, include:

System information

macOS version
Hardware (Intel vs Apple Silicon)
Hydra version/commit hash

Reproduction steps

Clear steps to reproduce
Expected behavior
Actual behavior

Additional context

Game/homebrew name and version
Screenshots/videos if applicable
Relevant logs
Config file (if customized)

License

Hydra is licensed under GPL-3.0. By contributing, you agree that your contributions will be licensed under the same license. Key points:

All contributions must be compatible with GPL-3.0
Original code must be your own or properly attributed
Third-party code must have compatible licenses

Code of Conduct

Be Respectful

Treat all contributors with respect
Welcome newcomers
Provide constructive feedback
Be patient with questions

Be Collaborative

Discuss design decisions openly
Accept feedback gracefully
Help review others’ contributions
Share knowledge

Quality Standards

Write clean, maintainable code
Test thoroughly before submitting
Document complex logic
Follow established patterns

Resources

Documentation

Building Guide: Building from Source
Architecture: System Architecture
GitHub: SamoZ256/hydra

External Resources

Nintendo Switch Homebrew: switchbrew.org
Metal Documentation: Apple Metal
ARM Architecture: ARM Developer
Maxwell GPU: NVIDIA documentation

Community

Discord: Join Server
GitHub Issues: Issue Tracker
GitHub Discussions: Discussions

Thank You

Your contributions make Hydra better for everyone. Whether you’re fixing bugs, implementing features, improving documentation, or helping other users, your efforts are appreciated! Happy coding, and welcome to the Hydra development community!

Getting Started

API Reference

​Welcome Contributors

​Getting Started

​Prerequisites

​Setting Up Your Development Environment

​Code Style Guidelines

​C++ Code Style

​Formatting

​Naming Conventions

​Pointer and Reference Alignment

​Headers and Includes

​Swift Code Style (SwiftUI Frontend)

​CMake Style

​Compilation Requirements

​Compiler Warnings

​C++ Standards

​Development Workflow

​Creating a Feature Branch

​Commit Messages

​Commit Guidelines

​Pull Request Process

​Before Submitting

​Submitting a Pull Request

​PR Review Criteria

​Areas for Contribution

​High Priority

​Service Implementation

​GPU Features

​Frontend Improvements

​Testing Guidelines

​Manual Testing

​Regression Testing

​Performance Testing

​Debugging

​GDB Debugger

​Xcode Debugging

​Logging

​Communication

​Discord Server

​GitHub Discussions

​Issue Tracker

​Reporting Issues

​License

​Code of Conduct

​Be Respectful

​Be Collaborative

​Quality Standards

​Resources

​Documentation

​External Resources

​Community

​Thank You

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

Prerequisites

Setting Up Your Development Environment

Code Style Guidelines

C++ Code Style

Formatting

Naming Conventions

Pointer and Reference Alignment

Headers and Includes

Swift Code Style (SwiftUI Frontend)

CMake Style

Compilation Requirements

Compiler Warnings

C++ Standards

Development Workflow

Creating a Feature Branch

Commit Messages

Commit Guidelines

Pull Request Process

Before Submitting

Submitting a Pull Request

PR Review Criteria

Areas for Contribution

High Priority

Service Implementation

GPU Features

Frontend Improvements

Testing Guidelines

Manual Testing

Regression Testing

Performance Testing

Debugging

GDB Debugger

Xcode Debugging

Logging

Communication

Discord Server

GitHub Discussions

Issue Tracker

Reporting Issues

License

Code of Conduct

Be Respectful

Be Collaborative

Quality Standards

Resources

Documentation

External Resources

Community

Thank You