Skip to content

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

Open
Apezdr wants to merge 1 commit intoBlueMap-Minecraft:masterfrom
Apezdr:feat/map-start-positions
Open

feat: per-map configurable start camera position (#427)#795
Apezdr wants to merge 1 commit intoBlueMap-Minecraft:masterfrom
Apezdr:feat/map-start-positions

Conversation

@Apezdr
Copy link
Copy Markdown

@Apezdr Apezdr commented Apr 25, 2026

Summary

Closes #427

Extends the map config with five new optional fields that control the full initial camera state when a map is opened without a URL hash:

  • start-distance — zoom/camera distance (default: 1500)
  • start-rotation — horizontal camera rotation in radians (default: 0)
  • start-angle — vertical camera angle in radians (default: 0)
  • start-tilt — camera tilt in radians (default: 0)
  • start-view — initial view mode: "perspective", "flat", or "free" (default: "perspective")

These complement the existing start-pos field. All five default to the same values as before, so existing configs are unaffected.

Example config

start-pos: { x: 118, z: -148 }
start-distance: 59
start-rotation: 2.86
start-angle: 1
start-view: "perspective"

The values map directly to the URL hash format (#mapId:x:y:z:distance:rotation:angle:tilt:ortho:state), making it easy to copy a position from the browser bar into the config.

Changes

  • MapConfig — five new fields with safe defaults
  • MapSettings — default interface getters for the new fields
  • MapSettingsSerializer — emits all five fields into each map's settings.json
  • map.conf template — documents the new options
  • Map.js — parses the new fields from settings.json
  • BlueMapApp.resetCamera() — applies per-map start values; start-view takes priority over the global defaultToFlatView setting, with graceful fallback when the requested view is not enabled on the map

Test plan

  • Open map without URL hash — camera starts at configured position/distance/angle
  • Existing maps with no new config use the same defaults as before (distance 1500, perspective view)
  • start-view: "flat" opens in flat/isometric view
  • start-view: "free" opens in free-flight view
  • If start-view requests a disabled view, falls back to the next available view
  • URL hash still overrides the config start position when present

Extend map config with start-distance, start-rotation, start-angle,
start-tilt, and start-view fields so each map can define its full initial
camera state beyond just start-pos x/z.

- MapConfig: add startDistance (1500), startRotation (0), startAngle (0),
  startTilt (0), startView ("perspective") fields
- MapSettings: add default getters for the new fields
- MapSettingsSerializer: emit all new fields into each map's settings.json
- map.conf template: document new options with defaults and comments
- Map.js: parse new fields from settings.json into map data
- BlueMapApp.resetCamera: apply per-map start values; per-map startView
  takes priority over global defaultToFlatView, with graceful fallback
  when the requested view is not enabled on the map
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

More detailed control over map-start positions

1 participant