cobbleCOBBLE MESH / ENGINEERING NOTES
让连接，
回到玩家之间。
Cobble Mesh 是圆石的可选联机层：本地身份、签名邀请、节点发现与游戏流桥接。基于 libp2p，把连接细节留给启动器。
目前的游戏入口采用显式中继。直连、AutoNAT 与 DCUtR 已有基础组件，仍在接入和验证。
目录负责相遇，中继承载连接。
目录与游戏流量走两条路径。节点目录提供引导信息；启动器使用已配置的种子，建立经过身份认证的长期连接。目录暂时为空，仍可通过已知种子加入网络。
左右滑动查看全图 ↔
名字方便识别，密钥负责证明。
身份在本地生成并保存。显示名称可以修改；完整 PeerId 与密钥关联，连接和签名验证以它为准。名称后的短后缀便于区分，不是全球唯一用户名。
左右滑动查看全图 ↔
签名证明“这段信息由控制该密钥的一方发出”，不证明真实姓名、唯一自然人或长期信誉。临时身份可以重新创建，因此身份本身不能阻止刷号。切换身份会改变当前会话使用的密钥，原身份与联系人仍可保留。
把一个本地地址，接到朋友的世界。
房主在 Minecraft 内开放局域网，确认端口后创建邀请。朋友接受邀请，启动器建立本地 TCP 入口；Minecraft 只需连接这个本地地址。桥接的目标限定在房主批准的游戏端口。
左右滑动查看全图 ↔
邀请是连接凭据
邀请带身份、用途与有效期。接收端验证证明，再建立对应的游戏连接。不要将邀请发布到不可信的位置。
路径来自实际证据
服务在线、预约中继成功和游戏流已建立是不同阶段。Inspector 记录连接标识、活动流与字节数，而不是仅凭一个直连事件判断游戏路径。
一个房主，一份共同的游戏现场。
当前多人小组以房主为中心，支持房主和两位加入者。每位加入者获得自己的本地桥接地址，连接同一个房主游戏。它是应用层游戏小组，不创建虚拟网卡或整段局域网。
左右滑动查看全图 ↔
复用成熟传输，把接口留在边界内。
Rust / Tokio 负责后台运行，libp2p 提供身份、连接和流管理。TCP 传输使用 Noise 认证与 Yamux 多路复用。协议名称区分身份观察、游戏流与小组流。
| 用途 | 协议 / 域 | 边界 |
|---|---|---|
| Identify | /cobblemesh/identify/1 | 对端身份与连接信息 |
| 游戏流 | /cobblemesh/game-stream/0.1.0 | 邀请约束下的游戏桥接 |
| 小组流 | /cobblemesh/group-stream/0.1.0/{peer} | 按对端区分的小组桥接 |
| 签名域 | cobble-mesh/user-profile/v1 | 公开档案签名的域分隔 |
MeshNetworkSnapshot
原生服务推送状态快照，界面订阅 mesh-network-changed。检测结果和真实会话证据分别保存。
phase · generation · attempt · retry_at services · checks · last_error session_route · session_evidence peer_scope · selected_connection bytes_sent · bytes_received active_streams · completed_streams
插件集成沿用宿主权限边界：以游戏上下文、受限动作和资源句柄暴露真实需要的能力。通用 Mesh 插件 API 仍需随具体消费者完善；当前原生快照不等于已经发布的稳定 SDK。
每一个“在线”，都应该有依据。
开启在线模式后，后台自动连接，不阻塞首页。首轮最多尝试三次，每次 10 秒，重试间隔为 2 秒和 5 秒并加少量抖动。失败后逐步延长后台重试间隔；关闭 Mesh 会取消当前连接与重试。
左右滑动查看全图 ↔
- 已接入本地签名身份、引导目录、长期认证连接、显式中继、游戏桥接、三人小组及 Inspector。
- 继续验证真实 Minecraft 多人小组完整流程、更多网络拓扑与断线恢复。页面中的结构图不是实时服务状态。
- 接入中的能力AutoNAT 外部地址验证、直达观察入口、DCUtR 与正式游戏入口的自动选路。双 NAT 公网打洞仍需要独立环境验证。
- 后续方向围绕实际应用完善 SDK 与节点能力发现。VLAN、群组聊天与评分网络不属于当前交付。