# rustamnsu/shcde-map-editor architecture

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

- Interactive diagram: https://gitdiagram.com/rustamnsu/shcde-map-editor
- Repository: https://github.com/rustamnsu/shcde-map-editor

## Overview

SHC DE Map Editor is a portable desktop editor for Stronghold Crusader: Definitive Edition maps and saves. Users create or open a map, edit cells and entities through map tools, inspect and validate the result, then save a map or export a save as a map. Its backend models map geometry and semantics, applies transactional edits, and preserves binary sections. The README documents additional mask, symmetry, selection, clipboard, and castle-area capabilities. Research modules analyze reference maps and saves; only sampled relationships are shown.

Main entry points: [`editor/gui.py`](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/gui.py) (Desktop window), [`editor/document.py`](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/document.py) (Map document), [`editor/cli.py`](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/cli.py) (Command line), [`editor/preview.py`](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/preview.py) (Map preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Editor Interface"]
  node_desktop["Desktop window<br/>[gui.py]"]
  node_panels["Tool panels<br/>[panels.py]"]
  node_mask_ui["Mask editor<br/>[mask_editor.py]"]
  node_cli["Command line<br/>[cli.py]"]
end

subgraph group_editing["Map Editing"]
  node_terrain["Terrain, height, variation<br/>[services.py]"]
  node_buildings["Building placement<br/>[buildings.py]"]
  node_vegetation["Vegetation placement<br/>[trees.py]"]
  node_clipboard["Map clipboard<br/>[clipboard.py]"]
  node_render["Map rendering<br/>[render.py]"]
  node_preview["Map preview<br/>[preview.py]"]
  node_menu["Castle markers<br/>[menu.py]"]
end

subgraph group_backend["Map Backend"]
  node_document["Map document<br/>[document.py]"]
  node_geometry["Map geometry<br/>[geometry.py]"]
  node_format["Map container I/O<br/>[maptool.py]"]
  node_semantics["Map semantics<br/>[semantics.py]"]
end

subgraph group_persistence["User Data"]
  node_patterns["Mask library<br/>[patterns.py]"]
  node_settings["Editor settings<br/>[settings.py]"]
  node_recent["Recent maps<br/>[recent.py]"]
  node_state["Editor state<br/>[state.py]"]
end

subgraph group_research["Map Research"]
  node_reference_analysis["Reference map analysis"]
  node_save_analysis["Save analysis"]
  node_findings["Reference findings"]
end

node_user(("Map editor user"))

node_user -->|"uses"| node_desktop
node_desktop -->|"edits"| node_document
node_desktop -->|"displays"| node_panels
node_desktop -->|"opens"| node_mask_ui
node_desktop -->|"loads"| node_settings
node_desktop -->|"tracks"| node_recent
node_desktop -->|"restores"| node_state
node_desktop -->|"uses"| node_clipboard
node_desktop -->|"renders"| node_render
node_desktop -->|"uses"| node_terrain
node_desktop -->|"places"| node_buildings
node_desktop -->|"places"| node_vegetation
node_desktop -.->|"previews"| node_preview
node_desktop -.->|"offers"| node_cli
node_document -->|"reads and writes"| node_format
node_document -->|"uses"| node_geometry
node_terrain -->|"patches"| node_document
node_buildings -->|"patches"| node_document
node_buildings -->|"uses layouts"| node_semantics
node_vegetation -->|"patches"| node_document
node_clipboard -->|"copies map data"| node_document
node_mask_ui -->|"edits masks"| node_patterns
node_desktop -->|"loads masks"| node_patterns
node_panels -->|"selects masks"| node_patterns
node_preview -->|"renders map"| node_render
node_preview -->|"reads entities"| node_terrain
node_preview -->|"gets markers"| node_menu
node_desktop -->|"uses"| node_menu
node_cli -->|"uses services"| node_terrain
node_cli -->|"uses"| node_buildings
node_cli -->|"uses"| node_vegetation
node_reference_analysis -->|"reads maps"| node_format
node_reference_analysis -->|"interprets"| node_semantics
node_save_analysis -->|"reads saves"| node_format
node_save_analysis -->|"interprets"| node_semantics
node_findings -->|"uses analysis"| node_reference_analysis
node_findings -->|"reads maps"| node_format
node_findings -->|"interprets"| node_semantics

click node_desktop "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/gui.py"
click node_panels "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/panels.py"
click node_mask_ui "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/mask_editor.py"
click node_cli "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/cli.py"
click node_document "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/document.py"
click node_geometry "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/geometry.py"
click node_format "https://github.com/rustamnsu/shcde-map-editor/blob/main/maptool.py"
click node_semantics "https://github.com/rustamnsu/shcde-map-editor/blob/main/semantics.py"
click node_terrain "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/services.py"
click node_buildings "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/buildings.py"
click node_vegetation "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/trees.py"
click node_clipboard "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/clipboard.py"
click node_render "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/render.py"
click node_preview "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/preview.py"
click node_menu "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/menu.py"
click node_patterns "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/patterns.py"
click node_settings "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/settings.py"
click node_recent "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/recent.py"
click node_state "https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/state.py"
click node_reference_analysis "https://github.com/rustamnsu/shcde-map-editor/blob/main/research/analyze_references.py"
click node_save_analysis "https://github.com/rustamnsu/shcde-map-editor/blob/main/research/analyze_savegame.py"
click node_findings "https://github.com/rustamnsu/shcde-map-editor/blob/main/research/reference_findings.py"

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_desktop,node_panels,node_mask_ui,node_cli,node_user toneBlue
class node_terrain,node_buildings,node_vegetation,node_clipboard,node_render,node_preview,node_menu toneAmber
class node_document,node_geometry,node_format,node_semantics toneMint
class node_patterns,node_settings,node_recent,node_state toneRose
class node_reference_analysis,node_save_analysis,node_findings toneIndigo
```

## Components

### Editor Interface

- [Desktop window](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/gui.py): `editor/gui.py`
- [Tool panels](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/panels.py): `editor/panels.py`
- [Mask editor](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/mask_editor.py): `editor/mask_editor.py`
- [Command line](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/cli.py): `editor/cli.py`

### Map Editing

- [Terrain, height, variation](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/services.py): `editor/services.py`
- [Building placement](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/buildings.py): `editor/buildings.py`
- [Vegetation placement](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/trees.py): `editor/trees.py`
- [Map clipboard](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/clipboard.py): `editor/clipboard.py`
- [Map rendering](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/render.py): `editor/render.py`
- [Map preview](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/preview.py): `editor/preview.py`
- [Castle markers](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/menu.py): `editor/menu.py`

### Map Backend

- [Map document](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/document.py): `editor/document.py`
- [Map geometry](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/geometry.py): `editor/geometry.py`
- [Map container I/O](https://github.com/rustamnsu/shcde-map-editor/blob/main/maptool.py): `maptool.py`
- [Map semantics](https://github.com/rustamnsu/shcde-map-editor/blob/main/semantics.py): `semantics.py`

### User Data

- [Mask library](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/patterns.py): `editor/patterns.py`
- [Editor settings](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/settings.py): `editor/settings.py`
- [Recent maps](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/recent.py): `editor/recent.py`
- [Editor state](https://github.com/rustamnsu/shcde-map-editor/blob/main/editor/state.py): `editor/state.py`

### Map Research

- [Reference map analysis](https://github.com/rustamnsu/shcde-map-editor/blob/main/research/analyze_references.py): `research/analyze_references.py`
- [Save analysis](https://github.com/rustamnsu/shcde-map-editor/blob/main/research/analyze_savegame.py): `research/analyze_savegame.py`
- [Reference findings](https://github.com/rustamnsu/shcde-map-editor/blob/main/research/reference_findings.py): `research/reference_findings.py`

### Other components

- **Map editor user**

## Connections

- Map editor user → Desktop window: uses (evidence: `README.md`)
- Desktop window → Map document: edits (evidence: `editor/gui.py`)
- Desktop window → Tool panels: displays (evidence: `editor/gui.py`)
- Desktop window → Mask editor: opens (evidence: `editor/gui.py`)
- Desktop window → Editor settings: loads (evidence: `editor/gui.py`)
- Desktop window → Recent maps: tracks (evidence: `editor/gui.py`)
- Desktop window → Editor state: restores (evidence: `editor/gui.py`)
- Desktop window → Map clipboard: uses (evidence: `editor/gui.py`)
- Desktop window → Map rendering: renders (evidence: `editor/gui.py`)
- Desktop window → Terrain, height, variation: uses (evidence: `editor/gui.py`)
- Desktop window → Building placement: places (evidence: `editor/gui.py`)
- Desktop window → Vegetation placement: places (evidence: `editor/gui.py`)
- Desktop window → Map preview: previews
- Desktop window → Command line: offers
- Map document → Map container I/O: reads and writes (evidence: `editor/document.py`)
- Map document → Map geometry: uses (evidence: `editor/document.py`)
- Terrain, height, variation → Map document: patches (evidence: `editor/services.py`)
- Building placement → Map document: patches (evidence: `editor/buildings.py`)
- Building placement → Map semantics: uses layouts (evidence: `editor/buildings.py`)
- Vegetation placement → Map document: patches (evidence: `editor/trees.py`)
- Map clipboard → Map document: copies map data (evidence: `editor/clipboard.py`)
- Mask editor → Mask library: edits masks (evidence: `editor/mask_editor.py`)
- Desktop window → Mask library: loads masks (evidence: `editor/gui.py`)
- Tool panels → Mask library: selects masks (evidence: `editor/panels.py`)
- Map preview → Map rendering: renders map (evidence: `editor/preview.py`)
- Map preview → Terrain, height, variation: reads entities (evidence: `editor/preview.py`)
- Map preview → Castle markers: gets markers (evidence: `editor/preview.py`)
- Desktop window → Castle markers: uses
- Command line → Terrain, height, variation: uses services (evidence: `editor/cli.py`)
- Command line → Building placement: uses (evidence: `editor/cli.py`)
- Command line → Vegetation placement: uses (evidence: `editor/cli.py`)
- Reference map analysis → Map container I/O: reads maps (evidence: `research/analyze_references.py`)
- Reference map analysis → Map semantics: interprets (evidence: `research/analyze_references.py`)
- Save analysis → Map container I/O: reads saves (evidence: `research/analyze_savegame.py`)
- Save analysis → Map semantics: interprets (evidence: `research/analyze_savegame.py`)
- Reference findings → Reference map analysis: uses analysis (evidence: `research/reference_findings.py`)
- Reference findings → Map container I/O: reads maps (evidence: `research/reference_findings.py`)
- Reference findings → Map semantics: interprets (evidence: `research/reference_findings.py`)
