mapstage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MapStage

Use this skill when building or tuning a MapStage scene: map/globe projection, satellite, hypsometric relief, Mapterhorn terrain, region isolate, CSS color grade, and JSON export.

在构建或调校 MapStage 场景时使用此 skill：地图/地球投影、卫星图、分层设色地形、Mapterhorn 地形、区域隔离、CSS 调色和 JSON 导出。

When to use

何时使用

Need a live MapStage tuner (map vs globe, satellite vs relief, isolate).
Need to lock paint / CSS / camera, then export JSON into another host.
Need tiered settlements (
```
capital
```
/
```
large
```
/
```
medium
```
/
```
small
```
/
```
pass
```
/
```
station
```
/
```
ordos
```
).

Do not use the tuner page as the final render host.

需要实时 MapStage 调校器（地图与地球、卫星图与地形、区域隔离）。
需要锁定绘制效果、CSS 和相机，然后将 JSON 导出到另一个宿主中。
需要分级聚落（
```
capital
```
/
```
large
```
/
```
medium
```
/
```
small
```
/
```
pass
```
/
```
station
```
/
```
ordos
```
）。

不要将调校器页面用作最终渲染宿主。

Modes

模式

Mode	Purpose
Production stack	Embed MapStage in your app: optional satellite/raster + Mapterhorn DEM ( `encoding: 'terrarium'` ) + hillshade + OpenFreeMap vector water + CSS filter + city extrusions. Drive look from exported JSON.
Tuner	HTTP page under `tuner/` (or the public demo) for sliders, projection, isolate, preset load/export.

模式	用途
生产环境（Production stack）	将 MapStage 嵌入应用：可选卫星图/栅格图层 + Mapterhorn DEM（ `encoding: 'terrarium'` ）+ hillshade + OpenFreeMap 矢量水体 + CSS 滤镜 + 城市建筑拉伸。通过导出的 JSON 驱动最终外观。
调校器（Tuner）	位于 `tuner/` 下的 HTTP 页面（或公共演示），用于调节滑块、投影、区域隔离以及预设加载/导出。

Workflow

工作流

Open the tuner: public demo https://hopechen067.github.io/MapStage/ or
```
cd tuner && python -m http.server
```
and open the local URL printed in the terminal.
Tiles: default EOX Sentinel-2 cloudless (on) + Mapterhorn (
```
tuner/map-tiles.config.js
```
). Override with gitignored
```
map-tiles.config.local.js
```
.

Apply default preset

tuner/preset-antique-default.json

(same as

tuner/presets/antique-default.json

). Schema version 3.

Adjust projection / satellite / relief / isolate / CSS / cities until the look locks.

Export JSON (copy or download). Confirm

version: 3

plus

ui.projection

ui.showSatellite

ui.showRelief

ui.showCssFilter

isolate

Migrate those fields into the production MapStage scene (see references).
In production:
```
jumpTo
```
camera; wait for
```
idle
```
; optionally pre-cache tiles. Avoid
easeTo
/
flyTo
for recorded frames.
Always set DEM with encoding: 'terrarium'
. Wrong encoding breaks hillshade/terrain.
Final frames render from the production host — not from the tuner UI.

打开调校器：公共演示 https://hopechen067.github.io/MapStage/，**或**执行
```
cd tuner && python -m http.server
```
，然后打开终端中打印的本地 URL。
瓦片：默认使用 EOX Sentinel-2 cloudless（开启）+ Mapterhorn（
```
tuner/map-tiles.config.js
```
）。可通过已被 gitignore 的
```
map-tiles.config.local.js
```
覆盖。

应用默认预设

tuner/preset-antique-default.json

（与

tuner/presets/antique-default.json

相同）。Schema 为 version 3。

调整投影、卫星图、地形、区域隔离、CSS 和城市显示效果，直至最终外观锁定。

导出 JSON（复制或下载）。确认

version: 3

，以及

ui.projection

、

ui.showSatellite

、

ui.showRelief

、

ui.showCssFilter

和

isolate

字段。

将这些字段迁移到生产环境中的 MapStage 场景（参见参考资料）。
在生产环境中：使用
```
jumpTo
```
控制相机；等待
```
idle
```
；可以选择预缓存瓦片。录制帧时避免使用
easeTo
/
flyTo
。
设置 DEM 时始终使用 encoding: 'terrarium'
。编码错误会导致 hillshade/terrain 失效。
最终帧应由生产宿主渲染，而不是调校器 UI。

Hard rules

硬性规则

Tiles not bundled — MapStage fetches DEM and basemap at runtime from configured URLs only.
Only use basemap endpoints you are allowed to use — defaults are public demo tiles (EOX); swap via config when needed.
encoding: 'terrarium'
on the terrain source — mandatory.
No
easeTo
/
flyTo
in recorded production paths; prefer
```
jumpTo
```
+
```
idle
```
.
Do not host final render on tuner.
Water on the public tuner is OpenFreeMap / OpenMapTiles vector layers (
```
water
```
/
```
waterway
```
). Export
```
ui.showWater
```
is always
```
false
```
(old GeoJSON overlay is off). Do not expect or commit
```
tuner/assets/water-data.js
```
.

不捆绑瓦片——MapStage 仅在运行时从已配置的 URL 获取 DEM 和 basemap。
仅使用有权使用的 basemap endpoint——默认使用公共演示瓦片（EOX）；必要时通过 config 替换。
地形源必须使用 encoding: 'terrarium'
。
录制的生产路径中不要使用
```
easeTo
```
/
```
flyTo
```
；优先使用
```
jumpTo
```
+
```
idle
```
。
不要在调校器上托管最终渲染。
公共调校器中的水体由 OpenFreeMap / OpenMapTiles 矢量图层（
```
water
```
/
```
waterway
```
）提供。导出的
```
ui.showWater
```
始终为
```
false
```
（旧版 GeoJSON overlay 已关闭）。不要依赖或提交
```
tuner/assets/water-data.js
```
。

Repo vs skill

仓库与 skill

git clone

of this GitHub repo pulls the whole project. The agent skill is only

mapstage/

. Install that folder with

npx skills add hopechen067/MapStage --skill mapstage -g

gh skill install hopechen067/MapStage mapstage --scope user

, or copy it into the host skills directory and reload. Agents do not auto-discover

mapstage/SKILL.md

from a clone.

对该 GitHub 仓库执行

git clone

会拉取整个项目。Agent skill 仅包含

mapstage/

。使用

npx skills add hopechen067/MapStage --skill mapstage -g

或

gh skill install hopechen067/MapStage mapstage --scope user

安装该文件夹，也可以将其复制到宿主的 skills 目录并重新加载。Agent 不会从 clone 的仓库中自动发现

mapstage/SKILL.md

。

References

参考资料

```
references/参数列表说明.md
```
— parameter tables + v3 defaults
```
references/tested-config.md
```
— sources, layer order, jumpTo + idle
```
references/tuner-workflow.md
```
— HTTP tuner → export → production
```
references/city-tier-schema.md
```
— settlement tiers
```
schemas/map-preset.schema.json
```
```
schemas/sample-sites.schema.json
```
```
tuner/
```
— live page, verify script, default preset, sample sites

```
references/参数列表说明.md
```
——参数表和 v3 默认值
```
references/tested-config.md
```
——数据源、图层顺序、jumpTo + idle
```
references/tuner-workflow.md
```
——HTTP 调校器 → 导出 → 生产环境
```
references/city-tier-schema.md
```
——聚落层级
```
schemas/map-preset.schema.json
```
```
schemas/sample-sites.schema.json
```
```
tuner/
```
——实时页面、验证脚本、默认预设和示例站点

Agents

See

agents/openai.yaml

for display name / default prompt.

有关显示名称和默认提示词，请参阅

agents/openai.yaml

。