{
  "id": "unity/terrain-alphamap-resolution-mismatch",
  "signature": "ArgumentException: TerrainData.SetAlphamaps - alphamap resolution does not match terrain data",
  "signature_zh": "ArgumentException: TerrainData.SetAlphamaps - 透明度贴图分辨率与地形数据不匹配",
  "regex": "ArgumentException: TerrainData\\.SetAlphamaps - alphamap resolution does not match terrain data",
  "domain": "unity",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "The alphamap (splatmap) texture passed to TerrainData.SetAlphamaps has a resolution that does not match the terrain's configured alphamap resolution (width and height), causing an array dimension mismatch.",
  "root_cause_type": "generic",
  "root_cause_zh": "传递给TerrainData.SetAlphamaps的透明度贴图（混合贴图）纹理的分辨率与地形配置的透明度贴图分辨率（宽度和高度）不匹配，导致数组维度不一致。",
  "versions": [
    {
      "version": "Unity 2021.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Unity 2022.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Unity 2023.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "SetAlphamaps expects a 3D float array (float[,,]), not a Texture2D. Resizing a texture does not convert it to the correct data format.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "While this can work, it alters the terrain's base settings and may affect performance or other scripts that depend on the original resolution.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The error prevents alphamap updates, so terrain texturing will be incomplete or incorrect, leading to visual bugs.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Before calling SetAlphamaps, ensure the float array dimensions match the terrain's alphamap resolution: int width = terrainData.alphamapWidth; int height = terrainData.alphamapHeight; int layers = terrainData.alphamapLayers; float[,,] alphamaps = new float[height, width, layers]; Then populate and assign.",
      "success_rate": 0.95,
      "how": "Before calling SetAlphamaps, ensure the float array dimensions match the terrain's alphamap resolution: int width = terrainData.alphamapWidth; int height = terrainData.alphamapHeight; int layers = terrainData.alphamapLayers; float[,,] alphamaps = new float[height, width, layers]; Then populate and assign.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using a texture as source, read its pixels into a 2D array and resample to the correct resolution using bilinear interpolation before converting to a 3D float array.",
      "success_rate": 0.85,
      "how": "If using a texture as source, read its pixels into a 2D array and resample to the correct resolution using bilinear interpolation before converting to a 3D float array.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use terrainData.GetAlphamaps(0, 0, width, height) to retrieve the current alphamaps, modify only the necessary cells, and then call SetAlphamaps with the same dimensions.",
      "success_rate": 0.9,
      "how": "Use terrainData.GetAlphamaps(0, 0, width, height) to retrieve the current alphamaps, modify only the necessary cells, and then call SetAlphamaps with the same dimensions.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "在调用SetAlphamaps之前，确保float数组维度与地形的透明度贴图分辨率匹配：int width = terrainData.alphamapWidth; int height = terrainData.alphamapHeight; int layers = terrainData.alphamapLayers; float[,,] alphamaps = new float[height, width, layers]; 然后填充并赋值。",
    "如果使用纹理作为源，先读取其像素到2D数组，使用双线性插值重新采样到正确分辨率，然后再转换为3D float数组。",
    "使用terrainData.GetAlphamaps(0, 0, width, height)获取当前的透明度贴图，仅修改必要的单元格，然后使用相同维度调用SetAlphamaps。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.unity3d.com/ScriptReference/TerrainData.SetAlphamaps.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2023-09-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}