feat: per-map configurable start camera position (#427)

common/src/main/java/de/bluecolored/bluemap/common/config/MapConfig.java

@@ -63,6 +63,11 @@ public class MapConfig implements MapSettings {
     private int sorting = 0;
 
     private Vector2i startPos = Vector2i.ZERO;
+    private int startDistance = 1500;
+    private float startRotation = 0;
+    private float startAngle = 0;
+    private float startTilt = 0;
+    private String startView = "perspective";
 
     private String skyColor = "#7dabff";
     private String voidColor = "#000000";

common/src/main/resources/de/bluecolored/bluemap/config/maps/map.conf

@@ -28,6 +28,32 @@ sorting: ${sorting}
 # Default is { x: 0, z: 0 }
 start-pos: { x: 0, z: 0 }
 
+# The starting camera distance (zoom level) when the map is opened.
+# You can change this at any time.
+# Default is 1500
+start-distance: 1500
+
+# The starting horizontal rotation of the camera in radians.
+# You can change this at any time.
+# Default is 0
+start-rotation: 0
+
+# The starting vertical angle of the camera in radians (0 = top-down, ~1.2 = low horizon).
+# You can change this at any time.
+# Default is 0
+start-angle: 0
+
+# The starting camera tilt in radians.
+# You can change this at any time.
+# Default is 0
+start-tilt: 0
+
+# The starting view mode for the map. Valid values are: "perspective", "flat", "free".
+# Note: the chosen view must be enabled (see enable-perspective-view, enable-flat-view, enable-free-flight-view).
+# You can change this at any time.
+# Default is "perspective"
+start-view: "perspective"
+
 # The color of the sky as a hex-color.
 # You can change this at any time.
 # Default is "#7dabff"

common/webapp/src/js/BlueMapApp.js

@@ -274,25 +274,28 @@ export class BlueMapApp {
 
         if (map) {
             controls.position.set(map.data.startPos.x, 0, map.data.startPos.z);
-            controls.distance = 1500;
-            controls.angle = 0;
-            controls.rotation = 0;
-            controls.tilt = 0;
-            controls.ortho = 0;
         }
 
-        controls.controls = this.mapControls;
-        this.appState.controls.state = "perspective";
-
-        if (this.settings.defaultToFlatView && map.hasView("flat")) {
-            this.setFlatView();
+        // Determine starting view: per-map config first, then global defaultToFlatView, then fallback
+        const startView = map?.data.startView ?? "perspective";
+        if (startView === "flat" && map?.hasView("flat")) {
+            this.setFlatView(0);
+        } else if (startView === "free" && map?.hasView("free")) {
+            this.setFreeFlight(0);
+        } else if (this.settings.defaultToFlatView && map?.hasView("flat")) {
+            this.setFlatView(0);
+        } else if (map && !map.hasView("perspective")) {
+            if (map.hasView("flat")) this.setFlatView(0);
+            else this.setFreeFlight(0);
+        } else {
+            this.setPerspectiveView(0);
         }
 
-        else if (!map.hasView("perspective")) {
-            if (map.hasView("flat"))
-                this.setFlatView();
-            else
-                this.setFreeFlight();
+        if (map) {
+            controls.distance = map.data.startDistance ?? 1500;
+            controls.rotation = map.data.startRotation ?? 0;
+            controls.angle = map.data.startAngle ?? 0;
+            controls.tilt = map.data.startTilt ?? 0;
         }
 
         this.updatePageAddress();

common/webapp/src/js/map/Map.js

@@ -65,6 +65,11 @@ export class Map {
 			texturesUrl: mapDataRoot + "/textures.json",
 			name: id,
 			startPos: {x: 0, z: 0},
+			startDistance: 1500,
+			startRotation: 0,
+			startAngle: 0,
+			startTilt: 0,
+			startView: "perspective",
 			skyColor: new Color(),
 			voidColor: new Color(0, 0, 0),
 			ambientLight: 0,
@@ -169,6 +174,12 @@ export class Map {
 
 				this.data.startPos = {...this.data.startPos, ...vecArrToObj(worldSettings.startPos, true)};
 
+				if (worldSettings.startDistance !== undefined) this.data.startDistance = worldSettings.startDistance;
+				if (worldSettings.startRotation !== undefined) this.data.startRotation = worldSettings.startRotation;
+				if (worldSettings.startAngle !== undefined) this.data.startAngle = worldSettings.startAngle;
+				if (worldSettings.startTilt !== undefined) this.data.startTilt = worldSettings.startTilt;
+				if (worldSettings.startView !== undefined) this.data.startView = worldSettings.startView;
+
 				if (worldSettings.skyColor && worldSettings.skyColor.length >= 3) {
 					this.data.skyColor.setRGB(
 						worldSettings.skyColor[0],

core/src/main/java/de/bluecolored/bluemap/core/map/MapSettings.java

@@ -34,6 +34,26 @@ public interface MapSettings extends RenderSettings {
 
     Vector2i getStartPos();
 
+    default int getStartDistance() {
+        return 1500;
+    }
+
+    default float getStartRotation() {
+        return 0;
+    }
+
+    default float getStartAngle() {
+        return 0;
+    }
+
+    default float getStartTilt() {
+        return 0;
+    }
+
+    default String getStartView() {
+        return "perspective";
+    }
+
     String getSkyColor();
 
     String getVoidColor();

core/src/main/java/de/bluecolored/bluemap/core/map/MapSettingsSerializer.java

@@ -65,8 +65,13 @@ public JsonElement serialize(BmMap map, Type typeOfSrc, JsonSerializationContext
         lowres.add("lodCount", context.serialize(lowresTileManager.getLodCount()));
         root.add("lowres", lowres);
 
-        // startPos
+        // startPos and camera defaults
         root.add("startPos", context.serialize(map.getMapSettings().getStartPos()));
+        root.addProperty("startDistance", map.getMapSettings().getStartDistance());
+        root.addProperty("startRotation", map.getMapSettings().getStartRotation());
+        root.addProperty("startAngle", map.getMapSettings().getStartAngle());
+        root.addProperty("startTilt", map.getMapSettings().getStartTilt());
+        root.addProperty("startView", map.getMapSettings().getStartView());
 
         // skyColor
         Color skyColor = new Color().parse(map.getMapSettings().getSkyColor());