authoring guide · 2018-11-15 · user guide in order to use the thememaker's toolkit you will...

AUTHORING GUIDEVERSION 1.0

Thememaker's Toolkit Authoring Guide Overview User Guide 3D Software Scene Setup Modelling Animation Texturing and UVs Materials Physics Exporting Example Scenes Error Descriptions

Overview With the Thememaker's Toolkit it is possible to build 3D models in some of the most popular 3D modelling packages and put them into Planet Coaster. By using 3D modelling programs (we currently support Maya, Blender and 3D Studio) you can convert your 3D files into small bespoke items that can be used as scenery pieces in Planet Coaster. These can be later downloaded and placed in your Planet Coaster theme parks, or used as building blocks to make even more amazing piece-by-piece creations. A core ethos of Planet Coaster when creating content has always been to encourage piece by piece creation and the creativity that enables and this something we hope the Thememaker’s Toolkit will help support. The Thememaker’s Toolkit does however have a few limitations in place: - Maximum Model Size: 8x8x8 meters - Maximum Base Texture Size: 2048x2048px - Up to 18 Bones for an animated scene These scenery pieces used on their own or as the building blocks for larger, more spectacular creations, are still able to be shared through the Steam Workshop for the entire community to enjoy. Please note: It is important to have a basic working knowledge of 3D authoring software to be able to use the Thememaker's Toolkit. You can create static and animated scenery that use the in-game custom colouring. This guide will provide you with the information required to take your 3D assets and implement them into Planet Coaster. Thememaker’s Toolkit © 2018 Frontier Developments plc. All rights reserved. Planet Coaster © 2016 – 2018 Frontier Developments plc. All rights reserved.

User Guide In order to use the Thememaker's Toolkit you will need to have created a 3D, textured model that adheres to the Thememaker's Toolkit Authoring Guide. Once you have made your creation and it is ready to go you will just need to follow a few simple steps.

Your Model

Combine your assets (Model in .fbx, Textures in .png, Game Icon named icon.png) into a single .zip file.

The icon.png is the in-game representation of your scenery piece. If flexi colours are used on the model it would be preferable that the icon matches the chosen flexi colour defaults

Create a preview image that will be used for the models that are stored and being built on the website. Unlike the icon.png, this will displayed the item in the toolkit queue and will not be used in the game.

Submission

Login to the Thememaker's Toolkit website (using your Steam account) and select 'Create New Item' - Items you have already uploaded are also listed here.

Upload the .zip file and preview image.

Fill in the required fields on the 'Create New Item' page. Ensure the information about the scenery item you are importing into Planet Coaster is correct, this will make it easier to find in the menus.

Use the tool tips for a description of what each field means. It is also important to consider the gameplay benefits of your asset so consider your price and running costs carefully and look at existing game assets for reference.

If your model has flexi colour masks, you can set the default colours here and these will be the defaults that will appear in the game. If the model has none, these values will have no effect.

Build Process

Once your files have been submitted, it will be added to a build queue and can take anywhere between 10 to 30 minutes to build.

You can monitor your scenery item's status in the list of 'Your Items'.

Build Completion and Download

Once the build has successfully completed you can click 'View' on the relevant asset on the items list which will take you to the revisions page for that item. Click on the download button for the completed item which will then save it to your internet browser's default location - This is usually your local 'Downloads' folder (This PC > Downloads). The file will have a .pcugc file extension and will have the name given when the item was created in the Thememaker's Toolkit.

Adding Items to Game

Once you have downloaded your asset you will need to place it into the following location:

C:\Users\<username>\Documents\Frontier Developments\Planet Coaster\TMT

Note: The .pcugc files can be renamed if needed.

Start the game and you will find your item the object browser. The location will depend on what 'Scenery Category' was defined when the item was created on the Thememaker's Toolkit.

Share Items to the Steam Workshop

You can share your creations with other players in the Planet Coaster community by locating the item in the 'Toolkit Items' tab. Select and place your scenery item and you will find the 'Upload to Steam' button on the scenery item's info panel.

You will then create an image to represent the item on the Steam Workshop. The item's name, description and price are taken from the Thememaker's Toolkit details entered on the items submission.

Once you have created the image you can edit the item's Workshop Title and Workshop Description. This can then be saved to the Steam Workshop.

Any uploaded items will be automatically subscribed to and unsubscribing to the item will not delete it. Deletion must be done through the Steam Workshop.

It is possible to unsubscribe from Toolkit Items in the Toolkit Items tab.

Build Errors

Upon submission the files will have multiple checks to determine the file's integrity. If there are problems with the files then you will receive an error message describing the issue. There are more details on these errors in the 'Asset Authoring Guide'.

Placement Audio

You can choose a material type and object size from the drop-down menus to set placement and multi-placement sounds to be triggered when you place the scenery item in game.

You can select from Glass, Metal, Plastic, Stone or Wood for the type of material in the 'Placement Sound Type' dropdown, and Small, Medium or Large from the 'Placement Sound Size', to reflect the size of your item.

Adding Audio to Scenery

In the 'Audio' category in the games' Scenery browser, there are different types of speakers, which show the options available to you to add audio to scenery.

'Park Speaker – Ambient' will play audio from a selection of looped ambiences included in the game – choose the Ambience you wish to play from the dropdown menu.

If you have an animated piece of scenery and wish to trigger a sound effect when the animation plays, you can add a 'Display Sequencer' and a 'Park Speaker – Triggered'.

Set your Scenery and Speaker to 'Activate on Trigger' and connect them both to the Display Sequencer

You can then choose from the selection of sounds effects included in the game from the Dropdown menu

You can also follow the instructions on the info panel to add your own custom sound effects

If you wish to add a looped sound effect, such as a motor or mechanism, then you can use a 'Park Speaker – Music' for it to play continuously.

Add your sound effect to your 'User Music' folder, select it from 'User Music' tab.

You can also use a 'Display Sequencer' to play a looped sound effect for the duration of an animation.

Place the animated scenery in game and set it to 'Activate on Trigger' Place a 'Display Sequencer' and select your looping sound from the 'User Music' tab Make a Trigger Sequence, add a Display Group and connect the animated scenery Create an empty Display Group as an end trigger to the sequence, timed to be triggered at the

end of the animation. For example: if the animation is 10 seconds long, set the empty Display Group to trigger at 10 seconds

Play the sequence to test

3D Software We use .fbx as our model format and have successfully exported files from the following packages:

Maya 2018 3D Studio Max 2019 Blender 2.79

It may be possible to export a working .fbx from other 3D software packages but these are the only ones we have tested to date.

Scene Setup For technical and performance reasons we have placed certain restrictions to the authoring pipeline to ensure the performance is not heavily affected when implementing new items.

There are also specific requirements that need to be in place to export a suitable model from your chosen 3D authoring package.

System Units

It is recommended that the system units are set to 1 system unit = 1 meter.

Scenery in Planet Coaster follows real-world scales but in some cases we increase the scale to 120% to give a greater visual impact.

Modelling When creating your item you need to consider the following:

Object scale

For technical and engine performance reasons the object scale has limitations:

No exported .fbx can have a volume that exceeds 8 meters in any axis

All objects combined must be a minimum of 0.5 meters in any one axis and 0.01 meters in the other two

Triangle count

To ensure optimal game performance we have limits on the number of triangles for the high level of detail model (LOD_0):

The maximum triangle count is 8000 triangles per .fbx The minimum triangle count is 6 triangles per .fbx

Levels of detail

For engine performance reasons every scenery item must have 6 level of detail (LOD) models.

The Level of Detail or LOD is a process of swapping models to 'less detailed' models that look the same over distance, as the camera moves away from the model the simpler models replace the more complex model. This allows for detailed models to be placed in game while maintaining good performance.

There is a total of 6 levels of detail that are always required as part of the model or it will fail submission.

LOD_0 - Highest detail model 100% triangle-count LOD_1 - 60%-80% triangle-count of the highest LOD LOD_2 - 40%-60% triangle-count of the highest LOD LOD_3 - 20%-40% triangle-count of the highest LOD LOD_4 - 10%-20% triangle-count of the highest LOD LOD_5 - 0%-10% triangle-count of the highest LOD

The LOD values shown are a guide as each item can have varying levels of complexity which define how the LODs can be reduced.

The way to make a model as efficient as possible is to reduce the triangle-count as quickly as possible. Any triangles that can be removed without affecting the items model's silhouette or UV edges, should be candidates for removal.

It is important to make the models as efficient as possible as inefficient models will harm performance.

Model Naming for LODs

For the game to recognise the order in which the LODs are displayed they must follow this naming convention for each object in the scene.

<Model_Name>_L0

<Model_Name>_L1

<Model_Name>_L2

<Model_Name>_L3

<Model_Name>_L4

<Model_Name>_L5

You can replace “<Model_Name>” with a name of your choosing but avoid adding spaces or using anything other than ASCII alphanumeric characters and underscores.

Simple object LODs

If a scenery item has less than 64 triangles, the model LOD can have the same triangle count without failing submission. However, there still needs to be 6 LOD models for each scenery item. For example; if your highest LOD model is a 6-sided cube (12 triangles), it would not be sensible to reduce the triangle count for this model as it would degrade the silhouette.

Animation Any animated scenery must be animated using bones. Animation can not be applied directly to mesh objects.

It is also possible to create more complex animations using a skeleton that can deform and animate mesh.

Animation Restrictions

Animations should not exceed the 8x8x8 meter volume defined in the Object scale category.

Any static objects within a scene that contains an animated object should be parented to a root bone to prevent them moving.

Vertices as part of a skin with no influences will be automatically assigned to an influence bone from the skin's hierarchy which may cause undesired results.

Blend weights and vertex animations are not supported.

All vertices should not exceed 1 in total assigned weight

The maximum amount of influences per vertex is 4.

The maximum number of bones per ..fbx is 18.

All joints are considered as part of the overall bone count, including deformer bones and count toward the maximum bone limit of 18 bones per ..fbx

Texturing and UVs Texture Sizes and number of textures

The maximum texture size for any .fbx is 2048x2048 pixels.

The maximum amount of texture sets for any .fbx is 8.

Texture Limit

The maximum texture budget for any item is 2048x2048 pixels.

This limit is in place to ensure the video memory is not compromised by custom creations.

This can comprise of a single set of 2028x2048 textures or multiple, smaller texture sets that are applied to a single model.

The texture budget is derived from the combined sizes of the base colour textures applied to the model (_BC.png).

Textures must be authored in powers of 2 in the following sizes:

32, 64, 128, 256, 512, 1024, 2048

It is possible to have non-uniform dimensional textures i.e. 1024x256, 128x1024 etc.

Pack your UVs as tightly as possible taking into account the following rules:

Ensure you leave at least 6 pixels of bleed between UV shells UVs should stay at least 3 pixels away from the edges of textures To make the most of a texture you should use tiling textures wherever possible

Texel Rate

The ideal texel rate for Planet Coaster is 256x256 pixels per square meter

Materials There can be no more than 8 materials applied to a single .fbx.

The texture names need to be the same as the material names, the textures have a suffix that defines their function.

Model and materials configuration example:

Model

<Model_Name>_L0 o Material_01

<Material_Name> Textures

<Material_01_Name>_BC.png <Material_01_Name>_RN.png <Material_01_Name>_CA.png <Material_01_Name>_AO.png <Material_01_Name>_MT.png <Material_01_Name>_OP.png <Material_01_Name>_EM.png <Material_01_Name>_F1.png <Material_01_Name>_F2.png <Material_01_Name>_F3.png <Material_01_Name>_F4.png

o Material_02 <Material_Name>

Textures <Material_01_Name>_BC.png

The materials are derived by a combination of textures - We use a Specular and Metalness workflow.

You can only use the Specular map or the smoothness(or roughness) Map and not both together.

Texture Suffix Table:

_BC = Base colour

_SM = Smoothness

_RN = Roughness

_CA = Cavity

_AO = Ambient Occlusion

_MT = Metalness

_NM = Normal Map

_NG = Normal Map Variant

_OP = Alpha Clip

_AL = Alpha Blend

_EM = Emissive

_SP = Specular

_F1 = Flexi Colour Alpha Blend Mask 01




Materials Descriptions

Base colour

The Base colour map is the underlying colour for your model. There should be no lighting information within the texture.

Roughness

The Roughness map dictates how shiny/reflective the object is; the lighter the image the higher the shine/reflection.

Smoothness

This is alternative method to roughness and is a reverse roughness; the darker the darker the texture, the higher the shine/reflection.

Cavity

The Cavity map texture is used for areas on the texture where no light can penetrate i.e. Cracks in plaster or small gaps between panels.

Ambient Occlusion

This map is used to generate extra light information when an object is in shadow. It creates the effect of the light dissipating over small areas and makes corners and crevices darker.

Metalness

The Metalness map defines areas on the texture that have a metallic response. This means that the specular shine will take the colour from the underlying base colour which gives metals their unique look.

Normal Map / Normal Map Variant

The Normal Map is used to create height information on the surface of the model and has the standard channel setup generated by most normal map generation programs.

The Normal Map Variant is the same as the normal map but has an inverted green channel as this is the default in some authoring packages.

Alpha Clip/Alpha Blend

This map defines visible areas of the texture and can be very useful for fencing and small details on models.

The alpha clip material creates a hard edge along the border of the alpha and is the most commonly used alpha type due to its efficiency.

The alpha blend material gives a softer edge to the border, this is one of the more expensive material types and should be used sparingly.

Emissive

The Emissive map functions as a luminosity texture and is used to create lit models or parts of a model.

Specular

The Specular map determines how much shine a surface will exhibit.

Flexi Colour

Planet Coaster allows up to 4 different flexi colour selections on each item.

The flexi colour maps are what is used to drive the masks that define the in-game custom colours.

There are a total of 4 maps that work as layered masks. These can have gradients or be hard edged and require the base colour underneath to be almost white (90% HSB), this is to ensure the brightness of the texture does not 'blow out' when made white in-game.

Authoring Base Colour For Flexi Colour Setup

When creating the base colour for items, any area that will be included in the flexi colour must have a base colour HSB value of 90% B (not pure white, as this causes issues in game) so that the assigned colours show up properly in game. For example, if you were to apply a bright red on top of a dark base colour or a non-grey base colour, that red would not appear to match the colour chosen by the colour picker in game, it would be too dark or the incorrect hue. The base colour CAN have variation in it, this way you can have darker shades of the chosen colour to emphasise areas or add interest. Any areas that you do not want to be included in the flexi colour should be textured as usual with your chosen base colours and not included in the flexi colour masks.

Backface Culling

Planet Coaster Thememaker's Toolkit materials cannot be double sided and are backface-culled.

Texture Combinations for Material Types

Each material type requires a combination of textures to allow it to function. Listed below are the various combinations and the relevant output.

All workflows can use the follow maps:

- Base colour (BC)

- Normal (NM)

- Ambient occlusion (AO)

- Cavity (CA)

- Flexi colour 1-4 (F1-4)

Specular workflow:

- Specular (SP)

- Smoothness (SM)

Specular workflow cannot use the following:

- Roughness (RN)

- Metalness (MT)

Metalness (Smoothness) workflow:

- Metalness (MT)

- Smoothness (SM)

Metalness (Smoothness) workflow cannot use the following:

- Specular (SP)

- Roughness (RN)

- Glass (GS)

Metalness (Roughness) workflow:

- Metalness (MT)

- Roughness (RN)

Metalness (Roughness) workflow cannot use the following:

- Specular (SP)

- Smoothness (SM)

- Glass (GS)

For transparency:

- Opacity (OP)

Transparent materials cannot use the following:

- Translucency (AL)

- Glass (GS)

For translucency:

- Translucency (AL)

Translucent materials cannot use the following:

- Emissive (EM)

- Glass (GS)

- Opacity (OP)

For specular translucency:

- Glass (GS)

Transparent materials cannot use the following:

- Translucency (AL)

- Opacity (OP)

For emissive glow:

- Emissive (EM)

Emissive materials cannot use the following:

- Translucency (AL)

- Glass (GS)

An example of a transparent metalness (smoothness) material with all available maps used:

- Base colour (BC)

- Normal (NM)

- Ambient occlusion (AO)

- Cavity (CA)

- Flexi colour 1-4 (F1-4)

- Metalness (MT)

- Smoothness (SM)

- Opacity (OP)

- Emissive (EM)

Keep in mind not all materials need this many inputs, this is the largest amount of texture inputs you can have on an object's material.

When authoring materials that have transparent or translucent qualities you need to place an additional suffix into the texture name which should be included in the material name.

For a transparent material:

_OP_BC = Base colour

_OP_OP = Alpha Clip

For a translucent material:

_AL_BC = Base colour

_AL_AL = Alpha Blend

For a specular transparent material:

_GS_BC = Base colour

_GS_GS = Specular Alpha Blend

These suffixes need to be applied to all textures that are used by the translucent or transparent material.

Physics Planet Coaster uses a system of invisible objects that are simplified versions of the in-game models to generate physics data, we call this 'Hitcheck'. This allows for object selection and calculating where the surface of a model is when playing the game.

When you have made your hitcheck shape you must give the model name the prefix “hitcheck” and each model name should be unique.

For example:

Hitcheck_01

Hitcheck_02

For performance reasons most of these objects are very simple shapes; often cubes are sufficient as the physics do not need to be to completely accurate to the model.

It is sometimes a good idea to overlap primitives which is perfectly acceptable.

For performance reasons there must be no more than 4 hitcheck objects in a single .fbx

Convex hulls

Some shapes are too complex to use primitives and in these case we use shapes called 'convex hulls'.

A convex hull is an irregular shape 3D object that has no inner facing edges

For performance reasons we have a maximum of 16 vertices per convex hull object.

Exporting For All Static Scenery the .fbx Export settings should be the standard configuration except for the 'Animation' should be disabled

For Animated Scenery the .fbx Export settings should be the standard configuration except for the 'bake animations' should be enabled.

Platform Specific Settings

Maya 2018

Before exporting, all objects should have their transforms reset and their 'history > by type > non-deformer', deleted.

Max 2019

The Skin modifier for animated objects should have 'Dual Quaternion Skinning' disabled on all skinned objects.

If dummies are used in a scene the 'Convert Dummies to Bones' option should be enabled.

Before exporting; collapse all stack items that are not related to the animation of the objects.

Blender 2.79

The export setting should have 'Y axis = forward' and 'Z axis = up'.

Animated objects will need to be rotated in the scene so that the Y axis = up and the Z axis = forwards.

Before exporting, apply rotation and scale and apply all modifiers that are not related to the animation of the objects.

Example Scenes We have provided a variety of scenes for each main supported 3D platforms demonstrating the correct setups for successfully exporting assets.

These can be downloaded on release of the Thememaker’s Toolkit.

Static object

This scene contains basic object to demonstrate the simplest form of asset configuration

Animated object – Simple

This scene contains basic set of animated objects that have no bone hierarchy.

Animated object – Complex

This scene contains a more complex object that has a skinned object using a hierarchical bone configuration.

Material Examples

This scene has a number of materials (worn and clean) from the game that have been balanced for best effect.

Flexi colours Transparency (clip, translucent) Glass Wood Metal Plastic

Error Descriptions

Code Description Solution/Fix

unknown

An unexpected error occurred preventing the build from completing [Unspecified].

Contact support at frontier https://support.frontier.co.uk/

ugcPreBuildFailed The pre-build checks failed.


ugcNoIcon

The pre-build failed because the uploaded zip does not contain an "icon.png" file.

Ensure there is a icon.png included in the .zip file

ugcNo.fbx

The pre-build failed because the uploaded zip does not contain an .fbx file.

Ensure there is a ..fbx included in the .zip file

ugcNoConfig The pre-build failed because of an invalid configuration.


ugcInitialise Build process could not be initialised.


ugcStatusUpdate Unable to modify the status of the build.


ugcClearResources Unable to prepare the builder tool.


ugcObjectRetrieve Builder could not download and process the zip resource file.


ugcArtifactNotFound Builder could not generate pcugc artifact.


ugcExtract Unable to extract build resources from zip file.


ugcBuilderTimeout Build process timed out. Contact support at frontier https://support.frontier.co.uk/

ugcBuilderFailed Build process failed. Contact support at frontier https://support.frontier.co.uk/

Empty Scene No objects found in the scene hierarchy.

Ensure you have exported your objects correctly

Missing Render Level No render mesh found for level.

Ensure the LOD suffixes are are named correctly and are all present

High Poly Count A render mesh blew the poly limit.

Ensure the LOD_0 model does not exceed 8000 triangles

EmptyLOD LOD contains no polys. Add missing LOD model(s). LOD models need to be poly based

SameComplexityLODs Same-complexity LODs found.


LODOrderBad LODs out of order. The LODs triangle counts should decrease as the LOD number increases

Too many hitcheck meshes The number of distinct hitcheck meshes exceeded the limit.

Ensure there are no more than 4 hitcheck models in the scene

High hitcheck vertex count Hitcheck mesh contains too many vertices.

The maximum number of vertices is 16 for a single hitcheck model

NoBounds Could not compute scene bounds from any .fbx node.


ZeroExtent Found zero extent in an axis.

The minimum object scale is 0.01m in any 2 axes

ModelTooBig Model is too large.

The maximum scale for a scene or asset is 8m in any axis - Decrease the model scale

ModelTooSmall Model is too small. The minimum object scale is 0.01m in any 2 axes - Increase the model scale

TextureTooLarge Texture is too large. Decrease the texture size to below 2048x2048 pixels

IncorrectTextureMask No shader uses this combination of textures.

Refer to Thememaker's Toolkit Authoring Guide Materials section

BlewTextureBudget The combined resolution of the provided texture maps is over the limit.

Decrease the texture-set size to below 2048x2048 pixels

BadFlexiColourChannels Invalid group of flexicolour masks specified.

Flexi colour textures should always start with <texturename>_F1.png

TooManyBones Number of bones in the scene exceeds the limit.

The maximum number of bones is 18 for an .fbx

Failed.fbxLoad Failed to load .fbx scene.


GridAnimated Grid pieces cannot be animated.

Do not export animation for grid based objects

FailedIconLoad Icon source image missing, fail.

Ensure there is a icon.png included in the .zip file

NoNameDesc Object name or description missing, fail.


BadSceneryType Unrecognised scenery type stored in settings object.


GenerateResourcesWriterCrashException Writer crashed attempting to generate resource, bailing.


GenerateResourcesWriterInvalidException

Writer failed resource generation and has no GetStringName implementation, or an incorrect implementation. Bailing.


WriterPrebuildException Writer crashed at prebuild.


WriterInvalidPrebuildException

Writer failed prebuild and has no GetStringName implementation, or an incorrect implementation.


WriterCleanupException Writer failed cleanup step.


WriterInvalidCleanupException

Writer failed cleanup step and lacks a correct GetStringName implementation.


ResourceControlCleanupFailed Failed resource control file cleanup.


ResourceGenerationFailed Resource generation failed.


TextureSizeInvalid Texture dimensions need to be multiple-of-four.

Refer to the Texturing and UVs section of the Thememaker's Toolkit Authoring Guide

TooManyLODs We only allow up to 6 LODs.

Setup the correct number of LODs in the scene