#moonroll

Sans-IO deterministic rollback netcode for MoonBit.

#为什么需要定点数

• 加减乘除、开方、插值全部是整数运算，语义由 MoonBit 的 Int64 保证；
• 不依赖任何浮点库，也就不存在"换个编译器结果就变"的问题。

#接入方式：4 个方法

///|
pub(open) trait Sim {
  fn save(Self) -> Bytes // 编码完整状态
  fn restore(Self, Bytes) -> Unit // 与 save 严格互逆
  fn step(Self, UInt64, UInt64) // 推进一帧，p0 / p1 是双方输入位图
  fn hash(Self) -> UInt64 // 状态哈希，不一致即 desync
}

#快速开始

moon add weopqrst/moonroll

// 1) 实现 Sim（略去 save/restore/hash）
impl @session.Sim for World with fn step(self, p0, p1) {
  self.x = self.x * 31UL + p0 + (p1 << 32)
}

// 2) 每个对等体一个会话，local_id 是本地玩家（0 / 1）
let peer = @session.Session::with_window(world, 0, 128)

// 3) 每帧推进；收到对端输入时自动回滚重放
ignore(peer.advance(my_input))
peer.receive(remote_frame, opponent_input)

// 4) 双方定期比对
if peer.hash() != remote_hash {
  // desync
}

let a = @fixed.Fixed::from_double(1.5)
let b = @fixed.Fixed::from_double(2.25)
let c = a * b

let d = @digest.Digest::new()
d.feed_bytes(b"state")
let checksum = d.finish()

let ring = @input.InputRing::new(64)
ring.set(frame, 0b101UL)

#字节协议

let wire = @protocol.encode(@protocol.Message::Input(
  @protocol.InputFrame::new(42, [0b101UL]),
))
let msg = @protocol.decode(wire)          // Some(Input(...))

// 一条链路每帧只发一个包时，把多个帧塞进同一个包
let batch = @protocol.encode_batch(msgs)
for m in @protocol.decode_batch(batch) { /* ... */ }

#网络模拟器

let net = @sim_net.NetSim::new(
  @sim_net.Link::new(delay, jitter, loss_pct, reorder_pct, seed),
)
net.send(frame, payload)                 // 可能被丢弃
for packet in net.recv(frame) { /* ... */ } // 到达的包，按到达时间排序
net.delivered()  // 已交付包数
net.dropped()    // 丢弃包数
net.in_flight()  // 在途包数

#性能

#包结构

#验证

moon test --target wasm-gc
moon test --target js
moon run cmd/main --target wasm-gc

• 定点数与 Double 对拍误差不超过 4 个 LSB；
• FNV-1a 64 对 "hello" 命中标准向量 0xa430d84680aabd0b；
• 双对等体 3000 帧、2 帧固定延迟：终态哈希与顺序参考实现完全一致；
• 乱序 + 0~3 帧抖动（不丢包）600 帧：终态哈希仍然一致；
• 8 条链路曲线（0 / 50 / 100 / 200 / 300ms、±50ms 抖动、5% 丢包、25% 乱序）× 300 帧， 两端终态哈希都等于顺序参考实现；
• 1000 组随机 (delay, jitter, loss, reorder, seed) fuzz：两端哈希一致；
• 协议 round-trip：1000 组随机输入帧 + 500 组确认 / 校验和帧逐位还原； 所有前缀截断与随机垃圾字节只返回 None，不 panic；
• 模拟器同种子可复现（同发送序列 → 同到达序列），抖动确实产生逆序交付；
• 输入环 / 快照环回绕后只保留窗口内帧，旧帧不会误命中。

#Roadmap

• V0.1 基础层：定点数、状态哈希、输入环（已完成）
• V0.2 回滚会话：预测、确认、快照/恢复、重放（已完成）
• V0.3 字节协议 + 延迟/抖动/丢包/乱序模拟 + fuzz（当前）
• V0.4 接入 moonphys 的 wasm-gc 可视化演示（帧时间线、回滚计数、延迟滑块）
• V1.0 CI 三后端一致性、文档、mooncakes 发布

#明确不做

• 真 UDP/TCP 联机（moonbitlang/async 的 socket 不支持 wasm-gc，浏览器内不可用）
• 服务端权威模式、房间匹配
• 具体引擎绑定（只提供 Sim 接口，接入成本目标 30 行）

#License