# mapeditor/tiled architecture

> Architecture diagram of the GitHub repository mapeditor/tiled, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mapeditor/tiled
- Repository: https://github.com/mapeditor/tiled

## Overview

1. **What this repository is**
   Tiled is a cross-platform desktop map editor for tile-based games. The architecture is centered on a reusable C++ core library, a Qt-based editor UI, and a plugin system for map/tileset import-export formats and scripted extensions.

2. **Core domain model: `src/libtiled`**
   This is the main engine of the repo. It defines the data model for maps, layers, tilesets, objects, worlds, properties, Wang sets, templates, and related helpers. It also contains the file format abstraction, reader/writer APIs, renderer abstractions, image caching, compression, and filesystem watching. Most non-UI functionality flows through this library.

3. **File I/O and format boundary**
   Map and tileset persistence is intentionally separated from the editor UI. `libtiled` exposes format interfaces and built-in formats such as TMX/TSX and converters to/from generic variant data. The plugin directories under `src/plugins/*` add support for other game/editor formats like JSON, Lua, Defold, GameMaker GMX/YY, TBIN, TSCN, RPMap, RPD, and others.

4. **Editor application: `src/tiled`**
   This is the main desktop application layer. It builds on `libtiled` and implements document management, project management, undo/redo commands, tools, dock widgets, dialogs, and interactive editing workflows. Most of the large number of files here are UI controllers and editor actions rather than domain model code.

5. **Primary runtime flow in the editor**
   The user opens a project or map; a document object is created; the underlying `libtiled` map/tileset/world model is loaded via a reader or plugin; editor tools mutate the model through command objects; changes are reflected in views and dock panels; save/export routes the model back through the selected writer/plugin. Undo/redo is a first-class boundary via command classes.

6. **Rendering and view subsystem**
   The editor has dedicated rendering and visualization code for orthogonal, isometric, staggered, hexagonal, and oblique maps, plus minimap rendering and tile/object layer items. This is separated from the model so the same map data can be drawn in the editor, in previews, and in utilities such as the rasterizer/viewer.

7. **Editing features as subsystems**
   The large editor codebase is organized around feature areas rather than a monolith: map editing tools, object creation/selection tools, tile painting/fill/selection tools, automapping, terrain/Wang editing, templates, project/world management, property editors, and scripting integration. These are mostly UI-facing orchestration layers over the shared model.

8. **Scripting and extensibility**
   Tiled supports scripting through a dedicated scripting subsystem in the editor and a Python plugin implementation under `src/plugins/python`. There is also scripted file format and scripted tool support in the editor, allowing external scripts to participate in editing workflows and format handling without modifying core code.

9. **Secondary UI/runtime surfaces**
   `src/libtiledquick`, `src/tiledquick`, and `src/tiledquickplugin` provide a Qt Quick/QML-facing layer for alternative UI surfaces or embedding. This is a separate presentation stack from the main QWidget-based editor, with its own map item, loader, and QML resources.

10. **Command-line and utility executables**
   The repository also builds standalone tools: `tmxrasterizer` for rendering maps to images, `tmxviewer` for viewing maps, and `terraingenerator` for generating terrain-related assets. These consume the same core `libtiled` model and render/export logic rather than reimplementing parsing or map semantics.

11. **Shared support libraries**
   `src/karchive` vendors a KDE archive library used for compression/archive handling, and `src/qtsingleapplication` provides single-instance application behavior. These are infrastructure dependencies embedded in the repo so the application can manage archives and enforce single-instance desktop semantics consistently across platforms.

12. **Packaging and distribution**
   The `dist`, `snap`, `org.mapeditor.Tiled.desktop`, `mime`, and appdata files show that the project is packaged for Linux AppImage/Flatpak/Snap, macOS, and Windows installers. The Qbs build files drive the multi-target build graph and packaging steps, with platform-specific launcher and installer assets.

13. **Quality, documentation, and verification**
   `tests` contains format, rendering, properties, automapping, and Wang-tile regression tests using real TMX/TSX fixtures. `docs` holds the user manual and reference docs, including schema files for the map format. `translations` contains the localized UI strings, which are part of the release pipeline but not the runtime data model.

14. **External integration boundary**
   The repo’s main external dependency is Qt (widgets, GUI, XML, SVG, QML, and related modules), plus platform toolchains and optional Python development libraries for scripting plugins. The architecture is therefore a layered Qt application: model/format core, editor/UI layer, plugin extensions, and auxiliary tools all built from the same shared domain library.

Main entry points: [`src/libtiled/map.h`](https://github.com/mapeditor/tiled/blob/master/src/libtiled/map.h) (Data model), [`src/libtiled/tmxmapformat.cpp`](https://github.com/mapeditor/tiled/blob/master/src/libtiled/tmxmapformat.cpp) (Formats), [`src/tiled/mainwindow.cpp`](https://github.com/mapeditor/tiled/blob/master/src/tiled/mainwindow.cpp) (App shell), [`dist/distribute.qbs`](https://github.com/mapeditor/tiled/blob/master/dist/distribute.qbs) (Packaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_lib_model["Data model<br/>core model<br/>[map.h]"]
  node_lib_format["Formats<br/>I/O boundary<br/>[tmxmapformat.cpp]"]
  node_lib_render["Rendering<br/>render backend<br/>[maprenderer.h]"]
  node_lib_plugin["Plugin host<br/>extension host<br/>[pluginmanager.cpp]"]
end

subgraph group_editor["Editor app"]
  node_editor_shell["App shell<br/>desktop UI<br/>[mainwindow.cpp]"]
  node_editor_docs["Documents<br/>edit session"]
  node_editor_commands["Commands<br/>undo/redo<br/>[commandmanager.cpp]"]
  node_editor_tools["Tools<br/>[toolmanager.cpp]"]
  node_editor_views["Views<br/>scene/view<br/>[mapview.cpp]"]
  node_editor_props["Panels<br/>dock/widgets<br/>[propertiesdock.cpp]"]
  node_editor_scripts["Scripting<br/>script runtime<br/>[scriptmanager.cpp]"]
end

subgraph group_plugins["Plugins"]
  node_plugin_formats["Format plugins<br/>import/export plugins<br/>[plugins.qbs]"]
  node_plugin_python["Python plugin<br/>scripting plugin<br/>[pythonplugin.cpp]"]
end

subgraph group_qtquick["Qt Quick"]
  node_quick_core["Quick core<br/>qml model layer<br/>[mapitem.cpp]"]
  node_quick_app["Quick app<br/>qml frontend<br/>[main.cpp]"]
  node_quick_plugin["Quick plugin<br/>qml plugin"]
end

subgraph group_tools["Utilities"]
  node_tool_raster["Rasterizer<br/>cli tool<br/>[main.cpp]"]
  node_tool_viewer["Viewer<br/>cli tool<br/>[main.cpp]"]
  node_tool_terrain["Terrain gen<br/>cli tool<br/>[main.cpp]"]
end

subgraph group_support["Support libs"]
  node_support_single["Single app<br/>infra lib"]
  node_support_archive["Archive lib<br/>vendored lib<br/>[karchive.cpp]"]
end

subgraph group_quality["Quality & docs"]
  node_quality_tests["Tests<br/>regression suite<br/>[tests.qbs]"]
  node_quality_docs["Docs<br/>manual/reference<br/>[index.rst]"]
  node_quality_dist["Packaging<br/>distribution<br/>[distribute.qbs]"]
end

node_editor_shell -->|"opens docs"| node_editor_docs
node_editor_shell -->|"hosts tools"| node_editor_tools
node_editor_shell -->|"renders UI"| node_editor_views
node_editor_docs -->|"uses model"| node_lib_model
node_editor_docs -->|"loads/saves"| node_lib_format
node_editor_commands -->|"mutates"| node_lib_model
node_editor_tools -->|"issues commands"| node_editor_commands
node_editor_tools -->|"edits data"| node_lib_model
node_editor_views -->|"draws via"| node_lib_render
node_editor_views -->|"shows model"| node_lib_model
node_editor_props -->|"inspects"| node_lib_model
node_editor_scripts -->|"bridges"| node_plugin_python
node_editor_scripts -->|"extends"| node_lib_plugin
node_lib_format -->|"registers"| node_lib_plugin
node_plugin_formats -->|"implements"| node_lib_format
node_plugin_python -->|"runs in"| node_editor_scripts
node_quick_app -->|"uses"| node_quick_core
node_quick_plugin -->|"exposes"| node_quick_core
node_tool_raster -->|"renders with"| node_lib_render
node_tool_viewer -->|"views with"| node_lib_render
node_tool_viewer -->|"loads model"| node_lib_model
node_tool_terrain -->|"generates data"| node_lib_model
node_support_single -->|"supports"| node_editor_shell
node_support_archive -->|"supports I/O"| node_lib_format
node_quality_tests -->|"verifies"| node_lib_format
node_quality_docs -->|"documents"| node_lib_format
node_quality_dist -->|"packages"| node_editor_shell
node_quality_dist -->|"packages"| node_tool_raster
node_quality_dist -->|"packages"| node_tool_viewer

click node_lib_model "https://github.com/mapeditor/tiled/blob/master/src/libtiled/map.h"
click node_lib_format "https://github.com/mapeditor/tiled/blob/master/src/libtiled/tmxmapformat.cpp"
click node_lib_render "https://github.com/mapeditor/tiled/blob/master/src/libtiled/maprenderer.h"
click node_lib_plugin "https://github.com/mapeditor/tiled/blob/master/src/libtiled/pluginmanager.cpp"
click node_editor_shell "https://github.com/mapeditor/tiled/blob/master/src/tiled/mainwindow.cpp"
click node_editor_docs "https://github.com/mapeditor/tiled/blob/master/src/tiled/documentmanager.cpp"
click node_editor_commands "https://github.com/mapeditor/tiled/blob/master/src/tiled/commandmanager.cpp"
click node_editor_tools "https://github.com/mapeditor/tiled/blob/master/src/tiled/toolmanager.cpp"
click node_editor_views "https://github.com/mapeditor/tiled/blob/master/src/tiled/mapview.cpp"
click node_editor_props "https://github.com/mapeditor/tiled/blob/master/src/tiled/propertiesdock.cpp"
click node_editor_scripts "https://github.com/mapeditor/tiled/blob/master/src/tiled/scriptmanager.cpp"
click node_plugin_formats "https://github.com/mapeditor/tiled/blob/master/src/plugins/plugins.qbs"
click node_plugin_python "https://github.com/mapeditor/tiled/blob/master/src/plugins/python/pythonplugin.cpp"
click node_quick_core "https://github.com/mapeditor/tiled/blob/master/src/libtiledquick/mapitem.cpp"
click node_quick_app "https://github.com/mapeditor/tiled/blob/master/src/tiledquick/main.cpp"
click node_quick_plugin "https://github.com/mapeditor/tiled/blob/master/src/tiledquickplugin/tiledquickplugin.cpp"
click node_tool_raster "https://github.com/mapeditor/tiled/blob/master/src/tmxrasterizer/main.cpp"
click node_tool_viewer "https://github.com/mapeditor/tiled/blob/master/src/tmxviewer/main.cpp"
click node_tool_terrain "https://github.com/mapeditor/tiled/blob/master/src/terraingenerator/main.cpp"
click node_support_single "https://github.com/mapeditor/tiled/blob/master/src/qtsingleapplication/src/qtsingleapplication.cpp"
click node_support_archive "https://github.com/mapeditor/tiled/blob/master/src/karchive/src/karchive.cpp"
click node_quality_tests "https://github.com/mapeditor/tiled/blob/master/tests/tests.qbs"
click node_quality_docs "https://github.com/mapeditor/tiled/blob/master/docs/index.rst"
click node_quality_dist "https://github.com/mapeditor/tiled/blob/master/dist/distribute.qbs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lib_model,node_lib_format,node_lib_render,node_lib_plugin,node_quality_tests,node_quality_docs,node_quality_dist toneBlue
class node_editor_shell,node_editor_docs,node_editor_commands,node_editor_tools,node_editor_views,node_editor_props,node_editor_scripts toneAmber
class node_plugin_formats,node_plugin_python toneMint
class node_quick_core,node_quick_app,node_quick_plugin toneRose
class node_tool_raster,node_tool_viewer,node_tool_terrain toneIndigo
class node_support_single,node_support_archive toneTeal
```

## Components

### Core library

Reusable domain model, formats, rendering, and plugin infrastructure.

- [Data model](https://github.com/mapeditor/tiled/blob/master/src/libtiled/map.h): core model · Maps, layers, tilesets, objects, worlds, properties, Wang sets, and templates. · `src/libtiled/map.h`
- [Formats](https://github.com/mapeditor/tiled/blob/master/src/libtiled/tmxmapformat.cpp): I/O boundary · Reader/writer APIs, built-in TMX/TSX support, and variant conversion. · `src/libtiled/tmxmapformat.cpp`
- [Rendering](https://github.com/mapeditor/tiled/blob/master/src/libtiled/maprenderer.h): render backend · Map renderers, minimap rendering, and projection-specific drawing logic. · `src/libtiled/maprenderer.h`
- [Plugin host](https://github.com/mapeditor/tiled/blob/master/src/libtiled/pluginmanager.cpp): extension host · Plugin interfaces and manager used by format and feature extensions. · `src/libtiled/pluginmanager.cpp`

### Editor app

Main Qt Widgets desktop editor and its workflows.

- [App shell](https://github.com/mapeditor/tiled/blob/master/src/tiled/mainwindow.cpp): desktop UI · Main window, application bootstrap, and top-level editor chrome. · `src/tiled/mainwindow.cpp`
- [Documents](https://github.com/mapeditor/tiled/blob/master/src/tiled/documentmanager.cpp): edit session · Map, tileset, project, and world document lifecycles. · `src/tiled/documentmanager.cpp`
- [Commands](https://github.com/mapeditor/tiled/blob/master/src/tiled/commandmanager.cpp): undo/redo · Command objects and undo manager form the editing mutation boundary. · `src/tiled/commandmanager.cpp`
- [Tools](https://github.com/mapeditor/tiled/blob/master/src/tiled/toolmanager.cpp): editing tools · Map, tile, object, world, and selection tools that mutate the model. · `src/tiled/toolmanager.cpp`
- [Views](https://github.com/mapeditor/tiled/blob/master/src/tiled/mapview.cpp): scene/view · Map scene, map view, minimap, and layer/object visualization widgets. · `src/tiled/mapview.cpp`
- [Panels](https://github.com/mapeditor/tiled/blob/master/src/tiled/propertiesdock.cpp): dock/widgets · Property, tileset, world, object, layer, and other editor side panels. · `src/tiled/propertiesdock.cpp`
- [Scripting](https://github.com/mapeditor/tiled/blob/master/src/tiled/scriptmanager.cpp): script runtime · Script manager, scripted actions/tools, and scripted file-format wrappers. · `src/tiled/scriptmanager.cpp`

### Plugins

Import/export and scripting extensions.

- [Format plugins](https://github.com/mapeditor/tiled/blob/master/src/plugins/plugins.qbs): import/export plugins · Built-in third-party format adapters such as JSON, Lua, Defold, GMX, TSCN, RPD, RPMap, TBIN, and related variants. · `src/plugins/plugins.qbs`
- [Python plugin](https://github.com/mapeditor/tiled/blob/master/src/plugins/python/pythonplugin.cpp): scripting plugin · Python-backed scripting and extension bridge. · `src/plugins/python/pythonplugin.cpp`

### Qt Quick

Alternative presentation/runtime layer.

- [Quick core](https://github.com/mapeditor/tiled/blob/master/src/libtiledquick/mapitem.cpp): qml model layer · Qt Quick-facing map item, loader, and node primitives. · `src/libtiledquick/mapitem.cpp`
- [Quick app](https://github.com/mapeditor/tiled/blob/master/src/tiledquick/main.cpp): qml frontend · Standalone QML application surface and resources. · `src/tiledquick/main.cpp`
- [Quick plugin](https://github.com/mapeditor/tiled/blob/master/src/tiledquickplugin/tiledquickplugin.cpp): qml plugin · QML plugin entry point for embedding the Quick layer. · `src/tiledquickplugin/tiledquickplugin.cpp`

### Utilities

Standalone CLI tools built on the shared core.

- [Rasterizer](https://github.com/mapeditor/tiled/blob/master/src/tmxrasterizer/main.cpp): cli tool · Command-line map-to-image renderer. · `src/tmxrasterizer/main.cpp`
- [Viewer](https://github.com/mapeditor/tiled/blob/master/src/tmxviewer/main.cpp): cli tool · Command-line map viewer built on the shared core. · `src/tmxviewer/main.cpp`
- [Terrain gen](https://github.com/mapeditor/tiled/blob/master/src/terraingenerator/main.cpp): cli tool · Standalone terrain-related asset generator. · `src/terraingenerator/main.cpp`

### Support libs

Embedded infrastructure dependencies.

- [Single app](https://github.com/mapeditor/tiled/blob/master/src/qtsingleapplication/src/qtsingleapplication.cpp): infra lib · Single-instance desktop application support. · `src/qtsingleapplication/src/qtsingleapplication.cpp`
- [Archive lib](https://github.com/mapeditor/tiled/blob/master/src/karchive/src/karchive.cpp): vendored lib · Embedded archive/compression library used for packaged assets and compression handling. · `src/karchive/src/karchive.cpp`

### Quality & docs

Tests, documentation, and release assets.

- [Tests](https://github.com/mapeditor/tiled/blob/master/tests/tests.qbs): regression suite · Format, rendering, properties, automapping, and Wang-tile regression coverage. · `tests/tests.qbs`
- [Docs](https://github.com/mapeditor/tiled/blob/master/docs/index.rst): manual/reference · User manual, reference docs, schema files, and localization pipeline. · `docs/index.rst`
- [Packaging](https://github.com/mapeditor/tiled/blob/master/dist/distribute.qbs): distribution · Installer, desktop, appdata, Snap, and release packaging assets. · `dist/distribute.qbs`

## Connections

- App shell → Documents: opens docs · The shell coordinates loaded documents and project state.
- App shell → Tools: hosts tools · Tool selection and editing interactions are managed by the app shell.
- App shell → Views: renders UI · Main editor chrome drives map and auxiliary views.
- Documents → Data model: uses model · Documents wrap the shared map/tileset/world domain objects.
- Documents → Formats: loads/saves · Document persistence flows through the format boundary.
- Commands → Data model: mutates · Undoable commands apply changes to the shared model.
- Tools → Commands: issues commands · Interactive tools express edits through command objects.
- Tools → Data model: edits data · Tools operate on the underlying map and tileset structures.
- Views → Rendering: draws via · The editor view layer relies on shared renderers and scene items.
- Views → Data model: shows model · Views visualize the same core data model used for editing.
- Panels → Data model: inspects · Dock widgets and property editors bind to model state.
- Scripting → Python plugin: bridges · The scripting subsystem delegates external scripting support to plugins.
- Scripting → Plugin host: extends · Scripted tools and file formats integrate through the plugin host.
- Formats → Plugin host: registers · Built-in formats participate in the plugin/format registry.
- Format plugins → Formats: implements · Format plugins provide additional readers and writers.
- Python plugin → Scripting: runs in · Python support participates in the editor scripting runtime.
- Quick app → Quick core: uses · The QML frontend consumes the Quick-specific map layer.
- Quick plugin → Quick core: exposes · The plugin exports the Quick layer for embedding.
- Rasterizer → Rendering: renders with · The rasterizer uses shared map rendering code.
- Viewer → Rendering: views with · The viewer uses shared rendering abstractions.
- Viewer → Data model: loads model · Viewer tools consume the core map data model.
- Terrain gen → Data model: generates data · Terrain generation is based on the shared domain structures.
- Single app → App shell: supports · Single-instance behavior underpins the desktop application entry point.
- Archive lib → Formats: supports I/O · Archive and compression support the persistence and packaging layer.
- Tests → Formats: verifies · Tests exercise loading, saving, rendering, properties, and automapping behavior.
- Docs → Formats: documents · Manual and reference docs explain the file formats and API boundaries.
- Packaging → App shell: packages · Distribution assets target the desktop editor and related tools.
- Packaging → Rasterizer: packages · Release packaging includes the CLI utilities.
- Packaging → Viewer: packages · Release packaging includes the CLI utilities.
