From c7492d3941510179930681e2254ff001c3507d84 Mon Sep 17 00:00:00 2001 From: Felipe Keller Braz Date: Fri, 25 Sep 2026 17:40:37 -0300 Subject: [PATCH 1/2] chore(build): remove submodules and relocate references to workspace - Remove git submodules and .gitmodules from GameClient repository - Relocate references (GameClient, GameServer) to workspace references directory - Update cmake/dx8.cmake to detect workspace ../generalsx-dxvk by default - Update cmake/ngmp.cmake to detect ../references/GameClient for ValveNetworkingSockets - Update instructions, documentation, and worklog diary --- .devin/wiki.json | 8 ++--- .github/instructions/build.instructions.md | 2 +- .../instructions/git-commit.instructions.md | 4 +-- .../platform-linux.instructions.md | 2 +- .../platform-macos.instructions.md | 6 ++-- .gitmodules | 10 ------ AGENTS.md | 4 +-- cmake/dx8.cmake | 13 ++++++-- cmake/ngmp.cmake | 3 ++ docs/WORKLOG/2026-09-DIARY.md | 33 +++++++++++++++++++ references/fbraz3-dxvk | 1 - 11 files changed, 60 insertions(+), 26 deletions(-) delete mode 100644 .gitmodules delete mode 160000 references/fbraz3-dxvk diff --git a/.devin/wiki.json b/.devin/wiki.json index a39695a318a..400ab081b88 100644 --- a/.devin/wiki.json +++ b/.devin/wiki.json @@ -21,7 +21,7 @@ "author": "GeneralsX Team" }, { - "content": "Build system uses CMake with presets defined in CMakePresets.json. Active release targets are 'linux64-deploy' and 'macos-vulkan'. Windows modern support is tracked under 'mingw-w64-i686' (Docker cross-compilation) and issue #29. DXVK source of truth is the fork branch generalsx-macos-v2.6 in references/fbraz3-dxvk. Scripts are structured under scripts/build/, scripts/qa/, scripts/env/, and scripts/tooling/.", + "content": "Build system uses CMake with presets defined in CMakePresets.json. Active release targets are 'linux64-deploy' and 'macos-vulkan'. Windows modern support is tracked under 'mingw-w64-i686' (Docker cross-compilation) and issue #29. DXVK source of truth is the fork branch generalsx-macos-v2.6 in generalsx-dxvk. Scripts are structured under scripts/build/, scripts/qa/, scripts/env/, and scripts/tooling/.", "author": "GeneralsX Team" } ], @@ -33,7 +33,7 @@ }, { "title": "Repository Structure", - "purpose": "Document the top-level directory layout: GeneralsMD/ (Zero Hour, primary), Generals/ (base game, secondary), Core/ (shared engine), cmake/ (modular build scripts), scripts/ (build, QA, tooling), references/ (fbraz3-dxvk, GameClient, GameServer), resources/, flatpak/, assets/, and docs/.", + "purpose": "Document the top-level directory layout: GeneralsMD/ (Zero Hour, primary), Generals/ (base game, secondary), Core/ (shared engine), cmake/ (modular build scripts), scripts/ (build, QA, tooling), references/ (GameClient, GameServer), resources/, flatpak/, assets/, and docs/.", "parent": "Project Overview" }, { @@ -58,7 +58,7 @@ }, { "title": "Rendering & DXVK Integration", - "purpose": "Document the W3D rendering engine and DXVK DirectX 8 to Vulkan translation layer across Linux, macOS (via MoltenVK to Metal), and Windows. Explain the fork source-of-truth policy in references/fbraz3-dxvk (branch generalsx-macos-v2.6) and FetchContent build mechanics.", + "purpose": "Document the W3D rendering engine and DXVK DirectX 8 to Vulkan translation layer across Linux, macOS (via MoltenVK to Metal), and Windows. Explain the fork source-of-truth policy in generalsx-dxvk (branch generalsx-macos-v2.6) and FetchContent build mechanics.", "parent": "Core Engine Architecture" }, { @@ -103,7 +103,7 @@ }, { "title": "Reference Repositories", - "purpose": "Document internal and external reference codebases: local references in references/ (fbraz3-dxvk, GameClient, GameServer) and upstream/historical references (TheSuperHackers upstream baseline, fighter19-dxvk-port for DXVK/SDL3, jmarshall-win64-modern for OpenAL/Win64).", + "purpose": "Document internal and external reference codebases: local references in references/ (GameClient, GameServer) and upstream/historical references (TheSuperHackers upstream baseline, fighter19-dxvk-port for DXVK/SDL3, jmarshall-win64-modern for OpenAL/Win64).", "parent": "Cross-Platform Port Strategy" }, { diff --git a/.github/instructions/build.instructions.md b/.github/instructions/build.instructions.md index 5a7f8001ff0..b74bda8429d 100644 --- a/.github/instructions/build.instructions.md +++ b/.github/instructions/build.instructions.md @@ -37,7 +37,7 @@ cmake --build build/mingw-w64-i686 --target z_generals ## DXVK Source of Truth (macOS) -- DXVK fixes must live in `references/fbraz3-dxvk` and be pushed to the fork branch `generalsx-macos-v2.6`. +- DXVK fixes must live in `generalsx-dxvk` and be pushed to the fork branch `generalsx-macos-v2.6`. - macOS build tracks that branch via CMake FetchContent (`UPDATE_DISCONNECTED FALSE`). - Local mode: `-DSAGE_DXVK_USE_LOCAL_FORK=ON` (disables update/fetch). diff --git a/.github/instructions/git-commit.instructions.md b/.github/instructions/git-commit.instructions.md index ca1ac5e75e8..beef2b6aaaf 100644 --- a/.github/instructions/git-commit.instructions.md +++ b/.github/instructions/git-commit.instructions.md @@ -131,8 +131,8 @@ docs: update macOS build instructions for Vulkan SDK setup - PR title should follow the same format as commit messages - the PR description should provide context and link to related issues - PR targets must be against main branch of `fbraz3/GeneralsX` repo, unless it's a user instruction to do otherwise (e.g., "Merge to `develop` branch" or "Merge to `feature/xyz` branch") -- There is a subproject called `dxvk-macos` located under `references/fbraz3-dxvk` folder, which is a fork of the original DXVK project. Commits related to that subproject should be made in that repository and follow the same commit message standards. -- `fbraz3-dxvk` subproject PRs should target the `generalsx-macos-v2.6` branch of `generalsx-project/dxvk` repository, and follow the same commit message standards. +- The DXVK fork project is located in `generalsx-dxvk` (`generalsx-project/dxvk`), which is a fork of the original DXVK project. Commits related to DXVK should be made in that repository and follow the same commit message standards. +- `generalsx-dxvk` PRs should target the `generalsx-macos-v2.6` branch of `generalsx-project/dxvk` repository, and follow the same commit message standards. --- diff --git a/.github/instructions/platform-linux.instructions.md b/.github/instructions/platform-linux.instructions.md index dbd38bfca2f..c6043307cf2 100644 --- a/.github/instructions/platform-linux.instructions.md +++ b/.github/instructions/platform-linux.instructions.md @@ -34,7 +34,7 @@ mkdir -p logs && gdb -batch -ex "run -win" -ex "bt full" -ex "thread apply all b - **Case-sensitive filesystem**: Include paths must match exact case. Use `scripts/tooling/cpp/maintenance/fixIncludesCase.sh`. - **DXVK requires Vulkan**: `vulkan-tools`, `mesa-vulkan-drivers`, or proprietary GPU drivers. - **SDL3**: fetched via CMake FetchContent — no system package needed. -- **DXVK source policy**: fixes go in `references/fbraz3-dxvk`, never in `build/_deps/...`. +- **DXVK source policy**: fixes go in `generalsx-dxvk`, never in `build/_deps/...`. - **CompatLib**: `GeneralsMD/Code/CompatLib/` provides Win32 API compatibility shims (`windows_compat.h`). - **No native POSIX calls**: use SDL3 abstractions for timers, threads, file I/O. No raw `pthread_*`, `open()`. - **`-logToCon`**: only available in debug builds (`RTS_BUILD_OPTION_DEBUG=ON`). diff --git a/.github/instructions/platform-macos.instructions.md b/.github/instructions/platform-macos.instructions.md index 7678deb8fce..bd765f37c51 100644 --- a/.github/instructions/platform-macos.instructions.md +++ b/.github/instructions/platform-macos.instructions.md @@ -1,5 +1,5 @@ --- -applyTo: 'scripts/build/macos/**,references/fbraz3-dxvk/**' +applyTo: 'scripts/build/macos/**' --- ## macOS Architecture @@ -14,7 +14,7 @@ applyTo: 'scripts/build/macos/**,references/fbraz3-dxvk/**' - DXVK is built via Meson as ExternalProject — must pass `-arch arm64` via `cmake/meson-arm64-native.ini` to avoid Rosetta2 confusion. - DXVK source of truth: fork branch `generalsx-macos-v2.6`; CMake tracks remote by default. -- Local fork mode: `-DSAGE_DXVK_USE_LOCAL_FORK=ON` (disables update/fetch, uses `references/fbraz3-dxvk`). +- Local fork mode: `-DSAGE_DXVK_USE_LOCAL_FORK=ON` (disables update/fetch, uses workspace `../generalsx-dxvk` repository). - Vulkan SDK **must** be from LunarG — provides MoltenVK ICD JSON. Not from Homebrew. - Vulkan SDK path: `~/VulkanSDK//macOS/` — must contain `libvulkan.dylib` and `libMoltenVK.dylib`. @@ -35,4 +35,4 @@ brew install cmake ninja meson - **Rosetta2 + Meson**: always use `cmake/meson-arm64-native.ini` to force `-arch arm64`. - **SDL3**: fetched via CMake FetchContent — no system package needed. - **No Cocoa/Metal calls in game code**: all platform access through SDL3 + DXVK layers. -- **DXVK fixes**: commit/push to `references/fbraz3-dxvk` first; never edit `build/_deps/...`. +- **DXVK fixes**: commit/push to `generalsx-dxvk` repository first; never edit `build/_deps/...`. diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 03a9917c3e6..00000000000 --- a/.gitmodules +++ /dev/null @@ -1,10 +0,0 @@ -[submodule "references/fbraz3-dxvk"] - path = references/fbraz3-dxvk - url = https://github.com/generalsx-project/dxvk.git - branch = generalsx-macos-v2.6 -[submodule "references/GameClient"] - path = references/GameClient - url = https://github.com/GeneralsOnlineDevelopmentTeam/GameClient.git -[submodule "references/GameServer"] - path = references/GameServer - url = https://github.com/generalsx-project/GeneralsOnlineGameServer.git diff --git a/AGENTS.md b/AGENTS.md index bffc2349e6f..6464870ba6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -268,7 +268,7 @@ printf "%s" "$body" | rg '\\n' && echo "HAS_LITERAL_BACKSLASH_N=YES" || echo "HA - `GeneralsMD/`: Zero Hour. - `Generals/`: base game. - `Core/`: shared libraries. -- `references/`: fbraz3-dxvk +- `references/`: workspace reference directory (`../references/` with GameClient, GameServer). - `docs/WORKDIR/`: current work docs. - `docs/HOWTO/`: redirection stubs pointing to the GitHub Wiki (user tutorials, SagePatch config, etc.) - `logs/`: build/run/debug logs. @@ -287,7 +287,7 @@ The `**` at applyTo means all files, you MUST load it everytime. | [.github/instructions/cpp-conventions.instructions.md](.github/instructions/cpp-conventions.instructions.md) | `**/*.{cpp,h,hpp,c}` | Code style, annotations, platform isolation | | [.github/instructions/build.instructions.md](.github/instructions/build.instructions.md) | `cmake/**,CMakeLists.txt,CMakePresets.json` | Build presets, DXVK source of truth | | [.github/instructions/platform-linux.instructions.md](.github/instructions/platform-linux.instructions.md) | `scripts/build/linux/**` | Linux build notes | -| [.github/instructions/platform-macos.instructions.md](.github/instructions/platform-macos.instructions.md) | `scripts/build/macos/**,references/fbraz3-dxvk/**` | macOS/DXVK build notes | +| [.github/instructions/platform-macos.instructions.md](.github/instructions/platform-macos.instructions.md) | `scripts/build/macos/**` | macOS/DXVK build notes | | [.github/instructions/docs.instructions.md](.github/instructions/docs.instructions.md) | `**/*.md` | Documentation structure and workflow | | [.github/instructions/scripts.instructions.md](.github/instructions/scripts.instructions.md) | `scripts/**` | Script organization and naming | | [.github/instructions/ngmp.instructions.md](.github/instructions/ngmp.instructions.md) | `**/GeneralsOnline/**,**/NextGenMP/**` | NGMP cross-platform multiplayer integration guidelines | diff --git a/cmake/dx8.cmake b/cmake/dx8.cmake index 8cd68daccaa..2da5151afc4 100644 --- a/cmake/dx8.cmake +++ b/cmake/dx8.cmake @@ -61,8 +61,17 @@ elseif(APPLE AND SAGE_USE_MOLTENVK) include(ExternalProject) # GeneralsX @build BenderAI 13/03/2026 Add explicit source mode to keep remote branch updates deterministic by default. - set(DXVK_LOCAL_FORK_DIR "${CMAKE_SOURCE_DIR}/references/fbraz3-dxvk") - option(SAGE_DXVK_USE_LOCAL_FORK "Build DXVK from local references/fbraz3-dxvk checkout" OFF) + # GeneralsX @build fbraz 25/09/2026 Default local DXVK fork to workspace generalsx-dxvk repository. + if(NOT DEFINED DXVK_LOCAL_FORK_DIR) + if(EXISTS "${CMAKE_SOURCE_DIR}/../generalsx-dxvk/.git") + set(DXVK_LOCAL_FORK_DIR "${CMAKE_SOURCE_DIR}/../generalsx-dxvk") + elseif(EXISTS "${CMAKE_SOURCE_DIR}/references/fbraz3-dxvk/.git") + set(DXVK_LOCAL_FORK_DIR "${CMAKE_SOURCE_DIR}/references/fbraz3-dxvk") + else() + set(DXVK_LOCAL_FORK_DIR "${CMAKE_SOURCE_DIR}/../generalsx-dxvk") + endif() + endif() + option(SAGE_DXVK_USE_LOCAL_FORK "Build DXVK from local generalsx-dxvk checkout" OFF) if(SAGE_DXVK_USE_LOCAL_FORK AND EXISTS "${DXVK_LOCAL_FORK_DIR}/.git") set(DXVK_SOURCE_DIR "${DXVK_LOCAL_FORK_DIR}") diff --git a/cmake/ngmp.cmake b/cmake/ngmp.cmake index 105d4f2d39e..f3b39aaef9e 100644 --- a/cmake/ngmp.cmake +++ b/cmake/ngmp.cmake @@ -149,6 +149,9 @@ if(SAGE_USE_NGMP) if(EXISTS "${CMAKE_SOURCE_DIR}/GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets/GameNetworkingSockets.lib") set(_VNS_DIR "${CMAKE_SOURCE_DIR}/GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets") set(_VNS_INC "${CMAKE_SOURCE_DIR}/GeneralsMD/Code/GameEngine/Include/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets") + elseif(EXISTS "${CMAKE_SOURCE_DIR}/../references/GameClient/GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets/GameNetworkingSockets.lib") + set(_VNS_DIR "${CMAKE_SOURCE_DIR}/../references/GameClient/GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets") + set(_VNS_INC "${CMAKE_SOURCE_DIR}/../references/GameClient/GeneralsMD/Code/GameEngine/Include/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets") elseif(EXISTS "${CMAKE_SOURCE_DIR}/references/GameClient/GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets/GameNetworkingSockets.lib") set(_VNS_DIR "${CMAKE_SOURCE_DIR}/references/GameClient/GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets") set(_VNS_INC "${CMAKE_SOURCE_DIR}/references/GameClient/GeneralsMD/Code/GameEngine/Include/GameNetwork/GeneralsOnline/Vendor/ValveNetworkingSockets") diff --git a/docs/WORKLOG/2026-09-DIARY.md b/docs/WORKLOG/2026-09-DIARY.md index 12d85a3f5e2..063b23e15d0 100644 --- a/docs/WORKLOG/2026-09-DIARY.md +++ b/docs/WORKLOG/2026-09-DIARY.md @@ -974,3 +974,36 @@ - **Validation**: - Rebuilt Zero Hour (`GeneralsXZH`) with CMake on macOS with 0 errors. - Verified headless startup and INI loading without crashes. + +## 25/09/2026 +### Restore Native ELO Rating Calculation & Leaderboard Updates in GameServer +- **Context**: Investigated why 100% of registered players in production remained with static base rating (`elo_rating = 1000`, `monthly_elo_rating = 1000`, `elo_num_matches = 0`) and empty periodic leaderboards (`leaderboard_daily`, `leaderboard_monthly`, `leaderboard_yearly`), despite completed matches with recorded telemetry in `match_history`. +- **Root Cause Analysis**: + 1. In upstream commit `748abdc025` (*"chore: Move fully to external leaderboards and disable native implementation"*), the native ELO calculation call (`UpdateLeaderboardAndElo`) was removed from `LobbyManager.DeleteLobby` in favor of a proprietary external HTTP microservice (`ExternalLeaderboardsClient.PostMatchResultAsync`). + 2. In self-hosted and independent community deployments where `ExternalLeaderboards:PostUrl` is unconfigured (`null`), matches ended without running any ELO engine, leaving player ratings frozen at 1000. + 3. The native method `UpdateLeaderboardAndElo` only allowed `ELobbyType.QuickMatch`, skipping competitive 1v1 Custom Lobbies (`ELobbyType.CustomGame`) where community matches were played. + 4. In `UpdateCurrentEloAsync`, opposing players with identical outcome (`a.won == b.won`, such as mutual loss) were not guarded against phantom loss attribution. + 5. In `UpdatePeriodEloAndLeaderboardsAsync`, rows in `leaderboard_daily`, `leaderboard_monthly`, and `leaderboard_yearly` were updated via `ExecuteUpdateAsync` without pre-existing entry creation, causing updates to affect 0 rows when tables were empty. +- **Solutions Implemented (`generalsx-server`)**: + 1. Restored the native `Database.MatchHistory.UpdateLeaderboardAndElo(_db, lobby)` call in `LobbyManager.DeleteLobby` immediately following `DetermineLobbyWinnerIfNotPresent`. + 2. Expanded eligibility in `UpdateLeaderboardAndElo` to support both `QuickMatch` and `CustomGame` when `IsTrackingStats == true`, `IsMapOfficial == true`, human player count >= 2, and no unhandled desync. + 3. Guarded `UpdateCurrentEloAsync` with `if (a.won == b.won) continue;` to ensure pairwise points are only exchanged between opposing winner and loser. + 4. Added parameterized `CreateUserEntriesIfNotExists(db, userId, day, month, year)` in `Database.Leaderboards.cs` and invoked it ahead of leaderboard updates to guarantee records exist. + 5. Synchronized calculated monthly ratings to `users.monthly_elo_rating` and active WebSocket session caches. + 6. Made `ExternalLeaderboardsClient` config parsing graceful (`TryGetExternalLeaderboardsConfig`), preventing unconfigured null endpoints from throwing exceptions. +- **Deployment & Historical Backfill**: + - Deployed cleanly to Dev (`192.168.1.120`) and Production (`web04-ctb.braz.cloud`). + - Executed chronological backfill script replaying all 11 past matches through the deterministic ELO engine, successfully updating `users` ratings (`fbraz3` 1114, `Rahaman` 1032, `chaosisfair` 1016, `kenan` 1006, `StringMagic` 994, `timstens` 984, `amir` 968, `brazcloud` 886) and populating daily, monthly, and yearly leaderboards in MariaDB. + +### Remove Submodules and Migrate References to Workspace Directory +- **Context**: Submodules in `references/` (`fbraz3-dxvk`, `GameClient`, `GameServer`) were causing spurious git status noise and maintenance overhead. In the multi-project workspace setup (`GeneralsX.code-workspace`), DXVK is managed in `generalsx-dxvk` and reference repositories are kept directly under the workspace `references/` folder for local inspection without polluting `GameClient` git submodules. +- **Changes**: + 1. De-initialized and removed all submodules from `GameClient` (`fbraz3-dxvk`, `GameClient`, `GameServer`). + 2. Migrated `GameClient` and `GameServer` reference working trees and git databases cleanly to the workspace-level `../references/` directory (`references/GameClient` and `references/GameServer`). + 3. Removed `.gitmodules` from `GameClient` as no submodules remain. + 4. Updated `cmake/dx8.cmake` local fork mode discovery (`SAGE_DXVK_USE_LOCAL_FORK`): it now checks `${CMAKE_SOURCE_DIR}/../generalsx-dxvk/.git` first as default workspace location before falling back to `references/fbraz3-dxvk`. + 5. Updated `cmake/ngmp.cmake` for Windows MSVC prebuilt `ValveNetworkingSockets` lookup to check `${CMAKE_SOURCE_DIR}/../references/GameClient/...`. + 6. Updated all documentation references, architecture guidelines, and instructions in `AGENTS.md`, `.github/instructions/git-commit.instructions.md`, `.github/instructions/build.instructions.md`, `.github/instructions/platform-linux.instructions.md`, `.github/instructions/platform-macos.instructions.md`, and `.devin/wiki.json`. +- **Validation**: + - Verified `git status` in both `../references/GameClient` and `../references/GameServer` are clean standalone repositories. + - Re-configured and built Zero Hour with CMake (`macos-vulkan`) target `GeneralsXZH` with 0 errors. diff --git a/references/fbraz3-dxvk b/references/fbraz3-dxvk deleted file mode 160000 index f66da559fd4..00000000000 --- a/references/fbraz3-dxvk +++ /dev/null @@ -1 +0,0 @@ -Subproject commit f66da559fd48cd55ddfebca38ed0f708c0f76a24 From 9891ae1604d541fc24b130745493f9392fb8da0e Mon Sep 17 00:00:00 2001 From: Felipe Keller Braz Date: Fri, 25 Sep 2026 18:03:32 -0300 Subject: [PATCH 2/2] docs(repo): update workspace reference paths in wiki and instructions --- .devin/wiki.json | 8 ++++---- .github/instructions/ngmp.instructions.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.devin/wiki.json b/.devin/wiki.json index 400ab081b88..309bb886d0b 100644 --- a/.devin/wiki.json +++ b/.devin/wiki.json @@ -9,7 +9,7 @@ "author": "GeneralsX Team" }, { - "content": "Multiplayer strategy: The legacy GameSpy online backend is discontinued and superseded by Next-Gen Multiplayer (NGMP / GeneralsOnline). Singleplayer campaigns, Skirmish (vs AI), and LAN multiplayer must remain fully functional. GameSpy online compatibility is not required and must not block NGMP development. Active client integration lives under GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/ with protocol references in references/GameClient and references/GameServer.", + "content": "Multiplayer strategy: The legacy GameSpy online backend is discontinued and superseded by Next-Gen Multiplayer (NGMP / GeneralsOnline). Singleplayer campaigns, Skirmish (vs AI), and LAN multiplayer must remain fully functional. GameSpy online compatibility is not required and must not block NGMP development. Active client integration lives under GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/ with protocol references in ../references/GameClient and ../references/GameServer.", "author": "GeneralsX Team" }, { @@ -33,7 +33,7 @@ }, { "title": "Repository Structure", - "purpose": "Document the top-level directory layout: GeneralsMD/ (Zero Hour, primary), Generals/ (base game, secondary), Core/ (shared engine), cmake/ (modular build scripts), scripts/ (build, QA, tooling), references/ (GameClient, GameServer), resources/, flatpak/, assets/, and docs/.", + "purpose": "Document the top-level directory layout: GeneralsMD/ (Zero Hour, primary), Generals/ (base game, secondary), Core/ (shared engine), cmake/ (modular build scripts), scripts/ (build, QA, tooling), workspace references (../references/: GameClient, GameServer), resources/, flatpak/, assets/, and docs/.", "parent": "Project Overview" }, { @@ -73,7 +73,7 @@ }, { "title": "Next-Gen Multiplayer (NGMP / GeneralsOnline)", - "purpose": "Document the Next-Gen Multiplayer (NGMP / GeneralsOnline) client integration under GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/. Explain REST API conventions (/env/dev/contract/1/ prefix, Bearer token auth), WebSocket routing via integer msg_id, room registration, P2P network synchronization, and reference implementations (references/GameClient, references/GameServer).", + "purpose": "Document the Next-Gen Multiplayer (NGMP / GeneralsOnline) client integration under GeneralsMD/Code/GameEngine/Source/GameNetwork/GeneralsOnline/. Explain REST API conventions (/env/dev/contract/1/ prefix, Bearer token auth), WebSocket routing via integer msg_id, room registration, P2P network synchronization, and reference implementations (../references/GameClient, ../references/GameServer).", "parent": "Core Engine Architecture" }, { @@ -103,7 +103,7 @@ }, { "title": "Reference Repositories", - "purpose": "Document internal and external reference codebases: local references in references/ (GameClient, GameServer) and upstream/historical references (TheSuperHackers upstream baseline, fighter19-dxvk-port for DXVK/SDL3, jmarshall-win64-modern for OpenAL/Win64).", + "purpose": "Document internal and external reference codebases: workspace references in ../references/ (GameClient, GameServer) and upstream/historical references (TheSuperHackers upstream baseline, fighter19-dxvk-port for DXVK/SDL3, jmarshall-win64-modern for OpenAL/Win64).", "parent": "Cross-Platform Port Strategy" }, { diff --git a/.github/instructions/ngmp.instructions.md b/.github/instructions/ngmp.instructions.md index 81fd357ad23..b2c24b5735b 100644 --- a/.github/instructions/ngmp.instructions.md +++ b/.github/instructions/ngmp.instructions.md @@ -55,9 +55,9 @@ When a piece of legacy UI code is in the critical path for NGMP but also serves - Ensure network packet data serialization handles network byte order (`htons`/`ntohs`, `htonl`/`ntohl`) explicitly to support cross-play between x86_64 Linux and ARM64 macOS. 7. **Reference repositories**: - - There are two reference repositories for NGMP, take a look on these to understand the protocol and implementation details: - 1. `references/GameClient`: The client-side implementation. - 2. `references/GameServer`: The server-side implementation. + - There are two reference repositories for NGMP located at workspace `../references/`, take a look on these to understand the protocol and implementation details: + 1. `../references/GameClient`: The client-side implementation. + 2. `../references/GameServer`: The server-side implementation. 8. **REST API & Routing Conventions (Lessons Learned)**: - **Environment/Contract Prefix**: The C# Kestrel backend strictly requires environment and contract version routing. Do **NOT** use `GetServerRESTEndpoint()` directly to build URLs. Always use `NGMP::GetAPIEndpoint("EndpointName")` (e.g. `NGMP::GetAPIEndpoint("Lobbies")`), which appends the required `/env/dev/contract/1/` prefix automatically.