Bluemap External Extender

Bluemap External Extender is a script that enhances the functionality of BlueMap, allowing for external control and extended features.

You can create new entire ui on parent site iframe on like example image

demo: https://mntale.fun/map

Installation

1. Click the "Code" button and select "Download ZIP".
2. Extract the ZIP file to your BlueMap web folder (e.g., bluemap/web/js/).
3. Rename the extracted folder to bluemap-external-extender.
4. Edit the BlueMap Web configuration file located at plugins/BlueMap/webapp.conf.
5. Add the Bluemap External Extender script to the scripts array:

scripts: [
  "js/bluemap-external-extender/main.js"
]

6. Save the configuration file and restart your server.

Post Messages

Set camera position

Command: updatePosition Data: x, y, z (number) - camera position in blocks

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'updatePosition', 
    x: 0, 
    y: 64, 
    z: 0 
  }, 
  '*'
);

Switch view mode

Command: setPerspectiveView, setFlatView, setFreeFlight Options: transition (number) - transition time in milliseconds Transition height: heightTransition (number) - transition height in blocks

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'viewMode', 
    command: 'setPerspectiveView', 
    options: { transition: 500, heightTransition: 256 } 
  }, 
  '*'
);

Follow player

Command: followPlayer Data: playerId (string) - player ID

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'followPlayer', 
    playerId: 'playerId' 
  }, 
  '*'
);

Update settings

Command: updateSettings Options: setting (string) - setting name

• hiresDistance (number) - set hires distance
• lowresDistance (number) - set lowres distance
• sunlightStrength (number) - set sunlight strength
• ambientLight (number) - set ambient light strength
• pauseTileLoading (boolean) - set pause tile loading
• invertMouse (boolean) - invert mouse
• mouseSensitivity (number) - set mouse sensitivity
• showChunkBorders (boolean) - set show chunk borders
• showDebug (boolean) - set show debug information
• superSampling (number) - set super sampling value
• resetSettings (boolean) - reset all settings Value: value (any) - setting value

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'updateSettings', 
    setting: 'hiresDistance', 
    value: 1000 
  }, 
  '*'
);

Teleport to player

Command: teleportToPlayer Data: playerId (string) - player ID

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'teleportToPlayer', 
    playerId: 'playerId' 
  }, 
  '*'
);

Switch map

Command: switchMap Data: mapId (string) - map ID

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'switchMap', 
    mapId: 'mapId' 
  }, 
  '*'
);

Reset view

Command: resetView

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'resetView' 
  }, 
  '*'
);

Animate sunlight strength

Command: animateSunlightStrength Data: targetValue (number) - target value

iframeRef.current.contentWindow.postMessage(
  { 
    type: 'animateSunlightStrength', 
    targetValue: 1 
  }, 
  '*'
);

Get marker list

Command: getMarkers

iframeRef.current.contentWindow.postMessage(
  { type: 'getMarkers' },
  '*'
);

Toggle marker set visibility

Command: toggleMarkerSet Data: markerSetId (string) - marker set id

iframeRef.current.contentWindow.postMessage(
  { type: 'toggleMarkerSet', markerSetId: 'markerSetId' },
  '*'
);

Get player list

Command: getPlayerList

iframeRef.current.contentWindow.postMessage(
  { type: 'getPlayerList' },
  '*'
);

Listen to player list update

Listener: playerListUpdate Data: players (string) - player list

window.addEventListener('playerListUpdate', (event) => {
  const players = JSON.parse(event.data.players);
  console.log(players);
});

Listen Events

Listen to camera position update

Listener: onPosition Data: x, y, z (number) - camera position in blocks

window.addEventListener('onPosition', (event) => 
  {
  console.log(event.data);
  }
);

Listen to view mode change

Listener: onViewMode Data: mode (string) - view mode

window.addEventListener('onViewMode', (event) => 
  {
  console.log(event.data);
  }
);

Listen to follow player status change

Listener: onFollowingPlayerStatus Data: isFollowing (boolean) - is following

window.addEventListener('onFollowingPlayerStatus', (event) => 
  {
  console.log(event.data);
  }
);

Listen to map change

Listener: onMapChange Data: mapId (string) - map ID

window.addEventListener('onMapChange', (event) => 
  {
  console.log(event.data);
  }
);

Listen to url update

Listener: onUrlChange Data: url (string) - url

window.addEventListener('onUrlChange', (event) => 
  {
  console.log(event.data);
  }
);

Listen to sunlight strength update (FIRST TIME ONLY)

Listener: onSunlightStrength Data: value (number) - sunlight strength

window.addEventListener('onSunlightStrength', (event) => {
  console.log(event.data);
});

Listen to map list update (FIRST TIME ONLY)

Listener: mapListUpdate Data: mapList (string) - map list

window.addEventListener('mapListUpdate', (event) => {
  console.log(event.data);
});

Listen to all settings update (FIRST TIME ONLY)

Listener: allSettings Data: settings (string) - settings

• hiresSliderMin (number) - hires slider min
• hiresSliderMax (number) - hires slider max
• hiresSliderDefault (number) - hires slider default
• lowresSliderMin (number) - lowres slider min
• lowresSliderMax (number) - lowres slider max
• lowresSliderDefault (number) - lowres slider default
• resolutionDefault (number) - resolution default
• version (string) - version
• maxZoomDistance (number) - max zoom distance
• minZoomDistance (number) - min zoom distance

window.addEventListener('allSettings', (event) => {
  console.log(event.data);
});

Listen to localStorage update (FIRST TIME ONLY) Listener: localStorageData Data: storage (string) - localStorage data

• bluemap-superSampling (number) - super sampling setting
• bluemap-mouseSensitivity (number) - mouse sensitivity setting
• bluemap-hiresViewDistance (number) - high resolution view distance
• bluemap-screenshotClipboard (boolean) - screenshot to clipboard setting
• bluemap-pauseTileLoading (boolean) - pause tile loading setting
• bluemap-theme (string | null) - theme setting
• bluemap-lang (string) - language setting
• bluemap-lowresViewDistance (number) - low resolution view distance
• bluemap-tileCacheHash (number) - tile cache hash
• bluemap-chunkBorders (boolean) - chunk borders display setting
• bluemap-resetSettings (boolean) - reset settings flag
• bluemap-debug (boolean) - debug mode setting
• bluemap-showZoomButtons (boolean) - show zoom buttons setting
• bluemap-invertMouse (boolean) - invert mouse setting

window.addEventListener('localStorageData', (event) => {
  console.log(event.data);
});

Listen to marker list update

Listener: markerListUpdate Data: markers (string) - marker set and marker data

window.addEventListener('markerListUpdate', (event) => {
  const markers = JSON.parse(event.data.markers);
  console.log(markers);
});

Update map (reload current map)

Command: updateMap

iframeRef.current.contentWindow.postMessage(
  { type: 'updateMap' },
  '*'
);

Update theme

Command: updateTheme Data: theme (string) - theme name ('light', 'dark', 'contrast', etc)

iframeRef.current.contentWindow.postMessage(
  { type: 'updateTheme', theme: 'dark' },
  '*'
);

Additional notes:

• Getting player list with (map url)/maps/(map id)/live/players.json Get player list:

const mapId = 'map id';
const mapUrl = 'https://example.com';
const fetchPlayers = async () => {
  try {
    const response = await fetch(`${mapUrl}/maps/${mapId}/live/players.json`);
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching players:', error);
  }
};

Response:

{
  "players": [
    {
      "uuid": "playerId",
      "name": "playerName",
      "foreign": playerForeign (boolean),
      "position": {"x":playerX,"y":playerY,"z":playerZ},
      "rotation": {"pitch":playerPitch,"yaw":playerYaw,"roll":playerRoll}
    },
    {
      "uuid": "playerId",
      "name": "playerName",
      "foreign": playerForeign (boolean),
      "position": {"x":playerX,"y":playerY,"z":playerZ},
      "rotation": {"pitch":playerPitch,"yaw":playerYaw,"roll":playerRoll}
    },
    ...
  ]
}

Getting iframeRef Examples

React Example

import React, { useRef, useEffect } from 'react';
function BlueMapComponent() {
  const iframeRef = useRef(null);
  useEffect(() => {
    if (iframeRef.current) {
      // Example: Set camera position
      iframeRef.current.contentWindow.postMessage(
        {
          type: 'updatePosition',
          x: 0,
          y: 64,
          z: 0
        },
        ''
      );
    }
  }, []);
  return (
    <iframe
      ref={iframeRef}
      src="https://example.com"
      title="BlueMap"
      width="100%"
      height="600px"
    />
  );
}

export default BlueMapComponent;

Normal JavaScript HTML Example

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>BlueMap Example</title>
</head>
<body>
  <iframe id="bluemap-iframe" src="https://example.com" width="100%" height="600px"></iframe>
  <script>
    const iframeRef = document.getElementById('bluemap-iframe');
    // Wait for the iframe to load
    iframeRef.onload = function() {
      // Example: Set camera position
      iframeRef.contentWindow.postMessage(
        {
          type: 'updatePosition',
          x: 0,
          y: 64,
          z: 0
        },
        ''
      );
    };
  </script>
</body>

These examples show how to get iframe and send messages to iframe.