GitHub Sharing Hub

From Epic Wiki
Jump to: navigation, search


GitHub is a fantastic resource for sharing changes and adding new features to UE4. Though the developers cannot always implement the changes they are given from the community, you can still make the changes to the engine if you so choose. Here you can browse a list of pulls or add your own.

GitHub submission pages must include the version of UE4 it is compatible with, author's name, size, date, a link and a description. Remember, only link to github commits and pull requests that are under a fork of UnrealEngine. That will make sure that there are no conflicts with the EULA in regards to code-sharing.

Note: If clicking on a link throws a 404 error, check to make sure you have your GitHub account associated with your Epic account as outlined here and are logged into GitHub. You must complete these steps in order to view forks of the Unreal Engine source.

Title Link Version Author Size Release Description
Example 4.0 J. Doe 100MB 01/01/2015 This is an example
GitDepsPacker 4.7+ Artem V. Navrotskiy 1MB 10/01/2015 Unofficial utility to create *.gitdeps.xml files for Unreal Engine 4.7+.
octobuild 4.8+ Artem V. Navrotskiy 1MB 23/11/2015 Compilation cache (like ccache)
Game Build 4.10+ Satheesh PV (ryanjon2040) 1MB 24/01/2016 BlueprintPure method that returns the type of build. This is useful for running any functions just for testing and to skip in any other build.
Toon Shading 4.10+ < 1MB 09/14/2015 Toon Shading model
4.10 Support for Xcode 7.3 4.10 Derek van Vliet <1MB 24/03/2016 Resolves errors that occur when compiling 4.10 using Xcode 7.3
Menu Fix 4.12 Robert Khalikov <1MB 14/04/2016 Fixes appearance of menu items that don't have icons assigned to them (follow the link to see the screenshot).
Alpha Composite Blend Mode 4.11+, integrated in 4.13 by Epic Moritz Wundke (Moss) <1MB 29/02/2016 Adding Alpha Composite aka 'pre-multiplied alpha' to the blend modes. Used in VFX such as Diablo III.
Toggle Light Propagation Volumes at Runtime 4.11 Michael Fortin <1MB 15/06/2016 Allow toggling of Global Illumination through Light Propagation Volumes at runtime. Tested in 4.8 and 4.11.
Intel Hardware Metrics for DX11/12 4.12 Jeff Rous (Intel) 150MB 06/28/2016 Adds a stat command to get data from Intel hardware counters through a driver interface.
Additional Ease functions 4.8+ Moritz Wundke (Moss) <1MB 12/17/2015 Partially merged into engine. Adds Elastic, Bounce and Back functions. Lets you customize the Amplitude, period and overshoot if the functions supports it.
Vehicle optimization via concurrent PxVehicleUpdate 4.15+ Deniz Piri (Ahoy Games) <1MB 03/09/2017 This patch makes PxVehicleUpdate be used concurrently from multiple threads (using TaskGraph).
Override functions context menu search functionality 4.18+ projectgheist <1MB 12/22/2017 Makes it possible to do a search query in the Override functions context menu.


GitHub submissions can be added to provide developers with various changes to the engine. If you'd like to add your repository to the page, please make sure to include the version, size, release date, link and a description of the changes made.

Share your project

While creating a fork is straightforward distributing a project will require some additional steps to be guarded by the EULA. The idea we will show you is very simple, we just create a new branch in an exiting engine fork (the fork must lie within an account that has been added to Epics Organization) and get rid of the history which results in a so called orphan branch.

Create an orphan branch:

git checkout --orphan MyProjectBranch
git rm -rf .

Add your content and commit it:

git add .
git commit -m "Initial Commit"

Push it back to GitHub tracking the new branch:

git push -u origin MyProjectBranch

Now you will have a shiny new branch that has it's own history and is living in your engine fork safely guarded by the EULA.

Submitting Pull Requests

This small guide will show you a common pipeline to submit and update your pull requests to the engines upstream (aka. main git).

Create a Pull Request

A pull requests is just a bunch of commits that are send the engines upstream to be integrated in the main branch. It's the main way to contribute to the engine.

Creating a pull requests is simple yet a challenge at times. One of the main errors when submitting a PR is creating it from a non clean history. What I mean by that is that you may be submitting the PR from a branch you actively work on and not only the explicit PR changes but all the differences between your branch and the one you submit the PR to will be pushed up.

So the first pull a clean version of the branch you will submit your PR to. I normally let all branches that come the upstream clean and just create my own branches from those. This way I just have to sync the clean branches (we will call them vendor branches from now on).

As an example we will use the release branch for our examples for now. You can also use the master branch it may not compile.

In case you have not set the upstream to the main git just use.

Warning: This guide does not work for pull requests. Use instead.

git remote add upstream

First we will switch to the release branch

git checkout release

or in case you haven't checked it out never (more info remotes)

git checkout -b release origin/release

So to sync your branch with the changes from the upstream we will simply pull and merge the changes.

git fetch upstream
git merge upstream/release


Update an existing Pull Request


Integrate into your own fork

The following guide will show you how to integrate a given PullRequest into your own engine fork. In this case we will try to integrate the original Toon Shading PullRequest into a clean 4.10 engine fork (the code is made for 4.11+ to show you how a hard case is handled). The final version can be found here:

What do you need


So first we will start of creating a 4.10 branch (using a specifc branch will give you the ability to try yourself and replicate the following steps), if you already have one then you can just skip this part and jump directlty to Adding the PRs remote.

git clone<your/github/user>/UnrealEngine.git -b 4.10

Once forked we ensure that the branch is updated to Epics 4.10 branch, when in development I always try to be as updated as possible. You may not want to update your branch but for sake of consistence I will go through the process of updating your fork.

First we will have to add a new remote that will point to the oficial UnrealEngine repository, this remote will be called upstream. Again, if you already have it configured just jump to Adding the PRs remote.

git remote add upstream

Now that our upstream is setup we just merge the changes in. We can use the merge or the pull commands, if you use merge remember to fetch the latest 4.10 branch from the upstream.

git fetch upstream 4.10
git merge upstream 4.10

Some folk prefer not to merge the entire history in, so if you just want a single commit generated by the merge command just add the --squash argument

git merge upstream 4.10 --squash

Ok now we have our nice 4.10 branch, let's create a new one from it that we use to hold the PR in. Using a seperate branch will helo you integrating it and if you are activily developing it will give you a sandbox test bed to test the PR appropiatly.

git checkout -b ToonShading.4.10
git push -u origin ToonShading.4.10

Nice we now have our separate updated 4.10 branch to play with!

Adding the PRs remote

To pull the changes in we will have to add a new remote to our git, a PR is actually just a collection of commits of diffs from one fork onto another, this is way when you commit to a branch that you made a PR the PR will get updated with those commits.

So first we have to discover the fork that the PR was made of, in our case the Toon shading model PR comes with a set of commits

Those commits will yield to so adding it as a new remote would be as follows:

git remote add toonUpstream

And let us fetch the branch where the actual PR lives in

git fetch toonUpstream master

Cherry pick the commits

The ^ is important, if not you wont pickup A but only what comes after A

git cherry-pick A^..B

So now we have to identify the commit we want to range cherrypic (supported from git 1.7.2+, in case you have a lower version you would use rebase instead). We simply check the commit made to the PR at (in our case which results in the following commands. Unfortunatly in the case of the Toon Shading PR we can not just cherry-pick a range of commits, so we have to cherrypick them one by one and resolve any conflicts that could we could get, the good news is that our commit will be consecutive and you could squash them together later on.

git cherry-pick 311cbeb

This one is tricky (actually all are tricky), a lot of rendering and shader code has been changed in the master branch. So what we get are conflicts due to the fact that the master is ahead the 4.10 branch. Let's pickup `DeferredhadingCommon.usf`:

The following conflict contains changes from the PR and changes made to the master itself.

Conflict example.png
A nice conflict to resolve

So the way to filter them out is to check what the PR changed and what are changes made by Epic and only applying those from the PR.

Conflict solved example.png
Aaaaaann it's solved

Another change we will perform on the PR is adding new material parameters to not reuse the default ones, the PR uses a set of custom pins that will be available in newer versions of the engine but for 4.10 we better add some custom ones (the more you know). So we will resolve the following conflicts as shown.

Fixing pused conflic.png
Tweaking and redoing

will become

Some custom changes.png
Not bad at all

The PR contains actually a lot more commits because the original author tried to update it to newer verions of the master branch. In our case we are good to go with what we have at the moment.

You have to carefully integrate changes that come from the master branch into your own due to the fact that you may pull not only changes from the PR itself but changes made in the actual master branch. It does not help that many PRs are not only pushing only their changes, people tend to sync their fork and so their PR get's really messy and you really lose track of what are actually changes from the PR or from Epic.

Too much rebase.png
Ok sometimes we might need a fresh start

The commits we wont actually cherry-pick:

git cherry-pick 8511fb9
git cherry-pick b69ddc0
git cherry-pick ccdf074
git cherry-pick 5abf035
git cherry-pick 2849422
git cherry-pick 4b77319

Sometimes it is easier to perform the cherrypick in the same branch that the PR is based of and then squashing/pulling the final result into the desired branch.

So after all the work and fixing code let us post our final result:

Toon shading.png
It was well worth the effort! Mhh that arrow is kinda pointy

But before we are done ensure to commit and push your integration. I recommend you to push it all in a single commit, if not backtracking any possible bugs will be hell.

In case you want to check all the changes I had to make I pushed them to so you will be able to just pick them and use them easily.

Final thoughts

When integrating engine changes it is always wise to mark those changes in some way. Now you ask why the heck should I mark those? Git will handle it for me. The answer is yes and no. Git knows about the history for sure but what if Epic decides to integrate that particular change you already merged into your own fork but you made some minor tweaks to it. So when it comes to updating to a new engine version all that conflict horror and not knowing what was from the PR, what was yours and what was done by Epics starts again without any hint.

It is common to tag any change made to the engine to avoid nasty bugs and silent changes that might go unoticed until a major bug touches the surface and those bugs come alive normally when you are stressing your game aka shipping it :)

So what I encourage you to do when changing any engine code is to add some *start/end* tags to your changes, also those tags should be descriptive enough to know what's all about and make it easier to spot a *start/end* pair. The following is an example of what is commonly used in the industry.

// --> <Compan or project tag> by <Who integrated it?> <Date here> - <Descriptoion, link to PR, commit from Epic, etc>
// ... Engine changes in here
// <-- <Compan or project tag> by <Who integrated it?> <Date here> - <Descriptoion, link to PR, commit from Epic, etc>

So the first change in *MaterialShader.cpp* could be tagged as follows

case MSM_TwoSidedFoliage:   ShadingModelName = TEXT("MSM_TwoSidedFoliage"); break;
// --> TOON by Moss 1/1/2016 - Integrated toon shader from
case MSM_Toon:              ShadingModelName = TEXT("MSM_Toon"); break;
// <-- TOON by Moss 1/1/2016 - Integrated toon shader from
default: ShadingModelName = TEXT("Unknown"); break;

I hope this guide could be useful for you when it comes to integrating a community Pull Request of a feature you need and Epic might not be able to integrate any time soon.