feat: Removing prefix from asset loaders

[erickzanardo]

Description

Remove the asset-loading prefix

Images and AssetsCache silently rewrote every path they were given. Images prepended assets/images/, AssetsCache prepended assets/, both configurable via a prefix property. The path you wrote was not the path that got loaded, and the cache key was a third string again.

Every Flame asset API now takes the full bundle path, exactly as declared in pubspec.yaml, and that same string is the cache key. Nothing is ever prepended.

  // Before
  await Flame.images.load('player.png');

  // After
  await Flame.images.load('assets/images/player.png');

Breaking change on the v2.0.0 train. No deprecation period, full migration guide included.

What changed

flame. prefix deleted from both caches. Path building happens once in a shared resolver, which collapsed the duplicated key and prefix ternaries in AssetsCache. loadAllImages and loadAllFromPattern now take a required directory instead of using the prefix as both manifest filter and key strip.

flame_texturepacker. Most of this package's path arithmetic existed only to undo the prefix, reading assetsCache.prefix and img.prefix back out to strip them off resolved paths. assetsPrefix is gone and resolvePath became dead code. texture_packer_parser.dart lost 73 lines.

flame_tiled. prefix removed from TiledComponent.load, RenderableTiledMap.fromFile/fromString, and FlameTsxProvider.parse. Map file names are full paths and the "no path separators" assert is gone. Tileset and image-layer sources resolve against a new imagesDirectory argument defaulting to assets/images/, so resolution behavior is unchanged.

flame_audio. Global AudioCache built with an empty prefix. FlameAudio.updatePrefix removed, along with the save-restore-prefix hack in Bgm.play.

flame_sprite_fusion. tilemapPrefix removed. mapJsonFile and spriteSheetFile are full paths.

Checklist

• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Related Issues