Skip to content

How To Contribute To The GameGuru Master Build

Lee Bamber edited this page Apr 13, 2018 · 6 revisions

Overview

In order to ensure the official version of GameGuru remains stable, only one person has been designated with the power to merge branches to the master build and release Steam updates. Anyone selected to collaborate can push changes they have made to this person, and these branches can be tested by anyone who has cloned the repository. Once the branch has been tested and approved, it can be added to GameGuru as a real update.

Collaboration

Right now we have a core set of collaborators, but if you have a specific task you would like to work on (such as rewriting the LUA system or fixing a bug) then it's best you create a branch from the master and work on it as an 'experiment'. If you are ready to share what you have created, get in touch with Lee Bamber ([email protected]) and make your proposal about the change you want to push to the master branch.

We are being careful who gets added as a collaborator. You will find we bring in collaborators as freelancers for short-term contract work and promote community members who are constantly contributing to GameGuru with quality changes, but if the proposal is good we are happy to consider all levels of participation.

Creating A Branch

The process of creating a branch is very simple. Simply go to the main page of the repository, which you can do by navigating here: https://github.com/TheGameCreators/GameGuruRepo then selecting the top left button which reads "Branch: master" and then giving your branch a unique name which identifies the addition you will be working on. Remember to use hyphens instead of spaces, and when you are happy with the name click the 'Create Branch:XXX' button where XXX is the name you created. You can then select the Branch tab from the main page to see your branch freshly created.

If you are using SourceTree Git Client you can also create a branch locally on your clone by clicking the BRANCH button from the top menu bar and selecting a unique name in the same style as above. Once you have selected the branch as the one you are working on (right click on the branch shown in your repository history) and select 'Checkout...' which will check out this branch (should be no changes to your local files) and you will now be working on the branch.

You can continue developing on the branch until you ready to commit back up to the server, which you would do again in your SourceTree Git Client, use the STAGE ALL button to select all your file changes into the staging area, then click the COMMIT button in the top left of the screen and type out a good description of what you have changed. Use an asterisk (*) symbol before the note if its a feature that should show up in the changelog, or leave it out if it's just a routine commit that should not show up in a changelog. You can then click the COMMIT button in the bottom right to finally commit. You will then see the PUSH button highlight to indicate you have something to push up to the server, which you can click.

Once your branch changes are pushed to the server, others have the ability to test and review those changes before they are considered for inclusion into the master trunk.

Notes

When you are a collaborator, you will need WRITE permissions in order to be able to commit, push and make pull requests on the master branch. By default you will get READ permissions and an attempt to commit/push your branch will result in an error message such as:

git -c diff.mnemonicprefix=false -c core.quotepath=false push -v --tags --set-upstream origin YourName001:YourName001 remote: Permission to TheGameCreators/GameGuruRepo.git denied to YourName. fatal: unable to access 'https://github.com/TheGameCreators/GameGuruRepo.git/': The requested URL returned error: 403 Pushing to https://github.com/TheGameCreators/GameGuruRepo.git

To get WRITE permissions assigned to your collaborator status, contact [email protected] when you are ready to present your branch for inspection by the community and repository reviewers. It is highly recommended that you test your changes thoroughly to ensure they are clean and that your commit description specifically details the changes. Any commits that vaguely change code across the source code and have no specific purpose are unlikely to be accepted in the short-term which we slowly set up the system to best serve the stability and evolution of GameGuru.

Converting non-PBR to PBR Assets

One of the larger tasks that will take some time to resolve is converting the massive collection of legacy non-PBR assets to proper PBR, which can be as simple as a small tweak and rename, to recreating a model and all its textures. In order to accelerate this process, both with stock media and store and community assets, here is some advice on how to convert your entities to use PBR while retaining backward compatibility with users who wish to keep using the old PBROVERRIDE=0 setting which defaults to the older DX9 level shaders and DNS (non-PBR) texture system.

The first change is to copy and rename the following file convention types (the extension can be DDS or PNG):

_D.dds to _color.dds _N.dds to _normal.dds _S.dds to _gloss.dds

When you are finished, you should have all the original DNS textures plus three new textures as named above. Now create a new texture with the _metalness.dds naming convention and keep this texture black unless the texture has some reflective metal you wish to come through in the PBR render.

Be aware the _normal.dds texture may need the green channel (-Y) inverting to produce the correct normal mapping effect when combined with your models' normals. Testing your PBR model after the full conversion is advised before confirming your new normal texture is correct.

The next step is to make sure your _gloss.dds texture is a representation of roughness, not glossiness, so, therefore, a black color denotes shiny and a white color denotes rough. As this was copied directly from the specular, it may be correct, but it may also be too shiny or too rough. Make a judgment call and adjust the texture accordingly, and as reference metals and plastics are shiny (black), whereas brick, stone, and wood are rough (white).

The final step once your textures are prepared is to open the FPE associated with the entity and edit two lines:

textured = yourtexture_D.dds to yourtexture_color.dds effect = effectbank\reloaded\entity_basic.fx to effectbank\reloaded\apbr_basic.fx

This is done so that the game engine knows to use the new PBR shader and new PBR texture set for the entity. For users with the PBROVERRIDE=0 set, these lines will revert to using the original DNS textures and legacy shaders. For most users, however, this change means the entity will be loaded in as a PBR entity and have the benefit of the new DX11 shaders.

Once your FPE and new textures are saved alongside the other entity files, you can load GameGuru to test your conversion. As usual, drag and drop the entity into a blank level and run test game. When in test game press F11 twice, then use the numeric keys at the top [1] through [9] to view the different layers of the PBR rendering system. Using this handy debug method you can double check your albedo, normal, gloss, metalness and related lighting stages are as required.

If you want to take the conversion a stage further, you can edit the textures you have so far created to pick out the materials represented in the textures, so for example nails, metal plates embedded inside a blank of wood could be painted into the gloss and metalness textures to bring those details out.

A further enhancement is to use the Ambient Occlusion texture to paint in local shadows for small detail greases and dark areas that would otherwise be missed by the larger scale global lighting system. To create one, simply add a _ao.dds texture to the texture set and start with a fully white texture. This represents a surface with no shadows. From here you can paint into the white texture using the albedo and other model cues as a guide to add the micro shadows required. Some off the shelf 3D modelling and texturing software can generate these AO texture maps along with normals and other texture types as part of it's export process so worth researching more for the best possible conversion.

As with most creative processes, the more time you spend on something the better it will turn out, but bear in mind some of the legacy entities are quite old now with low geometry resolution and small textures so it might be necessary to completely retexture models, but bear in mind if this option is chosen to retain the exact details and most importantly the exact shape of the entity model. When these entities are upgraded (converted) they are still used by projects currently in progress and end users might not like their buildings, objects and characters changing completely in the middle of their game development.

If you have further questions on this process, email [email protected] and we will add additional information to this page as it happens. Best of luck on your journey into the cool world of PBR rendering!