Add runahead support to GameSession (#45)

* Add runahead support to GameSession

* Rename _runahead_base_frame to _runahead_start_frame

* Fix runahead correctness issues

* Fix local input frame and add runtime delay/runahead controls to online example

* Minimize runahead footprint in existing code

Move running_ahead flag to InputBuffer state via SetRunaheadMode() instead
of threading it through GetCurrentInputs/GetInput parameters. Reset sync
frame immediately inside HandleRunahead so AddLocalInput and network logic
always see the real frame, removing the need for GetSessionFrame().

Author: HeatXD

Examples/OnlineSession/OnlineSession.cpp

@@ -109,6 +109,8 @@ int main(int argc, char* argv[]) {
     gekko_start(session, &config);
     gekko_net_adapter_set(session, gekko_default_adapter(ports[local_players[0]]));
 
+    gekko_set_runahead(session, 8);
+
     int remote_handle = -1;
     for (int i = 0; i < num_players; i++) {
         bool is_local = false;
@@ -121,7 +123,7 @@ int main(int argc, char* argv[]) {
 
         if (is_local) {
             gekko_add_actor(session, GekkoLocalPlayer, nullptr);
-            gekko_set_local_delay(session, i, 1);
+            gekko_set_local_delay(session, i, 10);
         }
         else {
             GekkoNetAddress addr = {};
@@ -137,6 +139,9 @@ int main(int argc, char* argv[]) {
     Gamestate gs = {};
     gs.Init(num_players);
 
+    unsigned char current_delay = 10;
+    unsigned char current_runahead = 8;
+
     bool running = true;
     while (running) {
         frame_start = SDL_GetPerformanceCounter();
@@ -147,6 +152,42 @@ int main(int argc, char* argv[]) {
             if (event.type == SDL_EVENT_QUIT) {
                 running = false;
             }
+            if (event.type == SDL_EVENT_KEY_DOWN) {
+                switch (event.key.key) {
+                case SDLK_F1:
+                    if (current_delay > 0) {
+                        current_delay--;
+                        for (int i = 0; i < num_local_players; i++) {
+                            gekko_set_local_delay(session, local_players[i], current_delay);
+                        }
+                        printf("delay: %d\n", current_delay);
+                    }
+                    break;
+                case SDLK_F2:
+                    if (current_delay < 15) {
+                        current_delay++;
+                        for (int i = 0; i < num_local_players; i++) {
+                            gekko_set_local_delay(session, local_players[i], current_delay);
+                        }
+                        printf("delay: %d\n", current_delay);
+                    }
+                    break;
+                case SDLK_F3:
+                    if (current_runahead > 0) {
+                        current_runahead--;
+                        gekko_set_runahead(session, current_runahead);
+                        printf("runahead: %d\n", current_runahead);
+                    }
+                    break;
+                case SDLK_F4:
+                    if (current_runahead < 15) {
+                        current_runahead++;
+                        gekko_set_runahead(session, current_runahead);
+                        printf("runahead: %d\n", current_runahead);
+                    }
+                    break;
+                }
+            }
         }
 
         auto local_input = gs.PollInput();
@@ -222,9 +263,10 @@ int main(int argc, char* argv[]) {
             gekko_network_stats(session, remote_handle, &netstats);
             char title[256];
             snprintf(title, sizeof(title),
-                "Pong | P: %ums PA: %.1fms J: %.1fms | S: %.2f R: %.2f KB/s | FA: %.2f",
+                "Pong | P: %ums PA: %.1fms J: %.1fms | S: %.2f R: %.2f KB/s | FA: %.2f | D: %d RA: %d",
                 netstats.last_ping, netstats.avg_ping, netstats.jitter,
-                netstats.kb_sent, netstats.kb_received, frames_ahead);
+                netstats.kb_sent, netstats.kb_received, frames_ahead,
+                current_delay, current_runahead);
             SDL_SetWindowTitle(window, title);
         }
 

GekkoLib/include/event.h

@@ -35,12 +35,16 @@ namespace Gekko {
     public:
         void Init(u32 input_size);
 
-        bool AddAdvanceEvent(SyncSystem& sync, bool rolling_back);
+        bool AddAdvanceEvent(SyncSystem& sync, bool rolling_back, bool running_ahead = false);
 
         void AddSaveEvent(SyncSystem& sync, StateStorage& storage, Frame* last_saved_frame = nullptr);
 
         void AddLoadEvent(SyncSystem& sync, StateStorage& storage);
 
+        void AddRunaheadSaveEvent(SyncSystem& sync, StateStorage& storage);
+
+        void AddRunaheadLoadEvent(StateStorage& storage);
+
         std::vector<GekkoGameEvent*>& GetEvents();
 
         void Reset();

GekkoLib/include/gekkonet.h

@@ -118,6 +118,7 @@ typedef struct GekkoGameEvent {
             unsigned int input_len;
             unsigned char* inputs;
             bool rolling_back;
+            bool running_ahead;
         } adv;
         struct GekkoSave {
             int frame;
@@ -189,6 +190,8 @@ GEKKONET_API int gekko_add_actor(GekkoSession* session, GekkoPlayerType player_t
 
 GEKKONET_API void gekko_set_local_delay(GekkoSession* session, int player, unsigned char delay);
 
+GEKKONET_API void gekko_set_runahead(GekkoSession* session, unsigned char runahead);
+
 GEKKONET_API void gekko_add_local_input(GekkoSession* session, int player, void* input);
 
 GEKKONET_API GekkoGameEvent** gekko_update_session(GekkoSession* session, int* count);

GekkoLib/include/input.h

@@ -48,6 +48,8 @@ namespace Gekko {
 
 		std::unique_ptr<GameInput> GetInput(Frame frame, bool prediction = false);
 
+		void SetRunaheadMode(bool running_ahead);
+
 		Frame GetLastReceivedFrame();
 
         void ClearIncorrectFrames(Frame clear_limit);
@@ -62,6 +64,8 @@ namespace Gekko {
 		bool CanPredictInput();
 
 	private:
+		bool _running_ahead;
+
 		u8 _input_delay;
 
 		u8 _input_prediction_window;

GekkoLib/include/session.h

@@ -15,6 +15,7 @@
 struct GekkoSession {
     virtual void Init(GekkoConfig* config) = 0;
     virtual void SetLocalDelay(i32 player, u8 delay) = 0;
+    virtual void SetRunahead(u8 runahead) = 0;
     virtual void SetNetAdapter(GekkoNetAdapter* adapter) = 0;
     virtual i32 AddActor(GekkoPlayerType type, GekkoNetAddress* addr) = 0;
     virtual void AddLocalInput(i32 player, void* input) = 0;
@@ -36,6 +37,8 @@ namespace Gekko {
 
         void SetLocalDelay(i32 player, u8 delay) override;
 
+        void SetRunahead(u8 runahead) override;
+
         void SetNetAdapter(GekkoNetAdapter* adapter) override;
 
         i32 AddActor(GekkoPlayerType type, GekkoNetAddress* addr) override;
@@ -75,6 +78,10 @@ namespace Gekko {
 
 		void HandleSavingConfirmedFrame();
 
+		void HandleRunahead();
+
+		void RewindRunahead();
+
         void SendSessionHealthCheck();
 
         void SendNetworkHealthCheck();
@@ -88,6 +95,10 @@ namespace Gekko {
 
         Frame _last_sent_healthcheck;
 
+		Frame _runahead_start_frame;
+
+		u8 _runahead_frames;
+
 		std::unique_ptr<u8[]> _disconnected_input;
 
 		GekkoConfig _config;
@@ -111,6 +122,8 @@ namespace Gekko {
 
         void SetLocalDelay(i32 player, u8 delay) override;
 
+        void SetRunahead(u8 runahead) override {}
+
         void SetNetAdapter(GekkoNetAdapter* adapter) override;
 
         i32 AddActor(GekkoPlayerType type, GekkoNetAddress* addr) override;
@@ -162,6 +175,8 @@ namespace Gekko {
 
         void SetLocalDelay(i32 player, u8 delay) override;
 
+        void SetRunahead(u8 runahead) override {}
+
         void SetNetAdapter(GekkoNetAdapter* adapter) override;
 
         i32 AddActor(GekkoPlayerType type, GekkoNetAddress* addr) override;

GekkoLib/include/storage.h

@@ -22,9 +22,13 @@ namespace Gekko {
 
 		StateEntry* GetState(Frame frame);
 
+		StateEntry* GetRunaheadState();
+
 	private:
 		u32 _max_num_states;
 
 		std::vector<std::unique_ptr<StateEntry>> _states;
+
+		StateEntry _runahead_state;
 	};
 }

GekkoLib/include/sync.h

@@ -21,6 +21,8 @@ namespace Gekko {
 
 		bool GetCurrentInputs(std::unique_ptr<u8[]>& inputs, Frame& frame);
 
+		void SetRunaheadMode(bool running_ahead);
+
 		bool GetSpectatorInputs(std::unique_ptr<u8[]>& inputs, Frame frame);
 
 		bool GetLocalInput(Handle player, std::unique_ptr<u8[]>& input, Frame frame);
@@ -31,7 +33,7 @@ namespace Gekko {
 
 		void SetInputPredictionWindow(Handle player, u8 input_window);
 
-		Frame GetCurrentFrame();
+		Frame GetCurrentFrame() const;
 
 		void SetCurrentFrame(Frame frame);
 

GekkoLib/src/event.cpp

@@ -171,7 +171,7 @@ void Gekko::GameEventSystem::Init(u32 input_size) {
     _current_events.clear();
 }
 
-bool Gekko::GameEventSystem::AddAdvanceEvent(SyncSystem& sync, bool rolling_back)
+bool Gekko::GameEventSystem::AddAdvanceEvent(SyncSystem& sync, bool rolling_back, bool running_ahead)
 {
     Frame frame = GameInput::NULL_FRAME;
     std::unique_ptr<u8[]> inputs;
@@ -186,6 +186,7 @@ bool Gekko::GameEventSystem::AddAdvanceEvent(SyncSystem& sync, bool rolling_back
     event->type = GekkoAdvanceEvent;
     event->data.adv.frame = frame;
     event->data.adv.rolling_back = rolling_back;
+    event->data.adv.running_ahead = running_ahead;
 
     if (event->data.adv.inputs) {
         std::memcpy(event->data.adv.inputs, inputs.get(), event->data.adv.input_len);
@@ -199,7 +200,6 @@ void Gekko::GameEventSystem::AddSaveEvent(SyncSystem& sync, StateStorage& storag
     const Frame frame_to_save = sync.GetCurrentFrame();
 
     auto state = storage.GetState(frame_to_save);
-
     state->frame = frame_to_save;
 
     _current_events.push_back(_event_buffer.GetEvent(false));
@@ -233,6 +233,38 @@ void Gekko::GameEventSystem::AddLoadEvent(SyncSystem& sync, StateStorage& storag
     event->data.load.state_len = state->state_len;
 }
 
+void Gekko::GameEventSystem::AddRunaheadSaveEvent(SyncSystem& sync, StateStorage& storage)
+{
+    const Frame frame_to_save = sync.GetCurrentFrame();
+
+    auto state = storage.GetRunaheadState();
+    state->frame = frame_to_save;
+
+    _current_events.push_back(_event_buffer.GetEvent(false));
+
+    auto event = _current_events.back();
+    event->type = GekkoSaveEvent;
+
+    event->data.save.frame = frame_to_save;
+    event->data.save.state = state->state.get();
+    event->data.save.checksum = &state->checksum;
+    event->data.save.state_len = &state->state_len;
+}
+
+void Gekko::GameEventSystem::AddRunaheadLoadEvent(StateStorage& storage)
+{
+    auto state = storage.GetRunaheadState();
+
+    _current_events.push_back(_event_buffer.GetEvent(false));
+
+    auto event = _current_events.back();
+    event->type = GekkoLoadEvent;
+
+    event->data.load.frame = state->frame;
+    event->data.load.state = state->state.get();
+    event->data.load.state_len = state->state_len;
+}
+
 std::vector<GekkoGameEvent*>& Gekko::GameEventSystem::GetEvents()
 {
     return _current_events;

GekkoLib/src/game_session.cpp

@@ -9,6 +9,8 @@ Gekko::GameSession::GameSession()
     _last_saved_frame = GameInput::NULL_FRAME - 1;
 	_disconnected_input = nullptr;
     _last_sent_healthcheck = GameInput::NULL_FRAME;
+    _runahead_start_frame = GameInput::NULL_FRAME;
+    _runahead_frames = 0;
     _config = GekkoConfig();
 }
 
@@ -41,6 +43,11 @@ void Gekko::GameSession::Init(GekkoConfig* config)
     _config.desync_detection = _config.limited_saving ? false : _config.desync_detection;
 }
 
+void Gekko::GameSession::SetRunahead(u8 runahead)
+{
+    _runahead_frames = runahead;
+}
+
 void Gekko::GameSession::SetLocalDelay(i32 player, u8 delay)
 {
     for (u32 i = 0; i < _msg.locals.size(); i++) {
@@ -129,6 +136,9 @@ GekkoGameEvent** Gekko::GameSession::UpdateSession(i32* count)
         // add inputs so we can continue the session.
         AddDisconnectedPlayerInputs();
 
+        // rewind any runahead frames from the previous tick
+        RewindRunahead();
+
         // check if we need to rollback
         HandleRollback();
 
@@ -150,6 +160,9 @@ GekkoGameEvent** Gekko::GameSession::UpdateSession(i32* count)
             }
             _sync.IncrementFrame();
         }
+
+        // run ahead if configured
+        HandleRunahead();
     }
 
     *count = _game_events.Count();
@@ -508,3 +521,35 @@ bool Gekko::GameSession::IsLockstepActive() const
 {
     return _config.input_prediction_window == 0;
 }
+
+void Gekko::GameSession::RewindRunahead()
+{
+    if (_runahead_start_frame == GameInput::NULL_FRAME) {
+        return;
+    }
+
+    _game_events.AddRunaheadLoadEvent(_storage);
+    _runahead_start_frame = GameInput::NULL_FRAME;
+}
+
+void Gekko::GameSession::HandleRunahead()
+{
+    if (IsLockstepActive() || _runahead_frames == 0) {
+        return;
+    }
+
+    _runahead_start_frame = _sync.GetCurrentFrame();
+    _game_events.AddRunaheadSaveEvent(_sync, _storage);
+
+    _sync.SetRunaheadMode(true);
+    for (u8 i = 0; i < _runahead_frames; i++) {
+        if (!_game_events.AddAdvanceEvent(_sync, false, true)) {
+            break;
+        }
+        _sync.IncrementFrame();
+    }
+    _sync.SetRunaheadMode(false);
+
+    // Reset back to the real frame so AddLocalInput and network logic see the correct frame
+    _sync.SetCurrentFrame(_runahead_start_frame);
+}

GekkoLib/src/gekkonet.cpp

@@ -59,6 +59,11 @@ void gekko_set_local_delay(GekkoSession* session, int player, unsigned char dela
     session->SetLocalDelay(player, delay);
 }
 
+void gekko_set_runahead(GekkoSession* session, unsigned char runahead)
+{
+    session->SetRunahead(runahead);
+}
+
 void gekko_add_local_input(GekkoSession* session, int player, void* input)
 {
     session->AddLocalInput(player, input);