Contributing

May 18, 2026 · View on GitHub

We love receiving PRs from the community with features and fixes. For big feature it's advised to raise an issue to discuss it first.

Getting Started

First Setup

To get started, clone the source code and run the initialization script:

# Clone the repository
git clone https://github.com/getsentry/sentry-unreal.git
cd sentry-unreal

# Run initialization (macOS/Linux)
./scripts/init.sh

# Run initialization (Windows)
./scripts/init-win.ps1

This script links the checked out version of the plugin (the plugin-dev directory) to the playground project (the sample directory) and downloads the latest pre-built SDK dependencies from CI using GitHub CLI.

Tip

When working with a sentry-unreal fork, run gh repo set-default to select the default remote repository used for GitHub API queries (required for pulling plugin dependencies from CI). If you don't plan to configure the CI pipeline for your fork, it's recommended to set getsentry/sentry-unreal as the default remote.

After that, you can generate project files for SentryPlayground.uproject to open it in your IDE and make changes to the SDK as you would with any other Unreal project.

Building Plugin Dependencies Locally

By default, the initialization scripts download pre-built SDK dependencies from CI. If you need to build platform dependencies locally (e.g., for development or debugging) you can use the build-deps.ps1 script.

The plugin uses the following platform-specific SDKs:

sentry-native - Windows support (requires Windows)
sentry-cocoa - Mac and iOS support (requires macOS)
sentry-java - Android support (any platform)

To build dependencies locally, first obtain the SDK source code, configure environment variables (optional) and run the build script:

# One-time: Set environment variables
$env:SENTRY_NATIVE_PATH = "D:\projects\sentry-native"
$env:SENTRY_COCOA_PATH = "D:\projects\sentry-cocoa"
$env:SENTRY_JAVA_PATH = "D:\projects\sentry-java"

# Option 1: Build all SDKs for current platform (uses environment variables)
./scripts/build-deps.ps1 -All

# Option 2: Build specific SDKs
./scripts/build-deps.ps1 -Native -Java
./scripts/build-deps.ps1 -Cocoa

# Option 3: Build with custom paths (without setting environment variables)
./scripts/build-deps.ps1 -Native -NativePath "D:\projects\sentry-native"
./scripts/build-deps.ps1 -All -CocoaPath "D:\custom\sentry-cocoa"

The script pre-builds the SDK binaries and copies them to plugin-dev/Source/ThirdParty directory, replacing any existing binaries.

Note

Windows: -All builds Native + Java (Cocoa requires macOS)
macOS: -All builds Cocoa + Java (Native requires Windows)

Modifying Plugin Content

All files that belong to the plugin are listed in the snapshot file:

/scripts/packaging/package.snapshot

If you add, delete or move files within the plugin-dev directory this snapshot file must be updated to reflect the changes. To do that, run:

pwsh ./scripts/packaging/pack.ps1
pwsh ./scripts/packaging/test-contents.ps1 accept`

Once completed, make sure to commit the updated snapshot files to Git.

CI will run a separate check to compare the actual plugin package contents against the snapshot file.

Building for Consoles

The Sentry Unreal SDK provides consoles support via platform extensions:

Once you've obtained the extension source code, run the following commands to complete the setup:

# One-time: Set environment variables
$env:SENTRY_SWITCH_PATH = "D:\projects\sentry-switch"
$env:SENTRY_PLAYSTATION_PATH = "D:\projects\sentry-playstation"
$env:SENTRY_XBOX_PATH = "D:\projects\sentry-xbox"

# Option 1: Setup all platforms
./scripts/init-consoles.ps1 -All

# Option 2: Setup specific platforms
./scripts/init-consoles.ps1 -Switch -Switch2 -PS5 -XSX -XB1 -WinGDK

# Option 3: Setup individual platform without configuring environment variables
./scripts/init-console-ext.ps1 -Platform Switch -ExtensionPath D:\projects\sentry-switch

These scripts pre-build the binaries required for consoles and copy them to sample project dir accordingly. They also symlink extension source files so that changes made while working with sentry-unreal are automatically tracked in the corresponding extension repositories.

Tip

For more details about the environment and Unreal Engine setup required for console development, refer to the corresponding plugin extension repositories' unreal/CONTRIBUTING.md files.

Plugin Structure

Sentry Unreal SDK consists of two modules:

SentrySDK - it declares the plugin API and contains separate implementations for each platform that is supported.
SentryEditor - contains editor utilities like customizations for plugin settings menu, tools allowing to re-compile or download dependencies, etc.

Other Sentry libraries are provided along with the plugin source code and can be found in Source/ThirdParty directory.

Sample Project

There is a demo level (SentryDemo.umap) in project's Content folder which presents a simple UI allowing to send some test events to Sentry. W_SentryDemo blueprint implementation shows how to call the plugin API and can be used as a reference.

In order to run the demo level navigate to Content Browser -> Content -> Maps and open SentryDemo map. Hit play to launch the demo.

Refer to sample project README.md for more details.

Important

When modifying binary assets in the sample project (e.g., Blueprints), use the oldest supported Unreal Engine version to maintain their compatibility across all supported versions. Refer to the EngineAssociation property in sample/SentryPlayground.uproject on the main branch for the correct version.

Automation Testing

In order to run automation tests via Editor navigate to Settings -> Plugins -> Testing and enable all the plugins available there. Editor restart will be required for the changes to take effect. After that Windows -> Test Automation menu will appear which opens the Session Frontend window. Switch to Automation tab there and select Sentry within the list of existing tests. Hit Start Tests button to run the tests and check the result.

Tests source code can be found at plugin-dev/Source/Sentry/Private/Tests.

Documentation

Sentry Unreal SDK has the official documentation. When introducing a new feature, make sure it's properly documented by opening a corresponding pull request in the sentry-docs repository and linking it to your PR here.