fledge_tiled library

Tiled tilemap support for the Fledge ECS game framework.

This library provides full integration with Tiled, a popular 2D tilemap editor. It supports:

TMX/TSX Parsing: Load Tiled maps and external tilesets
Tile Layers: Efficient rendering with atlas batching
Object Layers: Spawn entities from Tiled objects
Animated Tiles: Automatic tile animation support
Collision Shapes: Generate collision from objects and tiles
Custom Properties: Type-safe access to Tiled properties
Infinite Maps: Chunk-based loading for large maps

Quick Start

import 'package:fledge_ecs/fledge_ecs.dart';
import 'package:fledge_tiled/fledge_tiled.dart';

void main() async {
  final app = App()
    .addPlugin(WallTimePlugin())
    .addPlugin(TiledPlugin());

  // Load a tilemap
  final loader = AssetTilemapLoader(
    loadStringContent: (path) => rootBundle.loadString(path),
  );
  final tilemap = await loader.load(
    'assets/maps/level1.tmx',
    (path, w, h) async => await loadTexture(path),
  );

  // Store and spawn
  app.world.getResource<TilemapAssets>()!.put('level1', tilemap);
  app.world.eventWriter<SpawnTilemapEvent>().send(
    SpawnTilemapEvent(assetKey: 'level1'),
  );

  await app.run();
}

Object Spawning

Objects from Tiled can be spawned as entities with custom components:

SpawnTilemapEvent(
  assetKey: 'level1',
  config: TilemapSpawnConfig(
    tileConfig: TileLayerConfig(
      generateColliders: true,
      colliderLayers: {'Collision'},
    ),
    objectTypes: {
      'enemy': ObjectTypeConfig(
        onSpawn: (entity, obj) {
          entity.insert(Enemy(
            health: obj.properties.getIntOr('health', 100),
          ));
        },
      ),
      'collectible': ObjectTypeConfig(
        createCollider: false,
        onSpawn: (entity, obj) {
          entity.insert(Collectible(
            value: obj.properties.getIntOr('value', 10),
          ));
        },
      ),
    },
  ),
)

Classes

AssetTilemapLoader: Loader for tilemaps bundled as Flutter assets or loaded from strings.
ChunkKey: Key for identifying chunks in infinite maps.
Collider: Component containing collision shapes.
CollisionConfig: Configuration for collision behavior.
CollisionDetectionSystem: Detects collisions between entities and writes CollisionEvents to the ECS event queue.
CollisionEvent: Event published when two entities collide.
CollisionGrid: A 2D grid representing walkability for pathfinding.
CollisionLayers: Base collision layer definitions.
CollisionResolutionSystem: Adjusts velocity to prevent movement into solid colliders.
CollisionShape: Base class for collision shapes from Tiled.
ContactYieldEnded: Emitted the step a yielding pair separates and blocking resumes.
ContactYieldStarted: Emitted the step a pair of dynamic bodies starts yielding to each other after sustained contact (see CollisionConfig.yieldAfter).
ContactYieldTracker: Per-pair contact-age bookkeeping for CollisionConfig.yieldAfter.
CulledTilemapExtractor: Camera-aware tilemap extractor that culls tiles at extraction time.
EllipseShape: An ellipse collision shape.
ExtractedTile: Extracted tile data for the render world.
LoadedTilemap: A fully loaded tilemap with all required resources.
LoadedTileset: A loaded tileset with texture and metadata.
ObjectLayer: Component for object layers from Tiled.
ObjectTypeConfig: Configuration for spawning a specific object type.
Pathfinder: A* pathfinding for tile-based maps.
PathResult: Result of a pathfinding operation.
PhysicsConfig: Configuration for the physics plugin.
PhysicsPlugin: Physics and collision handling plugin.
PointShape: A point collision shape.
PolygonShape: A polygon collision shape.
PolylineShape: A polyline collision shape (open path).
RectangleShape: A rectangle collision shape.
SpatialHash: Uniform-grid spatial hash used by CollisionDetectionSystem to cut broad-phase pair generation from O(n^2) down to O(n) for well-spread scenes.
SpawnTilemapEvent: Event to spawn a tilemap in the world.
TileAnimation: Animation data for a single animated tile.
TileAnimationFrame: A single frame in a tile animation.
TileAnimationSystem: System that updates tile animations.
TileChunk: Chunk data for infinite maps.
TileCollider: Utility for generating collision shapes from Tiled data.
TileCollisionData: Data for a tile with collision.
TiledAnimationFrame: Intermediate representation of Tiled animation frame data.
TileData: Pre-computed tile data for a single tile.
TiledContentProvider: Provider for loading TMX/TSX content from different sources.
TiledObject: Component attached to entities spawned from Tiled objects.
TiledObjectData: Normalized object data from Tiled.
TiledPlugin: Plugin that adds Tiled tilemap support to Fledge.
TiledPluginConfig: Configuration for the Tiled plugin.
TiledProperties: Type-safe wrapper for Tiled custom properties.
TileFlipFlags: Bit flag layout used by fledge_tiled for flipped/rotated tiles.
TileLayer: Component for a single tile layer.
TileLayerConfig: Configuration for tile layer spawning.
Tilemap: Root component representing a complete Tiled map.
TilemapAnimator: Component tracking animated tiles for a tilemap.
TilemapAssets: Resource managing loaded tilemap assets.
TilemapExtractor: Extractor for tilemap layers.
TilemapLoader: Abstract interface for loading tilemaps from various sources.
TilemapSpawnConfig: Configuration for tilemap spawning.
TilemapSpawnedEvent: Event fired when a tilemap is spawned.
TilemapSpawnSystem: System that spawns entities from loaded tilemaps.
TilesetLookup: Result of looking up a tileset for a GID.
TilesetRegistry: Resource for managing shared tilesets across multiple maps.
TmxLoader: A Loader that reads a .tmx tilemap from a path.
TsxLoader: A Loader that reads a .tsx external tileset from a path.
Velocity: Component representing an entity's velocity.
VelocityIntegrationSystem: Advances Transform2D by Velocity scaled to real time.

Enums

DrawOrder: Draw order for objects in an object layer.
ObjectShape: Shape types for Tiled objects.
PhysicsMode: Controls which clock fledge_physics's per-step systems read from.
RenderOrder: Render order for tiles in the map.

Extensions

ContactYieldTrackerInternal on ContactYieldTracker: Package-internal handles the resolver uses to mutate the tracker. Kept in the same library as ContactYieldTracker so private fields stay reachable without exposing them on the public API.

Constants

physicsReferenceFrameSeconds → const double: One 60 Hz frame in seconds — the reference used to convert per-frame-at-60fps velocity into per-second movement.

Functions

contactYieldPairKey(Entity a, Entity b) → int: Canonicalised unordered pair key for the yield tracker.
extractCollisionGrid(LoadedTilemap tilemap, {Set<String> collisionLayers = const {'Collision', 'collision'}}) → CollisionGrid: Extracts a CollisionGrid from a LoadedTilemap.
extractCollisionGridFromTmx(String tmxContent, {required int mapWidth, required int mapHeight, Set<String> collisionLayers = const {'Collision', 'collision'}}) → CollisionGrid: Extracts a CollisionGrid directly from TMX content.
extractCollisionGrids(Map<String, LoadedTilemap> tilemaps, {Set<String> collisionLayers = const {'Collision', 'collision'}}) → Map<String, CollisionGrid>: Extracts collision grids from multiple tilemaps.
tileToSprite({required TextureHandle texture, required Rect sourceRect, required Offset tileTopLeft, required double tileWidth, required double tileHeight, required Color color, required int sortKey, required int flipFlags}) → ExtractedSprite: Convert a single tile's data into an ExtractedSprite suitable for the shared render-widget pipeline (FledgeRenderView / LitFledgeRenderView).

Typedefs

TextureLoader = Future<TextureHandle> Function(String path, int width, int height): Callback for loading textures.
TilemapAsset = LoadedTilemap: The value type stored in Assets<TilemapAsset> — a parsed .tmx tilemap plus every tileset it references.
TilesetAsset = LoadedTileset: The value type stored in Assets<TilesetAsset> — a parsed .tsx tileset plus its texture atlas.

fledge_tiled library

Quick Start

Object Spawning

Classes

Enums

Extensions

Constants

Functions

Typedefs

fledge_tiled package

fledge_tiled library