# opentibiabr/remeres-map-editor architecture

> Architecture diagram of the GitHub repository opentibiabr/remeres-map-editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opentibiabr/remeres-map-editor
- Repository: https://github.com/opentibiabr/remeres-map-editor

## Overview

1. This repository is a cross-platform C++ desktop map editor for OpenTibia/Tibia servers. Its core responsibility is editing game maps, tile contents, houses, spawns, zones, and related metadata, then saving/loading them in OpenTibia-specific formats.

2. The application shell is split into a traditional editor UI layer and a stateful editor core. `application`, `editor`, `map_window`, `map_tab`, `palette_window`, `main_toolbar`, `main_menubar`, and the various property/dialog windows form the user-facing shell, while `preferences` and `settings` hold persistent editor configuration.

3. The central domain model is the map world itself: `map`, `tile`, `item`, `house`, `town`, `zones`, `waypoints`, `selection`, and `copybuffer`. These types represent the editable state that the UI manipulates and that the persistence layer reads/writes.

4. Editing behavior is organized around a large brush/tool subsystem. The `brush` base class and its many variants (`ground`, `doodad`, `wall`, `carpet`, `raw`, `table`, `house`, `house_exit`, `monster`, `npc`, `spawn_*`, `zone`, `waypoint`, `eraser`, `monster/npc` palettes, etc.) encapsulate placement and transformation logic. The palette windows select which brush/tool is active.

5. Rendering is a separate layer centered on `gl_renderer`, `map_display`, `map_drawer`, `graphics`, `light_drawer`, and minimap support. The editor appears to use OpenGL for map visualization, with auxiliary rendering for icons, overlays, and a minimap. UI images and toolbar icons are stored as XPM assets.

6. Game-content metadata is data-driven and loaded from the `data/` tree. XML files under `data/materials`, `data/items`, `data/clients.xml`, and `data/menubar.xml` define tilesets, brush groups, item definitions, client-specific material catalogs, and menu structure. This makes the editor’s content palette and item behavior configurable without recompiling.

7. Persistence is handled by dedicated map-format adapters and file helpers. `iomap_otbm`, `iomap_otmm`, `filehandle`, `templates`, and the `templatemap*` files isolate version-specific map serialization/deserialization. `bitmap_to_map_converter` adds an import path from images into map structure.

8. The Lua subsystem is a major extension boundary. `lua_engine`, `lua_script_manager`, `lua_script`, `lua_dialog`, and the many `lua_api_*` modules expose map, item, brush, geometry, HTTP, JSON, noise, and selection operations to scripts. The `scripts/` directory contains shipped automation and generator scripts such as cave/forest/river/maze/dungeon generators, visualizers, counters, and exporters.

9. There is also a live/networked editing subsystem. `live_server`, `live_client`, `live_peer`, `live_socket`, `net_connection`, `live_action`, and `rme_net` suggest support for synchronized or remote editing sessions. `live_tab` and related UI classes provide the user-facing entry point for this mode.

10. Several supporting subsystems round out the editor: `items`, `materials`, `client_assets`, `sprite_appearances`, `sprites`, `monster`, `npc`, `spawn_*`, and `outfit` handle game-data interpretation; `actions` and `actions_history_window` implement undo/redo; `properties_window` and specialized property dialogs edit object attributes; `minimap_window` and `dat_debug_view` aid inspection and debugging.

11. The repository is strongly build- and distribution-oriented. It uses CMake, CMake presets, and vcpkg for dependency management, with platform-specific CI workflows, Docker support, and Visual Studio project files. The `docs/compiling` folder documents supported build targets on Linux, Windows, and WSL.

12. Architecturally, the key data flow is: load client/material definitions and map files → populate the core map model → render the model in the UI → edit through brushes/tools and actions → persist back through the format adapters, with optional Lua automation and live network synchronization as side channels.

Main entry points: [`source/map.cpp`](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map.cpp) (Map), [`source/brush.cpp`](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/brush.cpp) (Brush Base), [`source/editor.cpp`](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/editor.cpp) (Editor), [`source/map_drawer.cpp`](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_drawer.cpp) (Map Drawer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI Shell"]
  node_application["Application<br/>app shell<br/>[application.cpp]"]
  node_editor["Editor<br/>controller<br/>[editor.cpp]"]
  node_map_window["Map Window<br/>workspace UI<br/>[map_window.cpp]"]
  node_palette_window["Palette<br/>tool UI<br/>[palette_window.cpp]"]
  node_properties_window["Properties<br/>inspector UI"]
  node_preferences["Preferences<br/>settings<br/>[preferences.cpp]"]
end

subgraph group_core["Map Core"]
  node_map[("Map<br/>world model<br/>[map.cpp]")]
  node_tile["Tile<br/>world cell<br/>[tile.cpp]"]
  node_item["Item<br/>object model<br/>[item.cpp]"]
  node_selection["Selection<br/>edit state<br/>[selection.cpp]"]
  node_copybuffer["Copy Buffer<br/>edit state<br/>[copybuffer.cpp]"]
end

subgraph group_tools["Brushes"]
  node_brush{{"Brush Base<br/>tool base<br/>[brush.cpp]"}}
  node_ground_brush["Ground<br/>brush<br/>[ground_brush.cpp]"]
  node_doodad_brush["Doodad<br/>brush<br/>[doodad_brush.cpp]"]
  node_house_brush["House<br/>brush<br/>[house_brush.cpp]"]
  node_zone_brush["Zone<br/>brush<br/>[zone_brush.cpp]"]
end

subgraph group_render["Rendering"]
  node_gl_renderer{{"GL Renderer<br/>[gl_renderer.cpp]"}}
  node_map_display["Map Display<br/>view layer<br/>[map_display.cpp]"]
  node_map_drawer["Map Drawer<br/>draw pipeline<br/>[map_drawer.cpp]"]
  node_light_drawer["Light Drawer<br/>overlay renderer<br/>[light_drawer.cpp]"]
end

subgraph group_io["Persistence"]
  node_iomap_otbm[("OTBM<br/>map format<br/>[iomap_otbm.cpp]")]
  node_iomap_otmm[("OTMM<br/>map format<br/>[iomap_otmm.cpp]")]
  node_templates["Templates<br/>format support<br/>[templates.h]"]
  node_bitmap_to_map_converter["Bitmap Import<br/>importer"]
end

subgraph group_ext["Extensions"]
  node_lua_engine{{"Lua Engine<br/>script runtime<br/>[lua_engine.cpp]"}}
  node_lua_script_manager["Script Manager<br/>script orchestration"]
  node_live_server["Live Server<br/>sync server<br/>[live_server.cpp]"]
  node_live_client["Live Client<br/>sync client<br/>[live_client.cpp]"]
end

subgraph group_data["Data & Assets"]
  node_materials[("Materials<br/>content catalog<br/>[materials.cpp]")]
  node_client_assets["Client Assets<br/>asset metadata<br/>[client_assets.cpp]"]
  node_sprites["Sprites<br/>asset data<br/>[sprites.h]"]
end

node_application -->|"starts"| node_editor
node_editor -->|"hosts"| node_map_window
node_editor -->|"hosts"| node_palette_window
node_editor -->|"hosts"| node_properties_window
node_editor -->|"loads"| node_preferences
node_map_window -->|"edits"| node_map
node_palette_window -->|"selects"| node_brush
node_brush -->|"specializes"| node_ground_brush
node_brush -->|"specializes"| node_doodad_brush
node_brush -->|"specializes"| node_house_brush
node_brush -->|"specializes"| node_zone_brush
node_brush -->|"applies to"| node_map
node_map -->|"contains"| node_tile
node_tile -->|"contains"| node_item
node_map -->|"tracks"| node_selection
node_selection -->|"copies to"| node_copybuffer
node_gl_renderer -->|"feeds"| node_map_display
node_map_display -->|"uses"| node_map_drawer
node_map_drawer -->|"renders"| node_map
node_map_drawer -->|"overlays"| node_light_drawer
node_iomap_otbm -->|"loads/saves"| node_map
node_iomap_otmm -->|"loads/saves"| node_map
node_templates -->|"supports"| node_iomap_otbm
node_templates -->|"supports"| node_iomap_otmm
node_bitmap_to_map_converter -->|"imports into"| node_map
node_lua_engine -->|"scripts"| node_map
node_lua_script_manager -->|"runs"| node_lua_engine
node_live_server -->|"syncs with"| node_live_client
node_live_client -->|"syncs"| node_map
node_materials -->|"configures"| node_brush
node_materials -->|"aligns"| node_client_assets
node_client_assets -->|"uses"| node_sprites
node_properties_window -->|"edits"| node_item

click node_application "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/application.cpp"
click node_editor "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/editor.cpp"
click node_map_window "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_window.cpp"
click node_palette_window "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/palette_window.cpp"
click node_properties_window "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/properties_window.cpp"
click node_preferences "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/preferences.cpp"
click node_map "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map.cpp"
click node_tile "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/tile.cpp"
click node_item "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/item.cpp"
click node_selection "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/selection.cpp"
click node_copybuffer "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/copybuffer.cpp"
click node_brush "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/brush.cpp"
click node_ground_brush "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/ground_brush.cpp"
click node_doodad_brush "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/doodad_brush.cpp"
click node_house_brush "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/house_brush.cpp"
click node_zone_brush "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/zone_brush.cpp"
click node_gl_renderer "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/gl_renderer.cpp"
click node_map_display "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_display.cpp"
click node_map_drawer "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_drawer.cpp"
click node_light_drawer "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/light_drawer.cpp"
click node_iomap_otbm "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/iomap_otbm.cpp"
click node_iomap_otmm "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/iomap_otmm.cpp"
click node_templates "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/templates.h"
click node_bitmap_to_map_converter "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/bitmap_to_map_converter.cpp"
click node_lua_engine "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/lua/lua_engine.cpp"
click node_lua_script_manager "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/lua/lua_script_manager.cpp"
click node_live_server "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/live_server.cpp"
click node_live_client "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/live_client.cpp"
click node_materials "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/materials.cpp"
click node_client_assets "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/client_assets.cpp"
click node_sprites "https://github.com/opentibiabr/remeres-map-editor/blob/main/source/sprites.h"

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_application,node_editor,node_map_window,node_palette_window,node_properties_window,node_preferences,node_materials,node_client_assets,node_sprites toneBlue
class node_map,node_tile,node_item,node_selection,node_copybuffer toneAmber
class node_brush,node_ground_brush,node_doodad_brush,node_house_brush,node_zone_brush toneMint
class node_gl_renderer,node_map_display,node_map_drawer,node_light_drawer toneRose
class node_iomap_otbm,node_iomap_otmm,node_templates,node_bitmap_to_map_converter toneIndigo
class node_lua_engine,node_lua_script_manager,node_live_server,node_live_client toneTeal
```

## Components

### UI Shell

Editor windows, tabs, palettes, and commands.

- [Application](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/application.cpp): app shell · Top-level application bootstrap and lifecycle. · `source/application.cpp`
- [Editor](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/editor.cpp): controller · Coordinates editor state and actions. · `source/editor.cpp`
- [Map Window](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_window.cpp): workspace UI · Primary map workspace and tabbed editing surface. · `source/map_window.cpp`
- [Palette](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/palette_window.cpp): tool UI · Tool and brush selection panel. · `source/palette_window.cpp`
- [Properties](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/properties_window.cpp): inspector UI · Object property editing and dialogs. · `source/properties_window.cpp`
- [Preferences](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/preferences.cpp): settings · Persistent editor preferences. · `source/preferences.cpp`

### Map Core

Editable world state and selection history.

- [Map](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map.cpp): world model · Main editable map and global structure. · `source/map.cpp`
- [Tile](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/tile.cpp): world cell · Per-position map cell contents and flags. · `source/tile.cpp`
- [Item](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/item.cpp): object model · Placeable map item and attributes. · `source/item.cpp`
- [Selection](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/selection.cpp): edit state · Current selected region and objects. · `source/selection.cpp`
- [Copy Buffer](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/copybuffer.cpp): edit state · Clipboard-like temporary map data. · `source/copybuffer.cpp`

### Brushes

Placement and transformation tools.

- [Brush Base](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/brush.cpp): tool base · Shared placement and transform behavior. · `source/brush.cpp`
- [Ground](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/ground_brush.cpp): brush · Ground and terrain placement brush. · `source/ground_brush.cpp`
- [Doodad](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/doodad_brush.cpp): brush · Decorative object placement brush. · `source/doodad_brush.cpp`
- [House](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/house_brush.cpp): brush · House-area editing brush. · `source/house_brush.cpp`
- [Zone](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/zone_brush.cpp): brush · Zone painting and region tagging brush. · `source/zone_brush.cpp`

### Rendering

Map visualization and overlays.

- [GL Renderer](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/gl_renderer.cpp): renderer · OpenGL-backed map rendering pipeline. · `source/gl_renderer.cpp`
- [Map Display](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_display.cpp): view layer · Interactive map viewport and overlays. · `source/map_display.cpp`
- [Map Drawer](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/map_drawer.cpp): draw pipeline · Composes tiles, items, and decorations for display. · `source/map_drawer.cpp`
- [Light Drawer](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/light_drawer.cpp): overlay renderer · Lighting and shading overlay rendering. · `source/light_drawer.cpp`

### Persistence

Map formats, templates, and import/export.

- [OTBM](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/iomap_otbm.cpp): map format · OpenTibia map serialization adapter. · `source/iomap_otbm.cpp`
- [OTMM](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/iomap_otmm.cpp): map format · Alternative map serialization adapter. · `source/iomap_otmm.cpp`
- [Templates](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/templates.h): format support · Template and version-specific map helpers. · `source/templates.h`
- [Bitmap Import](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/bitmap_to_map_converter.cpp): importer · Converts bitmap input into map structure. · `source/bitmap_to_map_converter.cpp`

### Extensions

Lua automation and live editing.

- [Lua Engine](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/lua/lua_engine.cpp): script runtime · Embedded scripting runtime and bindings host. · `source/lua/lua_engine.cpp`
- [Script Manager](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/lua/lua_script_manager.cpp): script orchestration · Loads, tracks, and runs shipped scripts. · `source/lua/lua_script_manager.cpp`
- [Live Server](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/live_server.cpp): sync server · Remote or synchronized editing server side. · `source/live_server.cpp`
- [Live Client](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/live_client.cpp): sync client · Client side live editing connection. · `source/live_client.cpp`

### Data & Assets

XML-driven content definitions and bundled art.

- [Materials](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/materials.cpp): content catalog · Loaded brush and tileset material definitions. · `source/materials.cpp`
- [Client Assets](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/client_assets.cpp): asset metadata · Client-specific assets and appearance metadata. · `source/client_assets.cpp`
- [Sprites](https://github.com/opentibiabr/remeres-map-editor/blob/main/source/sprites.h): asset data · Sprite and appearance data access. · `source/sprites.h`

## Connections

- Application → Editor: starts · Bootstraps the editor controller.
- Editor → Map Window: hosts · Creates and manages the main workspace.
- Editor → Palette: hosts · Provides tool selection UI.
- Editor → Properties: hosts · Opens object inspectors and dialogs.
- Editor → Preferences: loads · Reads and stores persistent UI/editor settings.
- Map Window → Map: edits · Primary workspace manipulates the map model.
- Palette → Brush Base: selects · Chooses the active brush/tool.
- Brush Base → Ground: specializes · Terrain-focused brush variant.
- Brush Base → Doodad: specializes · Decoration-focused brush variant.
- Brush Base → House: specializes · House editing brush variant.
- Brush Base → Zone: specializes · Zone editing brush variant.
- Brush Base → Map: applies to · Brushes mutate the core world model.
- Map → Tile: contains · Map is composed of tiles.
- Tile → Item: contains · Tiles store items and attributes.
- Map → Selection: tracks · Selection state references map content.
- Selection → Copy Buffer: copies to · Selected content can be buffered for paste.
- GL Renderer → Map Display: feeds · Renderer supplies viewport drawing.
- Map Display → Map Drawer: uses · Viewport delegates composition to drawer.
- Map Drawer → Map: renders · Draws the world model.
- Map Drawer → Light Drawer: overlays · Adds lighting and overlay pass.
- OTBM → Map: loads/saves · Primary OTBM persistence boundary.
- OTMM → Map: loads/saves · Alternative OTMM persistence boundary.
- Templates → OTBM: supports · Template helpers inform map format handling.
- Templates → OTMM: supports · Template helpers inform map format handling.
- Bitmap Import → Map: imports into · Converts images into map structure.
- Lua Engine → Map: scripts · Lua scripts can inspect and mutate the map.
- Script Manager → Lua Engine: runs · Coordinates script loading and execution.
- Live Server → Live Client: syncs with · Remote editing connection boundary.
- Live Client → Map: syncs · Live editing changes affect the map model.
- Materials → Brush Base: configures · XML-driven materials define brush/group catalogs.
- Materials → Client Assets: aligns · Client-specific definitions drive asset interpretation.
- Client Assets → Sprites: uses · Appearance metadata is resolved against sprite data.
- Properties → Item: edits · Property dialogs adjust object attributes.
