Transition guide

Transition Guides #

Transition to Gameface 1.2+ #

Plugin structure #

With Gameface 1.2, the rendering part of our Unreal Engine integration is now separated in its own plugin - the Coherent Rendering Plugin. This means that CohtmlPlugin has a dependency on the new rendering plugin (specified in CohtmlPlugin.uplugin). Here are the structural changes that occurred with that:

• The FCohRenoirBackend rendering backend is now moved from CohtmlPlugin to CoherentRenderingPlugin, along with all relevant source files (with a Coh prefix).
• The FCohtmlFileManipulator is now FRenderingFileManipulator and has also been moved from CohtmlPlugin to CoherentRenderingPlugin.
• The Renoir public headers in RenoirBackend, RenoirBackends and RenoirCore have been moved from the Cohtml module (Engine/Source/ThirdParty/Cohtml/include) to the new Renoir module (Engine/Source/ThirdParty/Renoir/include).
• The Renoir import library is now packaged in the Renoir module (Engine/Source/ThirdParty/Renoir/lib), so that the module can load the Renoir dynamic library.
• The Renoir binaries have been moved from the Cohtml module (Engine/Binaries/ThirdParty/Cohtml) to the new Renoir module (Engine/Binaries/ThirdParty/Renoir).

This is what the new structure looks like:

|-Engine
  |-Binaries
    |-ThirdParty
      |-Cohtml
      |-Renoir
        |-Win32
          |-RenoirCore.WindowsDesktop.dll
        |-Win64
          |-RenoirCore.WindowsDesktop.dll
        |-...
  |-Plugins
    |-Runtime
      |-Coherent
        |-CoherentRenderingPlugin
        |-CohtmlPlugin
  |-Source
    |-ThirdParty
      |-Cohtml
        |-lib
        |-include
          |-cohtml
      |-Renoir
        |-include
          |-RenoirBackend
          |-RenoirBackends
          |-RenoirCore
        |-lib
          |-Win32
            |-RenoirCore.WindowsDesktop.lib
          |-Win64
            |-RenoirCore.WindowsDesktop.lib
          |-...

Migration steps #

Depending on whether you use our installer, or an archive, there are some steps required to transition to Gameface 1.2+:

Using installer #

Make sure you check the Clean install option during installation. If you don’t, this will lead to compiler errors due to redefinition of Renoir-related code due to source file duplication in both CohtmlPlugin and CoherentRenderingPlugin.

Using archive & game-only plugin #

If you’re using Gameface as a Game-only plugin, you will have to delete the <YourGameRoot>/Plugins/Runtime/Coherent/CohtmlPlugin folder before running GamePluginCohtml.bat. This is required to avoid that same issue mentioned in the Using installer section above.

Transition to Gameface 1.14.3+ #

Gameface atlas metadata #

In previous versions the atlas metadata file stored the following data:

- AtlasPath
- Width
- Height
- ContentRectWidth
- ContentRectHeight

In newer versions the stored data now includes the origin X and Y coordinates for each atlased texture as well:

- AtlasPath
- Width
- Height
- ContentRectWidth
- ContentRectHeight
- OriginX
- OriginY

The plugin will automatically detect this and you will be advised to rebuild your atlases, so that the correct data is populated in the metadata file, as otherwise you may experience visual problems with your atlas textures.

Transition to Gameface 1.45+ #

If you’re transitioning from a pre-1.14.3 version and also happen to have an atlas metadata file, it is highly recommended to first rebuild your atlases using Unreal Engine 4.27, as backward compatibility was removed for newer engine versions and you are likely to encounter an engine hang.