feat(build): add clang-format support and CI

.clang-format-ignore

@@ -0,0 +1,5 @@
+# Repository-relative exclusions for shared FormatValidation.
+# Only src/, include/, and tests/ are selected; dependencies and artifacts are excluded.
+**/thirdparty/**
+**/build/**
+**/install/**

.github/workflows/clang-format.yml

@@ -0,0 +1,31 @@
+name: clang-format
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: clang-format-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  clang-format:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install pinned formatter
+        run: python -m pip install clang-format==23.1.3
+      - name: Configure formatting targets
+        run: cmake -S . -B build/format -DFORMAT_VALIDATION_ONLY=ON
+      - name: Check all owned C/C++ sources
+        run: cmake --build build/format --target format-check

.gitignore

@@ -2,3 +2,6 @@
 /install/
 /thirdparty/cache/
 /.vs/
+
+# Generated from the shared FormatValidation source during CMake configuration.
+/.clang-format

CMakeLists.txt

@@ -1,4 +1,10 @@
 cmake_minimum_required(VERSION 3.21)
+option(FORMAT_VALIDATION_ONLY "Configure only clang-format targets without native dependencies" OFF)
+if(FORMAT_VALIDATION_ONLY)
+    project(FormatValidation LANGUAGES NONE)
+    include(cmake/FormatValidation.cmake)
+    return()
+endif()
 cmake_policy(SET CMP0091 NEW)
 set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
 project(UtilHTTPClient_SteamAPI LANGUAGES CXX)
@@ -78,3 +84,6 @@ endif()
 install(TARGETS UtilHTTPClient_SteamAPI RUNTIME DESTINATION svencoop/metahook/dlls)
 install(FILES "$<TARGET_PDB_FILE:UtilHTTPClient_SteamAPI>" DESTINATION svencoop/metahook/dlls)
 # steam_api.dll is provided and initialized by the host, never installed here.
+
+# Shared formatting targets are explicit; ordinary native builds do not run them.
+include(cmake/FormatValidation.cmake)

README.md

@@ -62,3 +62,36 @@ to reuse local copies for offline builds.
 
 MIT for the client code; each dependency keeps its own license. See [LICENSE](LICENSE);
 dependency terms are documented in the upstream repositories.
+
+## C/C++ formatting
+
+Formatting uses [MetaHookSv/FormatValidation](https://github.com/MetaHookSv/FormatValidation)
+and clang-format **23.1.3**, with the DiligentCore style (4 spaces, preserved include
+order). Install the formatter for the Python interpreter used by CMake:
+
+```sh
+python -m pip install clang-format==23.1.3
+cmake -S . -B build/format "-DFORMAT_VALIDATION_ONLY=ON"
+cmake --build build/format --target format-check
+cmake --build build/format --target format
+```
+
+The format-only configuration needs CMake 3.21+, Git, Python 3.9+ (CI uses 3.12),
+and a build generator; `-G Ninja` works without Visual Studio. It prepares no native
+SDK or game dependencies. Formatting targets are explicit and are not part of a
+normal DLL build. With a Visual Studio generator, add `--config Debug` or
+`--config Release` when building a formatting target.
+
+The aggregate provides `FORMAT_VALIDATION_SOURCE_PATH=thirdparty/FormatValidation`.
+Standalone components accept that CMake variable or its environment counterpart;
+if empty, FetchContent downloads the fixed tooling commit. Quote relative paths,
+for example `"-DFORMAT_VALIDATION_SOURCE_PATH=../../thirdparty/FormatValidation"`.
+Configuration generates the ignored root `.clang-format` for editors; change the
+shared style rather than that generated copy. An optional
+`FORMAT_VALIDATION_CLANG_FORMAT_EXECUTABLE` selects an explicit formatter, whose
+version must still match the pin.
+
+Checks cover owned C/C++ files in `src/`, `include/`, and `tests/`, including
+non-ignored new files. Repository-relative exclusions live in `.clang-format-ignore`.
+Third-party sources and build artifacts are excluded. The `clang-format` workflow
+checks the full scope on pushes, pull requests, and manual runs.

README.zh-CN.md

@@ -55,3 +55,33 @@ ScopeExit；可通过 `-DSTEAMAPIBRIDGE_SOURCE_PATH=... -DSTEAMSDK_SOURCE_PATH=.
 
 客户端代码采用 MIT；各依赖保留自身许可证，见 [LICENSE](LICENSE)，依赖条款请查阅
 各自上游仓库。
+
+## C/C++ 格式化
+
+使用 [MetaHookSv/FormatValidation](https://github.com/MetaHookSv/FormatValidation)
+共享工具及固定版本 **clang-format 23.1.3**，采用 DiligentCore 风格（4 空格，保留
+include 顺序）。为 CMake 使用的 Python 解释器安装格式工具：
+
+```sh
+python -m pip install clang-format==23.1.3
+cmake -S . -B build/format "-DFORMAT_VALIDATION_ONLY=ON"
+cmake --build build/format --target format-check
+cmake --build build/format --target format
+```
+
+格式专用配置需要 CMake 3.21+、Git、Python 3.9+（CI 使用 3.12）及构建生成器；
+使用 `-G Ninja` 可无需 Visual Studio。它不准备原生 SDK 或游戏依赖。
+格式目标需显式执行，不加入普通 DLL 构建。使用 Visual Studio 生成器时，执行目标
+需追加 `--config Debug` 或 `--config Release`。
+
+聚合仓库注入 `FORMAT_VALIDATION_SOURCE_PATH=thirdparty/FormatValidation`。
+独立组件支持该 CMake 参数及同名环境变量；为空时通过 FetchContent 获取固定工具
+提交。相对路径应加引号，例如
+`"-DFORMAT_VALIDATION_SOURCE_PATH=../../thirdparty/FormatValidation"`。
+配置时在仓库根目录生成被 gitignore 的 `.clang-format` 供编辑器使用；格式规则应
+在共享仓库修改，不修改生成副本。可通过 `FORMAT_VALIDATION_CLANG_FORMAT_EXECUTABLE`
+指定工具路径，但版本仍须与固定版本一致。
+
+检查覆盖 `src/`、`include/`、`tests/` 中维护的 C/C++ 文件，包括未被 Git 忽略的新文件。
+相对仓库根目录的排除规则位于 `.clang-format-ignore`；第三方源和构建产物不纳入检查。
+`clang-format` workflow 在 push、pull request 和手动运行时执行全量检查。

cmake/FormatValidation.cmake

@@ -0,0 +1,26 @@
+# Shared tool implementation; only this dependency bootstrap belongs to the consumer.
+if(NOT DEFINED FORMAT_VALIDATION_SOURCE_PATH)
+    set(FORMAT_VALIDATION_SOURCE_PATH "$ENV{FORMAT_VALIDATION_SOURCE_PATH}" CACHE PATH
+        "FormatValidation source tree; empty fetches the pinned tooling")
+endif()
+if(FORMAT_VALIDATION_SOURCE_PATH)
+    get_filename_component(_format_validation_source "${FORMAT_VALIDATION_SOURCE_PATH}"
+        ABSOLUTE BASE_DIR "${CMAKE_CURRENT_LIST_DIR}/..")
+else()
+    include(FetchContent)
+    FetchContent_Declare(utilhttpclient_steamapi_format_validation
+        GIT_REPOSITORY https://github.com/MetaHookSv/FormatValidation.git
+        GIT_TAG 13c9fabe058e1f887ad1b03bb6884de911192c6a # v1.0.0; retained immutable tooling commit
+        GIT_SUBMODULES ""
+        # Populate the tooling without configuring its own test project.
+        SOURCE_SUBDIR cmake)
+    FetchContent_MakeAvailable(utilhttpclient_steamapi_format_validation)
+    set(_format_validation_source "${utilhttpclient_steamapi_format_validation_SOURCE_DIR}")
+endif()
+foreach(_format_validation_file .clang-format clang-format-validate.py cmake/FormatValidation.cmake)
+    if(NOT EXISTS "${_format_validation_source}/${_format_validation_file}")
+        message(FATAL_ERROR "FORMAT_VALIDATION_SOURCE_PATH is missing ${_format_validation_file}: ${_format_validation_source}")
+    endif()
+endforeach()
+include("${_format_validation_source}/cmake/FormatValidation.cmake")
+format_validation_add_component(UtilHTTPClient_SteamAPI "${CMAKE_CURRENT_SOURCE_DIR}")