[flame_texturepacker] Improve Path Resolution and Region Parsing #3848

[s1r1m1r1]

How can we reproduce this?

1. Path Resolution: Create a modular Flutter project where assets are located in a different package. Attempt to load a .atlas file using a path that starts with packages/. Flame's AssetsCache will incorrectly prepend assets/, resulting in a load failure (e.g., trying to load assets/packages/pkg_name/...).
2. Region Parsing: Use an atlas file where region names include file extensions (e.g., knight_walk_01.png). The current parser incorrectly identifies these as new page headers.
3. Animation Indexing: Use region names with numeric suffixes (e.g., frame_01, frame_02) but without explicit index: properties in the atlas file. findSpritesByName will fail to group them correctly for animations.

What steps should take to fix this?

1. Auto-Package Detection: Modify TexturePackerAtlas.load (specifically _parse and _parsePage) to automatically detect packages/ in the path string, extract the package name, and pass it to Flame's readFile and Images.load while cleaning the path.
2. Region Identification: Update the region parsing loop to peek at the next line. If it contains region-specific properties like bounds: or rotate:, treat the current line as a region name even if it has a file extension.
3. Index Extraction: In _parseRegion, use a RegExp to extract numeric suffixes (like _01) from the name and use them as the default index if no explicit index is provided.

Do have an example of where the bug occurs?

Yes, this occurs in projects using flutter_gen for asset management in modular architectures, and with certain TexturePacker export profiles that include extensions in the atlas file.

Relevant log output

flutter:  error:Unable to load asset: "assets/packages/mygame_assets/assets/images/knight.atlas".
flutter: PlatformDispatcherUnable to load asset: "packages/mygame_assets/assets/images/knight_export_aim3_01.png".
flutter: PlatformDispatcher'package:flame/src/sprite_animation.dart': Failed assertion: line 145 pos 14: 'frames.isNotEmpty': There must be at least one animation frame

Execute in a terminal and put output into the code block below

Output of: flutter doctor -v

[✓] Flutter (Channel stable, 3.41.2, on macOS 26.2 25C56 darwin-arm64, locale en-RU)
    • Flutter version 3.41.2 on channel stable at /Users/$USER/.asdf/installs/flutter/3.41.2-stable
    • Framework revision 90673a4eef (2 weeks ago), 2026-02-18 13:54:59 -0800
    • Engine revision 6c0baaebf7
    • Dart version 3.11.0
    • DevTools version 2.54.1

[✓] Android toolchain - develop for Android devices (Android SDK version 36.1.0)
    • Android SDK at /Users/$USER/Library/Android/sdk
    • Java binary at: /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment Temurin-21.0.8+9 (build 21.0.8+9-LTS)

[✓] Xcode - develop for iOS and macOS (Xcode 26.2)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 17C52
    • CocoaPods version 1.16.2

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Connected device (2 available)
    • macOS (desktop) • macos  • darwin-arm64   • macOS 26.2 25C56 darwin-arm64
    • Chrome (web)    • chrome • web-javascript • Google Chrome 145.0.7632.160

[✓] Network resources
    • All expected network resources are available.

Affected platforms

macOS, Android, iOS

Other information

I have already implemented and verified these fixes in a local fork. The changes include:

• Refined path resolution for modular projects.
• Robust parsing for various atlas formats (including those with extensions in names).
• Automatic index extraction for smoother animation loading.
• Comprehensive regression tests in atlas_path_resolution_test.dart.

Are you interested in working on a PR for this?

• I want to work on this

[spydon]

Duplicate of #3847