一个基于 Vue 3 + Vite 构建的 Tampermonkey 脚本，用于把 TeamViewRelay 后端中的远程玩家、路标和战局信息投影到 squaremap 网页地图。
相关组件：
- Minecraft-TeamViewer-Backend：提供
/web-map/ws数据通道 - Minecraft_TeamViewer：负责从 Minecraft 客户端上报团队状态
- map-nodemc-plugin-blocker：可选的 NodeMC 页面屏蔽脚本
这个脚本运行在浏览器中，连接 TeamViewRelay 后端后，会把同一房间号（roomCode）下的状态渲染到 squaremap 页面。
当前主要用途：
- 显示远程玩家投影
- 可分别控制在线与离线玩家的图标和文字；离线玩家可选显示最后出现位置，历史 Tab 可用时会按最后记录的城镇与敌友关系着色，并以半透明样式呈现。离线时间与坐标悬停提示默认关闭，可在显示设置中单独开启；大量历史玩家只会在当前地图视口外扩区域内创建标记，移动或缩放结束后自动刷新
- 显示共享路标、战术标记和战局区块
- 支持从 Mod 剪贴板导入个人城镇敌友档案，并在浏览器本地维护逐玩家标记
- 提供浏览器侧的配置面板、配置导入导出和连接控制
- 需要配合
Minecraft-TeamViewer-Backend使用，单独安装脚本不会产生远程投影数据。 - 一般由
Minecraft_TeamViewer上报状态，网页地图脚本负责可视化。 map-nodemc-plugin-blocker是可选附加脚本，只用于屏蔽 NodeMC 页面上的某些问题扩展。
- 安装 Tampermonkey。
- 安装本脚本。
- 启动后端
Minecraft-TeamViewer-Backend。 - 打开受支持的 squaremap 页面。
- 在脚本设置中填写后端地址和房间号（
roomCode）。 - 验证地图上是否出现远程玩家、路标或战局区块。
需要：
- Tampermonkey
- 一个可访问的 TeamViewRelay 后端
当前脚本支持的站点：
https://map.nodemc.cc/*http://map.nodemc.cc/*https://map.fltown.cn/*http://map.fltown.cn/*
安装方式有两种。
仓库内可直接导入的脚本产物：
build-artifacts/team-view-relay-web-script-v0.4.20-proto0.7.1.user.js
也可以自行构建后，导入 dist/*.user.js。
pnpm install
pnpm dev
pnpm build构建产物位于：
dist/*.user.js
- 安装脚本后打开受支持的 squaremap 页面。
- 打开脚本设置面板。
- 填写后端地址，例如
ws://127.0.0.1:8765/web-map/ws。WebTransport 默认关闭；显式 选择WebTransport时，还需填写 HTTPS URL，例如https://relay.example.com:8766/web-map/wt，并确保后端 UDP 端口直连可达。 - 设置房间号（
roomCode），默认是default。 - 应用连接设置并等待连接成功。
- 如果对应房间里已有 Mod 客户端上报状态，应能看到地图投影出现。
当前默认连接地址：
ws://127.0.0.1:8765/web-map/ws
- 开关类选项通常即时生效，不需要再次点击保存
- 输入框类选项采用手动确认，避免边输入边触发重连
- 连接设置分组使用“应用连接设置”，保存后会触发重连
- 在线玩家与离线玩家的图标、文字独立设置；离线玩家的悬停信息默认关闭
- 支持导出当前配置为 JSON 文件
- 导入时会校验兼容版本
- 导入后的配置会统一经过归一化处理，缺失字段自动回落默认值，冗余字段自动忽略
- 在 Minecraft 中启用 Mod 的“Tab 标签敌我识别”插件，运行
/town或/t完成采集。 - 在插件页点击“复制关系档案到 Web”。
- 打开网页设置的“敌友关系”，点击“从剪贴板导入”，检查预览后替换 Mod 自动档案。
关系只保存在当前浏览器的当前地图来源（origin），不按 TeamViewRelay 房间共享，也不会回传给
Mod。判定优先级为“逐玩家标记 > Mod 自动档案 > 手动标签”；导入新档案只替换上一份 Mod
自动档案，逐玩家标记与手动标签会保留。新版本 Web 不发送玩家标记命令，也不采用房间快照中的
共享 playerMarks；这避免不同用户的个人敌友关系互相覆盖。
逐玩家标记的玩家选择器只列出实时 Tab 或实时地图快照中的在线玩家；纯历史 Tab 记录仍用于离线
位置的城镇和敌友关系展示，但不会让“在线玩家”列表随历史数据无限增长。
- 先确认后端已启动，并且脚本连接的是
/web-map/ws - 再确认 Minecraft Mod 也连接到了同一个后端
- 最后确认双方
roomCode一致
- 这个脚本不负责屏蔽
nodes扩展 - 如果你是在
map.nodemc.cc使用，可额外安装 map-nodemc-plugin-blocker
- 先检查对应玩家是否真的在上报
- 再检查房间号和后端是否一致
- 必要时用后端的
/snapshot接口确认服务端当前状态
常用命令：
pnpm install
pnpm dev
pnpm build
pnpm proto:generate构建前置依赖：
bufCLI 用于从third_party/TeamViewRelay-Protocol生成 TypeScript 协议代码- 如果本机没有
buf，可执行：
mkdir -p /tmp/buf/bin && GOBIN=/tmp/buf/bin go install github.com/bufbuild/buf/cmd/buf@v1.46.0- 脚本会优先使用
/tmp/buf/bin/buf，也可以自行设置BUF_BIN=/your/path/to/buf
关键目录：
src/index.ts：脚本主入口src/network/：WebSocket 与协议编解码src/ui/：设置面板与页面交互src/meta.ts：userscript 与协议元信息src/constants.ts：默认配置与运行时常量
当前版本基线：
- userscript：
0.4.20 - 协议版本：
0.7.1 - 最低兼容协议版本：
0.6.1
共享 ProtoBuf 协议源位于：
third_party/TeamViewRelay-Protocol/proto/teamviewer/v1/teamviewer.proto
本地 TS 协议代码生成命令：
pnpm proto:generate子模块与协议版本：
- 推荐使用
git clone --recursive - 已有仓库可执行
git submodule update --init --recursive - 当前依赖锁定在
third_party/TeamViewRelay-Protocol的指定 commit，不会自动跟随远端更新
升级协议版本的常规流程：
git -C third_party/TeamViewRelay-Protocol fetch --tags
git -C third_party/TeamViewRelay-Protocol checkout dfad7c22c106fcc0e689044ee93d5a6ce3821302
git add third_party/TeamViewRelay-Protocol
pnpm proto:generate
pnpm build