Contributing

Guidelines for contributing to the Hydra emulator project

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:

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

Setting Up Your Development Environment

1. Fork the repository

   Create a fork of the Hydra repository on GitHub:

   # Click 'Fork' on https://github.com/SamoZ256/hydra
   
2. Clone your fork

   Clone your fork locally:

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

   Add the original repository as upstream:

   git remote add upstream https://github.com/SamoZ256/hydra.git
   
4. 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

Classes and Structs

// 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

1. Sync with upstream

   git fetch upstream
   git checkout main
   git merge upstream/main
   
2. 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
   
3. Make your changes

   Edit code, following style guidelines

4. Test your changes

   Build and test thoroughly:

   ninja -C build
   # Test with actual games/homebrew
   

Commit Messages

Write clear, descriptive commit messages:

Good Examples

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

1. Code quality checks

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

   • Test with multiple games/homebrew
   • Verify no regressions
   • Check both Debug and Release builds
3. Documentation

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

Submitting a Pull Request

1. Push your branch

   git push origin feature/your-feature-name
   
2. Create pull request

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

3. Fill out PR template

   Title: Descriptive summary

   Description:

   ## 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]
   
4. 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:

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

GPU Features

To add GPU features:

1. Study Maxwell architecture documentation
2. Locate relevant engine code (src/core/hw/tegra_x1/gpu/engines/)
3. Implement in Metal renderer (src/core/hw/tegra_x1/gpu/renderer/metal/)
4. 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:

1. Homebrew apps: Simple test cases
2. Commercial games: Real-world testing
3. 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:

1. System information

   • macOS version
   • Hardware (Intel vs Apple Silicon)
   • Hydra version/commit hash
2. Reproduction steps

   1. Clear steps to reproduce
   2. Expected behavior
   3. Actual behavior
3. 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!