mahal_map 1.6.16 → 1.6.18

package/README.md

@@ -12,16 +12,24 @@ npm install mahal_map maplibre-gl
 
 `maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
 
-Для нового 3D-движка (`engine: "3d"`) дополнительно нужен `@osm/maps3d-web`. Пакет **не публикуется в npm** — скачайте его со страницы платформы (кнопка «Web SDK — стартер»; в Vue-стартере это папка `libs/maps3d-web` с уже собранным `dist/`), положите в проект и поставьте как локальную зависимость:
+Для нового 3D-движка (`engine: "3d"`) дополнительно нужен `@grammaps/maps3d-web`:
+
+```sh
+npm i @grammaps/maps3d-web maplibre-gl
+```
+
+`three` идёт зависимостью SDK, `maplibre-gl` — peer (экземпляр карты создаёте вы через `mahal_map`).
+
+Оффлайн-вариант: в стартере со страницы платформы лежит папка `libs/maps3d-web` со собранным `dist/` — ставится как локальная зависимость:
 
 ```sh
 npm i ./libs/maps3d-web maplibre-gl
 ```
 
-`package.json` запишет ссылку на локальную папку:
+`package.json` в этом случае запишет ссылку на локальную папку:
 
 ```json
-"@osm/maps3d-web": "file:./libs/maps3d-web"
+"@grammaps/maps3d-web": "file:./libs/maps3d-web"
 ```
 
 Без сборщика возьмите `lib/maps3d.global.js` из скачанного стартера (IIFE-глобал `Maps3D`, three бандлится внутрь) и подключите скриптом после `maplibre-gl`:
@@ -141,11 +149,11 @@ interface IMahalMapOptions {
 | `lang`                | `"tj" \| "ru"`          | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`.             |
 | `center`              | `[number, number]`      | Центр карты в формате `[lng, lat]`.                                                                 |
 | `zoom`                | `number`                | Начальный zoom.                                                                                     |
-| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида).                                                        |
+| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида). Если не задан и `enable3D` включен — авто `58` (при `pitch: 0` экструзия зданий не видна, камера смотрит строго сверху). |
 | `bearing`             | `number`                | Начальный поворот камеры.                                                                           |
 | `autoAddVectorSource` | `boolean`               | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.           |
 | `engine`               | `"legacy" \| "3d"`     | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D. |
-| `enable3D`             | `boolean`              | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`.                        |
+| `enable3D`             | `boolean`              | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. По умолчанию `true` для `engine: "3d"` — передайте `false`, чтобы отключить. |
 | `base`                 | `string`               | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`.                  |
 | `preset`               | `string`               | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`. |
 | `maps3d`               | `object`               | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
@@ -157,7 +165,7 @@ interface IMahalMapOptions {
 ```ts
 import maplibregl from "maplibre-gl";
 import "maplibre-gl/dist/maplibre-gl.css";
-import { Maps3D } from "@osm/maps3d-web";
+import { Maps3D } from "@grammaps/maps3d-web";
 import { MahalMap, keyUtils } from "mahal_map";
 
 keyUtils.saveKey("YOUR_MAP_API_KEY");
@@ -177,7 +185,7 @@ const map = MahalMap.create(
 );
 ```
 
-`Maps3D` (третий аргумент `create()`) — опционален: если не передан, SDK попробует взять его из `window.Maps3D`. `@osm/maps3d-web` — необязательный peer dependency, ставится только если используется `engine: "3d"`.
+`Maps3D` (третий аргумент `create()`) — опционален: если не передан, SDK попробует взять его из `window.Maps3D`. `@grammaps/maps3d-web` — необязательный peer dependency, ставится только если используется `engine: "3d"`.
 
 Получить слой Maps3D после создания карты:
 
@@ -187,7 +195,7 @@ const layer = map.getMaps3DLayer();
 MahalMap.getMaps3DLayer(map);
 ```
 
-`getMaps3DLayer()` возвращает реальный инстанс `Maps3D` (не обёртку) — типы `mahal_map` описывают всю его публичную поверхность, так что подключающему сервису не нужно ставить или типизировать `@osm/maps3d-web` отдельно.
+`getMaps3DLayer()` возвращает реальный инстанс `Maps3D` (не обёртку) — типы `mahal_map` описывают всю его публичную поверхность, так что подключающему сервису не нужно ставить или типизировать `@grammaps/maps3d-web` отдельно.
 
 ### Опции `maps3d` (расширенные)
 
@@ -206,19 +214,25 @@ MahalMap.getMaps3DLayer(map);
 
 ### 3D-здания
 
+`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс:
+
+```ts
+const layer = new Maps3D({ apiKey, base, buildings: true });
+await layer.attach(map); // attach асинхронный, дожидается load карты сам
+```
+
 Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её:
 
 ```ts
 const layer = map.getMaps3DLayer();
 
-layer?.setBuildingsEnabled(false); // 3D-здания ⇄ штатные здания стиля
-
 const b = layer?.buildings;
 b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
-b?.setWindowDepth(0.85);
+b?.setWindowDepth(0.85); // глубина ниши окна 0..1 (реальная геометрия вблизи)
 b?.setWindowColor("#6b9ed1");
 b?.setWindowFrameColor("#f2f2f4");
-b?.setEdgeRadius(1.2);
+b?.setEdgeRadius(1.2); // скругление кромок, м
+// Свет обычно НЕ задают руками — его несёт metadata стиля, сеттеры её перебивают
 b?.setSunIntensity(3.2);
 b?.setAmbient(0.76);
 b?.setSky(0.91);
@@ -230,6 +244,26 @@ layer?.onBuildingClick((info) => {
 });
 ```
 
+#### Вкл/выкл 3D-здания на лету
+
+Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты:
+
+```ts
+layer?.setBuildingsEnabled(false); // напрямую через слой
+```
+
+Либо через обёртку `MahalMap` — она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
+
+```ts
+const map = MahalMap.getInstance("map");
+
+map.toggle3DBuildings(false); // выкл
+map.toggle3DBuildings(true);  // вкл обратно
+
+// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
+MahalMap.toggle3DBuildings(map, false);
+```
+
 ### Пробки
 
 ```ts
@@ -461,6 +495,8 @@ MahalMap.setLanguage(map, "ru");
 MahalMap.setCenter(map, [69.624024, 40.279687]);
 MahalMap.setZoom(map, 14);
 MahalMap.addMarker(map, marker);
+MahalMap.getMaps3DLayer(map);
+MahalMap.toggle3DBuildings(map, false);
 MahalMap.destroy(map);
 ```
 
@@ -498,6 +534,8 @@ MahalMap.setZoom(map, 14);
 | `setCenter(instance, center)`  | Меняет центр карты.                                |
 | `setZoom(instance, zoom)`      | Меняет zoom карты.                                 |
 | `addMarker(instance, marker)`  | Добавляет маркер.                                  |
+| `getMaps3DLayer(instance)`     | Возвращает инстанс слоя Maps3D (только `engine: "3d"`). |
+| `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
 | `destroy(instance)`            | Полностью удаляет карту.                           |
 | `loadKeyFromScriptUrl()`       | Читает `apikey` из URL SDK скрипта.                |
 | `loadLanguageFromScriptUrl()`  | Читает `lang` из URL SDK скрипта.                  |

package/dist/index.d.mts

@@ -248,6 +248,7 @@ declare class MahalMap {
     static getMap(instance: MahalMap): Map;
     static setStyle(instance: MahalMap, theme: Theme): void;
     static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
+    static toggle3DBuildings(instance: MahalMap, enabled: boolean): void;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -259,6 +260,14 @@ declare class MahalMap {
     setStyle(theme: Theme): void;
     setLanguage(lang: MapLanguage): void;
     getMaps3DLayer(): IMaps3DLayer | undefined;
+    /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
+    toggle3DBuildings(enabled: boolean): void;
+    /**
+     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
+     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
+     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     */
+    private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;

package/dist/index.d.ts

@@ -248,6 +248,7 @@ declare class MahalMap {
     static getMap(instance: MahalMap): Map;
     static setStyle(instance: MahalMap, theme: Theme): void;
     static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
+    static toggle3DBuildings(instance: MahalMap, enabled: boolean): void;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -259,6 +260,14 @@ declare class MahalMap {
     setStyle(theme: Theme): void;
     setLanguage(lang: MapLanguage): void;
     getMaps3DLayer(): IMaps3DLayer | undefined;
+    /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
+    toggle3DBuildings(enabled: boolean): void;
+    /**
+     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
+     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
+     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     */
+    private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;