syntax = "proto3";

// 初始化最新的序列帧 - 这个事件是服务端和客户端双向共享, 也就是 Request-Response 响应方式
// 其实就是从服务端获取的最新序列帧ID, 然后挂载客户端目前已经执行的序列化帧上等待下个帧运行
// 后续需要初始化玩家坐标信息,场景信息也是通过该初始化事件加载; 比如下面声明初始化坐标位置[其实应该定义个 Vec2(x,y) 坐标结构]
message InitFrame{
  int32 frame = 1;
  // 后续初始化内容在以下扩充
  float x = 2;
  float y = 3;
}

// 广播单项 - 玩家引发的发生帧变动
// 核心的 frame 字段是帧序列的编号, 需要确保客户端和服务端对发生帧做同步
// 当网络丢包重传的时候, 就能明确从那一个帧序列开始丢帧从而采用追帧方式让玩家回滚到最新状态
// frame 采用 uint32 最佳, 但无法确认开发语言是否支持 unsigned 特性, 所以采用到达最大值回滚为0重置或者设置int64也可以
// 从性能考虑来说采用 int32 就行, 对于小游戏来说 0 到 2^31-1 足够帧序列做行为序列处理
// 注意: 到达最大帧的时候服务端和客户端都要同步回滚处理才能对齐序列帧编号
message InputFrame{
  string sessionId = 1; // 玩家唯一标识
  int32 frame = 2; // 发生帧
  int32 direction = 3; // 方向
  bool jump = 4; // 是否触发跳跃
}

// 广播事件 - 依据客户端提交的 InputFrame.frame, 服务端响应的后续发生帧列表
message Frames{
  int32 frame = 1; // 发生帧
  repeated InputFrame frames = 2; // 所有玩家输出的帧操作列表
  int64 timestamp = 5 ;// 毫秒级别时间戳
}

var frame = 0  or ? # 本地同步帧号（与服务端对齐）

# 核心帧循环逻辑, 这里就是客户端在拉取最新帧之后初始化具体每次运行周期(15/30/60fps)的定时器
func Update():
    frame += 1
    
    # 收集输入(对应你的移动/跳跃逻辑)
    var direction = Input.get_axis("move_left", "move_right")
    var jump = Input.is_action_just_pressed("jump")
    
    # 封装成 Protobuf 并且网络推送指令等
    var msg = InputFrame{ sessionId: "玩家唯一标识", frame, direction, jump}
    WebSocket.send(100,msg) 
    
# 注意: 服务端和客户端必须采用相同的帧率运行, 具体精度为 15/30/60fps(1000÷15ms,1000÷30ms,1000÷60ms)
# 一般来说15帧(0.03秒)适合大部分轻中度类型游戏, 30帧适合塔防MMORPG类型游戏, 60帧则专业的FPS和格斗竞技类游戏
# 也就是后续不再使用 Godot._process 或者 Unity.Update 更新方法处理玩家输入, 而是利用启动的自定义帧率定时器处理逻辑

private final AtomicInteger frame = new AtomicInteger(0); // 全局帧号, 从0开始且必须原子量保证帧率不会乱序
private final Map<Integer,List<InputFrame>> frames = new ConcurrentHashMap(); // 输入缓存, 按帧号存储玩家输入, 也是必须要保证线程安全性

// 核心帧循环逻辑, 这里就是定时器的具体每次运行周期(15/30/60fps), 服务端和客户端必须保持一致
void Update(){
    long frameTime = System.currentTimeMillis(); // 记录毫秒帧时间戳
    int currentFrame = frame.get(); // 获取当前帧号(递增前的帧号,作为本帧标识)
    
    // 收集本帧所有玩家的输入
    List<InputFrame> inputs = frames.remove(currentFrame);
    if (inputs == null) {
        inputs = new ArrayList<>(); // 若没有输入，用空列表
    }
    
    // 生成Protobuf帧数据并广播给所有客户端 - Frames 消息结构
    BroadcastToAllClients(new Frames{ frame:currentFrame,frames: inputs,timestamp: frameTime});
    
    // 序列帧递增
    frame.incrementAndGet();
}

syntax = "proto3";


// 输入行为, 其他略
message InputFrame{
  string session_id = 1; // 玩家唯一标识
  int32 frame = 2; // 发生帧
  int32 direction = 3; // 方向
  bool jump = 4; // 是否触发跳跃
}

// 注意: 在发起追帧的时候是不能参与帧同步广播的, 也就是无法收到 Frames 消息
// 请求追帧: 客户端→服务端, 包含需要追赶的帧范围
// 比如刚进场景目前客户端 frame = 0, 而服务端目前 frame = 1000, 通过 InitFrame.frame 拉取最新服务帧
// snapshot 则是加速同步些场景初始化状态, 比如道具位置和是否获取|其他所有玩家的血量装备更新等
message CatchFrameRequest{
  string session_id = 1; // 玩家唯一标识
  int32 start = 2; // 起始帧数ID, 如果是刚进入场景则为0
  int32 target = 3; // 目前服务器同步的最新的帧ID
  bool snapshot = 4; // 是否需要同步场景某些状态, 比如NPC和场景破坏程度等
}


// 响应追帧: 服务端→客户端, 返回追帧所需的历史帧数据, 可能会分多包传输
message CatchFrameResponse{
  string session_id = 1; // 玩家唯一标识
  int32 start = 2; // 起始帧数ID, 如果是刚进入场景则为0
  int32 offset = 3; // 目前服务器同步的最新的帧ID, 注意如果数据量过大这里可能是偏移值, 需要比较 InitFrame.frame 最新服务帧
  int32 frame = 4; // 当前的服务帧
  repeated InputFrame frames = 5; // 历史帧数据列表 - 按帧号递增
  CatchFrameSnapshot snapshot = 6; // 最近的状态快照 - 仅在 need_snapshot=true 时返回
  bool last = 7; // 是否为最新的服务帧数据包, 服务端获取 CatchFrameRequest.start 比较序列帧是否为最新
}


// 响应内部的其他快照信息, 玩家和场景的同步状态放置内部
message CatchFrameSnapshot{
  int32 frame = 1; // 快照对应帧
  repeated RoleFrameState roles = 2; // 队友场景内角色状态
}


// 二维坐标
message Vector2{
  float x = 1;
  float y = 2;
}

// 快照场景的状态
message RoleFrameState{
  string session_id = 1; // 角色玩家唯一标识
  Vector2 position = 2; // 坐标位置
}


// 请求完成: 客户端→服务端, 已经追帧完成可以参与 Frames 广播消息的接收
message CatchupCompleted{
  string session_id = 1; // 玩家唯一标识
  int32 frame = 2; // 目前同步的客户端本地帧
  bool success = 3; // 是否追帧完成, 如果不成功就继续从 frame 该帧追起
}

// 响应微调: 服务端→客户端, 服务端按照追帧数过程当中动态调整的策略
// 当追帧命令过多, CPU/GPU 负载过高导致帧率暴跌可以动态调整追帧频率
// 设置与有的游戏核心业务是在客户端做碰撞运算体积的时候, 也是需要返回开启本地碰撞计算
// 并且还可以动态纠正客户端异常追帧的问题, 比如提交的 frame 帧明显对不上的时候就需要重新校正
message CatchFrameCommand{
  enum CommandType {
    CONTINUE = 0;  // 继续追帧
    ABORT = 1;     // 中断追帧, 重新同步(包括检测到作弊就直接退出游戏)
    SLOW_DOWN = 2; // 减慢追帧速度(避免客户端过载)
    RESET_FRAME = 3; // 重置最新服务帧
  }
  CommandType type = 1;
  string reason = 2;  // 命令原因, 用于返回该指令说明
}

package io.fortress.quarkus.protobuf;

import io.fortress.quarkus.protobuf.message.Game;
import org.apache.pekko.actor.*;
import org.apache.pekko.event.LoggingAdapter;

import java.time.Duration;
import java.util.*;

/**
 * 多人游戏场景, 优先遵循 Actor 模型原则, 所以内部是不需要锁对象和原子量处理
 *
 */
public class ProtobufFrameScene extends AbstractActor {


    /**
     * 对外的场景容器对象, 用于全局容器化
     */
    public static class ProtobufFrameSceneWrapper {

        final ActorRef actorRef;

        public ProtobufFrameSceneWrapper(ActorRef actorRef) {
            this.actorRef = actorRef;
        }
    }

    /**
     * 坐标地址
     *
     * @param x
     * @param y
     */
    public record Vec2(int x, int y) {
    }

    /**
     * 服务器的核心定时延迟
     */
    public enum Fps {
        Fps15(1000 / 15),
        FPS30(1000 / 30),
        FPS60(1000 / 60),
        ;

        /**
         * 毫秒
         */
        final int value;

        Fps(int value) {
            this.value = value;
        }
    }

    /**
     * 帧更新
     */
    public interface FixedUpdate {
    }

    /**
     * 日志对象
     */
    final LoggingAdapter log = context().system().log();

    /**
     * Actor 核心定时器
     */
    final Scheduler scheduler = context().system().scheduler();

    /**
     * 帧指令列表, 可以考虑采用更高性能的容器工具, 因为帧同步属于高频会做读写处理的功能
     */
    final Map<Integer, List<Game.InputFrame>> frames = new LinkedHashMap<>();

    /**
     * 加入场景的所有玩家, Key = 玩家唯一标识(可以考虑换成Long之类), Value = Actor 地址
     */
    final Map<String, ActorRef> actors = new LinkedHashMap<>();

    /**
     * 服务端定时器帧率
     */
    final Fps fps;


    /**
     * 帧率定时器
     */
    final Cancellable timer;


    /**
     * 当前的服务帧
     */
    int frame = 0;


    /**
     * 角色坐标列表快照
     */
    final Map<ActorRef, Vec2> positions = new HashMap<>();


    /**
     * 构造方法
     *
     * @param fps 帧率配置
     */
    public ProtobufFrameScene(Fps fps) {
        this.fps = fps;
        this.timer = scheduler.scheduleAtFixedRate(
                Duration.ofMillis(fps.value),
                Duration.ofMillis(fps.value),
                getSelf(),
                new FixedUpdate() {
                    //ignore
                },
                context().dispatcher(),
                ActorRef.noSender()
        );
    }


    /**
     * Actor 关闭回调
     */
    @Override
    public void postStop() {
        if (Objects.nonNull(this.timer)) this.timer.cancel();
    }

    /**
     * 事件绑定
     *
     * @return Receive
     */
    @Override
    public Receive createReceive() {
        return receiveBuilder()
                .match(Game.JoinScene.class, (e) -> !actors.containsKey(e.getSessionId()), (event) -> {
                    actors.put(event.getSessionId(), getSender());
                    positions.put(getSender(), new Vec2(1, 1));// 初始化坐标地址

                    // 广播玩家加入场景
                    actors.forEach((key, value) -> value.tell(event, getSelf()));
                })
                .match(Game.LeaveScene.class, (e) -> {
                    actors.remove(e.getSessionId());

                    // 广播玩家离开场景
                    actors.forEach((key, value) -> value.tell(e, getSelf()));
                })
                .match(Game.InitFrame.class, (e) -> {
                    ActorRef sender = getSender();
                    Vec2 vec2 = positions.get(sender);

                    // 打包返回的初始化事件
                    var message = Game
                            .InitFrame
                            .newBuilder()
                            .setFrame(frame)
                            .setX(Objects.isNull(vec2) ? 0 : vec2.x)
                            .setY(Objects.isNull(vec2) ? 0 : vec2.y)
                            .build();
                    getSender().tell(message, getSelf());
                })
                .match(Game.InputFrame.class, this::onInputFrame)
                .match(FixedUpdate.class, this::onFixedUpdate)
                .build();
    }

    /**
     * 帧更新方法
     */
    private void onFixedUpdate(FixedUpdate ignore) {
        long frameTime = System.currentTimeMillis(); // 记录毫秒帧时间戳

        // 收集本帧所有玩家的输入
        List<Game.InputFrame> inputs = frames.remove(frame);
        if (Objects.isNull(inputs)) {
            // 若没有输入，用空列表
            inputs = Collections.emptyList();
        }

        // 按照不同业务类型这里采用不同处理方式:
        // - 主流帧同步: 服务端不运行客户端业务逻辑, 仅负责输入转发和帧号管理, 依赖客户端逻辑的确定性保证状态一致
        // - 增强型帧同步: 服务端选择性运行核心逻辑(如防作弊校验、全局事件), 客户端仍运行完整逻辑, 通过双重计算确保安全性
        // 这里更新玩家的坐标信息, 这部分其实更需要抽离单独的同步方法调用, 因为实际上游戏逻辑并不仅仅要处理位置信息, 还有体积碰撞等
        for (Game.InputFrame input : inputs) {
            ActorRef actor = actors.get(input.getSessionId());
            if (Objects.nonNull(actor)) {

                // 更新角色坐标, 用来校正玩家是否到达地图最大尺寸
                Vec2 pos = positions.get(actor);
                Vec2 newPos = new Vec2(pos.x + input.getDirection(), pos.y);
                positions.put(actor, newPos);
            }
        }


        // 有参与的 Actor 才需要构建发送, 生成 Protobuf 广播给所有人
        if (!actors.isEmpty()) {
            var builder = Game
                    .Frames
                    .newBuilder()
                    .setFrame(frame)
                    .setTimestamp(frameTime);
            for (Game.InputFrame input : inputs) {
                builder.addFrames(input);
            }
            var message = builder.build();
            for (ActorRef actor : actors.values()) {
                actor.tell(message, getSelf());
            }
        }


        // 序列帧递增
        frame = frame + 1;

        // 值回滚成0
        if (frame == Integer.MAX_VALUE) frame = 0;
    }

    /**
     * 追加当前帧数行为
     *
     * @param f 玩家提交的帧
     */
    private void onInputFrame(Game.InputFrame f) {
        int value = f.getFrame(); // 获取客户端提交的序列帧
        if (value == frame || value == (frame + 1)) {
            // 需要判断游戏的逻辑是否成立
            var opt = onLogicUpdate(f);
            if (opt.isEmpty()) {
                log.warning("Validated logical update for frame " + f.getFrame());
            } else {
                // 允许当前帧或者下一帧的指令通过, 写入目前的等待定期发送的更新方法
                frames.computeIfAbsent(value, k -> new ArrayList<>()).add(f);
            }
        } else {
            log.warning("Invalid frame value: {}, session: {}", value, f.getSessionId());
        }
    }

    /**
     * 游戏输入逻辑判断
     *
     * @param f 玩家提交的帧
     * @return 逻辑返回的 Optional
     */
    private Optional<Game.InputFrame> onLogicUpdate(Game.InputFrame f) {

        // 移动方向是否合法(-1, 0, 1)
        var direction = f.getDirection();
        if (direction < -1 || direction > 1) {
            f.toBuilder().setDirection(0).build(); // 修正为静止
        }

        // 可能需要在这里判断是否允许到达地图最大位置

        return Optional.of(f);
    }

}