API documentation overview
TODO: introduction to API documentation here.
Assets
Handles management of the asset library (and containing asset packs), indexing, thumbnail generation and provides an interface for searching and resolving assets from this library.
The primary feature is to abstract the exact location on the device away so that the same assets can be located on different devices, even if they are in different locations on each device. Each asset is assigned a stable identifier that is the same on each device, independent for the specific location in the file system, and maps refer to these assets by their assigned IDs. When resolving an asset, this crate is responsible for finding the actual location in the filesystem and providing it to Bevy's asset system.
Features
| Feature | Description | default |
|---|---|---|
| jpeg | Enables the crate to process and generate JPEG files | ❌ |
| png | Enables the crate to process and generate PNG files | ✅ |
| webp | Enables the crate to process and generate WEBP files | ❌ |
CLI
The DungeonRS CLI is a command line interface to interact
with assets and maps.
Features
| Feature | Description | default |
|---|---|---|
| jpeg | Enables the CLI to process and generate JPEG files | ❌ |
| png | Enables the CLI to process and generate PNG files | ✅ |
| webp | Enables the CLI to process and generate WEBP files | ❌ |
Config
Configuration management for the application. This crate handles loading and validation of configuration files during early startup, before Bevy initialisation, allowing configuration of the entire bootstrap process.
The two main configuration types are:
Configuration- Application settings including language preferences, recent files, and asset directory pathsLogConfiguration- Logging system configuration with output levels and destinations
Configuration files are loaded from platform-appropriate directories and validated at startup.
Data
Core data structures shared throughout the application.
This crate is kept lightweight and dependency-free so other crates can use these types without pulling in heavy dependencies.
Compiling this crate with dev feature enabled will derive Reflect for all types.
Contains the fundamental types:
Project- Top-level marker component that defines the boundary of saveable map contentElement- Individual map elements and componentsLayer- Map layer organisation and structureLevel- Multi-floor/level support and metadata
The Project component serves as a crucial boundary marker in the ECS hierarchy.
Only entities beneath a Project component are considered during save/load and export operations, which prevents editor tools, gizmos, and temporary objects from being inadvertently included in persisted data.
To make working with these data structures easier, the data crate provides a Query implementation for each type.
The fundamental types and their corresponding Query implementations are:
Project-ProjectQueryLevel-LevelQueryLayer-LayerQueryElement-ElementQuery
There is also the [DungeonQueries] system parameter for fetching all the above types in a single query.
Editor
The DungeonRS editor is where most users will actually be working in.
It's the binary crate that actually handles bootstrapping the application,
setting up a graphical interface and run the application.
Features
| Feature | Description | default |
|---|---|---|
| jpeg | Enables the editor to process and generate JPEG files | ❌ |
| png | Enables the editor to process and generate PNG files | ✅ |
| webp | Enables the editor to process and generate WEBP files | ❌ |
| no_console | Disables showing the console window (only works on Windows) | ❌ |
i18n
A wrapper around fluent-template to make static access a bit more convenient.
It does this by providing a static LOCALES which wraps ArcLoader and tracks
the currently selected language. It also provides a t! macro which makes
using it even more intuitive.
IO
Core functionality of the editor that isn't tied specifically to the UI.
This crate centralises shared functionality between the ui and cli crates, preventing code duplication and providing
a consistent event-driven architecture.
The core crate implements an event-driven system where:
- Events are exposed for triggering core functionality
- Event listeners handle the actual implementation
- Other crates can dispatch events to trigger functionality without duplicating logic
The core crate serves as the foundation for:
- Map manipulation and processing algorithms
- Asset management operations
- Core editing operations and transformations
- Event-driven business logic shared between UI and CLI implementations
By centralising this logic with an event-based approach, functionality can be easily shared between different frontends (UI, CLI, automation tools).
Logging
Handles configuring Bevy's logging system and handles outputting logging to a rolling file.
Features
| Feature | Description | default |
|---|---|---|
| console | Enables a few console-only enhancements (such as auto progress-tracking of spans) | ❌ |
Serialisation
This crate handles serialisation from and to binary representations. It's essentially a wrapper around Serde using various formats depending on the enabled features.
These are the currently supported features:
| Format | Doc | Feature |
|---|---|---|
| MessagePack | Binary format with small output size | msgpack |
| JSON | Human-readable text format | json |
| TOML | Human-readable configuration format | toml |
UI
Handles building the user interface that users can interact with.
Currently, this implementation uses the excellent egui crate,
but this might change in the future to bevy_ui once it matures enough.
Utils
Common utilities shared across the codebase.
This includes platform-specific directory resolution, async ECS helpers, path manipulation utilities, hashing functions, build version information, and re-exported macros from utils_macros.
The directory handling follows each platform's recommended conventions:
- Windows: Known Folder API
- Linux: XDG Base Directory specifications
- macOS: Standard Directories
This implementation is based on the approach used by the directories crate, though we maintain our own version due to licensing considerations.
Utils macros
Contains several utility macros exported through utils.
Notably, the bevy_system macro is used by all Bevy systems.