Add the proxy mesh to the project.

To add our models for the different parts, we’ll be looking mostly in the .app file, under our main appearance.

Open the “AppearanceVisualController” in the appearance’s item list. It should be the last item in the list. Then select the “meshProxy” value.

Go ahead and add this mesh to the project by clicking the yellow arrow.

This mesh is used at distance, before your vehicle is loaded fully. We’ll be using it as a reference for our modeling in blender, as it is a low poly, complete model with wheels and all.

Open the Export Tool, under the Tools menu on the top of wkit.

Hit refresh to load all items, and select your proxy mesh you just added, then hit “Export Selected”. This should have created a .glb and .json file under the new “raw” folder above the resources in the Project Explorer.

Example:

Open a new project in blender, delete the base cube. Hit File > Import > Cyberpunk GLTF and load the proxymesh.glb

Your proxy mesh should now load in blender.

Example:

You can now import your source 3d models for your vehicle.

The proxy mesh will initially be positioned offset from other vanilla meshes. This is due to the vehicle’s .rig file settings(will be discussed later).

Example showing the offset:

To get the exact offset, open the .rig file located at this path in the .ent file:

• RDTDataViewModel > components > deformation_rig > rig

Open the boneNames list and look for the index (number to the left) of “Base”, in this case 2:

Then close boneNames and open boneTransforms. Open the same index value as “Base” and look at the translation values:

(Values that are set at “_.___E-17” are in scientific notation, and if the E number is negative as they are here, the number is close to 0)

Look at the Z value and noticee how it is 0.4399999 in the example. (~0.44) This is the number we will translate the proxy mesh by. Return to blender and select the proxymesh object. Translate it by the same value just found in the .rig file by using the Transform Location values in the Object Properties menu: (positive to negative)

Repeat the translation for all objects in the proxymesh collection:

The proxy mesh can be used as a reference in blender for scale. Note the porsche is especially convenient, as it has real-world dimensions available online. If you don’t know your source car’s size, (length, wheelbase, width) You can compare in-game between it and the Porsche, then convert those numbers as appropriate.

Import the source 3D model for your mod into the same project.

Your model will likely be scaled incorrectly.

Find the correct scale of your vehicle in reference to the proxy mesh.

• Example: A mini cooper has a wheelbase of 97.1”, and a porsche 911 has a wheelbase of 89.45”. So, Mini cooper wheelbase should be 8.55% longer in Blender once scaled correctly.

Fix positioning with the move, rotate, and scale tools. “Numpad 5” can be used for orthographic perspective, which is useful for comparing wheelbase accurately. I recommend matching the wheel bottoms at the same height, and matching the driver seat position as close as you can. This will save some steps later for poses.

Example with both rendered:

Apply all transformations to all objects in blender. This is required after any blender changes, if you skip this before exporting from Blender into WolvenKit, any positioning changes will not be saved.

Disable visibility on the proxy mesh for now, but leave it in the project as we’ll need it later.

Now we can setup the model so it can be converted into meshes for Cyberpunk.

Depending on your source model, you may need to either split or join your model into groups for different meshes in game. These “groups” are the components list/array in the .app file.

Here’s a quick reference for the major groupings to look for:

• 2 tire models, one for font and back (left and right mirror the model)

• 2 wheel/rim models, see ↑

• Body

• Engine

• Window front & window back

• Chassis

• Various lights, backleft, backright, body, reverse, break,

• Wipers

• Door left & door right, front/back

• Window left & right, front/back

• Hood

• Trunk

• Interior

• Mirror

• Steering wheel

• License plate

• Bumper front / back

Make a backup of your blender project often while editing. I suggest keeping multiple copies as you work with your model. While splitting/joining objects you might not realize certain components need to be different until later on in the mod project, and an older project file will be very helpful.

I recommend creating “collections” or folders in blender, one for each component. Split and join the files as necessary to organize them together.

Example of Collection/Folder/Object structure in Blender:

For each component in the vehicle, you’ll want a separate collection to organize meshes together. Each mesh will need a separate object in Blender for each material layer.

Here are the major mesh groupings you will want in your project:

Split and join objects as needed to organize the Blender project structure.

Join objects by selecting multiple, and using Object > Join:

Now we’ll import our first mesh into Cyberpunk.

In wkit, open the .app file and navigate to the default appearance. Open the components and find “body_01” and expand it. Look for the “mesh” value, and add it to your project.

Example:

Use the export tool as we did with the proxy mesh to convert it to a .glb file.

Import this body.glb file into the blender project.

Prepare your custom body mesh and ensure the replacement is one object. Join relevant objects together if needed.

You can check the face count in the top left of your blender window:

As a general rule, keep the count low if you can to preserve performance in-game. Higher polygon count will increase quality, but decrease game performance.

Use the decimate modifier (or other methods) to reduce the face count if needed.

Example adding decimate modifier:

For simplicity, we’ll join all the parts of the body into one object for exporting. We can split them as submeshes later, when we want to indicate separate materials within a mesh.

With the body object selected, go to File > Export > Export Selection to GLB for Cyberpunk:

Save it to a new folder for your project’s .glb files.

Copy the .glb file into the folder with the original exported body mesh.

Copy the original file’s name, delete it, and rename your new part with the old file’s name.

Open the import tool in wkit, find the correct body .glb and import it into the game.

Select the updated .mesh file in the Project Explorer, and it will open in the File Information window. It should show your new mesh. Example:

Rename your new .mesh file to a project-specific name, and move it to a custom folder. Example:

“boe6\mini_cooper\meshes\boe6_mini_cooper_body.mesh”

Update your .app file with the path to the new body file. You’ll need to update it in 2 places:

• RDTDataViewModel > appearances > 0 > components > body_01 > mesh

• RDTDataViewModel > appearances > 0 > components > AppearanceVisualController > appearanceDependancy > body_01 > mesh

Test the mod in-game. It should look very wrong since we only replaced one mesh. Example:

Next, make all other visible components invisible while we’re modeling.

Easiest way to mark components as invisible is to break the entVisualControllerComponent appearances path.

• “RDTDataViewModel > appearances > 0 > components > entVisualControllerComponent > appearanceDependency > partname > mesh”

I do this by renaming the file with an added “-disabled” in the name. This breaks the file path, and notes that it is disabled for reference later. example:

You will receive warning in the log when saving the .mesh if you use this method, be aware:

Save and test in-game. The renamed component should now not render in-game. Note that this only removes the visual mesh. The interactions still exist. Example:

Continue to change components until all except the modded body and wheels remain. Start with the major parts, bumpers, doors, etc. Test in-game frequently. Only disable parts that render in-game.

Once you have disabled all the other components, you can see your model clearly and notice any initial problems. Expect the textures to be broken. Opposite sides may not render as we still need to add an interior. Example:

Some model issues may show themselves at this point. Check out the “Fixing Body Glitches” section of this document below.

You can use the body_01 instructions for creating most non-moving parts. (engine, trim, chassis, etc)

For the non-moving windows, we’ll start by enabling the mesh in the entVisualController, removing the “-disabled”. Then we can add the mesh to our project. Move/rename is appropriate. Example:

“boe6\mini_cooper\meshes\boe6_mini_cooper_window_f.mesh”

Update the .app file with both .mesh paths for the component.

Export it to .glb, replace it with your model’s window, and import it back.

Save and Test.

Repeat for each non-moving window. (door windows are done after doors)

• Similar materials can be copy/pasted as meshes, and then import/exported, and entered into the .app file. This is instead of importing from the original car that is being mirrored. This saves time on moving files.

Save and test.

To add a new component instead of replacing a default one, you can duplicate the entVisualControllerDependency of the most similar component by right-clicking and selecting “Duplicate Item in Array/Buffer”. Example:

Edit the new component’s “componentName”, here I use “body_02”, as it is for exterior trim bodywork.

Edit the “mesh” value to the correct new .mesh file. Example:

“boe6\mini_cooper\meshes\boe6_mini_cooper_body_trim.mesh”

Duplicate the entPhysicalMeshComponent of the part you are copying. Rename it with the “name” value to the one you used earlier, (body_02). Set the “mesh” value to the same mesh path. Example:

Some familiarity with WolvenKit is required.

I go into as much detail as I can, but try to be familiar with the project explorer, asset browser, and other windows.

Mod file types

• .ent file is the base file of a vehicle. It contains all settings and child files.

• .app is the vehicle’s appearances settings.

• .mesh is a 3d file, used for vehicle body parts.

• .xbm are raw texture files.

• .mlsetup has settings for texture sets

• .mlmask is zipped mask texture/finish layers, normal maps, etc.

• .inkatlas contain reference texture information

• .inkwidget configures texture layering, position, & animations

• .rig has 3D information for how the .mesh files are linked and move.

• .yaml files configure TweakDB items.

• .json files list string localization information.

• .phys is used to set vehicle collision/interaction bounds

Understanding of different Data Types

• Int/Integer : whole numbers

• Float : fractional numbers, decimal places

• String : sequence of characters

• Boolean : true or false

• Array : collection or list of items of the same data type

• Nothing : “null”

Some understanding of blender is assumed.

• Object/edit mode

• Object management

• Object edits

• Joining and separating models

• Know the difference between object origin, world origin, and the blender cursor

• Cyberpunk 2077 glTF Importer plugin / Wolvenkit resources plugin (View Options > plugins to install)

Knowledge of a photo editor of your choice.

• Must have support for .tga files

• Must have support for alpha channels

• Photoshop (Photopea), Krita, Paint.net, and Gimp are good options

Some Python familiarity

• There are some python scripts and python commands to use.

• Be able to edit and run a .py script

• Not necessary for most changes

Mod requirements

Install these to your game before starting:

• Virtual Car Dealer

• TweakXL (required, without it you won't be able to load Vehicle tweak at all)

• ArchiveXL

• Material and Texture override (unknown if required after 2077 version 2.0+)

A 3D model to use

• Have a 3D vehicle model ready to use for converting into cyberpunk.

• Important features are details parts, doors, trunk, etc. and textures.

• Higher face/vertice count is better. Modeled interiors are a must.

• Sketchfab is one great option for finding models, but Google is also useful.

Parts that require a .rig file will not import the same. For example, the bumper’s 3D models are not positioned in-line with the body_01 object in blender. Bumpers are centered around the origin of the 3D space. The part is then lined up correctly with the .rig file, which is linked in the .ent file.

To model the front bumper, we’ll first export the base game bumper as .glb, and import into our blender project. As you can see, the game model is positioned around the origin, unlike the custom bumper.

Move it with the move tool, so the corner of the bumper is at the origin and apply all transforms.

If you do not have the rig file already, you can now add it to the project. Open your vehicle’s .ent file and open this path: RDTDataViewModel > components > deformation_rig > rig

Add the file to the project, and rename/move it. Example: “boe6\mini_cooper\boe6_mini_cooper.rig”

Update the .ent rig path with the new file:

You can also update the .rig path in your vehicle’s .anims file, as well as the rig references here:

• .ent file > RDTDataViewModel > resolvedDependencies > 0 > .anims file path

• .ent file > RDTDataViewModel > components > vehicle_rig > animations > gameplay > 0 > animSet

• .ent file > RDTDataViewModel > components > deformation_rig > animations > gameplay > 0 > animSet

Add it to your project, rename and move it as usual. Then in the .anims file, set the rig path to the new one we just created:

Additionally update these paths to your .anims file.

Open the .rig file and notice these 3 arrays:

These map all the position data of each .mesh file. boneNames tells you which index value is each item, boneParentIndex tells you what each bone’s parent is (example; wheel_back_left is a child of suspension_back_left. If you change suspension position, wheel will move with it.), and boneTransforms is the positional and rotational values for each bone.

For a reference of where the bones are in a model, you can export the vehicle’s .anims file to .glb and import it into blender. You can select each bone to see their name and properties. Example:

Your 0,0,0 position should be in the center of the vehicle. Here is the translation data for each of the suspension wheels of a vanilla car (porsche):

These are frontLeft, frontRight, backLeft, and backRight respectively. The Translation values are XYZ values:

• (-) x = left of car, driver side

• (+) x = right of car, passenger side

• (-) y = back of car

• (+) y = front of car

• (-) z = bottom of car

• (+) z = top of car.

It may help to visualize the car as if from a top-down ariel view, left is -x, right is +x, up is +y, down is -y.

You’ll need to update the .mlmask and .mlsetup files in these .mesh files as well, however they may show up at a different location. If they are not listed under “localMaterialBuffer”, check under the “preloadLocalMaterialInstances” array. The masks set should be in there instead.

Modify the existing X Y Z values for the bumper, changing one value at a time to see the amount changed. I suggest starting with a value of +/- 0.1.

For moving parts, such as hoods and doors, we start by replacing the 3D model. Notice the rotation point in-game is a pivot along the origin in 3d space:

In my case, I have my hood aligned forward, as the axis should be further behind in the real vehicle.

Your part will not align at first. If it is a large distance, try to adjust the 3D model first. Keep in mind the pivot will be the origin, so only adjust in the axis you can edit without messing with how the part will move(left/right for hood/trunk, up/down for doors). Once it’s close, you can adjust the .rig file as well to get it positioned correctly:

Swap the .mesh’s .mlmask and .mlsetup to the same as your body_01 has set. (or to whatever other file you need)

You can also change how components are connected in the vehicle rig.

• For components that don’t have their own movement or bones, they are attached to another component that does. This can be changed to attach a model to another model’s movement.

• .app file “RDTDataViewModel > appearances > 0 > components > entPhysicalMeshComponent > parentTransform > bindName” Example:

• Components that do have their own bones are set to the bindName “vehicle_slots”, and their slotName is set to a boneName value in the .rig file. Example of body_01 in .app:

If a component is linked to another component, we cannot use the .rig file to move it. Instead, in the .app file is each component’s localTransform. This can be used to change the position and orientation relative to the parent component. Example:

Notice that the x,y,z position is saved as Bits, instead of as a float. To edit the positon data here, we need to convert from a float value to a fixed bit value.

The code for this conversion was written by Loomy(Loomy#3375) on the modding discord, here.

This can be run in a python console:

• int( ( n * pow(2,32) ) ) >> 15

Where “n” is a float value.

If you do not have python installed, you can try an online console, such as here. (paste the command into the “shell” side on the right, and hit enter)

Rigging wheels requires a 2nd .rig file that is used for vehicle handling. It is referenced here:

• .ent file > RDTDataViewModel > components > vehicle_rig > rig (path to wheelbase rig)

You can add this new rig to your project and rename/move it.

Notice that the new rig file only has wheel related bones:

This is the rig file that is referenced for vehicle wheel handling. It controls where the wheels/suspension are located. This file overwrites the values in the deformation_rig created earlier.

To update the wheels, generally you want to modify the suspension bones. Since the wheel_front_left, wingarm_front_left, and break_front_left are all parented to suspension_front_left, updating the location for suspension also keeps the brakes and swingarms in the correct position relative to the wheel.

If the suspension values are updated/changed in the vehicle_rig, the deformation_rig may cause issues in some cases. To avoid this, rename the boneNames in the deformation_rig that are the same as the vehicle_rig. This ensures that the vehicle only uses the vehicle_rig values. Do not rename front wheel suspension in the deformation_rig, as it will break wheel turning.

For the Mini Cooper, I edited all 4 suspension positions in the vehicle_rig to update wheel positions, so I renamed the 2 front in the deformation_rig (excluding the front, as described above):

To change the size of the wheel, you need to change both the 3D models and the rig files. You can update the wheels by first replacing all the wheel and tire meshes with ones to match your vehicle. This is similar to how the doors, windows, and hood work. Make sure to have the center of the wheel as the mesh’s origin. Example:

Once the wheel model is updated, you need to update the .rig files.

In both the deformation_rig and vehicle_rig, find the wheel bones (wheel_back_left, wheel_front_right, etc.) and update the Scale values. Example:

There are many ways of converting a high-res model to a low-res model, but for this guide the “Remesh” modifier in Blender will be used.

Set all the parts visible and positioned correctly relative to the body in Blender. In my case I also added the wheel shadow meshes, as the rim holes caused issues with remeshing details. Join all the objects into one and select the object. Example:

The Remesh Modifier is available in the properties menu, under modifier properties: It

It is recommended to save before adding or changing settings in the modifier, as unintended settings can crash blender fairly easily. Here are the settings to adjust in Remesh:

Try to create a final proxy mesh with a low amount of faces/triangles. The face current face count visible in blender can be seen in the top left of the viewer. Example:

Most use less than 2 thousand faces for a proxy mesh. You’ll also need to update the blender model to be correctly position, as the .rig will modify it. Translate your model with the reverse values used to translate the initial proxy mesh.

Once the mesh is ready, a texture is needed. I recommend this guide for texture painting:

Once the texture is ready, you can export it from Blender under Image > Save As.. >

Save it as a .png, and then import it into the project as an .xbm

In the proxy.mesh, update the texture path:

• .mesh > RDTDataViewModel > preloadLocalMaterialInstances > 0 values > baseColor

In this guide I’ll be bringing a Mini Cooper into Cyberpunk 2077. All methods should translate to whatever vehicle you add. The guide assumes you’ve generally followed along in order. The later steps will skip basic info covered in previous steps, unless its written otherwise.

If at any point you get stuck & have questions, DM me on discord @boe6, or ask in one of the MODDING sections of the Cyberpunk 2077 Modding Discord. https://discord.gg/Epkq79kd96

If you discover info or additional details that you figured out during this guide, please right-click and add a comment in the original document so the guide can be updated! (do not ask questions in comments, use discord please)

For the visual learners among us, you can find a youtube video series by boe6 here:

Add the .phys file to your project, rename, and move the file as appropriate. It is linked through the .ent file. Path:

• .ent file > RDTDataViewModel > components > chassis > collisionResource

Convert the .phys to a JSON file:

Now you’ll need 2 python scripts created by “The Magnificent Doctor Presto!”. They can be downloaded on github here:

https://github.com/DoctorPresto/Cyberpunk-Helper-Scripts

Download both export_phys.py and import_.phys.py

In Blender, open the “Scripting” workspace:

At the top of the text editor that just openned, use the folder icon to find the importing .py file we just downloaded.

This should open the .py file into the text editor. It should look like this:

Edit the “physJsonPath” value to the converted phys.json file. Example:

Once you’ve run the script, you should have vertices that look close to the outline of the original car model. Notice the outline similar to the porsche:

.phys files don’t like complex meshes, so they use only vertices without faces or edges. Each “submesh” is a small object shape, with no concave angles. Each submesh is then joined to create the overall collision mesh.

Switch back to the Layout workspace.

The easiest way to edit these in blender is to enable your vehicle’s body mesh, is to switch to Wireframe shading, by holding Z, and moving your mouse to “Wireframe”. Example:

This will allow you to see your body mesh, but also see vertices behind and around it. Example:

Once done editing, select all the vertices objects and run the export_phys.py, similar to the import script.

The .phys file should now be finished. Import from json, update path references, and test in-game. Make sure to update the physJsonPath again, as this is the path it will save the new .json to.

Once the script has been run, you should have a new file with the “new_” prefix added in the same folder as the phys.json. Example:

This file can now be converted back from json and used in game. Example:

Summary

Published: Nov 5, 2023 by Meta Pixel Last documented edit: Oct 15 2024 by

This guide is part of Boe6's Guide: new car from A to Z and covers the material part of it.

Wait, this is not what I want!

To learn more about materials, you can browse Cheat sheet: Materials and its sub-pages.

Let's get started

.mlmask , .mlmaskset & .masklist

To fix the odd textures that appear after importing your custom models, we have to edit the .mlmask layers.

Find the .mlmask corresponding file by opening a .mesh in wkit to edit. Go to the path:

• RDTDataViewModel > localMaterialBuffer > materials > 0 (...maskset) > values > 0 > value

Add the .mlmask to the project.

Rename and move the .mlmask file into your project filepath. Example:

“boe6\mini_cooper\meshes\textures\boe6_mini_cooper_exterior_maskset.mlmask”

Export the .mlmask file. It should result in a .masklist file and a folder with .png files inside:

Notice the first white image, and the remaining black images with white cutouts.

These textures don’t map onto the new vehicle’s mesh correctly. These can be edited to add more detail to your model.

As a temporary solution, we can edit the first image to be pure white, and the rest to be pure black. Example:

Import the .masklist file

Update your .mesh file with the new .mlmask name/path file:

• RDTDataViewModel > localMaterialBuffer > materials > 0 (...maskset) > values > 0 > value

Your vehicle should now be much smoother.

.mlsetup & MLsetupBuilder

To change paint color, we need to edit the .mlsetup file.

You will need the MLsetupBuilder plugin for editing these files. Install it in wkit:

• HOME button (top left) > Plugins (left list) > MLsetupBuilder, right side, install.

• Once installed, hit open. It will open a folder with a “MlsetupBuilder.exe” executable. Run it to open the program.

The .mlsetup file we need is linked in the .mesh file, similar to the .mlmask:

• RDTDataViewModel > localMaterialBuffer > materials > 0 / masksset > values > MultilayerSetup > Value

Add this .mlsetup file to the project. Rename and move it. Example:

“boe6\mini_cooper\meshes\textures\boe6_mini_cooper_exterior.mlsetup”

Convert the .mlsetup file into .json by right clicking:

Open MlsetupBuilder.

Import the .mlsetup.json file by hitting the arrow in the top left:

Once you open the file, a window will appear on the left with a list of materials. These are the texture layers of your mesh.

At the top is a large orange button titled “Import the Multilayer Setup >>”. Click it to load the .mlsetup file into the editor. It should populate the Layers list:

Now, assuming you created a .mlmask file similar to our previous steps, with all but 1 black image (see below), we know only the first layer, Layer 0, is the only one that will currently render on our .mesh

Since Layer 0 is the visible layer, select it and it will load in the Material view:

This is where we edit the layer. If you only want to change the color to a common one, choose one from the lower color palette. Here I have chosen blue:

You can also change to another material texture here by clicking the preview ball:

This can be used to create different paint finishes, cloth texture, etc.

Once you have finished editing a layer, you can save it by clicking “Apply edits” at the top of the Layers panel:

Then you can select another layer and edit the next one if needed. If you select a new layer without applying the edits, the changes will be lost.

Once finished, you can Export to save it to your file explorer, and then load it in wkit by right clicking the .json and selecting “convert from JSON”. Example:

Save and Test in game

Working color:

Custom RGB value colors can be set with a custom .mltemplate file. Here we will only set RGB values, but this file can control other material settings/textures as well.

Find the material you want to have a custom RGB value for in MlsetupBuilder, and click on the material name to show it’s file path. Example:

Add that file to the project, rename, and move it. Once it’s in place, you can copy it’s relative path and paste it into MlsetupBuilder for that layer:

Open the .mltemplate file in wkit and navigate to the colorScale array:

• RDTDataViewModel > overrides > colorScale

This array contains all colors in the material. Open one of the Multilayers and it’s “v” values, which control the RGB values:

First, you can verify the color in . Copy the “n” value here, and paste it into MlsetupBuilder in the Color filter:

Select the color, and it’s rgb values should match the values in the “v” colorScale in the .mltemplate:

Edit the 0,1,2 (R,G,B) values to the color values needed and save. Make sure to save the .mlsetup as well with the layer set to the same color code as before.(“n” value, [00cf56_69039f])

Save and test.

Multiple materials

To have multiple materials in a single .mesh file, the .glb export requires separate submeshes all selected in blender. Separate your blender .mesh into parts, and group them based on material.

First separate/split your meshes into small components, and then join them into groups:

For example, mine are grouped by body paint, silver trim, reflective black, matte black, and grey fabric. Take note, the order in your blender selection will be the order each submesh is called by the .mesh file settings. This order is important.

With all the objects selected in blender, export it to .glb and import it as you normally would.

You can save and test. If it worked properly, only the first object included in the blender export will render properly at the moment.

Example of a finished body mesh in blender:

Currently the other submeshes will not render properly. This is due to submesh materials being controlled by the chunkMaterials in your appearance settings (.app file).

To correct this, start by duplicating an item in the chunkMaterials list. Path:

• .mesh > RDTDataViewModel > appearances > 0 > chunkMaterials

Make sure to edit the name to a unique name, as we are creating new materialEntries. Repeat as needed. In my case I needed 6 extra layers:

Next, navigate to RDTDataViewModel > materialEntries

This list controls the names and index of each item in the localMaterialBuffer, which we’ll edit soon. You’ll want to duplicate an item with similar qualities. If you are adding a plastic material, duplicate another plastic or solid material in the list. If you are adding glass, duplicate from a vehicle_lights material, then edit as needed. Duplicate one for each new material.

Make sure to update the index values of each item in the materialEntries array. They must all be the same as their index in their current array. 4 to 4, and so on:

Next we’ll update the materialBuffer with new .mlsetup and .mlmask files. Keep in mind the .mlmask files can be edited to match the model to a texture. However we’ll be working around that by using the same method used previously, to have a .mlmask file with one additional white layer.

Example:

Notice how I have a .mlmask file dedicated to the 4th layer, so all other layers are muted. I have 20 (0 through 19) unique .mlmask files, each selecting a different layer from a .mlsetup file.

Speaking of .mlsetup, I have created a .mlsetup file with MlsetupBuilder. Layers 0 through 7 are used for the new materials:

Now to finish the materials setup, open the following .mesh path:

• .mesh > RDTDataViewModel > localMaterialBuffer > materials

This array contains every CMaterialInstance for the .mesh file. This array has it’s items named via the materialEntries list we just edited. Since we added items to that list, those names now show in this localMaterialBuffer > materials list. However the data in each item is still it’s original.

For example, in this picture, the array hasn’t been updated yet, however the names are updated. This means the index 1 item, …”masksset_texture” has the properties of “reflector”, which would normally be the 2nd item.

To fix this, duplicate the appropriate items, similar to before, once for each new material. Once done, the previous index 1 item will now be higher, but matched correctly. In my files, I duplicated “ml_v_sport2_porsche_911turbo_exterior_masksset” 6 times, and they each pasted directly below the 1st.

You can tell if the materials are correct by opening them, and looking into the “values” array. Each will have similar keyValuePairs related to the material type. Glass mentions GlassSpecular, normal paint has many map layers, stickers dont have much, etc:

For each new material layer, update the paths:

• CMaterialInstance > values > MultilayerMask > value

• CMaterialInstance > values > MultilayerSetup > value

For mlsetup, I use the previously mentioned file, with layers setup for individual materials.

For the mlmask, use the “masksset_00” for the layer you want to enable.

Submeshes should now load in order with matched materials.

Fix broken UVs

Editing UV maps may be necessary for some meshes if they do not display correctly, or for custom editing. Broken & Fixed UV map example:

To edit UV maps in blender, select your object to modify and enter the UV Editing workspace:

The current UV map should display on the left:

In the right window in Edit Mode, select all vertices (“a” key in blender), and hit “U” for the UV mapping dialog. Select “Smart UV Project”, and hit OK:

This should update the UV mapping to an even spread map:

Save and test. Your meshes should have even material mapping now.

Some objects are better with different UV projection options. For example, a tire can be cleanly mapped by using the orthographic view and selecting Sphere Projection. Try some of these options to see what fits best for your use case.

Summary

This section collects information for vehicle modding.

Wait, this is not what I want!

• For to Blender, check the Wolvenkit Wiki's step-by-step guide.

What you can find here

Boe6 has been so nice to share their (very detailed) and given full permission to transfer it to the wiki. However, the transfer is a work in progress (check )

A second guide is , although it is not very detailed.

For the visual learners among us, you can find a youtube video series by boe6 here:

Most of the vehicles have the windows going down when you get your gun, allowing you to shoot without breaking it. Others have the door opening because the window can't retract itself, or because the glass is replaced by opaque screens. And special ones have mounted weapons, so no windows or doors, but big guns and missiles.

If you want to choose a specific opening for your custom vehicle, or just modifying existing ones, you can do it with couple of lines in a .yaml file.

The string you need to change looks like this : DriverCombatTypes.Standard

There's 5 variations of it:

• DriverCombatTypes.Standard ("Roll down driver and passenger windows for driver combat.")

• DriverCombatTypes.Doors ("Open driver and passenger doors for driver combat.")

• DriverCombatTypes.MountedWeapons ("Doors and windows do not open, player controls mounted weapon(s) on the vehicle.") PS: You need to add all needed weapons components to your vehicle to make it work, in .app, .ent and .mesh. I still need to explore this part)

• DriverCombatTypes.Disabled ("Driver combat disabled.")

• DriverCombatTypes.CrystalDome ("Unsupported for now")

Mounted weapons' locations are determined by the .ent file of the vehicle, and generally are identical to the base car .ent being used for the custom mesh. This can result in misplacement of the weapon emitters - the parts which actually shoot a bullet/missile - and requires some work to change. In WolvenKit, open the .ent file directly. In the file editor, expand RDTDataViewModel\components\vehicle_slots\slots and scroll down, looking for the following entries, usually at the end:

• VehiclePowerWeaponLeftSlotA

• VehiclePowerWeaponRightSlotA

• VehiclePowerWeaponLeftSlotB

• VehiclePowerWeaponRightSlotB

• VehiclePowerWeaponLeftSlotC

• VehiclePowerWeaponRightSlotC

• VehicleMissileLauncherA

• VehicleMissileLauncherB

• VehicleMissileLauncherC

In these records, slots can be assigned to specific bones in the rig, or have their position and rotation adjusted.

Finding the string

You can search for it using Tweak Browser inside WolvenKit.

Choose the vehicle name you want to find and look for this structure:

• Vehicle.v_type_yourvehicle

Once you are inside, follow the path and unwrap the sub-categories. Here's an example with the Shion car.

The path looks like this :

▼ Vehicle.v_sport2_mizutani_shion_player ∟ ▼ vehDataPackage ­∟ ▼ driverCombat ∟ enumeName : Standard

Two examples in Wolvenkit:

You can see that vehDataPackage is also refered to Vehicle.v_type_yourvehicle_inlineX ( X = the line number inside the main file)

Result of the 2 previous example:

• Vehicle.v_sport2_mizutani_shion_inline1

• Vehicle.v_standard2_makigai_maimai_inline0

Modify the value in game using CyberEngineTweaks

If you want to do some tests with various vehicles and see if it's working, you can do it using CET. In the TweakDB Editor, search for your current vehicle and look for gamedataVehicleDataPackage_Record.

You will have the content of the vehDataPackage with the corresponding inline number.

Look in the right column for the value of driverCombat. Expand the tab and write DriverCombatTypes to see all the variations.

Now let's try to change the Porsche from Standard (windows) to Doors.

Add the changes in your mod

If you want to add this setting on an existing car or inside your new custom vehicle, you can add some lines in your .yaml file like this :

Many lights, such as the headlights on the porsche, are reflective lights, with headlight lenses. These lenses require lots of lighting settings, such as IOR, RefractionDepth, FresnelBias, and more. Example:

The other common option, is to use solid lights, as many modded cars do. These lights avoid using the complex light options, and instead opt to use block-style lights. These are done by creating a custom mesh, setting it as a light material, and covering it with blank normal map lenses or glass. (IOR=1.0 & RefractionDepth<0.2) Example:

Here is an explanation of some light options, based on my own experience. Note that these values are not fully understood currently. If you learn something about these values, please share!

• IOR : “Index of Refraction”. This seems to be an on/off switch for enabling refraction. Values greater than 1 enable refraction.

• RefractionDepth

• FresnelBias : Unknown. (does nothing?)

• NormalStrength : Strength of normal map on the mesh

• NormalMapAffectsSpecular : Strength of normal map on reflected light

• Normal : Path to normal map

• GlassRoughnessBias : n/a

• BlurRadius : n/a

For the emitted light beam, there are “vehicleLightComponent”s in the .app file components list. The localTransform can be edited by the position xyz bit values. Orientation will control which direction the light is aimed. Example LightComponent localTransform values:

To create a new light in a mesh that doesn’t have one already, you can duplicate the material in the mesh settings. Make sure to update the localMaterialBuffer or preloadLocalMaterialInstances, materialEntries, and appearance chunkMaterials. See:

Once the vehicle_lights material is linked in the mesh, it also need to be linked to a vehicleLightComponent in the .app file. You can use an existing lightComponent or duplicate a new one. The component has a parentTransform entry, and a bindName value which is used to set what mesh it is a part of. Example:

For lights like brakes, headlights, or reverse lights - you need to edit the vertex paint in Blender. Select the light emitting object in blender and switch to "Vertex Paint" mode. Example:

Set the color to one that enables the brake behavior, for brakes this is red in hex:

You must use these specific hex colors for lights to be activated properly:

• Headlights: #7C0101

• Taillights: #e7010

• Reverse lights: #cb0000

Use the Draw tool in Vertex Paint mode to draw on the color to the entire part. Example:

Lights should now be fully working.

Change headlight colors

Headlight colors are controlled in your vehicle's tweak file. You need to add this entry to your main Vehicle record:

The values are RGBA respectively so the above changes the headlight color to blue

Adjusting the tweak file from the previous section, here's how it should all look like:

To make interior lights work, you first need to create the light boundary/shape which will contain the interior light. This is defined in an entLightChannelComponent in your vehicle's ent

For eg in the porsche 911 .ent:

To create this shape, first we need to create a "cutout" of the interior mesh. Load your car's interior in a Blender project and join them all into a single mesh

Then you can create a cutout mesh by overlaying an Icosphere over your car's interior mesh and then using a Shrinkwrap modifier as shown:

You'll need to convert the .ent to JSON in wolvenkit, replace the indices and vertices array with the output of that script

Then you can convert the JSON back to .ent in wolvenkit

That's it! Like other light stuff (such as brake lights or headlights covered in other pages) - ensure you have an entLightChannelComponent in your .app parented to the interior.mesh (or whichever mesh has the interior light mesh + vehicle_lightsmaterial + vertex colors assigned )

Background

CrystalCoat™ works in a unique way: they make use of Inkwidgets

Inkwidgets are used to create in-game UI - like car interior UI, in-game computers, etc

This is important to understand because if you're hearing inkwidgets for the first time - you have to understand, this is not what they are traditionally used for. The game cleverly hacked inkwidgets to use as a dynamic material. Imagine car paint but it's made of tiny LEDs. So while it's brilliant in theory, it has its own challenges when adding to a custom vehicle.

CrystalCoat is made possible with two core components:

1. The core inkwidget: this consists of two inkImageWidget : primaryColor and a secondaryColor painted on a mask texture

2. The Crystal Coat .mt ( base\vehicles\common\materials\vehicle_modding_destruction.mt): this multilayer shader works behind the scenes to load/unwrap the above inkwidget onto the car part, whereas traditional inkwidgets would need a separate submesh - CrystalCoat inkwidgets don't.

How to add Crystal Coat

.ent

In your vehicle's .ent file, add a new appearance for Crystal Coat

We also need an entEffectSpawnerComponent for Crystal Coat fx effects. You can copy paste this as-is from the Aerondight .ent (base\vehicles\sport\v_sport1_rayfield_aerondight__basic_01.ent): EffectSpawner3546

.app

Define the appearance that you just created in the .ent: You can duplicate your default appearance to start with.

Updating mesh appearances

• For all the meshes that will change color, we need to add a new mesh appearance that uses the .mt I mentioned earlier

• To do this, simply duplicate your default mesh appearance, add a new customizable material entry, and copy-paste the material definition from for eg. base\vehicles\sport\v_sport1_rayfield_aerondight\entities\meshes\v_sport1_rayfield_aerondight__ext01_hood_a_01.mesh

• Remember to update the material values with your custom vehicle's mlsetup and mlmask paths

• Set the customizable material entry for all the submeshes that change color

Adding WorldWidgetComponent

• Go to Aerondight's .app file (base\vehicles\appearances\sport\rayfield_aerondight__basic.app) and find its customizable appearance ( appearances > player_01_customizable_01)

• Copy and paste all WorldWidgetComponents related to Crystal Coat (all of them will start with visual_customization_) to your customizable appearance

• Update the parentTransform and meshTargetBindingfor each of the components to the respective car part in your appearance as needed (they don't necessarily need to match one to one: for e.g., you can use the fuel_cap WorldWidgetComponent for something that's not a fuel cap)

.yaml / tweak edits

Add the following to your vehicle's tweak:

That's it! Install and launch - and you should see something happen.

Addressing issues

Unless you're extremely lucky, you should start seeing issues. Roughly there are two buckets of issues:

Glitches

What this is: Crystal Coat paint glitching to black or something in certain angles or certain TPP camera views

There are a few known causes and way to fix this:

• You have more than 10 WorldWidgetComponents

  • The game currently for whatever reason (likely for resource management) glitches if you have more than 10 WorldWidgetComponents defined and used in your customizable appearance

  • To address this, for now, you can try joining meshes like the fuelcap doesn't need to be a separate mesh, it can be part of the body so you can save 1 WorldWidgetComponent

• Angled meshes

  • Sometimes, or even randomly, certain meshes that are angled like door meshes for instance, can have a persistent glitch effect that comes and goes in certain angles

  • To address this, first try 'breaking' the component name

    • Crystal Coat identifies different car parts by looking at their component names, which are standard and common across cars like door_fl_a, etc

    • So for example, if you're facing glitches on your left door, try renaming your door_fl_a entPhysicalMeshComponent > door_fl_a_broken

    • Remember to update parentTransform and meshTargetBinding for the corresponding WorldWidgetComponent and see if this fixes your issue

    • If it does, rememeber to also update the destruction > detachableParts tweak record in your vehicle's tweak file since the door component name is now different

Artifacts

What this is: rectangluar or something artifacts on the paint OR inconsistent or incorrect direction of gradient colors

To fix this, we need to understand how the core inkwidget functions

To do this let's look at the Crystal Coat inkwidget (WorldWidgetComponent > widgetResource > base\gameplay\vehicles\visual_customization\vvc_car_appearance_widget.inkwidget)

Click into the "Widget Preview" tab > Export inkWidget as XML > save and open the XML file

The XML file (although currently Wkit doesn't support editing XML > inkwidget) will give you a good overview of how the inkwidget functionally works.

There are a lot of components (that aren't really needed -- we will see this in the next section) however the most important section is this one:

Here we see two InkImageWidgets being defined for the two colors that can be set for Crystal Coat. We also see a textureAtlas -> this is the mask which defines how the color is painted and controlled further with the layout and renderTransform values.

This is primarily what we're concerned with. The artifacts originate from these masks and any other color gradient issues as well

For most custom vehicles, it makes sense to have only one color i.e primaryColor as the customizable option. While it is possible to define both and somehow adjust the layout values to get the correct orientation, I have not tried that so let's focus on making this inkwidget paint ONLY the primaryColor

To do this, go back to the edit view and go to libraryItems > Root > package > inkWidgetLibraryItemInstance > gameController

You should see primaryColor and secondaryColor

From here you need to swap the mask with a completely white mask, adjust the layout an d renderTransform values so that primaryColor occupies the entire space. Then you need to make secondaryColor disappear similarly: you can delete the textureAtlas value and make the size = 1,1 which should make it disappear.

Note - you might also notice glitchAnims (and a dedicated an .inkanim file): these are used when the car gets hit by a bullet or collission. Feel free to remove or tweak thos as well.

Color accuracy

As of 2.12a, the base color (i.e. defined in the mlsetup of the customizable mesh appearance) of the vehicle has a heavy influence on the final Crystal Coat color

For eg, if your base color is white, then it's impossible to get accurate darker colors. And vice versa.

Changing the GUI

The Crystal Coat GUI is primary controlled via this Inkwidget: base\gameplay\gui\widgets\notifications\vehicle_visual_customization.inkwidget

If you want to load a custom GUI for your custom vehicle, you can use this redscript:

How to edit the Crystal Coat GUI

• You can replace assets by adding the respective .inkatlases to your project and linking them inside the inkwidget (fool proof of way of doing this is by converting the inkwidget to JSON, CTR + F and replace paths)

  • This way you can replace the default car preview with your own, remove the Rayfield logo, etc. You can also change the text by editing the Lockey

• To remove the secondary color picker, CTR + F in the inkwidget JSON for inkCircleInnerWidget, colorPickerInner, pointerTargetSelectedInner, inner-circle, gradient_circle_inner, color_wheel_inner, CirclesInner and set their opacity values: 0. Also set the isInteractive value to 0 (wherever it is set to 1 for the mentioned). You can then adjust the outer color picker as well, replace it with maybe a thicker color wheel like so in the inkatlas file:

Create a new WolvenKit project

In this section I will explain the minimal steps required in order to enable the feature on the vehicle. I will use the Mahir Supron vehicle as an example. You can buy this vehicle at the autofixer.

Enable the feature

First you need to make your vehicle entity aware of the CrystalCoat feature. To do this you need to use TweakXL. Open WolvenKit and look into the Tweak Browser. Type your vehicle record name and right-click on it. Then create a TweakXL Override.

This will generate a new YAML file with the record name into your project at resources/r6/tweaks. Open it and write this content. If needed, replace the vehicle record name at line 1 with yours. We will fill the customizableAppearance field later.

This will tell the game to allow this vehicle to toggle CrystalCoat and to display the color picker widget. Now in the vehicle entity (*.ent) file you need to create a new appearance dedicated to CrystalCoat for your vehicle.

How do appearances work ?

The game will load the vehicle using its base appearance that is defined in the vehicle record at the field appearanceName. This is what it does for all entities.

If the vehicle supports CrystalCoat, the game will assemble the entity during loading by swapping the appearance silently with the customizableAppearance.

What is important to note is that the appearance being used will still be the base appearance. But the components being loaded and visually present on the screen will be the customizable ones.

This is why I am saying that the customizableAppearance is being used silently.

Enable the visual distortion effect

When you toggle the CrystalCoat feature the game plays a distortion effect on the vehicle. This must be appended into the ENT file in the components > EffectSpawner3546 > effectDescs array.

The easiest way is to copy the effect entry from the Rayfield Caliburn's ENT file and paste it into yours.

Create a new entity appearance

Open the ENT file in WolvenKit. Click on the appearances array and then create a new appearance on the right.

Now define a unique name for the CrystalCoat appearance and write it down into the two fields:

• appearanceName

• name

It is not mandatory to use the same name in both fields but it will make things more simple. I would advise you to define a name that will not collide with another mod. You could for example use your nickname followed by the vehicle model followed by a CrystalCoat suffix:

You must also set the path to the APP file of the vehicle which contains the actual appearance definition. The appearanceName field must correspond to the appearance name that you will define into the APP file.

Additional steps for an existing vehicle

If you are modifying an existing vehicle of the game you should not replace the ENT file of the base game with yours or this will prevent other modders from adding new appearances to this vehicle.

Instead you shall use ArchiveXL to append your entity appearance to the base game ENT file dynamically. Create a new XL file by using the WolvenKit menu File > New File. Click on ArchiveXL then select the XL file type.

This will create a new file into resources folder. Add this content into it.

On the left side you must use the relative path to your own ENT file. Right-click on your ENT file in WolvenKit and copy its relative path then paste it here.

On the right side you must use the relative path to the base game ENT file. Find it using the Asset Browser and copy-paste its relative path.

Create a new APP appearance

Now you have created the top-level appearance you need to actually define it. This part is done into the APP file. Find the APP file using the Asset Browser and add it to your project. Then place it into your unique folder.

You shall duplicate the base appearance of the vehicle and change its name with what you have defined previously in the appearanceName field of the entity appearance. Then remove all appearances from the file leaving only the one you have just created.

Then you shall add engine\ink\textures\4x4_transparent.xbm into the resolvedDependencies array of the appearance.

Summary

This page will show you how to create the base files that will tell your game about the new car.

• in WolvenKit (wKit).

Create a new tweakXL .yaml file

Create a new tweakXL file by going to “New File” in the top left of wkit, just next to the HOME button.

Select TweakDB and TweakXL file. Name it something specific to your mod. example: “boe6_mini_cooper.yaml”

Open the .yaml file in your favorite text editor. I used notepad++.

Create a new tweak entry for your model.

Explanation:

$base:

• This should be set to the most similar in-game vehicle to your project. This is the tweak record that your car will mirror unless you set your own. You can find tweak names in the wKit tweak browser, search for the source car in the search bar on top. Look for Vehicle.v_NAME, it’s first entry should be “gamedataVehicle_Record”

  • example: “Vehicle.v_sport2_porsche_911turbo”

appearanceName:

• Needs to be set to the appearance name in the vehicle’s .ent file. The .ent file can be found inside your source vehicle’s tweak records. Locate the vehicle’s tweaks like before, Vehicle.v_sport2_porsche_911turbo for example, and scroll down for an entry titled “entityTemplatePath”. It should have an entry similar to this:

  • “Base\vehicles\sport\v_sport2_porsche_911turbo__basic_01.ent”

displayName:

• Set with your json file below.

player_audio_resource:

• This line is not necessary yet. It can be swapped for another vehicle’s engine sound later with whichever sounds closest to your desired vehicle.

entityTemplatePath:

• This is the file we just added in the appearanceName step earlier. To easily get this: in the project explorer, right click on the file and hit rename, or press F2. In the open window you can copy the path starting at base/… You can also copy the relative path by right clicking the file and selecting “copy relative path”. Now you can paste it into the .yaml entry.

Add your new vehicle tweak to the vehicle_list tweak, so the game can find it.

Create a .json file

Create a .json file in your project, the same as creating the .yaml. The option is about half way down the “CR2W Files” category. Name it the same as your vehicle (e.g. “boe6_mini_cooper.json”)

You’ll want to create your own project path at this point. With your mouse over the new .json file, on the right side hit the yellow “open in explorer” button to find the .json file in your file explorer, you should see just your .json file and a “base” folder. Create a new folder/path for your project files here. I created “boe6/mini_cooper/”. Now in wkit, move your .json into the new folder.

Your project file structure should now be similar to this:\

Open the .json in wKit by double clicking.

Under RDTDataViewModel, click on “root” : handle:ISerializable.

“root.root” will appear on the right side. Next to handle:ISerializable, click the yellow “Create Handle” button.

In the window that opens, click on the bottom text box to type in the following:

“localizationPersistenceOnScreenEntries”

You can use the autofill. Click “create”

Now under RDTDataViewModel, “root” is expandable. Click on the entries array under “root”.

Now on the right side, click “Create Item In Array”

Now we'll customize the new entry. Expand the item options and complete it to these values:

• “primaryKey” can be left at 0, and “maleVarient” can be left blank.

• “secondaryKey” is what your .yaml is referencing. This is the name given that will link to the .yaml. Example: “boe6_mini_cooper_name”

• “femaleVariant” is the actual display string. In this case, the vehicle’s name as it should be shown in the menus. Example: “Mini Cooper S”

Create 2 more entries in the array by right clicking the first array entry we just created, and hit “duplicate item in array/buffer” as shown:\

Swap the 2nd and 3rd string values for your vehicle’s year and description text.

example:

2nd:

secondaryKey: boe6_mini_cooper_info

femaleVariant: fancy description

3rd:

secondaryKey: boe6_mini_cooper_year

femaleVarient: 2003

\

Final .json should look similar this:

Return to your .yaml file and make sure your vehicle’s “displayName” is your secondaryKey entry. See earlier .yaml screenshot.

At this point you can test your mod to see if it loads in-game correctly. In general, you’ll want to launch the game and test as often as you can. I recommend changing one file at a time and testing each along the way to easily diagnose issues.

In wKit, at the end of the same line as “New File”, there is an “Install” button. For ease of testing, click the down arrow to show options and switch to “Install and Launch”. Now press “Install and Launch” to test the mod in-game.

Command Example:

It should show up as “TEST” in the vehicle call menu, as we haven't linked the json file to our mod yet. Once you call it, it should drive up with the model you are mirroring.

If the command does not add your vehicle to the vehicle call list, check if the Tweak Records have been saved correctly. To do this, open the TweakDB Editor in the CET overlay. Search for your vehicle’s name, and look for the Vehicle.name Record.

Move your source vehicle’s .ent file into the same file path as your .json file. Copy the file’s new path starting after “archive/…”, and update your .yaml tweak record so entityTemplatePath is showing your new path.

Example:

Save the file, and test again by using the Install and launch button. Load a save from before you’ve used the summon command in CET console.

Rename the .ent file and update the tweak in .yaml, like last step.

Example:

“boe6\mini_cooper\boe6_mini_cooper_basic.ent”

Now we’ll clean up the .ent file. Open it in wkit by double clicking. Under “RDTDataViewModel”, open the “appearances” array.

Find the appearance you’re currently mirroring and make note of it. Then select all the other appearances with ctrl+click, then right click and hit “Delete Selection in Array/Buffer”. This will leave you with one appearance. We’ll duplicate this later when we get to adding different paint colors.

Edit the “name” value to edit the array item. In my case, I change it from “porsche_911turbo__basic_johnny” to “boe6_mini_cooper_basic”

Also update your .yaml tweak to this for the appearanceName value.

Save, Install and Launch, test that it still works.

Add the .app file

Add the .app file to your project. Find it by navigating to the appearanceResource in your main appearance, which links to an .app file. Hit the yellow “Add File to Mod” button.

You’ll want to clean the appearances from this file as well. In the .ent file, note the appearanceName value. Then look at the .app file for the matching item in the list. That is the appearance we want to keep. The other appearances can be deleted as you did with the .ent file.

Now we can edit the appearanceName to an appropriate value related to our car.

Example:

And update it in your .app file as well in the “name” value:

Save and test. Get in the habit of testing often!

Notice the “components” list inside the appearance settings. These are the main parts of your vehicle, and all 3D model parts are referenced through here, with a .mesh file.

Move your .app file and rename it to a relevant name. Example:

“boe6\mini_cooper\boe6_mini_cooper.app”

Update your .ent file so the appearanceResource value matches the new file name & path.

Install & Test.

Finish setting up tweaks.

Open up your .yaml file.

We’ll start with adding a logo record for the vehicle’s brand/manufacturer. Add a UIIcon Tweak Record, with a $type: UIIcon_Record, atlasPartName, and atlasResourcePath. Example:

\

Copy the part name and path from your mirror car’s UIIcon_Record Tweak, which you can find in the tweak browser in wKit:

We’ll update these to custom file names/paths soon.

Next create a Tweak in the .yaml for the vehicle’s brand. This needs $type: VehicleManufacturer_Record, and an enumName. Example:

Now we need a gui data Tweak Record for our vehicle, with $type: VehicleUIData, productionYear, and info: LocKey#[vehicle]_info. Example:

\

Now we create a UIIcon Record for the vehicle’s image in the call menu, titled vehicle_icon or similar. Example:

Now these items can be referenced in the main vehicle tweak record. Add:

• icon: UIIcon.[your_vehicle]_icon

• manufacturer: Vehicle.[brand]

Example:

\

Add Virtual Car Dealer Tweak Values. Main settings are dealerPrice, dealerCred, dealerAtlasPath, and dealerPartName. We’ll just do the first 2 for now until we create the images for Virtual Car Dealer. These are added to you main vehicle. Example:

Recommended order:

• UIIcon.Brand_Logo:

• Vehicle.Brand:

• Vehicle.vehicle_data:

• UIIcon.vehicle_icon:

• Vehicle.vehicle:

• Vehicle.vehicle.[dealer settings]

• Vehicle.vehicle_list.list:

Example of currently finished .yaml:

Add the .xl file

Now we will add our .xl file.

This file lets the game know to use our .json file as localization.

Create a new file in wkit as done before. Under the ArchiveXL category, select “ArchiveXL file”. It should automatically open in your default text editor. Edit it with just 3 lines, a file structure for the .json file. Example:

Save and test.

The vehicle’s call menu should now show the vehicle’s name as specified in the .json, as well as the description info text.

Rename your .xl file to something appropriate. Files can cause issues if you use the same file name as another mod. Example:

“resources\boe6_mini_cooper.xl”

\

It's a problem that occurred when I created the vehicle mode and how to solve it

Create a WorldWidgetComponent

Each mesh component that you want to make colorable needs its own WorldWidgetComponent. For example you want the body_01_painted_custom component to be colored so you need to create a new item in the component list with type WorldWidgetComponent.

Now we will set it up for CrystalCoat. Some of its fields shall use specific values.

limitedSpawnDistanceFromVehicle = False
sceneWidgetProperties.IsAlwaysVisible = True
screenAreaMultiplier = 2
spawnDistanceOverride = 80
staticTextureResource = engine\ink\textures\4x4_transparent.xbm

For both the meshTargetBinding and parentTransform fields you shall create a handle. To do this click on the field, then on the right create a handle and select the only available type. Finally write the name of the mesh component into the bindName field of it. In this example the component name is body_01_painted_custom.

The name of the WorldWidgetComponent can use a pattern that will allow the script to handle any component for CrystalCoat. In order for this to work you must always use a name like this:

visual_customization_<mesh component name>

For this example the name will be visual_customization_body_01_painted_custom.

Now for the widgetResource field you must give it the InkWidget file that defines how the color will be wrapped onto the mesh.

The game uses a InkWidget that is customized for the Rayfield Caliburn or for the Rayfield Aerondight vehicles so it is unlikely to be usable as it is for any other vehicle without displaying unmatching patterns.

The details of how this InkWidget is structured and how to modify it will be covered into another paragraph. We will start in easy mode for now so we want a InkWidget that can be used on any part of any vehicle.

I have modified the InkWidget from the Rayfield Caliburn of the game v2.12a so it will display only a primary color on the entire UV map.

I will explain into another paragraph how the InkWidget is structured, how it works and how you can modify it to define a secondary color for your specific vehicle.

Deploy the CrystalCoat InkWidget

This ZIP archive contains 6 files:

• primary_color.inkatlas: this file uses a simple white square texture from the base game in order to apply a primary color for widgets.

• secondary_color.inkatlas: this file will be useful to add a secondary color mask to the widget.

• secondary_color.xbm: the mask texture associated with the InkAtlas.

• vvc_car_appearance_widget.inkwidget: this widget is meant to apply both a primary color and a secondary color on the vehicle. The secondary color will be applied using a mask. This is the most advanced widget we will use at the end of the tutorial.

• vvc_full_primary_only.inkwidget: we will use this widget at the beginning. It only applies a primary color on the entire component it is bound to.

• vvc_full_primary_and_secondary.inkwidget: this widget applies both a primary color and a secondary color on the entire component it is bound to. It does not use a mask file for the secondary color.

You must deploy these files into your project's unique folder, for example into a widget folder. Then we need to update the relative to the InkAtlas files into the three widgets.

When it comes to modifying a resource path into a InkWidget file it is more reliable to convert the widget into JSON and to modify the text file.

Right-click on the InkWidget file and click on Convert to JSON. This will create a clear-copy of the file as readable JSON into the raw folder. Open it with a text editor and replace the 3 occurrences of:

hgyi56_modding\\widget\\primary_color.inkatlas

By your relative path to primary_color.inkatlas (you must use double-backslashes \\). Next, replace the 2 occurrences of:

hgyi56_modding\\widget\\secondary_color.inkatlas

By your relative path to secondary_color.inkatlas (you must use double-backslashes \\).

Then save the file and right-click on the readable JSON file in the raw folder of the Project Explorer and click on Convert from JSON to rebuild the InkWidget file.

Now your InkWidget files are ready to be used by any component. For now we will only use the vvc_full_primary_only.inkwidget. Copy the relative path to your InkWidget file and write it into the widgetResource field of the WorldWidgetComponent.

You now have a WorldWidgetComponent properly configured for CrystalCoat. All you have to do in order to work with another mesh component is to duplicate this WorldWidgetComponent and then update its meshTargetBinding > bindName and parentTransform > bindName fields with the new component name.

You can finally test your mod !

Wait ! My doors are not colored ! This is not good !

Connect all the other components to CrystalCoat

This is great ! Now we need to apply CrystalCoat to all 6 doors and the side mirrors which correspond to these components:

• Driver door: door_fl_a

• Front passenger door: door_fr_a

• Back left door: door_bl_a

• Back right door: door_br_a

• Trunk left door: trunk_a

• Trunk right door: trunk_b

• Left mirror: mirror_fl_01

• Right mirror: mirror_fr

All you have to do is to follow this tutorial for each part of the vehicle.

Wait ! This is cheap CrystalCoat ! What kind of green is this ?

As you can see the base color of the vehicle under the CrystalCoat is still present and modifies the resulting color. When applying CrystalCoat on a vehicle we shall use dark gray or black color as the base color. I will cover this modification later in the tutorial.

Update detachable parts

Now you have added all 6 doors and side mirrors to CrystalCoat, you need to make the new components detachable along with their original component.

Use the Tweak Browser and look into the vehicle record in the destruction > detachableParts. Then look for the parts that correspond to the one you have duplicated.

In this picture you can see the TrunkLeft detachable part that corresponds to the trunk_a component. As we have duplicated this one to create the trunk_a_painted_custom, we need to add it into the list of components for this detachable part.

In order to create a YAML file dedicated to detachable parts, right-click on the detachableParts array and create a TweakXL override.

Then right-click on the TrunkLeft element and select TweakXL > Copy to clipboard. Finally erase the YAML file content with this data.

We want to append a new element to the components array.

Vehicle.VehicleDestructionParamsSupron_inline9.components:
  - !append trunk_a_painted_custom

Then repeat the same operation for all relevant detachable parts of the list. You should now have a YAML file with this content.

Vehicle.VehicleDestructionParamsSupron_inline9.components:
  - !append trunk_a_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline11.components:
  - !append trunk_b_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline19.components:
  - !append door_fl_a_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline20.components:
  - !append door_fr_a_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline21.components:
  - !append door_bl_a_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline22.components:
  - !append door_br_a_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline17.components:
  - !append mirror_fl_01_painted_custom

Vehicle.VehicleDestructionParamsSupron_inline18.components:
  - !append mirror_fr_painted_custom

Concerning the trunk_a part, you can see that it is also present into the destruction > deformableParts array.

So you need to perform the same operation that we did for the body_01_painted_custom component.

Let's say we want to give the user some choices to customize his vehicle. It would be great to allow for multiple paint aspects just like in real life.

Add a new mod setting to change paint

If we want to allow the user to choose between multiple paint aspects we need to create a choice mechanism. Mod Settings is made for this purpose. So let's create a new settings class into our script.

Let me explain what lies into the following code snippet. The SettingsPackage class contains the settings you will see in the Mod Settings menu of the game. Here you have two settings paintAspectEnabled and paintAspect.

The first one is a toggle that allows to turn on the custom paint feature. Indeed you still want to be able to use the default CrystalCoat we have already created which is what the base game is doing. The second setting will be enabled only if the first one is enabled too because I have set a dependency attribute (line 23).

The second setting uses a enumerated type EPaintAspect which is defined on top of the snippet. This enum will contain any paint aspect we want to define. To begin I have added a single one that corresponds to a metallic paint.

The second class is the MyModSettings class that we will call anywhere into the script to access our settings. This class contains the settings package instance into its settings field.

In order for this code to work into your mod you need to perform some case-sensitive replacements. First replace occurrences of "MyModName" (including quotes) by your mod name (with quotes) as you want it to appear in the ModSettings mods list. You should have replaced 2 occurrences.

Now you need to replace MyNickName-MyModName by what you may have already used during this paragraph to define your secondary keys for translation. You should have replaced 7 occurrences.

Finally replace MyNickName.MyModName by your module name which is at the very top of the script file. You should have replaced 1 occurrence.

enum EPaintAspect {
  Metallic = 0
}

public class SettingsPackage {

  /////////////////////////
  // GENERAL
  /////////////////////////

  @runtimeProperty("ModSettings.mod", "MyModName")
  @runtimeProperty("ModSettings.category", "MyNickName-MyModName-general-cat")
  @runtimeProperty("ModSettings.category.order", "1")
  @runtimeProperty("ModSettings.displayName", "MyNickName-MyModName-general-paint_aspect_enabled")
  @runtimeProperty("ModSettings.description", "MyNickName-MyModName-general-paint_aspect_enabled-desc")
  public let paintAspectEnabled: Bool = false;

  @runtimeProperty("ModSettings.mod", "MyModName")
  @runtimeProperty("ModSettings.category", "MyNickName-MyModName-general-cat")
  @runtimeProperty("ModSettings.category.order", "1")
  @runtimeProperty("ModSettings.displayName", "MyNickName-MyModName-general-paint_aspect")
  @runtimeProperty("ModSettings.description", "MyNickName-MyModName-general-paint_aspect-desc")
  @runtimeProperty("ModSettings.dependency", "paintAspectEnabled")
  @runtimeProperty("ModSettings.displayValues.Metallic", "MyNickName-MyModName-enum-metallic")
  public let paintAspect: EPaintAspect = EPaintAspect.Metallic;
}

public class MyModSettings extends ScriptableSystem {
  
  public let settings: ref<SettingsPackage>;

  public static func Get(gi: GameInstance) -> ref<MyModSettings> {
    return GameInstance.GetScriptableSystemsContainer(gi).Get(n"MyNickName.MyModName.MyModSettings") as MyModSettings;
  }

  private func OnAttach() -> Void {
    this.settings = new SettingsPackage();

    ModSettings.RegisterListenerToClass(this.settings);
  }
  
  private func OnDetach() -> Void {
    ModSettings.UnregisterListenerToClass(this.settings);
  }
}

You also need to add a new Painted value into the EMeshAppearanceCC enumerated type so we can handle paint materials.

enum EMeshAppearanceCC {
  Standard = 0,
  Coated = 1,
  Painted = 2
}

Finally we need to revise our Utils.CustomizeMesh method that actually swaps mesh appearances so it can accept a new one.

In the switch statement at line 7 we look for the vehicle model. You may need to update it if you are not using the Mahir Supron.

What this code block does is select the relevant mesh appearance depending on the CrystalCoat state. If it is turned off then it will use the standard mesh appearance. Otherwise if the custom paint toggle is enabled it will use the selected paint aspect (metallic) and if the toggle is disabled it will use the default coated mesh appearance you already know.

Then the for loop at line 24 looks for a corresponding WorldWidgetComponent associated with the current mesh component if one exists.

And finally the final switch statement at line 31 is actually affecting the new mesh appearance to the component.

public func CustomizeMesh(vehicleModel: ESupportedVehicle, ccEnabled: Bool, meshComp: ref<MeshComponent>, components: array<ref<IComponent>>) -> ref<IComponent> {
  let gi: GameInstance = this.GetGameInstance();

  let meshAppearance: String;
  let paintAspect: String = StrLower(ToString(MyModSettings.Get(gi).settings.paintAspect));
  let widget: ref<IComponent>;

  switch vehicleModel {
    case ESupportedVehicle.Supron:
      if ccEnabled {
        meshAppearance = ToString(MyModSettings.Get(gi).settings.paintAspectEnabled ? EMeshAppearanceCC.Painted : EMeshAppearanceCC.Coated);
      }
      else {
        meshAppearance = ToString(EMeshAppearanceCC.Standard);
      }
      break;

    default:
      return null;
      break;
  }
  meshAppearance = StrLower(meshAppearance);
  
  // Retrieve the optional CC widget
  for comp in components {
    if Equals(s"\(comp.GetName())", s"visual_customization_\(meshComp.name)") {
      widget = comp;
      break;
    }
  }
  
  switch meshAppearance {        
    case "painted":
      meshComp.meshAppearance = StringToName(paintAspect);
      break;

    default:
      meshComp.meshAppearance = StringToName(meshAppearance);
      break;
  }

  if Equals(meshAppearance, "coated")
  || Equals(meshAppearance, "painted") {
    return widget;
  }

  return null;
}

Add new localization keys for the menu

Now the code is ready, we need to add new localized strings to our existing JSON files. In the following content you need to replace the MyNickName-MyModName occurrences by what you have used previously. If you don't have created a translation file yet, then refer to this paragraph.

You should have replaced 6 occurrences.

{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Supron / General",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-cat"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Paint aspect",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-paint_aspect"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Choose what kind of paint you want to apply on the vehicle.",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-paint_aspect-desc"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Custom paint",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-paint_aspect_enabled"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Use a custom paint for the vehicle.",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-paint_aspect_enabled-desc"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Metallic",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-enum-metallic"
}

Defining a new paint material

We have just created the mechanism that allows the user to choose a different paint. Now we need to create the new paint material and add it into our mesh files.

Duplicate your existing coated.mlsetup file and name it metallic.mlsetup. Then convert it into JSON and open it in MlsetupBuilder (MLSB). Then in MLSB import layers to the editor by clicking on the orange button.

We know that our paint layer is 0 so we just need to modify this layer. Into the material template field use this one.

base\surfaces\materials\paint\car_paint\car_paint_metallic_01.mltemplate

This is the default metallic car paint material of the game. Then set these values into the material settings. Apply edits on the left before doing anything else or your changes will be lost.

Finally export the file and erase the JSON file. Then convert the JSON file back into mlsetup in WolvenKit.

Tiles = 25.0
Opacity = 1.0
Offset U = 0.0
Offset V = 0.0
Roughness In = null
Roughness Out = null
Normals = null
Metalness Out = null
ColorCode = 3eaf77_null
µBlends texture = base\surfaces\microblends\default.xbm
µBlends tiles = 10,1000004
µBlends contrast = 1
µBlends normals = 0
µBlends offset U = 0
µBlends offset V = 0

Create a new material into your mesh files

Add a new mesh appearance in the appearances array with name metallic containing a single chunk named metallic too.

Now you need to update the mesh file for each of your *_painted_custom components and add a new metallic material into them.

To do this duplicate the last entry of the materialEntries array and name it metallic then right-click on the array and choose Recalculate child index properties.

Then in the localMaterialBuffer > materials array right-click on the coated material and select Copy from Array/Buffer. Then right-click on the array and select Paste into Array/Buffer so it will be added to the end.

Now we need to set the material parameters. Open the metallic material and modify its MultilayerSetup field with the relative path to the new metallic.mlsetup file you have created.

Next we need to add several parameters into this material. To do this click on the values array and on the right click on Create Item In Array. Then for each parameter you will need to use the relevant type.

• Simple numbers like CoatFresnelBias or Opacity are using the Scalar type.

• RGBA colors like CoatTintFwd are using the Color type.

• Fields that use a XBM file path like GlobalNormal are using the Texture type.

For each parameter you need to set its name and its value. Then you will be able to copy these parameters or even the entire metallic material into the other mesh files as they all use the same mlmask and mlsetup in the case of the Mahir Supron.

Otherwise you need to copy the parameters into the existing material you have previously duplicated.

Now lets see the result.

Nice ! But I can see some stairs in the paint on the back doors !

Fix the paint on the back doors

As we have isolated all the painted parts it allows us to use a dedicated mlmask that will only allow the paint layer to be displayed. All of our painted components will use this new mlmask.

Copy any existing mlmask and rename it painted.mlmask. For example use the one from the Mahir Supron.

base\vehicles\standard\v_standard25_mahir_supron\entities\meshes\textures\mahir_supron__ext01_body_01_masksset.mlmask

Use the export tool Tools > Export Tool to generate PNG images for each layer in the raw folder. Then go into this folder and see that there are 20 layers as PNG files.

We know that the layer 0 is responsible for the painted areas. Then all we need to do is to use a full white image for layer 0 and a full black image for all the other layers so we are sure that they won't conflict with our paint.

The layer 0 is already a full white image so there is no need to change it. Either find another layer that is already full black or create one with an image editor software using the same image size. Then duplicate this file for all the other layers except layer 2 and reuse their name.

Then import the layers back into the mlmask file using the Tools > Import Tool.

Then affect your new mlmask file to all the painted components in the metallic material in the field MultilayerMask.

Then test the mod and see if the problem is solved.

Now all of our painted components are fixed. This metallic paint is beautiful !

What if I want to add another paint aspect ? Like a glossy paint ?

Creating a glossy paint

The work is essentially the same as the metallic paint we have just created. As we already have created the user choice mechanism before we can now simply add a new paint type into the script.

Add a new paint aspect in the enum type

enum EPaintAspect {
  Metallic = 0,
  Glossy = 1
}

Add a new translation item for the menu

At line 8 in this code snippet we need to add a new runtimeProperty to translate the new enum value.

@runtimeProperty("ModSettings.mod", "MyModName")
@runtimeProperty("ModSettings.category", "MyNickName-MyModName-general-cat")
@runtimeProperty("ModSettings.category.order", "1")
@runtimeProperty("ModSettings.displayName", "MyNickName-MyModName-general-paint_aspect")
@runtimeProperty("ModSettings.description", "MyNickName-MyModName-general-paint_aspect-desc")
@runtimeProperty("ModSettings.dependency", "paintAspectEnabled")
@runtimeProperty("ModSettings.displayValues.Metallic", "MyNickName-MyModName-enum-metallic")
@runtimeProperty("ModSettings.displayValues.Glossy", "MyNickName-MyModName-enum-glossy")
public let paintAspect: EPaintAspect = EPaintAspect.Metallic;

In the en-us.json language file we need to add a new localized string entry. Do the same for any other language file you may have defined.

{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Glossy",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-enum-glossy"
}

Create a new paint material

Duplicate the existing metallic.mlsetup file and name it glossy.mlsetup. Then open it in MLSB and replace layer 0's template file with this one.

base\surfaces\materials\plastic\plastic_hq\plastic_tech_hq_01_30.mltemplate

Then set these parameters for layer 0.

Tiles = 10.0
Opacity = 1.0
Offset U = 0.0
Offset V = 0.0
Roughness In = null
Roughness Out = (0.196,0)
Normals = (0.15)
Metalness Out = (0,0.25)
ColorCode = 3eaf77_null
µBlends texture = base\surfaces\microblends\default.xbm
µBlends tiles = 10,1000004
µBlends contrast = 1
µBlends normals = 0
µBlends offset U = 0
µBlends offset V = 0

Then save the file and import it back into WolvenKit.

Create a new appearance/material in mesh files

For all painted components duplicate the metallic appearance and replace its name and chunk with glossy. Then duplicate the materialEntries metallic entry and name it glossy then duplicate the associated localMaterialBuffer > materials metallic entry.

Finally assign the new glossy.mlsetup file into this material. Keep all the parameters identical to the metallic paint.

All you have to do now is to install the mod and select the new paint aspect in the mod settings !

Wonderful ! I can't believe it ! Well do you think that I could add other premios stuff to this vehicle ?

Summary

Created: Jun ?? 2024 by @hgyi56 Last documented update: -

What is CrystalCoat

From the in-game perspective, this is a technology developed by Rayfield manufacturer that enables a vehicle to get colored dynamically. You can think of it either as a huge matrix composed of tiny LEDs that would cover most parts of the vehicle allowing its user to select a color at any time.

Or it could also be a holographic technology that would cover the vehicle with some kind of 3D projection of a new color.

Now from the modder's perspective, this feature is made possible by applying InkWidgets onto mesh components.

InkWidgets were initially developed in order to display animated content for TVs, computer monitors or vehicle UI. From game v2.11 they are now also used to display colored shapes wrapped on a mesh dynamically.

Required mod dependencies

In order for your mod to work you need to install dependencies from Nexusmods:

• Codeware

• ArchiveXL

• TweakXL

• redscript

• RED4ext

• Mod Settings

• Either Crystal Coat Fix v2.12 or Enhanced Vehicle System

Required tools and skills

Well it depends on what you intend to do. This tutorial is incremental. It means that you start at the beginning and you can eventually stop at some point if what you have created satisfies your goal.

Although I explain things step by step it may not be exhaustive otherwise this tutorial would become very long. Here is a list of skills that will help you to go through this tutorial.

• Usage of WolvenKit. Using its tools, adding game files into your project, modifying array elements, knowing how to pack and install a mod, importing and exporting files from WolvenKit.

• Usage of MlsetupBuilder (MLSB). Installing and preparing the tool, importing and exporting mlsetup files, modifying a material layer.

• Usage of Blender. Installing the Cyberpunk related extension. Importing and exporting a entity or mesh file, creating a submesh.

• Usage of Adobe Photoshop (or another image editor). Have a basic knowledge of layers, channels, know how to use some tools like the magic wand, gradient tool, fill a selection, create a selection, create a layer style, apply a filter.

• Scripting basics. Know how to navigate into a JSON file, YAML file, REDS file, perform a replacement of a string, append a block by copy-pasting it from the tutorial.

• Usage of a good text editor. I recommend using Visual Studio Code and installing the redscript-ide extension and the redscript syntax highlight extension.

What can I do with this tutorial ?

You can test my mod Crystal Coat for Rayfield Caliburn to have an idea of what can be done.

Things you will be able to do after learning this tutorial:

• Add CrystalCoat to any kind of vehicle.

• Define a secondary color.

• Customize the color picker widget with your brand and vehicle image.

• Create multiple paint aspects and use any of them during runtime.

• Create multiple appearances for all the vehicle parts and use any of them during runtime.

• Clean the rust and dust from your vehicle parts and windows.

• Modify window glass.

• Create any amount of customizable components on your vehicle. They can be sub-parts of existing component.

• Customize the vehicle appearance when CrystalCoat is ON and when it is OFF during runtime.

• Allow anyone to add translations to your mod.

• Display vehicle part images in the mod settings menu.

• Create a default settings package for your mod settings to allow mod community admins to customize the mod's default settings for their users.

We have added customizable parts in the mod settings in this paragraph. So we can define parts appearance when CrystalCoat is ON and also when it is OFF. Most of the time, users will want to customize only one of the CrystalCoat states at a time.

So it would be nice to be able to hide all CrystalCoat ON/OFF settings. Mod Settings allows to do this natively using dependencies.

In the general settings category we need to add two toggle settings.

@runtimeProperty("ModSettings.mod", "MyModName")
@runtimeProperty("ModSettings.category", "MyNickName-MyModName-general-cat")
@runtimeProperty("ModSettings.category.order", "1")
@runtimeProperty("ModSettings.displayName", "MyNickName-MyModName-general-enable_cc_on")
@runtimeProperty("ModSettings.description", "MyNickName-MyModName-general-enable_cc_on-desc")
public let enableCCOnSettings: Bool = true;

@runtimeProperty("ModSettings.mod", "MyModName")
@runtimeProperty("ModSettings.category", "MyNickName-MyModName-general-cat")
@runtimeProperty("ModSettings.category.order", "1")
@runtimeProperty("ModSettings.displayName", "MyNickName-MyModName-general-enable_cc_off")
@runtimeProperty("ModSettings.description", "MyNickName-MyModName-general-enable_cc_off-desc")
public let enableCCOffSettings: Bool = false;

You must replace the secondary keys and the mod name with yours. Then into your JSON language files you must define 4 new keys.

{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Show CrystalCoat™ ON settings",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-enable_cc_on"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Show settings concerning the CrystalCoat™ ON state.",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-enable_cc_on-desc"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Show CrystalCoat™ OFF settings",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-enable_cc_off"
},
{
  "$type": "localizationPersistenceOnScreenEntry",
  "femaleVariant": "Show settings concerning the CrystalCoat™ OFF state.",
  "maleVariant": "",
  "primaryKey": "0",
  "secondaryKey": "MyNickName-MyModName-general-enable_cc_off-desc"
}

Then for each setting that concerns the CrystalCoat OFF state, we need to add a new runtimeProperty to create a dependency with the OFF toggle setting we have just created.

@runtimeProperty("ModSettings.dependency", "enableCCOffSettings")

Each setting that concerns the CrystalCoat ON state needs a new runtimeProperty to create a dependency with the ON toggle setting we have just created.

@runtimeProperty("ModSettings.dependency", "enableCCOnSettings")

When you disable either one of the toggle settings, their associated settings we be hidden from the mod settings page. This will allow for a better readability of your settings page.

Display vehicle parts

Another cool feature would be to display the vehicle parts associated with each setting so the user easily understand what he is modifying.

This feature requires to use additional files to add to your project.

This ZIP archive contains 3 files:

• vehicle_part.inkatlas: this file acts like an organizer for the following texture so the script can select only a portion of it.

• vehicle_part.xbm: a texture that contains one vehicle picture for each setting.

• vehicle_picture.inkwidget: this widget will display the vehicle image into the mod settings page.

Regroup these files into a folder then open the InkAtlas file and update its slots array by using the XBM texture file path into the texture field of each array element.

In order to create pictures for your settings you can use the photo mode of the game while your vehicle is using a specific appearance. In the example picture of the Caliburn above I have used a black matte paint with only the relevant component using a red glossy appearance.

Create a matte paint aspect

First lets create the matte paint aspect following this paragraph. I will only talk about the differences. Concerning the mlsetup, the base mltemplate file to use is this one.

base\surfaces\materials\plastic\plastic_hq\plastic_tech_hq_01_30.mltemplate

And the mlsetup parameters are these ones.

Offset U = 0.0
Offset V = 0.0
Roughness In = null
Roughness Out = (0.2953,0.498)
Normals = (undefined)
Metalness Out = (0,0.5)
ColorCode = 3eaf77_d42857
µBlends texture = base\surfaces\microblends\default.xbm
µBlends tiles = 10,1000004
µBlends contrast = 1
µBlends normals = 0
µBlends offset U = 0
µBlends offset V = 0

Next, for each impacted mesh file in the matte material remove all parameters except the MultilayerMask and MultilayerSetup.

Create a red appearance

Now we want all customizable components to be able to use a red glossy appearance. In order to do this follow this paragraph. I will only talk about the differences here.

In order to a have a deep color we need to create a custom mltemplate and define color codes into it. Then use this mltemplate file into the mlsetup instead of the original one. Add this file to your project and open it in WolvenKit.

base\surfaces\materials\plastic\plastic_hq\plastic_tech_hq_01_30.mltemplate

Go into overrides > colorScale > c2162c_null > v and set these values (1, 0, 0) for a deep red color. It uses a RGB float code. Index 0 is red, index 1 is green and index 2 is blue. Value 0 is black, 1 is white. Now save the file and copy its relative path.

In the mlsetup file use the path to your custom mltemplate file and then use the red color code we have modified c2162c_null. Then into the red material definition of the mesh files, set these parameters values.

CoatTintFwd = (red:127, green:127, blue:127, alpha:255)
CoatTintSide = (red:127, green:127, blue:127, alpha:255)
CoatSpecularColor = (red:191, green:191, blue:191, alpha:255)

For this we need to modify the type used by the sun visor setting field related to CrystalCoat ON state.

@runtimeProperty("ModSettings.mod", "MyModName")
@runtimeProperty("ModSettings.category", "MyNickName-MyModName-body-cat")
@runtimeProperty("ModSettings.category.order", "2")
@runtimeProperty("ModSettings.displayName", "MyNickName-MyModName-body-on-sunvisor")
@runtimeProperty("ModSettings.description", "MyNickName-MyModName-body-on-sunvisor-desc")
@runtimeProperty("ModSettings.displayValues.Standard", "MyNickName-MyModName-enum-standard")
@runtimeProperty("ModSettings.displayValues.Coated", "MyNickName-MyModName-enum-coated")
@runtimeProperty("ModSettings.displayValues.Painted", "MyNickName-MyModName-enum-painted")
@runtimeProperty("ModSettings.displayValues.Black", "MyNickName-MyModName-enum-black")
@runtimeProperty("ModSettings.displayValues.Red", "MyNickName-MyModName-enum-red")
@runtimeProperty("ModSettings.dependency", "enableCCOnSettings")
public let sunvisorAppearanceCC: EMeshAppearanceCC = EMeshAppearanceCC.Black;

Next we need to create a WorldWidgetComponent to enable CrystalCoat coloring on the sun visor.

Finally we need to copy the missing appearances, materialEntries and localMaterialBuffer > materials entries from the roof component and paste them into the sun visor mesh file.

We need to copy the coated, metallic, glossy and matte appearances and materials. Now our vehicle is ready for a photo shoot.

Create the vehicle parts texture

We have added a file named vehicle_parts.xbm to our project. This file contains a matrix of pictures for each of the customizable components of the vehicle. In order to populate this texture we will use Adobe Photoshop or another image editor.

Now take clean screenshots of the vehicle focused on the red part. We need one picture for each customizable component.

Into your image editor create a new project with a size of 2000x2000 pixels and a transparent background. We are going to append our pictures stick to each other from top to bottom and apply some color correction. As we only have 4 pictures we can simply put them one under the other.

Import your pictures one by one and resize them to 800px large by using Edit > Free Transform. Then use the Image > Auto Tone to fix the overall colors. You must have one picture per layer. So you need to apply the color correction on each of them seperately.

Now we need to enhance the red color to make it more visible. To do this select the areas that correspond to the red parts using the menu Select > Color Range. Then use a tolerance of 100 and once you are done, remove any part of the selection that wouldn't correspond to the red areas of the vehicle component.

Next use the menu Image > Adjustments > Vibrance and set a saturation of 100 and a vibrance of 50.

Next we need to crop the bottom corners so the images will fit into the widget. To do this create a rectangle selection with size 70x70 pixels. Then use Select > Transform Selection to rotate it to 45° so you get a diamond-shaped selection. Now save your selection using the menu Select > Save Selection and name it "big diamond".

Now move your selection to the bottom-right corner of the first picture so the center of the selection is aligned with the corner. Then select the corresponding layer, right-click on it and select Rasterize Layer. Then hit the DEL key to remove the pixels. Repeat this operation for the other pictures.

Now create a new selection with size 16x16 pixels and repeat the same operation with the bottom-left corner of all the pictures. You should now have this final result.

Export the vehicle_parts.xbm file into PNG using the Tools > Export Tool. Now erase the PNG file with your new texture. Then import it back into WolvenKit using these options.

Organize the texture parts

The next step is to open the vehicle_parts.inkatlas and define the different parts of the texture. To do this go into the slots > [0] > parts array. Edit the part_name element by changing its name with the component name body_01_roof_custom.

Then into the clippingRectInUVCoords field we need to define the texture area corresponding to the picture. UV coordinates goes from 0 to 1 in both axis. (0;0) is the top left corner of the texture, and (1;1) is the bottom-right corner. As we have defined 4 pictures vertically we must divide the parts as following.

Create duplicate this element in the parts array to create the other ones.

• body_01_roof_custom: Bottom:0,25, Left:0, Right:1, Top:0

• body_01_sunvisor_custom: Bottom:0,5, Left:0, Right:1, Top:0,25

• wheel_01_painted_custom: Bottom:0,75, Left:0, Right:1, Top:0,5

• wheel_01_inserts_custom: Bottom:1, Left:0, Right:1, Top:0,75

Now save the file and go into the Part Mapping tab to check the result. You should be able to select your pictures individually.

Add a new feature using script

In order for the mod settings menu to use your pictures and display a widget we need to add some code to create this new feature.

First add the new class into your script. Then perform some case-sensitive replacements into it.

• Replace MyNickName.MyModName with your module name (line 13).

• Replace path\\to\\vehicle_picture.inkwidget with the relative path to yours. You must use double-backslashes (\\) at line 18.

public class VehiclePart_WidgetHandler extends ScriptableSystem {
  
  public let modList: ref<inkWidget>;
  public let modListProxy: ref<inkAnimProxy>;

  public let widget: wref<inkWidget>;
  public let atlasResource: ResRef;
  public let texturePart: CName;

  public let shouldBeVisible: Bool = false;

  public static func Get(gi: GameInstance) -> ref<VehiclePart_WidgetHandler> {
    return GameInstance.GetScriptableSystemsContainer(gi).Get(n"MyNickName.MyModName.VehiclePart_WidgetHandler") as VehiclePart_WidgetHandler;
  }

  public func CreateWidget(parentWidget: ref<inkWidget>, settingsSelector: ref<SettingsSelectorController>) {
    if !IsDefined(this.widget) {
      let widgetResource: ResRef = r"path\\to\\vehicle_picture.inkwidget";
      this.widget = settingsSelector.SpawnFromExternal(parentWidget, widgetResource, n"Root");
    }
  }
  
  protected cb func ChangeVehiclePart(e: ref<inkAnimProxy>) -> Bool {
    if IsDefined(this.widget) {

      let imageWidget = (this.widget as inkCompoundWidget).GetWidgetByPathName(n"hint/car") as inkImage;
      imageWidget.SetAtlasResource(this.atlasResource);
      imageWidget.SetTexturePart(this.texturePart);

      if this.shouldBeVisible {
        this.FadeWidget(true);
      }
    }
  }

  public func FadeWidget(visible: Bool) -> ref<inkAnimProxy> {
    let targetOpacity = visible ? 1.0 : 0.0;
    let targetModListOpacity = visible ? 0.05 : 1.0;

    if !IsDefined(this.widget) {
      return null;
    }

    if IsDefined(this.modListProxy)
    && !this.modListProxy.IsFinished() {
      this.modListProxy.Stop();
    }

    let alphaAnim = new inkAnimTransparency();
    alphaAnim.SetStartTransparency(this.modList.GetOpacity());
    alphaAnim.SetEndTransparency(targetModListOpacity);
    alphaAnim.SetType(inkanimInterpolationType.Quartic);
    alphaAnim.SetMode(inkanimInterpolationMode.EasyOut);
    alphaAnim.SetDuration(0.5);
    
    if !visible {
      alphaAnim.SetStartDelay(1.0);
    }
    
    let animDef = new inkAnimDef();
    animDef.AddInterpolator(alphaAnim);
    this.modListProxy = this.modList.PlayAnimation(animDef);

    alphaAnim = new inkAnimTransparency();
    alphaAnim.SetStartTransparency(this.widget.GetOpacity());
    alphaAnim.SetEndTransparency(targetOpacity);
    alphaAnim.SetType(inkanimInterpolationType.Quartic);
    alphaAnim.SetMode(inkanimInterpolationMode.EasyInOut);
    alphaAnim.SetDuration(0.2);
    
    animDef = new inkAnimDef();
    animDef.AddInterpolator(alphaAnim);

    return this.widget.PlayAnimation(animDef);
  }
  
  public func ShowVehiclePart(atlasResource: ResRef, texturePart: CName, parentWidget: ref<inkWidget>, settingsSelector: ref<SettingsSelectorController>) {
    this.atlasResource = atlasResource;
    this.texturePart = texturePart;
    this.shouldBeVisible = true;

    this.CreateWidget(parentWidget, settingsSelector);
    let animProxy = this.FadeWidget(false);

    if IsDefined(animProxy) {
      animProxy.RegisterToCallback(inkanimEventType.OnFinish, this, n"ChangeVehiclePart");
    }
  }
}