Panel/docs/features/STATUS_SYSTEM.md

Status System

Current Goal

The status system should tell the truth about a server's state without depending on stale marker files or query success alone.

Current Direction

The current codebase is moving toward agent-owned structured status.

Important files:

• Panel/includes/lib_remote.php
• Panel/modules/gamemanager/home_handling_functions.php
• Panel/modules/gamemanager/server_monitor.php
• Agent_Linux/ogp_agent.pl
• Agent-Windows/ogp_agent.pl

Recommended State Model

State	Meaning
OFFLINE	No managed session/process and no required port listening.
STARTING	Managed session/process exists but the required port is not ready yet.
ONLINE	Managed session/process exists and the required port is listening.
STOPPING	Stop is in progress and the session/process still exists.
UNRESPONSIVE	The server did not become ready in time or stop did not complete cleanly.
UNKNOWN	The agent cannot be reached or cannot determine state.

What Should Be Checked

The agent should check, in this order:

1. managed session or screen name
2. process or PID tree when available
3. required game port listening
4. optional query/RCON port listening
5. optional query metadata

Known Problems To Remember

• LGSL/GameQ may fail for supported games, blocked ports, or slow startups.
• Marker files can become stale after crashes or power loss.
• A game can be online even if query metadata is temporarily unavailable.
• Some games need long startup windows, so timeouts must be configurable per game.

Planned Improvement Shape

• make the agent the source of truth
• preserve optional query metadata
• use state hints for start/stop transitions
• expose clear messages for STARTING and UNRESPONSIVE
• add precise log excerpts when startup fails