기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Proton의 호환성 문제 해결
<a name="troubleshoot-compatibility-wp-proton"></a>

 이 단계에서는 Amazon GameLift Streams 애플리케이션과 Proton 간의 호환성 문제를 해결할 수 있도록 자체 시스템에 Proton을 설정합니다. Amazon GameLift Streams 서버 없이 시뮬레이션된 환경에서 애플리케이션을 실행하면 애플리케이션 및 런타임 환경과 관련된 문제를 식별하는 데 도움이 될 수 있습니다.

## 사전 조건
<a name="troubleshoot-compatibility-wp-proton-prereq"></a>
+  GPU 드라이버가 설치된 Ubuntu 22.04 LTS. 지침은 [로컬 시스템 설정](troubleshoot-compatibility-setup-local.md) 또는 단원을 참조하십시오[원격 시스템 설정](troubleshoot-compatibility-setup-remote.md).

## Proton 설치
<a name="troubleshoot-compatibility-wp-proton-install"></a>

Ubuntu 22.04 LTS 시스템에 Proton을 설치하려면 다음 스크립트를 사용하여 Proton [ GitHub 리포지토리에서 테스트하려는 Proton](https://github.com/ValveSoftware/Proton/) 버전을 복제, 빌드 및 구성합니다.

1. 다음 코드를 복사하여 Ubuntu 22.04 LTS 시스템의 라는 파일에 붙여 `proton-setup.sh` 넣습니다.

   ```
   #!/bin/bash
   # This is a script to build Proton. The default build is a tag from the 
   # experimental_9.0 branch of Proton, but can be changed as a parameter to this script.
   #
   # Usage: ./proton-setup.sh [optional proton_branch_name {default: experimental-9.0-20241121b}]
   set -e
   
   sudo apt install -y podman make git
   
   # clone proton from github, recurse submodules
   # if no proton git link is supplied, use a default tag from the experimental_8.0 branch
   PROTON_BRANCH=${1:-"experimental-9.0-20241121b"}
   PROTON_BUILD_DIR=protonBuild
   PROTON_DIR=$(pwd)/proton
   if git clone https://github.com/ValveSoftware/Proton.git --recurse-submodules --branch $PROTON_BRANCH proton;
   then
   	echo "Successfully cloned Proton and its submodules."
   else
   	echo "Warning: a proton directory/repository already exists. It is recommended to delete this folder and re-run this script unless it is a valid repository with initialized submodules."
   fi
   
   if [ -d $PROTON_BUILD_DIR ];
   then
   	echo "Error: protonBuild directory already exists. Delete this folder first to create a fresh build of Proton before re-running this script."
   	exit 1
   fi
   mkdir $PROTON_BUILD_DIR
   cd $PROTON_BUILD_DIR
   $PROTON_DIR/configure.sh --enable-ccache --container-engine=podman
   
   # build proton
   echo "Building Proton"
   make
   echo "Done building Proton!"
   
   # prepare proton for execution
   cd dist
   mkdir compatdata
   if [ -e ./dist ]; then
     PROTON_FILES=dist
   elif [ -e ./files ]; then
     PROTON_FILES=files
   fi
   cp version $PROTON_FILES/
   echo "Finished installing proton. Proton binary location: $(pwd)/proton"
   echo "STEAM_COMPAT_DATA_PATH: $(pwd)/compatdata"
   echo "STEAM_COMPAT_CLIENT_INSTALL_PATH: anything"
   ```

1. 이 단계에서는 Proton 설정 스크립트를 실행하여 Proton 및 추가 종속성을 복제하고 설치합니다. 스크립트는 설치하려는 Proton 버전의 태그 또는 브랜치 이름을 인수로 허용합니다. Amazon GameLift Streams가 제공하는 Proton의 사용자 지정 빌드 중 하나를 시뮬레이션하려면 아래 해당 버전에 대한 지침을 사용합니다.
**참고**  
 GitHub에서 복제하는 데 시간이 걸릴 것으로 예상합니다. 다운로드할 수 있는 하위 모듈은 여러 기가바이트입니다.

    터미널에서 스크립트를 실행하고 Proton 버전 `proton-setup.sh` 브랜치를 지정합니다.
   +  **기본 제공 Proton 버전** 
     + Proton 9.0-2(`PROTON-20250516`)의 경우 [experimental-9.0-20241121b](https://github.com/ValveSoftware/Proton/tree/experimental-9.0-20241121b)를 사용합니다.

       ```
       proton-setup.sh experimental-9.0-20241121b
       ```
     + Proton 8.0-5(`PROTON-20241007`)의 경우 [experimental-8.0-20240205](https://github.com/ValveSoftware/Proton/tree/experimental-8.0-20240205)을 사용합니다.

       ```
       proton-setup.sh experimental-8.0-20240205
       ```

       일반적으로 추가 소스 코드는 필요하지 않습니다. 그러나 Electra Media Player(Unreal Engine 플러그인)에 문제가 발생하는 경우 [https://github.com/ValveSoftware/wine/pull/257](https://github.com/ValveSoftware/wine/pull/257) 있는 수정 사항을 사용하는 것이 좋습니다.
**참고**  
 Proton 8.0-2c(`PROTON-20230704`)의 경우 Amazon GameLift Streams는 로컬에서 확장할 수 없는 독점 빌드를 사용합니다.
   +  **권장 사용자 지정 Proton 버전** 

      사용자 지정 Proton 버전의 경우 Proton experimental\$18.0 브랜치를 사용하는 것이 좋습니다.

     ```
     proton-setup.sh experimental_8.0
     ```
   +  **기타 사용자 지정 Proton 버전** 

      다른 Proton 버전의 경우 [Proton 릴리스](https://github.com/ValveSoftware/Proton/releases)에 나열된 정확한 브랜치 또는 태그 이름을 사용합니다.

     ```
     proton-setup.sh branch-or-tag-name
     ```

    설치에 성공하면 터미널의 출력은 다음과 비슷해야 합니다.

   ```
   ...
   Done building Proton!
   Finished preparing proton. Proton binary location: /home/test/protonBuild/dist/proton
   STEAM_COMPAT_DATA_PATH: /home/test/protonBuild/dist/compatdata
   STEAM_COMPAT_CLIENT_INSTALL_PATH: anything
   ```

    다음 단계에서 Proton을 실행해야 하므로 출력에서 다음 변수를 기록해 둡니다.
   + 양성자 바이너리 위치
   + `STEAM_COMPAT_DATA_PATH`
   + `STEAM_COMPAT_CLIENT_INSTALL_PATH`

## Proton에서 애플리케이션 실행
<a name="troubleshoot-compatibility-wp-proton-run"></a>

 다음 단계에서는 애플리케이션 실행 파일이에 있다고 가정합니다`path/myapplication/bin/application.exe`. 이를 애플리케이션의 경로 및 파일 이름으로 바꿉니다.
+ 터미널에서 애플리케이션 실행 파일이 있는 폴더로 이동합니다.

  ```
  cd path/myapplication/bin/application.exe
  ```
+ Proton에서 애플리케이션을 실행합니다. 이전 단계에서 얻은 Proton 바이너리 위치와 환경 변수를 사용합니다.

  ```
  STEAM_COMPAT_DATA_PATH=/home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH=anything /home/test/protonBuild/dist/proton run application.exe
  ```

 이제 애플리케이션이 시작을 시도해야 합니다. 애플리케이션이 로컬에서 시작되지만 Amazon GameLift Streams에서는 시작되지 않는 경우 Amazon GameLift Streams APIs. API 호출 파라미터가 올바른지 확인합니다. 그렇지 않으면 디버깅을 위한 다음 단계를 계속합니다.

## 로그 파일을 통해 애플리케이션 디버깅
<a name="troubleshoot-compatibility-wp-proton-debug-logs"></a>

 애플리케이션에 로컬 Proton 환경에서 실행되는 문제가 있는 경우 출력 로그를 확인합니다. 로그에는 애플리케이션 및 런타임 환경의 출력이 포함됩니다. 애플리케이션이 애플리케이션 측에서 문제를 발견하지 못하는 위치를 추적합니다.

 로그 출력을와 같은 텍스트 파일로 덤프하려면 다음 명령을 `proton.log`사용합니다.

```
STEAM_COMPAT_DATA_PATH=/home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH=anything /home/test/protonBuild/dist/proton run application.exe &>proton.log
```

 또한 Proton은 Wine 플러그인, 구현되지 않은 함수, 누락된 dll 등으로 인한 문제인지 여부를 나타냅니다. 자세한 내용은 [Wine HQ의 Debugging Wine](https://wiki.winehq.org/Wine_Developers_Guide/Debugging_Wine) 가이드를 참조하세요. 애플리케이션 측에서 수정할 수 없는 Proton 또는 Wine 오류가 로그에서 발견되면 AWS 계정 관리자에게 문의하거나 [AWS re:Post](https://repost.aws/tags/TAOU7EpUOuTQSSWmIHCfb2fQ/amazon-gamelift-streams)에 질문을 게시하여 추가 디버깅에 대한 도움을 받으세요.