Art Asset Naming and Upload Standards
中文 | English
Run this command at the repository root to replay the examples through the local Unity MCP.
python Docs/Manual/manual/tools/tutorials.py run upload-naming-art-standards
Click to expand MCP actionsClick to collapse MCP actions
Prepare the teaching sample. The recipe provides ${variables}.
{
"variables": {},
"calls": [
{
"tool": "invoke",
"arguments": {
"path": "static:UnityEditor.AssetDatabase/CreateFolder",
"args": [
"${fixtureParent}",
"${folder}"
]
},
"expect": {
"contains": "(String)"
}
}
]
}
Keep each contribution to one coherent change, and give assets meaningful names. These rules apply to vehicles, maps, and shared resources in the official asset repository.
1. Branch scope
Each branch should contain as few changes as possible — ideally one tank or one aircraft per branch. Do not pile up a large batch of vehicle changes on a single branch and then ask for a merge; such merges will not be accepted. Narrow branches are easier to review one by one, to debug, and to revert.
2. Naming
- Start every file name with an uppercase letter, for example
PantherTurret.fbxrather thanpantherTurret.fbx,panther turret.fbx, or the all-capsPANTHERTURRET.FBX. - Use a name that says what the asset is, instead of
asdf.fbxorNewFile2.fbx. Use the same words for the model, textures, materials, and prefab of one part. - Watch your spelling:
Turret, notTuret. Check the file names once before exporting.
3. Replacing an FBX when modifying an existing model
Export the new FBX from your modelling software and overwrite the FBX at its existing path: either export under the same file name, or copy the new file over the old one in the folder. This cannot be done inside the Unity editor.
Keep the existing .meta so Unity continues to identify the FBX by the same GUID. Renaming or rebuilding a child mesh can still change its local file ID. After import, inspect the prefab's mesh references, material slots, and affected hierarchy nodes. Deleting the .meta or importing to a new path creates a new GUID.
If you added models inside the FBX, drag the reimported FBX into an empty scene, copy the newly added parts into the original prefab, and save it. Do not add a separate FBX file just because you added one more piece of geometry; otherwise you end up with XXX_fix.fbx, XXX_fix2.fbx, and so on, which turns the project into a mess.
4. Keep normal maps separate from base color maps
The normal map and the base color (RGB) map must be two separate textures; do not use one texture for both. In your modelling software, do not feed the RGB map into the Normal input. In Unity, set the normal texture's Texture Type to Normal map, connect the base color texture to the Base Color input, and let each input point at its own texture.
The legacy advice "do not set Normal strength" is scoped to imported materials: keep the default Normal strength and do not override it per model without a reason. Unity shaders do expose a Normal strength / Bump scale parameter; the rule is about avoiding arbitrary per-model overrides on imported assets.
5. Avoid duplicate materials
Duplicate materials are separate materials that use exactly the same textures. They increase rendering cost and make later bulk edits easy to miss.
When duplicating objects in Blender, use Shift+D instead of Ctrl+C and Ctrl+V, and avoid copying objects between files; pasting across files copies the materials with them and creates duplicates.
For duplicates that already exist, unify them by hand: replace each object's material reference with the same shared material. The material dropdown lists the candidates, and duplicated ones normally end with .001, .002, and so on; you can also look them up by name in the search box above.
Click to expand MCP actionsClick to collapse MCP actions
Verify separate base-color and normal texture imports plus stable asset GUID on overwrite. Check an FBX's child mesh references separately.
[
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"\nlocal u, e, io = CS.UnityEngine, CS.UnityEditor, CS.System.IO\nlocal base = \"${fixture}/TutorialTank_BaseColor.png\"\nlocal normal = \"${fixture}/TutorialTank_Normal.png\"\nlocal tex = u.Texture2D(2, 2, u.TextureFormat.RGBA32, false)\nlocal function write(path, r, g, b)\n for x=0,1 do\n for y=0,1 do\n tex:SetPixel(x, y, u.Color(r,g,b,1))\n end\n end\n tex:Apply()\n io.File.WriteAllBytes(path, u.ImageConversion.EncodeToPNG(tex))\n e.AssetDatabase.ImportAsset(path, e.ImportAssetOptions.ForceSynchronousImport)\nend\nlocal ok, issue = pcall(function()\n write(base,0.7,0.6,0.5)\n write(normal,0.5,0.5,1)\n local baseGuid = e.AssetDatabase.AssetPathToGUID(base)\n assert(baseGuid ~= \"\" and baseGuid ~= e.AssetDatabase.AssetPathToGUID(normal))\n local baseImporter = e.AssetImporter.GetAtPath(base)\n baseImporter.textureType = e.TextureImporterType.Default\n baseImporter.sRGBTexture = true\n baseImporter:SaveAndReimport()\n local normalImporter = e.AssetImporter.GetAtPath(normal)\n normalImporter.textureType = e.TextureImporterType.NormalMap\n normalImporter.sRGBTexture = false\n normalImporter:SaveAndReimport()\n write(base,0.2,0.4,0.6)\n assert(e.AssetDatabase.AssetPathToGUID(base) == baseGuid)\n assert(e.AssetImporter.GetAtPath(base).sRGBTexture)\n assert(e.AssetImporter.GetAtPath(normal).textureType == e.TextureImporterType.NormalMap)\n assert(not e.AssetImporter.GetAtPath(normal).sRGBTexture)\nend)\nu.Object.DestroyImmediate(tex)\nassert(ok,issue)\nreturn \"Independent texture imports verified; overwrite kept original asset GUID\"\n",
"art-import-sample",
"null"
]
},
"expect": {
"contains": "overwrite kept original asset GUID"
}
}
]