Panel/docs/architecture/PANEL_AGENT_FLOW.md

Panel Agent Flow

Workspace reference: GSP-WORKSPACE.md

Overview

The Panel does not directly run servers. It prepares the request, sends it to the agent, and interprets the response.

User action
  -> Panel module page
  -> OGPRemoteLibrary in lib_remote.php
  -> XML-RPC request to agent /RPC2
  -> ogp_agent.pl method
  -> local screen/process/port work
  -> return status or payload
  -> Panel renders result

Request Path

Important Panel files:

• Panel/includes/lib_remote.php
• Panel/modules/gamemanager/start_server.php
• Panel/modules/gamemanager/stop_server.php
• Panel/modules/gamemanager/restart_server.php
• Panel/modules/gamemanager/server_monitor.php
• Panel/modules/gamemanager/view_server_log.php
• Panel/modules/gamemanager/get_server_log.php
• Panel/modules/gamemanager/home_handling_functions.php

Start

1. Panel loads the selected server home and game XML.
2. Panel composes startup parameters from stored values and XML templates.
3. Panel calls universal_start on the agent.
4. Agent creates the screen session and starts the server command.
5. Panel polls remote_server_status.
6. When the agent reports that the process/session exists and the game port listens, the server is treated as ONLINE.

Stop

1. Panel calls remote_stop_server.
2. Agent sends the configured graceful stop command if one exists.
3. Agent watches the session/process and required port.
4. If the session/process does not exit in time, the agent escalates to screen quit or process kill.
5. Panel treats the server as stopped only when the agent confirms it is actually gone.

Restart

Restart should be:

stop
  -> wait
  -> start

The wait period should be explicit and visible in logs. Restart should not depend on marker files or query success.

Status

1. Panel calls remote_server_status.
2. Agent checks:
   • managed screen/session
   • PID or process tree when available
   • required game port
   • optional query/RCON ports
3. Agent returns a structured status object.
4. Panel maps the result to the UI state.

Logs

1. Panel calls get_log.
2. Agent returns the latest screen or console log data.
3. The log view updates via AJAX instead of full-page refresh.
4. The UI should preserve scroll position and only auto-scroll when the user is already at the bottom.

Data Returned by Status

Recommended status fields:

• status
• ready
• process_running
• session_running
• game_port_listening
• query_port_listening
• rcon_port_listening
• pid
• session_name
• ip
• port
• query_port
• last_error
• optional query metadata

Practical Notes

• The Panel should not mark a server failed only because query metadata was unavailable.
• The agent should be the source of truth.
• Marker files may exist, but they should be treated as hints only.
• The same high-level flow should work for Linux and Windows/Cygwin.