Crate bevy_map 

bevy_map

Complete 2D tilemap editor and runtime for Bevy games.

This crate provides everything you need to load and render tile-based maps created with bevy_map_editor.

Quick Start

use bevy::prelude::*;
use bevy_map::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MapRuntimePlugin)
        .add_systems(Startup, load_map)
        .run();
}

fn load_map(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Load map with hot-reload support
    commands.spawn(MapHandle(asset_server.load("maps/level1.map.json")));
}

Features

• runtime (default) - Includes map loading and bevy_ecs_tilemap rendering
• physics - Adds avian2d collision support
• hot-reload (default) - File watching for development

Crate Structure

This umbrella crate re-exports all bevy_map_* sub-crates:

• core - Core data types (Level, Layer, Tileset, etc.)
• animation - Sprite animation system
• dialogue - Branching dialogue trees
• autotile - Terrain auto-tiling (Wang tiles)
• runtime - Map loading and rendering (requires runtime feature)

Modules

animation

Sprite animation system with frame-based animations.

autotile

Tiled-compatible terrain auto-tiling system.

core

Core data types for representing tile-based maps.

dialogue

Branching dialogue tree system.

neighbors

Legacy neighbor direction flags for bitmask calculation

prelude

Commonly used types and traits.

runtime

Runtime map loading and rendering via bevy_ecs_tilemap.

schema

Schema validation for entity types.

Structs

AnimatedSprite

Component for playing sprite animations

AnimationCustomEvent

Convenience event for custom payloads

AnimationDef

A single animation definition

AnimationParticleEvent

Convenience event for particle/VFX payloads

AnimationSoundEvent

Convenience event for sound payloads

AnimationTrigger

A one-shot animation trigger - fires once at a specific time

AnimationTriggerEvent

Event fired when an AnimationTrigger fires (one-shot)

AnimationTriggerRegistry

Registry for custom animation trigger types.

AnimationTriggered

Entity-scoped event fired when an animation trigger fires.

AnimationWindow

A duration-based animation window - has begin, tick, and end phases

AnimationWindowChanged

Entity-scoped event fired when an animation window changes phase.

AnimationWindowEvent

Event fired for AnimationWindow phase changes (duration-based)

AnimationWindowRegistry

Registry for custom animation window types.

AutotileConfig

Configuration for autotiling in a project

CellInfo

Information about constraints for a single cell

CollisionData

Collision data for a tile or entity

Color

Simple RGBA color for terrain visualization (no Bevy dependency)

Dialogue

Component marking an entity that has an associated dialogue

DialogueChoice

A player choice option in a dialogue

DialogueChoiceEvent

Message sent when the player makes a choice

DialogueEndEvent

Message sent when a dialogue ends

DialogueHandle

Component that holds a handle to a dialogue tree asset

DialogueNode

A single node in the dialogue tree

DialoguePlugin

Plugin for dialogue support

DialogueRunner

Current state of an active dialogue

DialogueTree

A complete dialogue tree with nodes and connections

EditorProject

Editor project format - matches what the editor exports

EntityInstance

An entity placed in the world

EntityProperties

Raw properties from the map editor, accessible by runtime systems

EntityRegistry

Registry storing entity spawners by type name

Layer

A layer (tiles or objects)

LegacyTerrainType

Legacy terrain type for backward compatibility with old 47-tile blob format

Level

A level/map containing tiles and entities

MapCollider

Marker component for map collision entities

MapCollisionPlugin

MapEntityMarker

Marker component for entities spawned from map data

MapHandle

Component for loading maps via the Bevy asset system

MapProject

A self-contained map project that includes level data and tileset metadata

MapProjectBuilder

Builder for creating a MapProject from separate level and tileset sources

MapProjectLoader

Asset loader for MapProject JSON files

MapRoot

Marker component for the root entity of a spawned map

MapRuntimePlugin

Plugin for runtime map rendering

MapSpawnedEvent

Event emitted when a map has been spawned

SpawnMapEvent

Event to spawn a map from a Level

SpawnMapProjectEvent

Event to spawn a map from a MapProject with embedded tileset metadata

SpriteAnimationPlugin

Plugin for sprite animation support

SpriteData

Sprite data with spritesheet reference and animations

SpriteSlot

Marker component for sprite slots on entities

StartDialogueEvent

Message to start a dialogue (sent via MessageWriter, read via MessageReader)

Terrain

A terrain type within a set (e.g., “Grass”, “Dirt”, “Water”)

TerrainBrush

Terrain brush state for painting with automatic tile selection

TerrainSet

A terrain set attached to a tileset

TileConstraints

Constraints for finding a matching tile (Tiled-style with masks)

TileProperties

Per-tile properties like collision, animation, and custom metadata

TileTerrainData

Terrain assignments for a single tile’s corners/edges/center

Tileset

Tileset configuration - can contain multiple images (Godot-style)

TilesetImage

A single image source within a tileset

TilesetTextures

Manages loaded tileset and sprite sheet textures for a map

WangFiller

Fills a region with Wang tiles based on constraints

WangId

Wang ID using array storage (Tiled-compatible) Color 0 = empty/no terrain Layout: [Top, TopRight, Right, BottomRight, Bottom, BottomLeft, Left, TopLeft]

WindowTracker

Tracks active animation windows for an entity

Enums

CollisionShape

Collision shape types supported by the editor

DialogueNodeType

Type of dialogue node

LayerData

The data contained in a layer

LayerType

The type of a layer

LoopMode

Animation loop mode

MapLoadError

Error type for map loading failures

OneWayDirection

Direction for one-way platforms

PaintTarget

Represents what the terrain brush is painting

PhysicsBody

Physics body type

TerrainSetType

Type of terrain set - determines how tiles are matched

TriggerPayload

Payload data for animation triggers and windows

Value

Generic property value (JSON-like but typed)

WangPosition

Position indices for WangId (clockwise from top) 7|0|1 6|X|2 5|4|3

WindowPhase

Phase of an animation window

Constants

OCCUPIED_CELL

Sentinel value for cells occupied by multi-cell tiles (but not the base cell)

Traits

AnimationEventExt

Extension trait for registering animation trigger and window types.

AnimationTriggerType

Trait for types that can be animation triggers.

AnimationWindowType

Trait for types that can be animation windows.

MapEntityExt

Extension trait for registering map entities with the Bevy App

MapEntityType

Trait implemented by entities that can be spawned from map data.

Functions

apply_autotile_to_region

Apply autotiling to a region of tiles (legacy)

attach_dialogues

System that automatically attaches Dialogue components to entities with dialogue properties

calculate_bitmask

Calculate the neighbor bitmask for a tile (legacy)

complete_sprite_loads

System that completes sprite setup once assets are loaded

erase_autotile

Erase a tile and update autotiling for neighbors (legacy)

optimize_bitmask

Apply corner optimization to a bitmask (legacy)

paint_autotile

Paint a single tile with autotiling and update neighbors (legacy)

paint_terrain

paint_terrain_at_target

Unified terrain painting function that handles corners and edges

spawn_map_project

Spawn a map from a MapProject with proper tileset handling

spawn_sprite_components

System that detects entities with sprite properties and adds Sprite + AnimatedSprite components

update_tile_with_neighbors

Update a single tile based on its neighbors

Type Aliases

TerrainId

Terrain color ID (0 = empty/no terrain, 1+ = terrain index + 1)

TerrainType

Type alias for backward compatibility

Derive Macros

MapEntity

Derive macro for creating map entities that can be spawned from EntityInstance data