DOCSEARCHbyAlgolia
Submit Docs

Proton Compatibility Layer

repository·proton_11.0·Indexed 12 days ago

https://github.com/valvesoftware/proton

A compatibility layer based on Wine that allows Windows games to run on Linux via the Steam client. This documentation covers building Proton from source using containerized SDK environments (Docker or Podman), configuring builds for x86_64 and ARM64 architectures, managing ICU DLLs, and tuning runtime behavior using environment variables such as PROTON_LOG and PROTON_USE_WINED3D.

Tokens
8.7K
Snippets
30
Records
49
Agent score
96%

What's inside Proton

  1. What is Proton?

    proton_11.0

    Proton is a tool used with the Steam client that allows Windows-exclusive games to run on Linux using Wine.

    Note: Most users should use the version of Proton provided directly by the Steam Client. The source code is intended for advanced users who wish to modify Proton, such as using a specific version of Wine for a particular game.

  2. Inject minidump files into Windows debugging tools

    proton_11.0

    To debug crashes from games running under Proton (on Steam Desktop or Steam Deck), you can use minidump files. These minidumps are fully reloadable in Microsoft tools like WinDbg or Visual Studio, provided the exact Proton system binaries used during the crash are available to the debugger.

    Important Requirements:

    • Native Code Only: This process applies only to native (non-managed) code. It does not support managed code (e.g., .NET) due to compatibility requirements between .NET and Mono.
    • Version Matching: You must use the exact same Proton system files that were used when the minidump was generated. If the versions do not match, the debugger will emit warnings (e.g., "couldn't match module", "invalid time stamp") and provide inaccurate information.

  3. Requirements for deploying the symbol server

    proton_11.0

    To deploy the symbol server, you must map a directory <TOP> (including all sub-directories) to a specific URI. The deployment environment must satisfy these two requirements:

    1. Binary Serving: All files within the <TOP> directory must be served as binary files.
    2. Case Insensitivity: The mapping of the <TOP> directory must be case-insensitive.

  4. Cherry-picking strategy for upstream commits

    proton_11.0

    When rebasing Proton onto new upstream releases, follow these rules for using the -x flag with git cherry-pick to maintain a clean history and facilitate future rebases:

    1. Use -x when cherry-picking commits that originate from upstream (e.g., Wine). This retains the original commit ID in the log message, allowing you to identify and drop these commits during future rebases because they will have been upstreamed.
    2. Do NOT use -x when picking commits that are not upstreamed (Proton-specific patches).

  5. Understand ICU compilation requirements

    proton_11.0

    The ICU (International Components for Unicode) DLLs used in Proton export C++ symbols. Consequently, building ICU from source requires either MSVC or clang on Windows.

    Because of these specific compiler requirements, ICU is not built as part of the standard Proton build process. Instead, Proton uses pre-built versions redistributed by The Unicode Consortium (specifically version 68.2).

  6. Steam Controller Mapping and XInput behavior

    proton_11.0

    Proton handles controller compatibility by leveraging Steam's mapping features and virtual devices:

    • Steam Controller Mapping: This feature is provided via SDL2. If a game bypasses SDL2, it will not benefit from Steam's controller mapping.
    • Virtual Steam Controllers: To ensure any controller can work with games that only support xinput, Steam presents a virtual Steam Controller. Proton converts this virtual controller into an xinput device.
    • Dual API Presence: When a controller is mapped via Steam, it appears to the game as an xinput device in addition to its real controller identity. Unmapped controllers appear only as their real hardware identity.
    • Direct Support: Modern games (e.g., those using Unity) may support specific controllers like the DualShock 4 directly. Proton avoids presenting every controller through xinput to preserve this direct support and correct in-game button layouts.

  7. How controller APIs are mapped in Proton

    proton_11.0

    Windows games access controllers through five primary APIs, which Proton maps down to Linux kernel interfaces. Understanding this mapping is crucial for debugging why a specific controller might not be recognized by a game.

    Windows Controller APIs

    • rawinput: Provides direct access to gamepad hardware. The application must understand the HID protocol or device-specific protocols (e.g., for Xbox controllers).
    • hid: A layer above rawinput where Windows translates raw HID protocol data into usable inputs like buttons and joysticks.
    • dinput: A legacy API for any type of joystick. On Windows, it is implemented on top of hid. It is often used by modern games to access controllers that other APIs cannot.
    • xinput: The modern API designed specifically for Xbox controllers. On Windows, it is typically implemented on top of rawinput.
    • winmm: A very legacy API (originally for soundcard-connected joysticks). On modern Windows, it is implemented on top of dinput.

    Proton Mapping Architecture

    Proton translates these Windows APIs through winebus.sys to Linux-native interfaces:

    • xinput $\rightarrow$ winebus.sys $\rightarrow$ SDL2 $\rightarrow$ hidraw / input event $\rightarrow$ Hardware
    • winmm $\rightarrow$ dinput $\rightarrow$ hid $\rightarrow$ winebus.sys $\rightarrow$ SDL2 $\rightarrow$ Hardware
    • rawinput $\rightarrow$ winebus.sys $\rightarrow$ hidraw $\rightarrow$ Hardware

    Note that winebus.sys must convert SDL2 events back into usable HID protocol data for the Windows layers.

  9. Build and install Proton using the easy way

    proton_11.0

    The simplest way to build and install Proton is using the top-level Makefile. This assumes you have already cloned the repository, updated submodules, and have a working Docker or Podman setup.

    After the build completes, you may need to restart the Steam client to see the new Proton tool. The name displayed in Steam is determined by the checked-out branch, but you can customize this using the build_name variable.

    # Build and install Proton
make install

  10. Download UmeFont (version 670)

    proton_11.0

    UmeFont is a set of metric-compatible fonts for MS Japanese fonts. You can download version 670 via the following link:

    https://osdn.net/projects/ume-font/downloads/22212/umefont_670.tar.xz/

    The package contains the following font files:

    • ume-tgo4.ttf: Ume Gothic
    • ume-pgo4.ttf: Ume P Gothic
    • ume-ugo4.ttf: Ume UI Gothic
    https://osdn.net/projects/ume-font/downloads/22212/umefont_670.tar.xz/

  11. Obtain debug Proton builds via Steam

    proton_11.0

    To perform live debugging with symbols, you must use a debug build of Proton. You can download these directly through the Steam client:

    1. Locate the Proton version in your Steam Library (e.g., Proton Experimental).
    2. Click the cog icon and select Properties.
    3. Navigate to the Betas tab.
    4. Select debug - unstripped from the dropdown menu.
    5. Steam will download the updated version containing the necessary symbols.

  12. Build and use ARM64 Proton SDK containers

    proton_11.0

    To target the aarch64 architecture, use the BUILD_ARCH variable during the make process. To use the resulting image, point the Proton configuration to the specific ARM64 image path.

    # Build the ARM64 LLVM image
make BUILD_ARCH=aarch64 proton-llvm

# Use the ARM64 image in Proton configuration
$PROTON_SRC/configure.sh --proton-sdk-image=registry.gitlab.steamos.cloud/proton/steamrt4/sdk/arm64:latest