{"record":{"id":"ac097d91b41603e3","repo":"stride3d/stride","slug":"failed-to-parse-spritestudio-cell-textures","errorCode":null,"errorMessage":"Failed to parse SpriteStudio cell textures.","messagePattern":"Failed to parse SpriteStudio cell textures\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.SpriteStudio.Offline/SpriteStudioModelAssetCompiler.cs","lineNumber":34,"sourceCode":"using Stride.Core.Assets;\nusing Stride.Core.Mathematics;\nusing Stride.Core.Serialization.Contents;\n\nnamespace Stride.SpriteStudio.Offline\n{\n    [AssetCompiler(typeof(SpriteStudioModelAsset), typeof(AssetCompilationContext))]\n    internal class SpriteStudioModelAssetCompiler : AssetCompilerBase\n    {\n        protected override void Prepare(AssetCompilerContext context, AssetItem assetItem, string targetUrlInStorage, AssetCompilerResult result)\n        {\n            var asset = (SpriteStudioModelAsset)assetItem.Asset;\n            var gameSettingsAsset = context.GetGameSettingsAsset();\n            var renderingSettings = gameSettingsAsset.GetOrCreate<RenderingSettings>();\n            var colorSpace = renderingSettings.ColorSpace;\n\n            var cells = new List<SpriteStudioCell>();\n            var images = new List<UFile>();\n            if (!SpriteStudioXmlImport.ParseCellMaps(asset.Source, images, cells)) throw new Exception(\"Failed to parse SpriteStudio cell textures.\");\n\n            var texIndex = 0;\n            asset.BuildTextures.Clear();\n            foreach (var texture in images)\n            {\n                var textureAsset = new TextureAsset\n                {\n                    Id = AssetId.Empty, // CAUTION: It is important to use an empty GUID here, as we don't want the command to be rebuilt (by default, a new asset is creating a new guid)\n                    IsStreamable = false,\n                    IsCompressed = false,\n                    GenerateMipmaps = true,\n                    Type = new ColorTextureType\n                    {\n                        Alpha = AlphaFormat.Auto,\n                        PremultiplyAlpha = true,\n                        UseSRgbSampling = true,\n                    }\n                };","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.SpriteStudio.Offline/SpriteStudioModelAssetCompiler.cs#L16-L52","documentation":"During asset compilation, SpriteStudioModelAssetCompiler.Prepare parses the SpriteStudio cell map XML via SpriteStudioXmlImport.ParseCellMaps to extract cell definitions and texture references. If parsing fails (returns false) — malformed XML, missing required nodes, or a missing/unreadable source file — the compiler throws a generic Exception since the asset cannot be built.","triggerScenarios":"ParseCellMaps returning false for asset.Source: the .ssp/cell map file doesn't exist at the source path, the XML is not a valid SpriteStudio cell map (missing <cellmap>/<cell> or <img> elements), or the XML fails to load (encoding/schema issues).","commonSituations":"Exporting from SpriteStudio with an unsupported version/format; forgetting to include referenced texture files next to the cell map; renaming assets after export so paths in the XML break; hand-edited XML with schema errors.","solutions":["Verify asset.Source points to an existing, readable SpriteStudio cell map file and that referenced textures are present next to it","Re-export the cell map from SpriteStudio in a format/version supported by the importer (check the exporter version)","Validate the XML structure (cellmap root, cell entries, img attributes) — fix or remove hand edits","Enable asset-compiler logs for SpriteStudioXmlImport to see the precise parse failure before the generic exception"],"exampleFix":"// before (broken XML: missing img attribute)\n<cell name=\"hero\" x=\"0\" y=\"0\"/> <!-- parse fails -->\n// after (valid SpriteStudio cellmap)\n<cellmap>\n  <img name=\"hero.png\" width=\"256\" height=\"256\"/>\n  <cell name=\"hero\" x=\"0\" y=\"0\" width=\"64\" height=\"64\"/>\n</cellmap>","handlingStrategy":"validation","validationCode":"if (!File.Exists(asset.Source))\n    throw new BuildException($\"SpriteStudio cell map not found: {asset.Source}\");\n// plus XSD/structure check for <cellmap>/<cell>/<img> before compiling","typeGuard":null,"tryCatchPattern":"try\n{\n    ParseCellMaps(asset.Source, images, cells);\n}\ncatch (Exception ex)\n{\n    Logger.Error($\"Cell map parse failed: {ex.Message}\");\n    throw;\n}","preventionTips":["Validate cell map XML structure at export time","Keep referenced textures next to the cell map and use relative paths","Pin a supported SpriteStudio exporter version"],"tags":["asset-compiler","spritesheet","xml"],"backgroundTag":"xml-parse-error","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}