How mapeditor/tiled works
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: map.h Data model · tmxmapformat.cpp Formats · mainwindow.cpp App shell · distribute.qbs Packaging
Components 24
Core library
Reusable domain model, formats, rendering, and plugin infrastructure.
- Data model · Maps, layers, tilesets, objects, worlds, properties, Wang sets, and templates.
src/libtiled/map.h - Formats · Reader/writer APIs, built-in TMX/TSX support, and variant conversion.
src/libtiled/tmxmapformat.cpp - Rendering · Map renderers, minimap rendering, and projection-specific drawing logic.
src/libtiled/maprenderer.h - Plugin 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 · Main window, application bootstrap, and top-level editor chrome.
src/tiled/mainwindow.cpp - Documents · Map, tileset, project, and world document lifecycles.
src/tiled/documentmanager.cpp - Commands · Command objects and undo manager form the editing mutation boundary.
src/tiled/commandmanager.cpp - Tools · Map, tile, object, world, and selection tools that mutate the model.
src/tiled/toolmanager.cpp - Views · Map scene, map view, minimap, and layer/object visualization widgets.
src/tiled/mapview.cpp - Panels · Property, tileset, world, object, layer, and other editor side panels.
src/tiled/propertiesdock.cpp - Scripting · Script manager, scripted actions/tools, and scripted file-format wrappers.
src/tiled/scriptmanager.cpp
Plugins
Import/export and scripting extensions.
- Format 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 · Python-backed scripting and extension bridge.
src/plugins/python/pythonplugin.cpp
Qt Quick
Alternative presentation/runtime layer.
- Quick core · Qt Quick-facing map item, loader, and node primitives.
src/libtiledquick/mapitem.cpp - Quick app · Standalone QML application surface and resources.
src/tiledquick/main.cpp - Quick plugin · QML plugin entry point for embedding the Quick layer.
src/tiledquickplugin/tiledquickplugin.cpp
Utilities
Standalone CLI tools built on the shared core.
- Rasterizer · Command-line map-to-image renderer.
src/tmxrasterizer/main.cpp - Viewer · Command-line map viewer built on the shared core.
src/tmxviewer/main.cpp - Terrain gen · Standalone terrain-related asset generator.
src/terraingenerator/main.cpp
Support libs
Embedded infrastructure dependencies.
- Single app · Single-instance desktop application support.
src/qtsingleapplication/src/qtsingleapplication.cpp - Archive lib · Embedded archive/compression library used for packaged assets and compression handling.
src/karchive/src/karchive.cpp
Quality & docs
Tests, documentation, and release assets.
Connections 29
- 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.