Skip to content

Commit f4987fa

Browse files
s1r1m1r1s1r1m1r1
committed
(#3861) fix example , improve example
1 parent a2b7f93 commit f4987fa

File tree

10 files changed

+920
-579
lines changed

10 files changed

+920
-579
lines changed

‎packages/flame_texturepacker/README.md‎

Lines changed: 112 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,96 @@ Import the plugin like this:
5656
Load the TextureAtlas passing the path of the sprite sheet atlas file:
5757

5858
```Dart
59-
final atlas = await atlasFromAssets('atlas_map.atlas');
59+
final atlas = await TexturePackerAtlas.load('atlas_map.atlas');
60+
```
61+
62+
63+
### Extension on Game
64+
65+
66+
For convenience, there is also an extension on `Game` (and `FlameGame`)
67+
that allows you to load an atlas directly:
68+
69+
70+
```dart
71+
class MyGame extends FlameGame {
72+
@override
73+
Future<void> onLoad() async {
74+
final atlas = await atlasFromAssets('atlas_map.atlas');
75+
// ...
76+
}
77+
}
78+
```
79+
80+
81+
### Loading from a Package
82+
83+
84+
To load an atlas from another Flutter package, use the `package` parameter:
85+
86+
```Dart
87+
final atlas = await TexturePackerAtlas.load(
88+
'atlas_map.atlas',
89+
package: 'my_assets_package',
90+
);
91+
```
92+
93+
94+
### Paths and Prefixes
95+
96+
97+
By default, `TexturePackerAtlas.load` looks for files in `assets/images/`. This is controlled by the
98+
`assetsPrefix` parameter, which defaults to `'images'`.
99+
100+
101+
#### 1. Default usage (relative to `assets/images/`)
102+
103+
104+
```dart
105+
// Path: assets/images/hero.atlas
106+
final atlas = await TexturePackerAtlas.load('hero.atlas');
107+
```
108+
109+
110+
#### 2. Custom prefix (relative to `assets/`)
111+
112+
113+
```dart
114+
// Path: assets/atlases/hero.atlas
115+
final atlas = await TexturePackerAtlas.load(
116+
'hero.atlas',
117+
assetsPrefix: 'atlases',
118+
);
119+
```
120+
121+
122+
#### 3. Full path (stripping standard prefix)
123+
124+
125+
If you provide a path that already includes the standard `assets/`
126+
or `images/` prefix, the library will automatically strip them to avoid duplication.
127+
This is particularly useful when working with full asset paths.
128+
129+
130+
```dart
131+
// Path: assets/images/mega_explosions.atlas
132+
final atlas = await TexturePackerAtlas.load(
133+
'assets/images/mega_explosions.atlas',
134+
assetsPrefix: '',
135+
);
136+
```
137+
138+
139+
#### 4. Automatic Package Detection
140+
141+
142+
If you provide a path that starts with `packages/package_name/...`,
143+
the library will automatically detect the package name
144+
and adjust the internal loading logic.
145+
146+
```dart
147+
// Path: packages/my_assets_package/assets/images/heroes.atlas
148+
final atlas = await TexturePackerAtlas.load('packages/my_assets_package/assets/images/heroes.atlas');
60149
```
61150

62151

@@ -81,7 +170,10 @@ If you are using file storage, grab your atlas file like this:
81170

82171
```Dart
83172
final documentsPath = (await getApplicationDocumentsDirectory()).path;
84-
final atlas = await atlasFromStorage('$documentsPath/atlas_map.atlas');
173+
final atlas = await TexturePackerAtlas.load(
174+
'$documentsPath/atlas_map.atlas',
175+
fromStorage: true,
176+
);
85177
```
86178

87179
Get a list of sprites ordered by their index, you can use the list to generate an animation:
@@ -96,6 +188,22 @@ final animation = SpriteAnimation.spriteList(
96188
);
97189
```
98190

191+
Or use the convenience method `getAnimation`:
192+
193+
```Dart
194+
final animation = atlas.getAnimation('robot_walk', stepTime: 0.1, loop: true);
195+
```
196+
197+
If your atlas contains multiple animations, load it once and reuse it:
198+
199+
```Dart
200+
final atlas = await TexturePackerAtlas.load('atlas_map.atlas');
201+
202+
final walkAnim = atlas.getAnimation('robot_walk');
203+
final runAnim = atlas.getAnimation('robot_run');
204+
final jumpAnim = atlas.getAnimation('robot_jump', loop: false);
205+
```
206+
99207
Get individual sprites by name:
100208

101209
```Dart
@@ -112,8 +220,8 @@ final idleSprite = atlas.findSpriteByName('robot_idle')!;
112220
| Allow Rotation | YES |
113221
| Multiple Pages | YES |
114222
| Use indices | YES |
115-
| Strip whitespace X | NO |
116-
| Strip whitespace Y | NO |
223+
| Strip whitespace X | YES |
224+
| Strip whitespace Y | YES |
117225

118226

119227
## Example

‎packages/flame_texturepacker/lib/flame_texturepacker.dart‎

Lines changed: 2 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,6 @@
11
library flame_texturepacker;
22

3-
import 'package:flame/cache.dart';
4-
import 'package:flame/game.dart';
5-
import 'package:flame_texturepacker/src/texture_packer_atlas.dart';
6-
3+
export 'package:flame_texturepacker/src/extension_on_game.dart';
74
export 'package:flame_texturepacker/src/texture_packer_atlas.dart';
5+
export 'package:flame_texturepacker/src/texture_packer_parser.dart';
86
export 'package:flame_texturepacker/src/texture_packer_sprite.dart';
9-
10-
extension TexturepackerLoader on Game {
11-
/// Loads the specified pack file from assets
12-
/// Uses the parent directory of the pack file to find the page images.
13-
Future<TexturePackerAtlas> atlasFromAssets(
14-
String assetsPath, {
15-
Images? images,
16-
AssetsCache? assets,
17-
bool useOriginalSize = true,
18-
List<String> whiteList = const [],
19-
String assetsPrefix = 'images',
20-
}) async => TexturePackerAtlas.load(
21-
assetsPath,
22-
images: images ?? this.images,
23-
assets: assets ?? this.assets,
24-
useOriginalSize: useOriginalSize,
25-
whiteList: whiteList,
26-
assetsPrefix: assetsPrefix,
27-
);
28-
29-
/// Loads the specified pack file from storage
30-
/// Uses the parent directory of the pack file to find the page images.
31-
Future<TexturePackerAtlas> atlasFromStorage(
32-
String storagePath, {
33-
Images? images,
34-
bool useOriginalSize = true,
35-
List<String> whiteList = const [],
36-
}) async => TexturePackerAtlas.load(
37-
storagePath,
38-
fromStorage: true,
39-
images: images ?? this.images,
40-
useOriginalSize: useOriginalSize,
41-
whiteList: whiteList,
42-
);
43-
}

‎packages/flame_texturepacker/lib/src/extension_on_game.dart‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import 'package:flame/cache.dart';
2+
import 'package:flame/game.dart';
3+
import 'package:flame_texturepacker/flame_texturepacker.dart';
4+
5+
extension TexturepackerLoader on Game {
6+
/// Loads the specified pack file from assets
7+
/// Uses the parent directory of the pack file to find the page images.
8+
Future<TexturePackerAtlas> atlasFromAssets(
9+
String assetsPath, {
10+
Images? images,
11+
AssetsCache? assets,
12+
bool useOriginalSize = true,
13+
List<String> whiteList = const [],
14+
String assetsPrefix = 'images',
15+
String? package,
16+
}) =>
17+
TexturePackerAtlas.load(
18+
assetsPath,
19+
images: images ?? this.images,
20+
assets: assets ?? this.assets,
21+
useOriginalSize: useOriginalSize,
22+
whiteList: whiteList,
23+
assetsPrefix: assetsPrefix,
24+
package: package,
25+
);
26+
27+
/// Loads the specified pack file from storage
28+
/// Uses the parent directory of the pack file to find the page images.
29+
Future<TexturePackerAtlas> atlasFromStorage(
30+
String storagePath, {
31+
Images? images,
32+
bool useOriginalSize = true,
33+
List<String> whiteList = const [],
34+
}) =>
35+
TexturePackerAtlas.load(
36+
storagePath,
37+
fromStorage: true,
38+
images: images ?? this.images,
39+
useOriginalSize: useOriginalSize,
40+
whiteList: whiteList,
41+
);
42+
}

‎packages/flame_texturepacker/lib/src/model/page.dart‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,14 @@ import 'dart:ui';
22

33
class Page {
44
late String textureFile;
5-
late Image texture;
5+
Image? texture;
66
late int width;
77
late int height;
88
late String format;
99
late String minFilter;
1010
late String magFilter;
11-
late String repeat;
11+
String? repeat;
12+
13+
/// Returns true if the texture has been loaded.
14+
bool get isLoaded => texture != null;
1215
}

0 commit comments

Comments
 (0)