Skip to content
Back to search

MapStage

MapStage live tuner: map/globe, satellite, hypsometric relief, region isolate, Mapterhorn DEM, JSON presets.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hopechen067/MapStage with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hopechen067/MapStage'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hopechen067--mapstage/badge.svg)](/listings/hopechen067--mapstage)

HTML

<a href="/listings/hopechen067--mapstage"><img src="/api/listings/hopechen067--mapstage/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**`git clone` pulls the whole repository, not a standalone skill.** You get README, showcases, the tuner, and the `mapstage/` skill folder. Agents do not auto-discover that folder from a clone. Copy `mapstage/` into your skills directory (step 2) if you want the agent skill.

1) Clone the repo

git clone https://github.com/hopechen067/MapStage.git
cd MapStage

Update later:

cd MapStage
git pull

2) Install as an agent skill

Skill folder (browse, not a second clone): [`mapstage/`](https://github.com/hopechen067/MapStage/tree/master/mapstage)

**One command** — installs only that folder:

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

GitHub CLI 2.90+:

gh skill install hopechen067/MapStage mapstage --scope user

Then reload skills. On Windows, add `--copy` to the `npx` command if symlink creation fails.

**Or** after a full clone, copy `mapstage/` into your agent's skills directory.

3) Paste this to your agent

请使用 MapStage skill。
在线调参:https://hopechen067.github.io/MapStage/
仓库:https://github.com/hopechen067/MapStage
我会在 demo 里调好风格后导出 JSON,请按 SKILL.md / references 应用到地图场景(jumpTo + idle,encoding terrarium)。

Style workflow: open the [live demo](https://hopechen067.github.io/MapStage/) → tune → **Copy JSON** → paste to your agent.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 179 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MapStage
  2. **English** | [中文](README.zh-CN.md)
  3. 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.
  4. ## Live site
  5. - **https://hopechen067.github.io/MapStage/** (GitHub Pages)
  6. - **https://mapstage1.pages.dev/** (Cloudflare Pages mirror)
  7. Home, docs, examples and the Studio tuner. Satellite imagery and terrain tiles are fetched at runtime, so you need internet access. Nothing to install.
  8. | Path | What |
  9. |------|------|
  10. | `/` | Home: live map hero with a scrubbable timeline |
  11. | `/docs/` | Docs, rendered straight from `mapstage/references/*.md` (people and agents read the same files) |
  12. | `/examples/` | Example library, filtered by Look / Story / Stage / Play, each with source |
  13. | `/studio/` | Studio: tune the look, copy the preset JSON |
  14. Recent changes: [CHANGELOG.md](CHANGELOG.md).
  15. ## What it does
  16. Three layers:
  17. - **Look**: the basemap preset (v3), exported from the Studio tuner. Skins, relief, settlement tiers, optional region isolate.
  18. - **Story**: `story.json` v1. Places, routes, place-name beats, camera, cards, compliance.
  19. - **Stage**: the `seek(t)` time contract, frame capture and QA.
  20. Plus **Play**: `MapStageBoard` gives games and interactive pages the same parchment map. MapStage only draws the map; the rules are yours.
  21. 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`.
  22. Not in scope: interactive web-map products, a marketplace, navigation or surveying.
  23. ### Demo video
  24. Example output of this stack in a real map-story episode (**Long March ep.14, 西路军**). Low-res clip:
  25. https://hopechen067.github.io/MapStage/media/long-march-ep14-demo.mp4
  26. <video
  27. controls
  28. playsinline
  29. preload="metadata"
  30. width="720"
  31. poster="mapstage/site/media/long-march-ep14-poster.jpg"
  32. src="https://hopechen067.github.io/MapStage/media/long-march-ep14-demo.mp4">
  33. </video>
  34. Longer clip (~36s): [showcases/long-march-ep14/ep14-map-clip.mp4](showcases/long-march-ep14/ep14-map-clip.mp4)
  35. ## Showcases
  36. Still frames from the same episode.
  37. <table>
  38. <tr>
  39. <td align="center" width="50%">
  40. <img src="showcases/long-march-ep14/still-01-route.jpg" alt="Route and timeline" />
  41. <br /><sub>Route + timeline card</sub>
  42. </td>
  43. <td align="center" width="50%">
  44. <img src="showcases/long-march-ep14/still-02-yellow-river.jpg" alt="Yellow River crossing" />
  45. <br /><sub>Yellow River · date card</sub>
  46. </td>
  47. </tr>
  48. <tr>
  49. <td align="center" width="50%">
  50. <img src="showcases/long-march-ep14/still-03-terrain.jpg" alt="Terrain and campaign arrow" />
  51. <br /><sub>Terrain · route arrow</sub>
  52. </td>
  53. <td align="center" width="50%">
  54. <img src="showcases/long-march-ep14/still-04-3d-city.jpg" alt="3D walled city" />
  55. <br /><sub>3D walled city (Gaotai)</sub>
  56. </td>
  57. </tr>
  58. <tr>
  59. <td align="center" width="50%">
  60. <img src="showcases/long-march-ep14/still-05-campaign.jpg" alt="Campaign area" />
  61. <br /><sub>Campaign area · tiered labels</sub>
  62. </td>
  63. <td align="center" width="50%">
  64. <img src="showcases/long-march-ep14/still-06-full-route.jpg" alt="Whole Long March route" />
  65. <br /><sub>Whole route</sub>
  66. </td>
  67. </tr>
  68. </table>
  69. More files: [showcases/long-march-ep14/](showcases/long-march-ep14/)
  70. | Item | Value |
  71. |------|--------|
  72. | Skill folder | `mapstage` |
  73. | Runtime | [MapLibre GL JS](https://maplibre.org/) 5.6.0, no bundler, no npm runtime dependency |
  74. | Default basemap | **EOX Sentinel-2 cloudless** (public demo WMTS; check provider terms) |
  75. | Terrain / hillshade | Terrarium-encoded DEM tiles (runtime fetch; `encoding: 'terrarium'`) |
  76. | Water / roads | OpenFreeMap vector tiles (OpenMapTiles); no data file in the repo, see [DATA-PROVENANCE.md](DATA-PROVENANCE.md) |
  77. | Region isolate | Optional 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 |
  78. | License | [MIT](LICENSE) for code and docs; showcase media and third-party terms in [LICENSE-EXCEPTIONS.md](LICENSE-EXCEPTIONS.md) / [NOTICE.md](NOTICE.md) |
  79. ## Install as an agent skill
  80. The skill lives in `mapstage/`. Copy that folder into your agent skills directory and reload skills.
  81. ```bash
  82. git clone https://github.com/hopechen067/MapStage.git
  83. cp -R MapStage/mapstage ~/.grok/skills/mapstage
  84. # or: ~/.claude/skills/mapstage, ~/.codex/skills/mapstage
  85. ```
  86. On Windows (PowerShell):
  87. ```powershell
  88. git clone https://github.com/hopechen067/MapStage.git
  89. Copy-Item -Recurse -Force .\MapStage\mapstage (Join-Path $env:USERPROFILE ".grok\skills\mapstage")
  90. ```
  91. Then tell your agent:
  92. ```text
  93. 请使用 mapstage skill。
  94. 官网与调参台:https://hopechen067.github.io/MapStage/
  95. 仓库:https://github.com/hopechen067/MapStage
  96. 我会在 Studio 里调好风格后导出 JSON,请按 SKILL.md / references 应用到地图场景。
  97. ```
  98. Style workflow: open the [Studio](https://hopechen067.github.io/MapStage/studio/), tune, **Copy JSON**, paste to your agent.
  99. ## Run locally
  100. Only needed for offline work or development. Do not open pages as `file://`.
  101. ```bash
  102. git clone https://github.com/hopechen067/MapStage.git
  103. cd MapStage
  104. node mapstage/site/serve.mjs # http://127.0.0.1:8770/ (same layout as the live site)
  105. ```
  106. Only the Studio:
  107. ```bash
  108. cd mapstage/tuner
  109. python -m http.server 8765 # then open http://127.0.0.1:8765/
  110. ```
  111. Static check (Node on `PATH`; expect `verify ok` at the end):
  112. ```bash
  113. cd mapstage/tuner
  114. node verify.mjs
  115. ```
  116. Build the full static site into `out/_site`:
  117. ```bash
  118. node mapstage/site/build.mjs
  119. ```
  120. The build refuses to run if data of unconfirmed license is present (see [DATA-PROVENANCE.md](DATA-PROVENANCE.md)).
  121. ## Map tiles
  122. Satellite, DEM and vector tiles are **not bundled**; they are fetched at runtime from configured URLs.
  123. 1. Read [NOTICE.md](NOTICE.md).
  124. 2. Defaults are in `mapstage/tuner/map-tiles.config.js`.
  125. 3. Personal endpoints go in `map-tiles.config.local.js` (gitignored); see `map-tiles.config.example.js`.
  126. EOX public tiles are typically non-commercial and need attribution. This project does **not** grant rights to any commercial map vendor.
  127. ## Attribution & compliance
  128. - Follow each basemap / DEM / CDN provider's terms for your use case.
  129. - **Data:** the China outline is Natural Earth (public domain); OSM-derived shapes are ODbL. No separate hydrography pack is shipped. See [DATA-PROVENANCE.md](DATA-PROVENANCE.md) and [LICENSE-EXCEPTIONS.md](LICENSE-EXCEPTIONS.md).
  130. - **Maps shown to the public** may need a review number (审图号) depending on platform and use; judge this for your own release.
  131. - **MapLibre / Three.js:** keep their licenses when redistributing builds.
  132. - **Showcase images and video:** All Rights Reserved demo media unless noted otherwise ([LICENSE-EXCEPTIONS.md](LICENSE-EXCEPTIONS.md)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.