Material Palette Asset Reference

Intermediate40-60 minutesWindowsUnturnedUnity Editor

The MaterialPaletteAsset is a configuration asset that allows an object to have multiple potential materials from which one is selected when the object is spawned in the level editor. Instead of every instance of a house, a tree, or a rock using the same material, a material palette provides visual variety by selecting a random material from a configured palette each time the object is placed. The system operates at the level editor placement stage: the palette is evaluated at spawn time, and the chosen material is baked into the placed object instance.

57 Studios has documented and validated the material palette asset configuration surface across the Unturned mapping community. This article covers the MaterialPaletteAsset .dat field reference, the master bundle pointer syntax for referencing materials in asset bundles, the random selection and manual assignment workflows in the level editor, and worked examples for common material palette use cases.

Documentation source: This article references the official Smartly Dressed Games modding documentation for field definitions and game behavior. Community-validated notes are marked where the official documentation is silent on a detail.

Who this article is for

This article is written for Unturned map authors who want to add visual variety to their maps by configuring material palettes for objects. If you are new to Unturned mapping, start with Custom Map Creation: Project Setup for the editor foundations, then return here for the material palette workflow.

How the material palette system works

The material palette system works at the level editor placement stage. An object asset defines a default material. A MaterialPaletteAsset associated with that object provides a list of alternative materials. When a map author places the object in the level editor, one material from the palette is selected at random and assigned to that specific instance. The map author can also manually assign a specific material from the palette to a selected object after placement.

As shown in the flowchart above, the palette is evaluated at the moment of object placement. After the material is baked into the object instance, the palette is not re-evaluated. Each placed instance retains its own material assignment independent of the palette.

Random selection

When an object with an associated material palette is placed in the level editor, the game randomly selects one material from the palette's Materials array. Each entry in the array has equal weight; there is no weighted selection mechanism. To bias the distribution toward a particular material, include that material multiple times in the array.

Manual assignment

After an object is placed, the map author can manually assign a material from the palette through the level editor's object properties panel. Manual assignment overrides the randomly selected material for that specific instance. The manual assignment persists across editor saves and reloads.

Material palette file structure

A material palette asset lives in the Bundles/Assets/ folder of a map project or mod:

Bundles/
└── Assets/
    └── Material_Palettes/
        └── House/
            ├── MaterialPalette.dat         ← palette asset definition
            └── MaterialPalette.unity3d     ← asset bundle containing the materials

The material palette asset references materials that are bundled in a Unity asset bundle. Each material in the palette is referenced by a master bundle pointer that specifies the bundle name and the path to the material within the bundle.

Complete .dat field reference

Metadata fields

Field	Type	Example	Required	Purpose
`GUID`	uint128 hex	`a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`	Yes	128-bit globally unique identifier. Generate a new GUID for every new material palette asset. Never reuse GUIDs.
`Type`	string	`SDG.Unturned.MaterialPaletteAsset`	Yes	The fully qualified type string that tells the engine this asset is a material palette. Must be exactly `SDG.Unturned.MaterialPaletteAsset`.

Material palette properties

Field	Type	Required	Purpose
`Materials`	array of master bundle pointer dictionaries	Yes	Each dictionary in the list points to a material bundled in Unity. The game randomly selects one material from this array when the object is placed.

Each entry in the Materials array is a master bundle pointer dictionary with the following fields:

Field	Type	Example	Purpose
`Name`	string	`core.masterbundle`	The name of the master bundle containing the material. Typically `core.masterbundle` for vanilla game materials, or a custom bundle name for modded materials.
`Path`	string	`Objects/Material_Palettes/House/House_00.mat`	The path to the material asset within the master bundle. The path is relative to the bundle's root.

Complete .dat example

GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
Type SDG.Unturned.MaterialPaletteAsset

Materials
[
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/House/House_00.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/House/House_01.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/House/House_02.mat
    }
]

This example defines a material palette with three material variants for a house object. When the house is placed in the level editor, one of the three materials is selected at random.

Worked examples

Example 1: Building material palette

A map author wants a warehouse object to have three material variants: clean, weathered, and rusted.

Materials array entries:

Materials
[
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Warehouse/Warehouse_Clean.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Warehouse/Warehouse_Weathered.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Warehouse/Warehouse_Rusted.mat
    }
]

Each time the warehouse is placed, the material is randomly selected from the three variants. The map author can override the selection for any specific instance through the level editor.

Example 2: Terrain prop palette

A map author wants a rock formation to have four color variants for natural variety.

Materials
[
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Rocks/Rock_Grey.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Rocks/Rock_Brown.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Rocks/Rock_Dark.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Rocks/Rock_Mossy.mat
    }
]

The rock formation randomly receives one of four color variants. The mossy variant is included as a less common variant; to increase its frequency, duplicate its entry in the array.

Example 3: Biased material distribution

A map author wants a tree to use a green leaf material 70% of the time and an autumn leaf material 30% of the time.

Materials
[
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Green.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Autumn.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Autumn.mat
    }
    {
        Name core.masterbundle
        Path Objects/Material_Palettes/Tree/Tree_Autumn.mat
    }
]

With 10 entries including 7 green and 3 autumn, the probability of selecting the green material is approximately 70% and the autumn material is approximately 30%. This is the standard technique for achieving weighted random selection in the material palette system.

Material authoring in Unity

The materials referenced by a material palette asset are standard Unity materials. They are bundled into a master bundle and referenced by path from the Materials array entries.

Material requirements

Requirement	Detail
Shader	Use Unturned-compatible shaders (Framework/Lit or similar)
Texture resolution	Power of two (256, 512, 1024, 2048)
Texture format	PNG or TGA for albedo, PNG for normal maps
Material name	Should match the path in the material palette entry
Bundle assignment	Material must be assigned to a master bundle

Material palette bundle structure in Unity

UnityProject/
└── Assets/
    └── Objects/
        └── Material_Palettes/
            └── House/
                ├── House_00.mat
                ├── House_01.mat
                ├── House_02.mat
                └── House_03.mat

The material files are standard Unity .mat assets. Each material is assigned to a master bundle in the Unity Asset Bundle system. The Path value in the material palette .dat file is the path to the material within the Unity project, relative to the Assets/ folder.

Frequently asked questions

How does the game choose which material from the palette to use?

The game performs a random selection from the Materials array at the moment the object is placed in the level editor. Each entry in the array has equal weight. To bias the selection, duplicate entries in the array. The selection is not re-evaluated after placement; each placed instance retains its material assignment permanently unless manually overridden.

Can a map author manually assign a material after placement?

Yes. Select the placed object in the level editor and choose a material from the palette through the object properties panel. The manual assignment overrides the randomly selected material for that specific instance. The override is permanent across editor saves and reloads.

Can a single material palette be used by multiple object types?

A material palette asset is not directly associated with a specific object type through the .dat file. The association is established in the level editor workflow: the palette is available as a material source for objects that reference it. The same palette can be used by multiple object types if those object types are configured to use the palette.

What happens if the Materials array is empty?

If the Materials array is empty or missing, the object uses its default material. The material palette system does not produce an error for an empty palette; it simply falls back to the object's built-in material. An empty palette is effectively a no-op.

Can I use materials from modded bundles?

Yes. The Name field in each material palette entry can reference any master bundle, including modded bundles. The Path field specifies the path within that bundle. If the bundle is not loaded at the time the object is placed, the material palette entry is skipped and a warning may be logged.

What is the difference between a material palette and a material override?

A material palette provides a list of potential materials from which the game randomly selects one at placement time. A material override is a direct assignment of a specific material to a specific object instance, performed manually by the map author after placement. The two mechanisms are complementary: the palette handles the initial random selection, and the override allows manual refinement.

How do I create a material for use in a palette?

Author the material in the Unity Editor with the Unturned-compatible shader, assign textures, configure material properties, and assign the material to a master bundle. The material is then referenced in the palette .dat file by its bundle name and path.

Can a material palette reference materials from a specific level's bundle?

Yes. The bundle can be a level-specific bundle or a shared master bundle. The Name field in the palette entry specifies which bundle to look in. If the bundle is not loaded when the object is placed, the entry is skipped.

Is there a limit to how many materials a palette can contain?

There is no documented limit on the number of entries in the Materials array. In practice, palettes with several dozen entries work correctly. Very large palettes (hundreds of entries) have not been tested by 57 Studios but should function within the engine's array size limits.

Can I reference the same material in multiple palettes?

Yes. The same material can be referenced by multiple material palette .dat files. The material bundle is loaded once and shared across all palettes that reference it. This reduces the total bundle size compared to duplicating materials across palette-specific bundles.

How do I debug a material palette that is not applying correctly?

Verify the material palette asset is loaded by checking the in-game console for asset loading messages. Confirm the GUID is unique and the Type string is exactly SDG.Unturned.MaterialPaletteAsset. Verify each material path by opening the referenced bundle and confirming the material exists at the specified path. Test with a single-entry palette first to isolate the issue.

Can I create a material palette with materials from multiple bundles?

Yes. Each entry in the Materials array specifies a bundle name and a material path. Different entries can reference different bundles. This allows a palette to combine materials from the core game bundle with materials from custom modded bundles.

What happens if a material referenced in the palette is not found at load time?

The engine logs a warning and skips the missing material entry. The palette continues to function with the remaining entries. If all entries fail, the object uses its default material. Verify material paths before publishing the map to avoid silent fallback behavior.

Can I use material palettes with animated materials?

Material palettes support any material type that the engine can render, including materials with animated properties. The material's animation is preserved when it is applied to the object instance. This is useful for objects with flickering lights, moving surfaces, or animated emissive effects.

Should every object type have a material palette?

No. Material palettes are beneficial for objects that appear multiple times across the map and would benefit from visual variety. Objects that appear once or twice (landmark buildings, unique props) do not need material palettes. Adding palettes to unique objects adds file management overhead without visual benefit.

Can I use a material palette with modded objects?

Yes. Material palettes work with any object type that supports material randomization, including modded objects. The palette is evaluated at placement time regardless of whether the object is vanilla or modded.

Best practices

Use descriptive names for material palette files and GUIDs to keep large map projects organized.
Organize material palettes into a folder structure that mirrors the object categories they serve (Buildings/, Foliage/, Terrain/, Props/).
Use biased distribution (duplicate entries in the array) sparingly and intentionally. A palette with 10 entries where 7 are identical is less maintainable than a palette with 3 unique entries.
Author at least 2-3 material variants per palette. A single-entry palette provides no randomness and is equivalent to no palette at all.
Test material palettes in the level editor by placing the object multiple times and verifying that different material variants appear.
Keep material textures at power-of-two resolutions for compatibility with the Unity asset pipeline.
Document the material bundle paths in the map project's documentation so other mappers on the team can find and edit the materials.

Appendix A: Material palette .dat quick-reference template

GUID <generated-uuid-no-hyphens>
Type SDG.Unturned.MaterialPaletteAsset

Materials
[
    {
        Name <bundle-name>
        Path <path/to/material.mat>
    }
    {
        Name <bundle-name>
        Path <path/to/material2.mat>
    }
]

Appendix B: Material palette organization for large map projects

Large map projects with dozens of material palettes benefit from a structured folder organization and naming convention.

Folder structure

Bundles/Assets/Material_Palettes/
├── Buildings/
│   ├── Warehouse/
│   │   ├── MaterialPalette.dat
│   │   └── WarehouseMaterials.unity3d
│   ├── House/
│   │   ├── MaterialPalette.dat
│   │   └── HouseMaterials.unity3d
│   └── Industrial/
│       ├── MaterialPalette.dat
│       └── IndustrialMaterials.unity3d
├── Terrain/
│   ├── Rocks/
│   │   ├── MaterialPalette.dat
│   │   └── RockMaterials.unity3d
│   └── GroundProps/
│       ├── MaterialPalette.dat
│       └── GroundPropMaterials.unity3d
├── Foliage/
│   ├── Trees/
│   │   ├── MaterialPalette.dat
│   │   └── TreeMaterials.unity3d
│   └── Bushes/
│       ├── MaterialPalette.dat
│       └── BushMaterials.unity3d
└── Props/
    ├── StreetFurniture/
    │   ├── MaterialPalette.dat
    │   └── StreetFurnitureMaterials.unity3d
    └── Decorative/
        ├── MaterialPalette.dat
        └── DecorativeMaterials.unity3d

Naming convention

Element	Convention	Example
Palette folder	PascalCase matching object category	`Warehouse`
Palette .dat	`MaterialPalette.dat`	`MaterialPalette.dat`
Material files	`ObjectName_VariantNN.mat`	`Warehouse_Clean.mat`
Bundle	`CategoryMaterials.unity3d`	`WarehouseMaterials.unity3d`
GUID	Freshly generated per palette	`a1b2c3d4...`

Appendix C: Material bundle authoring checklist

When authoring a master bundle for material palette materials, confirm the following:

[ ] Materials use Unturned-compatible shaders
[ ] Textures are at power-of-two resolutions
[ ] Material paths in the palette .dat match the Unity project paths
[ ] All materials are assigned to their intended bundle
[ ] The bundle builds without errors
[ ] The bundle filename matches the palette's Name field
[ ] Material colors are consistent with the object category's visual design
[ ] Each material in the palette is visually distinct from the others

Appendix D: Material palette use cases by object category

The table below documents common object categories and the recommended number of material variants per palette.

Object category	Recommended variants	Rationale
House exteriors	3-5	Visible variety across residential areas
Industrial buildings	2-3	Clean, weathered, rusted
Rocks and boulders	3-4	Grey, brown, dark, mossy
Trees (palette for bark)	2-3	Slight color variation for natural appearance
Street furniture	2-3	Clean and weathered variants
Fences and walls	2-3	Different wood or paint conditions
Ground props	2-4	Color variation for organic ground scatter
Decorative props	2	Standard and alternate color scheme

The variant counts above balance visual variety against file management overhead. A palette with too many variants (more than 5) adds marginal visual benefit while increasing the bundle size and palette file length. Three well-chosen variants produce a noticeably varied appearance without excess file weight.

Appendix E: Material palette troubleshooting table

Symptom	Most likely cause	Resolution
Object always uses default material	Material palette is not associated with the object	Verify palette association in the level editor
Some palette materials not appearing	Material bundle not loaded or path is incorrect	Verify the bundle name and material path in the palette entry
Material appears pink in the editor	Shader not found or material is missing textures	Verify the material's shader and texture assignments in Unity
Only one material variant appears	Other entries in the `Materials` array point to the same material or to missing materials	Verify each entry has a unique and valid material path
Palette does not appear in the editor	GUID conflict or type string is incorrect	Verify `GUID` is unique and `Type` is exactly `SDG.Unturned.MaterialPaletteAsset`
Manual material assignment reverts	Object instance not saved	Save the level after manual material assignment
Random selection is not random	Array entries all point to the same material	Verify each entry points to a distinct material
Material from modded bundle missing	Modded bundle not loaded at placement time	Ensure the mod is loaded in the level editor

Appendix C: External references

Smartly Dressed Games official modding documentation - Material Palette Assets - the authoritative field reference.
Unturned on Steam - the Unturned store page and community hub.
Custom Map Creation: Project Setup - the level editor foundations article.
Landscape Material Asset Reference - terrain material configuration.

Cross-references

Spawn Tables - the previous article; covers weighted loot table configuration.
Foliage Asset Reference - the next article; covers foliage and tree configuration for map environments.
Custom Map Creation: Project Setup - the level editor foundations article.
Landscape Material Asset Reference - terrain material configuration for landscape painting.
Smartly Dressed Games modding documentation - official field reference.
Unturned on Steam - game page and community.

Appendix F: Material palette migration between projects

When moving material palettes between map projects, the following fields must be updated for the new project.

Field	Action	Reason
GUID	Generate a new GUID	The GUID must be unique across all loaded assets
Bundle path	Verify the bundle exists in the new project	The bundle name may differ between projects
Material paths	Verify materials exist at the specified paths	The project asset structure may differ

The palette content (the list of materials) can be reused directly. The materials themselves must be bundled in the new project's asset bundles.

Appendix G: Material palette file audit checklist

Before adding a material palette to a map project, confirm the following file-level criteria:

[ ] GUID is unique across all palettes in the project
[ ] Type string is exactly SDG.Unturned.MaterialPaletteAsset
[ ] Materials array has at least 2 entries for meaningful randomization
[ ] Each material entry has a valid bundle name and material path
[ ] All referenced materials exist in the specified bundles
[ ] The bundle containing the materials builds without errors
[ ] The palette folder is organized according to the project convention
[ ] The palette GUID is documented in the project's asset registry

Authoring checklist

Before using a material palette in a map project, confirm the following:

[ ] GUID is unique and freshly generated
[ ] Type is SDG.Unturned.MaterialPaletteAsset
[ ] Materials array contains at least two entries for meaningful randomization
[ ] Each entry has a valid Name (bundle name) and Path (material path)
[ ] All referenced materials exist in the specified bundles
[ ] Tested in the level editor by placing the object multiple times
[ ] Manual material assignment works on placed instances
[ ] Biased distribution (duplicate entries) is documented

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Full MaterialPaletteAsset .dat field reference, master bundle pointer syntax, random selection and manual assignment workflows, worked examples, FAQ.

Material Palette Asset Reference ​

Who this article is for ​

How the material palette system works ​

Random selection ​

Manual assignment ​

Material palette file structure ​

Complete .dat field reference ​

Metadata fields ​

Material palette properties ​

Complete .dat example ​

Worked examples ​

Example 1: Building material palette ​

Example 2: Terrain prop palette ​

Example 3: Biased material distribution ​

Material authoring in Unity ​

Material requirements ​

Material palette bundle structure in Unity ​

Frequently asked questions ​

How does the game choose which material from the palette to use? ​

Can a map author manually assign a material after placement? ​

Can a single material palette be used by multiple object types? ​

What happens if the Materials array is empty? ​

Can I use materials from modded bundles? ​

What is the difference between a material palette and a material override? ​

How do I create a material for use in a palette? ​

Can a material palette reference materials from a specific level's bundle? ​

Is there a limit to how many materials a palette can contain? ​

Can I reference the same material in multiple palettes? ​

How do I debug a material palette that is not applying correctly? ​

Can I create a material palette with materials from multiple bundles? ​

What happens if a material referenced in the palette is not found at load time? ​

Can I use material palettes with animated materials? ​

Should every object type have a material palette? ​

Can I use a material palette with modded objects? ​

Best practices ​

Appendix A: Material palette .dat quick-reference template ​

Appendix B: Material palette organization for large map projects ​

Folder structure ​

Naming convention ​

Appendix C: Material bundle authoring checklist ​

Appendix D: Material palette use cases by object category ​

Appendix E: Material palette troubleshooting table ​

Appendix C: External references ​

Cross-references ​

Appendix F: Material palette migration between projects ​

Appendix G: Material palette file audit checklist ​

Authoring checklist ​

Document history ​