feat: Add network assets package. (flame-engine#2314)

# Description

Adds some documentation and a package that can be used to fetch assets
from the network.

.github/.cspell/gamedev_dictionary.txt

@@ -154,3 +154,4 @@ viewport's
 viewports
 vsync
 widget's
+unawaited

.gitignore

@@ -31,6 +31,9 @@ pubspec.lock
 .pub/
 android/
 ios/
+macos/
+windows/
+linux/
 desktop/
 build/
 coverage/

doc/bridge_packages/bridge_packages.md

@@ -25,6 +25,11 @@ A Box2D physics engine (bridge package for [Forge2D]).
 Use isolates to offload heavy computations to another thread.
 :::
 
+:::{package} flame_network_assets
+
+Fetch assets over the network.
+:::
+
 :::{package} flame_oxygen
 
 Replace FCS with the Oxygen Entity Component System.
@@ -68,6 +73,7 @@ flame_fire_atlas    <flame_fire_atlas/flame_fire_atlas.md>
 flame_forge2d       <flame_forge2d/flame_forge2d.md>
 flame_isolate       <flame_isolate/flame_isolate.md>
 flame_lottie        <flame_lottie/flame_lottie.md>
+flame_network_assets        <flame_network_assets/flame_network_assets.md>
 flame_oxygen        <flame_oxygen/flame_oxygen.md>
 flame_rive          <flame_rive/flame_rive.md>
 flame_splash_screen <flame_splash_screen/flame_splash_screen.md>

doc/bridge_packages/flame_network_assets/flame_network_assets.md

@@ -0,0 +1,35 @@
+# FlameNetworkAssets
+
+`FlameNetworkAssets` is a bridge package focused on providing a solution to fetch, and cache assets
+from the network.
+
+The `FlameNetworkAssets` class provides an abstraction that should be extended in order to create
+asset specific handler.
+
+By default, the package relies on the `http` package to make http requests, and `path_provider`
+to get the place to store the local cache, to use a different approach for those, use the
+optional arguments in the constructor.
+
+This package bundles a specific asset handler class for images:
+
+```dart
+final networkAssets = FlameNetworkImages();
+final playerSprite = await networkAssets.load('https://url.com/image.png');
+```
+
+To create a specific asset handler class, you just need to extend the `FlameNetworkAssets` class
+and define the `decodeAsset` and `endcodeAsset` arguments:
+
+```dart
+class FlameNetworkCustomAsset extends FlameNetworkAssets<CustomAsset> {
+  FlameNetworkImages({
+    super.get,
+    super.getAppDirectory,
+    super.cacheInMemory,
+    super.cacheInStorage,
+  }) : super(
+          decodeAsset: (bytes) => CustomAsset.decode(bytes),
+          encodeAsset: (CustomAsset asset) => asset.encode(),
+        );
+}
+```

doc/flame/rendering/images.md

@@ -120,6 +120,32 @@ class MyGame extends Game {
 ```
 
 
+## Loading images over the network
+
+The Flame core package doesn't offer a built in method to loading images from the network.
+
+The reason for that is that Flutter/Dart does not have a built in http client, which requires
+a package to be used and since there are a couple of packages available out there, we refrain
+from forcing the user to use a specific package.
+
+With that said, it is quite simple to load images from the network once a http client package
+is chosen by the user. The following snippet shows how an `Image` can be fetched from the web
+using the [http](https://pub.dev/packages/http) package.
+
+```dart
+import 'package:http/http.dart' as http;
+import 'package:flutter/painting.dart';
+
+final response = await http.get('https://url.com/image.png');
+final image = await decodeImageFromList(response.bytes);
+```
+
+```{note}
+Check [`flame_network_assets`](https://pub.dev/packages/flame_network_assets)
+for a ready to use network assets solution that provides a built in cache.
+```
+
+
 ## Sprite
 
 Flame offers a `Sprite` class that represents an image, or a region of an image.

packages/flame_network_assets/.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+  channel: stable
+
+project_type: package

packages/flame_network_assets/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Blue Fire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/flame_network_assets/README.md

@@ -0,0 +1,25 @@
+# flame_network_assets
+
+<!-- markdownlint-disable MD013 -->
+<p align="center">
+  <a href="https://flame-engine.org">
+    <img alt="flame" width="200px" src="https://user-images.githubusercontent.com/6718144/101553774-3bc7b000-39ad-11eb-8a6a-de2daa31bd64.png">
+  </a>
+</p>
+
+<p align="center">
+Adds network images support to <a href="https://github.com/flame-engine/flame">Flame</a>.
+</p>
+
+<p align="center">
+  <img src="https://github.com/flame-engine/flame_network_image/workflows/Lint/badge.svg?branch=master&event=push" alt="Test" />
+  <a title="Discord" href="https://discord.gg/pxrBmy4" ><img src="https://img.shields.io/discord/509714518008528896.svg" /></a>
+</p>
+<!-- markdownlint-enable MD013 -->
+
+---
+
+This package makes it easy to use and cache assets from the network inside a Flame game.
+
+For instructions on how to use this package to load images,
+check [Flame docs](https://docs.flame-engine.org/1.6.0/bridge_packages/flame_network_assets/flame_network_assets.html).

packages/flame_network_assets/analysis_options.yaml

@@ -0,0 +1,5 @@
+include: package:flame_lint/analysis_options.yaml
+
+linter:
+  rules:
+    - public_member_api_docs

packages/flame_network_assets/example/.metadata

@@ -0,0 +1,45 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled.
+
+version:
+  revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+  channel: stable
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+    - platform: android
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+    - platform: ios
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+    - platform: linux
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+    - platform: macos
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+    - platform: web
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+    - platform: windows
+      create_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+      base_revision: b06b8b2710955028a6b562f5aa6fe62941d6febf
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

packages/flame_network_assets/example/README.md

@@ -0,0 +1,3 @@
+# flame_network_images example
+
+An example app that shows how to use the `flame_network_images` package.

packages/flame_network_assets/example/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flame_lint/analysis_options.yaml

packages/flame_network_assets/example/lib/main.dart

@@ -0,0 +1,43 @@
+import 'dart:async';
+
+import 'package:flame/components.dart';
+import 'package:flame/extensions.dart';
+import 'package:flame/game.dart';
+import 'package:flame/input.dart';
+import 'package:flame_network_assets/flame_network_assets.dart';
+import 'package:flutter/material.dart' hide Image;
+
+void main() {
+  runApp(const GameWidget.controlled(gameFactory: MyGame.new));
+}
+
+class MyGame extends FlameGame with TapDetector {
+  final networkImages = FlameNetworkImages();
+  late Image playerSprite;
+
+  @override
+  Future<void> onLoad() async {
+    playerSprite = await networkImages.load(
+      'https://examples.flame-engine.org/assets/assets/images/bomb_ptero.png',
+    );
+  }
+
+  @override
+  bool onTapUp(TapUpInfo info) {
+    add(
+      SpriteAnimationComponent.fromFrameData(
+        playerSprite,
+        SpriteAnimationData.sequenced(
+          textureSize: Vector2(48, 32),
+          amount: 4,
+          stepTime: .2,
+        ),
+        size: Vector2(100, 50),
+        anchor: Anchor.center,
+        position: info.eventPosition.game,
+      ),
+    );
+
+    return true;
+  }
+}

packages/flame_network_assets/example/pubspec.yaml

@@ -0,0 +1,17 @@
+name: flame_network_assets_example
+description: A flame network assets example.
+publish_to: 'none'
+
+version: 1.0.0+1
+
+environment:
+  sdk: '>=2.18.0 <3.0.0'
+
+dependencies:
+  flame: ^1.6.0
+  flame_network_assets: ^0.1.0
+  flutter:
+    sdk: flutter
+
+dev_dependencies:
+  flame_lint: ^0.1.3

packages/flame_network_assets/lib/flame_network_assets.dart

@@ -0,0 +1,5 @@
+library flame_network_assets;
+
+export 'src/flame_asset_response.dart';
+export 'src/flame_network_assets.dart';
+export 'src/flame_network_images.dart';

packages/flame_network_assets/lib/src/flame_asset_response.dart

@@ -0,0 +1,19 @@
+import 'dart:typed_data';
+
+/// {@template flame_assets_response}
+/// A class containing the relevant http attributes to
+/// Flame Assets Network package.
+/// {@endtemplate}
+class FlameAssetResponse {
+  /// {@macro flame_assets_response}
+  const FlameAssetResponse({
+    required this.statusCode,
+    required this.bytes,
+  });
+
+  /// Http status code.
+  final int statusCode;
+
+  /// response bytes.
+  final Uint8List bytes;
+}