⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

mapstage

hopechen067@hopechen067⭐ 528 stars· last commit 21d ago· 1 open issues

MapStage live tuner for map/globe projection, satellite, hypsometric relief, 3D terrain, region isolate, CSS color grade, and JSON presets.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 528 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

MapStage

English | 中文

A narrative map stage for historical videos: one MapLibre engine plus one agent skill. Antique parchment basemap, routes that march, place names that fade in, cameras that follow the narration, and a seek(t) contract so HyperFrames, Remotion or Playwright can capture frame by frame.

Live site

Home, docs, examples and the Studio tuner. Satellite imagery and terrain tiles are fetched at runtime, so you need internet access. Nothing to install.

PathWhat
/Home: live map hero with a scrubbable timeline
/docs/Docs, rendered straight from mapstage/references/*.md (people and agents read the same files)
/examples/Example library, filtered by Look / Story / Stage / Play, each with source
/studio/Studio: tune the look, copy the preset JSON

Recent changes: CHANGELOG.md.

What it does

Three layers:

  • Look: the basemap preset (v3), exported from the Studio tuner. Skins, relief, settlement tiers, optional region isolate.
  • Story: story.json v1. Places, routes, place-name beats, camera, cards, compliance.
  • Stage: the seek(t) time contract, frame capture and QA.

Plus Play: MapStageBoard gives games and interactive pages the same parchment map. MapStage only draws the map; the rules are yours.

Built-in rules for platform-safe output: no provincial or national border lines, no fog or vignette, Taiwan, Hainan and the South China Sea shown complete. The ten-dash line appears only on full-China shots. See mapstage/references/compliance.md.

Not in scope: interactive web-map products, a marketplace, navigation or surveying.

Demo video

Example output of this stack in a real map-story episode (Long March ep.14, 西路军). Low-res clip:

https://hopechen067.github.io/MapStage/media/long-march-ep14-demo.mp4

Longer clip (~36s): showcases/long-march-ep14/ep14-map-clip.mp4

Showcases

Still frames from the same episode.

More files: showcases/long-march-ep14/

ItemValue
Skill foldermapstage
RuntimeMapLibre GL JS 5.6.0, no bundler, no npm runtime dependency
Default basemapEOX Sentinel-2 cloudless (public demo WMTS; check provider terms)
Terrain / hillshadeTerrarium-encoded DEM tiles (runtime fetch; encoding: 'terrarium')
Water / roadsOpenFreeMap vector tiles (OpenMapTiles); no data file in the repo, see DATA-PROVENANCE.md
Region isolateOptional parchment mask (ui.showRegionIsolate). The China outline comes from Natural Earth 10m (public domain); provincial / city shapes are simplified OSM polygons (ODbL). Narrative silhouettes, not official borders
LicenseMIT for code and docs; showcase media and third-party terms in LICENSE-EXCEPTIONS.md / NOTICE.md

Install as an agent skill

The skill lives in mapstage/. Copy that folder into your agent skills directory and reload skills.

git clone https://github.com/hopechen067/MapStage.git
cp -R MapStage/mapstage ~/.grok/skills/mapstage
# or: ~/.claude/skills/mapstage, ~/.codex/skills/mapstage

On Windows (PowerShell):

git clone https://github.com/hopechen067/MapStage.git
Copy-Item -Recurse -Force .\MapStage\mapstage (Join-Path $env:USERPROFILE ".grok\skills\mapstage")

Then tell your agent:

请使用 mapstage skill。
官网与调参台:https://hopechen067.github.io/MapStage/
仓库:https://github.com/hopechen067/MapStage
我会在 Studio 里调好风格后导出 JSON,请按 SKILL.md / references 应用到地图场景。

Style workflow: open the Studio, tune, Copy JSON, paste to your agent.

Run locally

Only needed for offline work or development. Do not open pages as file://.

git clone https://github.com/hopechen067/MapStage.git
cd MapStage
node mapstage/site/serve.mjs      # http://127.0.0.1:8770/  (same layout as the live site)

Only the Studio:

cd mapstage/tuner
python -m http.server 8765        # then open http://127.0.0.1:8765/

Static check (Node on PATH; expect verify ok at the end):

cd mapstage/tuner
node verify.mjs

Build the full static site into out/_site:

node mapstage/site/build.mjs

The build refuses to run if data of unconfirmed license is present (see DATA-PROVENANCE.md).

Map tiles

Satellite, DEM and vector tiles are not bundled; they are fetched at runtime from configured URLs.

  1. Read NOTICE.md.
  2. Defaults are in mapstage/tuner/map-tiles.config.js.
  3. Personal endpoints go in map-tiles.config.local.js (gitignored); see map-tiles.config.example.js.

EOX public tiles are typically non-commercial and need attribution. This project does not grant rights to any commercial map vendor.

Attribution & compliance

  • Follow each basemap / DEM / CDN provider's terms for your use case.
  • Data: the China outline is Natural Earth (public domain); OSM-derived shapes are ODbL. No separate hydrography pack is shipped. See DATA-PROVENANCE.md and LICENSE-EXCEPTIONS.md.
  • Maps shown to the public may need a review number (审图号) depending on platform and use; judge this for your own release.
  • MapLibre / Three.js: keep their licenses when redistributing builds.
  • Showcase images and video: All Rights Reserved demo media unless noted otherwise (LICENSE-EXCEPTIONS.md).

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • mapstage/SKILL.md4.0 KBupstream ↗
    ---
    name: mapstage
    description: MapStage live tuner for map/globe projection, satellite, hypsometric relief, 3D terrain, region isolate, CSS color grade, and JSON presets.
    ---
    
    # 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.
    
    ## 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.
    
    ## 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. |
    
    ## Workflow
    
    1. 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.
    2. Tiles: default **EOX Sentinel-2 cloudless** (on) + **Mapterhorn** (`tuner/map-tiles.config.js`). Override with gitignored `map-tiles.config.local.js`.
    3. Apply default preset [`tuner/preset-antique-default.json`](tuner/preset-antique-default.json) (same as [`tuner/presets/antique-default.json`](tuner/presets/antique-default.json)). Schema **version 3**.
    4. Adjust projection / satellite / relief / isolate / CSS / cities until the look locks.
    5. **Export JSON** (copy or download). Confirm `version: 3` plus `ui.projection`, `ui.showSatellite`, `ui.showRelief`, `ui.showCssFilter`, `isolate`.
    6. **Migrate** those fields into the production MapStage scene (see references).
    7. In production: `jumpTo` camera; wait for `idle`; optionally pre-cache tiles. **Avoid `easeTo` / `flyTo`** for recorded frames.
    8. Always set DEM with **`encoding: 'terrarium'`**. Wrong encoding breaks hillshade/terrain.
    9. Final frames render from the production host — **not** from the tuner 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`.
    
    ## Repo vs skill
    
    `git clone` of this GitHub repo pulls the **whole project**. The agent skill is only [`mapstage/`](https://github.com/hopechen067/MapStage/tree/master/mapstage). Install that folder with `npx skills add hopechen067/MapStage --skill mapstage -g` or `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.
    
    ## References
    
    - [`references/参数列表说明.md`](references/参数列表说明.md) — parameter tables + v3 defaults
    - [`references/tested-config.md`](references/tested-config.md) — sources, layer order, jumpTo + idle
    - [`references/tuner-workflow.md`](references/tuner-workflow.md) — HTTP tuner → export → production
    - [`references/city-tier-schema.md`](references/city-tier-schema.md) — settlement tiers
    - [`schemas/map-preset.schema.json`](schemas/map-preset.schema.json)
    - [`schemas/sample-sites.schema.json`](schemas/sample-sites.schema.json)
    - [`tuner/`](tuner/) — live page, verify script, default preset, sample sites
    
    ## Agents
    
    See [`agents/openai.yaml`](agents/openai.yaml) for display name / default prompt.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/hopechen067-mapstage-mapstage.md

// REPO STATS

528 stars
1 open issues
Last commit: 21d ago