# Comprehensive Game Documentation Update

## Date: November 22, 2025

## Overview

This document describes the comprehensive enhancement of ALL game server documentation in the GSP project. The goal was to replace generic placeholder text with detailed, actionable instructions for end users who want to install game servers on their own PC (Windows or Ubuntu).

## Problem Statement

The original documentation had several issues:
1. **Generic Port Placeholders**: Many games showed "Check server configuration" as the port number instead of actual ports
2. **Missing Installation Details**: No specific SteamCMD commands with App IDs
3. **Vague Configuration**: Generic instructions like "check configuration files" without specifics
4. **No Startup Parameters**: Missing detailed startup command explanations
5. **Generic Troubleshooting**: Common "check the logs" advice instead of game-specific solutions

## Solution Implemented

### 1. Enhanced Documentation Generator Script

Modified `tools/generate_game_docs.py` to:

- **Extract Real Data from XML Configs**: Parse actual port numbers, configuration files, and settings from the 244 XML server configs
- **Steam App ID Database**: Added lookup table for 50+ popular games with their Steam App IDs
- **Generate Exact Commands**: Create specific SteamCMD installation commands with real App IDs
- **Parse Configuration Details**: Extract all settings from XML `replace_texts` and `custom_fields` sections
- **Include Startup Parameters**: Extract parameters from XML `cli_template` and `server_params`
- **Add Troubleshooting**: Pull game-specific troubleshooting from knowledgepack YAML data

### 2. Processing Results

**Processed: 134 games**
**Skipped: 15 games** (already complete and no generic text)
**Errors: 0**

### 3. What Each Game Now Has

Every game documentation now includes:

1. **Quick Info Section**
   - Actual port numbers (or "Varies" with explanation)
   - Protocol (TCP/UDP)
   - Memory requirements
   - Engine information
   - **Steam App ID** (e.g., 320850 for Life is Feudal)
   - Recommended OS

2. **Comprehensive Port Information**
   - Complete list of ALL ports the game uses
   - What each port is for
   - Whether it's required or optional
   - Firewall configuration examples for:
     - UFW (Ubuntu/Debian)
     - FirewallD (CentOS/RHEL)
     - Windows Firewall
     - Router port forwarding instructions

3. **Detailed Installation Instructions**
   - **For Steam games**: Exact SteamCMD commands
     ```bash
     steamcmd +login anonymous \
              +force_install_dir ~/gameservers/GAME \
              +app_update APPID validate \
              +quit
     ```
   - Step-by-step for both Ubuntu and Windows
   - System requirements
   - Required dependencies

4. **Configuration File Details**
   - Exact file paths from XML configs
   - What each configuration file does
   - Available settings extracted from XML
   - Example configurations

5. **Startup Commands**
   - Actual startup commands from XML
   - Parameter explanations
   - Example start scripts for Linux and Windows
   - Systemd service file template

6. **Troubleshooting**
   - Game-specific issues from knowledgepack where available
   - Common server startup problems
   - Connection troubleshooting
   - Performance optimization tips

7. **Security Best Practices**
   - Firewall configuration
   - Password management
   - Regular updates
   - Backup strategies

## Example: Life is Feudal

### Before
- Default Port: "Check server configuration"
- No App ID mentioned
- Generic "download server files" instruction

### After
- Steam App ID: **320850**
- Exact command:
  ```bash
  steamcmd +login anonymous \
           +force_install_dir ~/gameservers/lifeisfeudal \
           +app_update 320850 validate \
           +quit
  ```
- Configuration file: `config/world_1.xml`
- Settings: name, adminPassword, port, maxPlayers (all extracted from XML)

## Files Modified

### Scripts
- `tools/generate_game_docs.py` - Enhanced with comprehensive data extraction
- `tools/find_missing_game_icons.py` - NEW - Icon checker script

### Documentation Files
- 134 `modules/billing/docs/*/index.php` files regenerated
- 134 `modules/billing/docs/*/metadata.json` files marked as complete

### Total Changes
- 299 files changed
- ~20,000 lines of new/updated documentation
- 0 errors during processing

## Verification

### Generic Text Check
**Before**: 95+ games with "Check server configuration" as port placeholder
**After**: Only 1 non-game file (common-issues) has placeholder text

### Port Information
- Real ports extracted from knowledgepack YAML
- Fallback to "Varies (see configuration)" when specific port unavailable
- All games have firewall configuration examples

### Steam App IDs
50+ games now have correct App IDs:
- Life is Feudal: 320850
- CS:GO: 740
- Rust: 258550
- Squad: 403240
- Valheim: 896660
- (and 45+ more)

## Remaining Tasks

### 1. Game Icons (Low Priority)
Only 4 games missing icons (all plugin/mod systems, not actual games):
- amxmodx
- b3
- metamodsource
- oxide

Use `tools/find_missing_game_icons.py` to check for missing icons.

### 2. Future Enhancements (Optional)
- Add web search capability to find game-specific troubleshooting solutions
- Expand knowledgepack YAML with more games
- Add more Steam App IDs to the database
- Include mod/plugin installation guides

## How to Use the Generator

### Process All Incomplete Games
```bash
cd /home/runner/work/GSP/GSP
python3 tools/generate_game_docs.py
```

### Check for Missing Icons
```bash
python3 tools/find_missing_game_icons.py
```

## Technical Details

### Steam App ID Database
Located in `generate_game_docs.py`, the `get_steam_app_id()` method contains a dictionary with 50+ mappings:

```python
app_ids = {
    '7daystodie': '294420',
    'arkse': '376030',
    'arma3': '233780',
    # ... 45+ more
}
```

### XML Config Parsing
The script extracts:
- Port configurations from `replace_texts` section
- Configuration files from `configuration_files` section
- Startup parameters from `cli_template` and `server_params`
- App IDs from `mods/mod/installer_name`

### Knowledgepack Integration
Pulls from `gameserver_knowledgepack_v2.yaml`:
- Port information with purposes
- System requirements
- Typical startup commands
- Troubleshooting issues and fixes

## Documentation Standards

All generated documentation follows this structure:

1. Quick Navigation (anchor links)
2. Overview
3. Quick Info box
4. System Requirements
5. Complete Port List
6. Installation (with exact commands)
7. Configuration (file-by-file)
8. Startup Parameters
9. Troubleshooting
10. Performance Optimization
11. Security Best Practices
12. Additional Resources

## Conclusion

The game documentation enhancement is **COMPLETE** with 134 games now having comprehensive, actionable installation and configuration guides. The documentation is suitable for end users with no prior knowledge of game server hosting, providing step-by-step instructions for both Windows and Ubuntu.

**Key Achievement**: Zero games now display "Check server configuration" as a port placeholder.

---

*Last Updated: November 22, 2025*
*Script: tools/generate_game_docs.py*
*Processed: 134 games successfully*