Added map-bounds clipping options for tile/image/object rendering with map-level clipRect override

[JustJ01]

Fixes #4153

Description:

This PR adds editor-side clipping controls to keep map visuals constrained, useful for world context maps and oversized/repeating content.

Features implemented:

1. View Toggle: Clip Map to Bounds

Adds a new toggle: View → Clip Map to Bounds

• On: Anything drawn outside the map's visible area is hidden.
• Off: Maps behave as before (overflow allowed).

Tile Layer and Image Layer rendering now respect clipping when this option is enabled.

---

2. View Submenu: Object Bounds

Adds a new submenu: View → Object Bounds

This controls how objects behave when they are near or outside the map bounds.

• Show All
  Old behavior. All objects remain visible, including those fully outside the map.

• Clip to Map Bounds
  Objects remain visible, but any portion outside the map bounds is visually clipped.

• Hide Out-of-Bounds
  Objects fully outside the map are hidden.
  Objects touching or crossing the map boundary remain visible.

Object rendering and visibility now follow the selected mode.

---

3. Map-Level Clipping Override (Custom Clipping)

Adds support for a custom map property: clipRect
This allows defining a custom clipping rectangle instead of using the full map bounds.

Primary property name: clipRect

Accepted formats:

• Rect/class-style value with x, y, width, height
• 4-number list: [x, y, width, height]
• String format: "x,y,width,height"
• If the property is absent or invalid (for example "hello"), clipping automatically falls back to the normal map bounds.

---

4. Unified Clipping Logic

Tile, image, and object rendering paths now use the same effective clipping bounds, ensuring consistent behavior across all layer types.

---

How to use:

1) Clip Map to Bounds ( Tile + Image layers)

• Open any map
• Add a Image Layer, Browse the image and add the image, Enable Repeat X and Repeat Y
• View -> Clip Map to Bounds, Toggle On or Off

toggle_clipping.mp4

2) Object Bounds Mode

• Add Object Layer
• Place Objects, one inside the map, one crossing the map border, one fully outside the map
• VIew -> Object Bounds -> (Select Modes from there)

object_modes.mp4

3) Custom Clipping rectangel (clipRect)

• Map -> Map Properties
• In Custom properties add:
  Name: clipRect
  Type: string
  value: (Valid format string mentioned above)

clipRect_override.mp4

[JustJ01]

Hi @bjorn ,

I've implemented core View clipping for Tile + Image layers, plus object modes (Show All / Clip / Hide Out of Bounds) , persistent preferences and view menu wiring , map-level custom clipping rectangle property (clipRect).

Please review the changes whenever possible.

Items like per-map background fill behavior in World view, world background draw-order policy (mentioned by @eishiya) are not included in this PR. I'm also considering adding dedicated first class UI fields in map properties for clipRect in a follow up.

If the current scope and implementation looks good, I can proceed with those additional features that @eishiya mentioned

[bjorn]

@JustJ01 This is already looking quite decent! However, I have some concerns about performance and the inclusion of the custom property handling and the "hide out of bounds objects" option.

[bjorn]

@JustJ01 In light of the discussions with @eishiya and after my previous code review, I'd like to see the following changes:

• No separate clipping option for tile/image layers vs. objects -> Clipping can then by applied either by the MapItem directly or by a dedicated "clip item", which is used as the parent of all layer items. By relying on setting the bounding rect to the area we want to clip in combination with QGraphicsItem::ItemClipsChildrenToShape.

• The global "Map Bounds Clipping" option should have three states:

  • No Map Clipping
  • Clip Maps to Bounds
  • Clip Other Maps to Bounds

This should simplify the implementation, avoid performance concerns and I think it's also a little more intuitive.

The following options should not be handled for now, I'd rather see them considered for future changes:

• Map-level clipping override (the need for this is not entirely clear to me yet)
• Clipping map background color (because it affects totally unrelated code and we need to decide whether this needs another option or whether we can apply this based on the above option)

[eishiya]

Map-level clipping override (the need for this is not entirely clear to me yet)

Should I open a separate issue for this, or would it suffice to leave the existing one open?
My use case for custom map bounding rects is that my maps are routinely much larger than their actual "live" area because I need to have room for foreground parallax layers (because they scroll faster than the "main" layers (parallax 1.0), they need more content). In my Worlds, the maps are aligned according to the main layers, so the foreground layers overlap and make it difficult to see . Clipping to map bounds doesn't help the problem at all because all the content is in-bounds - the map bounds are just larger than the part of the map that's actually important in the context of a World. An alternative fix for this issue would be per-layer sizing, but that creates the question of which layer to use as the map bounds, so either way a setting to help deal with parallax>1 layers in maps would be useful.
I can send some screenshots (or even screenshare) on Discord to help understand the problem, if you like.

Edit: Perhaps the middle option should be "Clip All Maps to Bounds", for clarity?
Would it be possible to disable the Other maps option and maybe change the text of these options when there are no Worlds loaded? I can see those wordings being confusing to someone who's never used Worlds.

[bjorn]

Should I open a separate issue for this, or would it suffice to leave the existing one open?

I think it would be better to create a new issue for that specific option, and it would indeed be good to see some screenshots to illustrate this need.

Edit: Perhaps the middle option should be "Clip All Maps to Bounds", for clarity?
Would it be possible to disable the Other maps option and maybe change the text of these options when there are no Worlds loaded? I can see those wordings being confusing to someone who's never used Worlds.

It could get a little strange for this menu to change based on that context, especially since one could officially still have it set to "Clip Other Maps to Bounds" but with the world unloaded.

[JustJ01]

Hi @bjorn , I have made the changes as per you requested.

Features implemented:

1. Unified Clipping System
   • Replaced per-layer (tile/image/object) clipping with a single unified system at the MapItem level
   • Clipping is applied at the map level, automatically affecting all layers and objects within that map
2. View Menu: Map Bounds Clipping
   • Adds new submenu: View → Map Bounds Clipping
   • Three mutually exclusive options:
     • No Map Clipping - Default behavior, maps can overflow
     • Clip All Maps to Bounds - All maps are clipped to their visible area
     • Clip Other Maps to Bounds - Only the currently selected map is un-clipped; other maps in world view are clipped
3. World-Aware Clipping
   • When using "Clip Other Maps", the editor detects which map is currently active
   • Switching between maps in a world automatically updates clipping state

Screen.Recording.2026-04-03.090619.mp4

Screen.Recording.2026-04-03.095004.mp4