backups/neoLegacy
2
0
Fork 0
mirror of https://github.com/neoStudiosLCE/neoLegacy.git synced 2026-06-09 03:02:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
neoLegacy/COMPILE.md
itsRevela 42a582fb9f feat: add FourKit plugin host with dual server build 
Adds the FourKit .NET 10 plugin host as a second dedicated server
build flavour alongside the existing vanilla server. Both flavours
build from the same source tree, with FourKit gated by the
MINECRAFT_SERVER_FOURKIT_BUILD preprocessor define.

Build layout:

  Minecraft.Server         vanilla, no plugin support, no .NET dep
  Minecraft.Server.FourKit FourKit-enabled, ships with bundled
                           .NET 10 self-contained runtime in runtime/
                           and an empty plugins/ folder

Both produce a Minecraft.Server.exe in their own per-target output
dir. The variant identity lives in the directory name, not the
binary name, so either flavour can be shipped as a drop-in.

Native bridge (Minecraft.Server/FourKit*.{cpp,h}):

* FourKitRuntime: hosts CoreCLR via hostfxr's command-line init API
  (the runtime-config API does not support self-contained components)
* FourKitBridge: ~50 Fire* event entry points, with inline no-op
  stubs for the standalone build so gameplay code can call them
  unconditionally
* FourKitNatives: ~80 native callbacks the managed side invokes
  for player/world/inventory mutations
* FourKitMappers: type and enum mapping helpers

Managed plugin host (Minecraft.Server.FourKit/):

* Bukkit-style API: Player, World, Block, Inventory, Command,
  Listener, EventHandler attribute, ~54 event classes
* PluginLoader with per-plugin AssemblyLoadContext
* FourKitHost as the [UnmanagedCallersOnly] entry point table
* Runtime resolves plugins relative to the host process so they
  always live next to Minecraft.Server.exe regardless of where the
  managed assembly itself is loaded from

Engine hooks (Minecraft.Client/, Minecraft.World/):

* Player lifecycle (PreLogin, Login, Join, Quit, Kick, Move,
  Teleport, Portal, Death) wired into PendingConnection and
  PlayerConnection without disturbing the cipher handshake or
  identity-token security flow
* Inventory open/click/drop hooks across every container menu type
* Block place/break/grow/burn/spread/from-to hooks across the
  full tile family
* Bed enter/leave, sign change, entity damage/death, ender pearl
  teleport hooks

Regression fixes preserved while applying donor diffs:

* ServerPlayer::die() retains the LCE-Revelations hardcore branch
  (setGameMode(ADVENTURE) + banPlayerForHardcoreDeath) in both the
  FourKit and non-FourKit code paths
* ServerLevel::entityAdded() retains the sub-entity ID reassignment
  loop required by the client's handleAddMob offset, fixing Ender
  Dragon and Wither boss multi-part hit detection
* LivingEntity::travel() retains the raw Player* cast and the
  cached frictionTile, both Revelations perf wins that the donor
  silently reverted
* ServerLogger.cpp keeps the file-logging code donor stripped
* PlayerList.cpp end portal transition fix and UIScene_EndPoem
  bounds-check are intact

Build system:

* Top-level CMakeLists.txt adds the Minecraft.Server.FourKit
  subdirectory and pulls in the new shared cmake/ServerTarget.cmake
  helper
* Minecraft.Server/cmake/sources/Common.cmake is now location
  independent (uses CMAKE_CURRENT_LIST_DIR) so the source list
  can be consumed from either server target's CMakeLists.txt
* The seven FourKit*.cpp/h files live in their own
  _MINECRAFT_SERVER_COMMON_SERVER_FOURKIT variable so the
  standalone target omits them
* configure-time .NET 10 SDK check fails fast with a clear
  download link if the SDK is missing
* global.json pins the SDK to 10.0.100 with latestFeature
  rollforward

Sample plugin (samples/HelloPlugin/) demonstrates the loader and
the PlayerJoinEvent listener pattern.

CI:

* nightly.yml builds both server flavours, ships
  LCE-Revelations-Server-Win64.zip and
  LCE-Revelations-Server-Win64-FourKit.zip, attests both, and
  updates release notes for the dual-flavour layout
* pull-request.yml pulls in actions/setup-dotnet so the FourKit
  publish step works in PR validation
* All zip artifacts and the client zip are renamed from
  LCREWindows64 to LCE-Revelations-{Client,Server}-Win64

Documentation:

* COMPILE.md gets a VS 2022 quick start, .NET 10 prereq section,
  server flavours explanation, and a troubleshooting section
* docs/FOURKIT_PORT_RECON.md captures the file-by-file recon that
  drove the port
* docs/FOURKIT_PARITY.md is the canonical reference for which
  events FourKit fires

Docker:

* docker-compose.dedicated-server.yml MC_RUNTIME_DIR default points
  at the vanilla CMake output. The FourKit Docker image is
  intentionally NOT shipped yet because hosting .NET 10 self
  contained inside Wine has not been smoke-tested
2026-04-08 03:02:48 -05:00

6.4 KiB
Raw Blame History

Compile Instructions

Prerequisites

  • Visual Studio 2022 with the Desktop development with C++ workload (this includes the CMake tools, MSVC toolchain, and Windows 10 SDK).
  • .NET 10 SDK, required to build the FourKit plugin host (Minecraft.Server.FourKit).
    • Download: https://dotnet.microsoft.com/download/dotnet/10.0 (pick the x64 SDK installer)
    • The exact SDK version is pinned in global.json at the repo root.
    • CMake will fail configure with a clear error message if .NET 10 is not installed, so you find out immediately rather than partway through a build.
    • The build invokes dotnet publish ... --runtime win-x64 --self-contained true, so the published output bundles a complete .NET 10 runtime alongside the FourKit assembly. End users running the produced server do not need to install .NET themselves.
    • All FourKit runtime files (DLL + .NET runtime + hostfxr.dll) land in a runtime/ subfolder next to Minecraft.Server.exe. An empty plugins/ folder is also created. Both are produced automatically by the build.

Visual Studio 2022 quick start (recommended)

VS 2022 has built-in CMake support, so there is no need to generate a .sln file by hand.

  1. Install the prerequisites above.
  2. Clone the repo.
  3. In Visual Studio: File > Open > Folder... and select the repo root (the folder that contains CMakeLists.txt).
  4. Wait for CMake to configure (~5 seconds on a warm cache, a few minutes on the first run while assets copy).
  5. Pick a build configuration in the dropdown, for example windows64-release.
  6. Build > Build All (or F7). Targets of interest:
    • Minecraft.Client: the game client.
    • Minecraft.Server: the vanilla dedicated server. Standalone C++ binary, no plugin host, no .NET dependency at runtime, smallest distribution.
    • Minecraft.Server.FourKit: the FourKit-enabled dedicated server. Bundles the .NET 10 plugin host alongside the exe (in runtime/) and creates an empty plugins/ folder for end users to drop plugin DLLs into. Building this target also triggers the Minecraft.Server.FourKit.Managed target which publishes the C# project.
  7. Use the debug target dropdown to pick Minecraft.Client.exe or whichever server flavour you want, then F5 to launch.

Server flavours

Both server targets compile from the same source tree and produce a binary literally named Minecraft.Server.exe. The variant identity lives in the build directory:

build/<preset>/Minecraft.Server/Release/
  Minecraft.Server.exe          (vanilla, no plugin support)
  Common/, Windows64/, ...

build/<preset>/Minecraft.Server.FourKit/Release/
  Minecraft.Server.exe          (FourKit-enabled, same exe name on purpose)
  runtime/                      (self-contained .NET 10 + Minecraft.Server.FourKit.dll)
  plugins/                      (empty drop point)
  Common/, Windows64/, ...

The FourKit target gets the MINECRAFT_SERVER_FOURKIT_BUILD preprocessor define. Inside FourKitBridge.h, the real plugin entry points are conditional on that define; the vanilla target sees inline no-op stubs instead, so gameplay code can call FourKitBridge::Fire* unconditionally and produce the right behaviour for each flavour without per-call-site #ifdefs.

Dedicated server debug arguments

  • Default debugger arguments for both Minecraft.Server and Minecraft.Server.FourKit:
    • -port 25565 -bind 0.0.0.0 -name DedicatedServer
  • You can override arguments in:
    • Project Properties > Debugging > Command Arguments
  • Both server targets post-build copy the dedicated-server asset set:
    • Common/Media/MediaWindows64.arc
    • Common/res
    • Windows64/GameHDD

CMake (Windows x64)

Configure (use your VS Community instance explicitly):

Open Developer PowerShell for VS and run:

cmake --preset windows64

Build Debug:

cmake --build --preset windows64-debug --target Minecraft.Client

Build Release:

cmake --build --preset windows64-release --target Minecraft.Client

Build vanilla Dedicated Server (Debug):

cmake --build --preset windows64-debug --target Minecraft.Server

Build vanilla Dedicated Server (Release):

cmake --build --preset windows64-release --target Minecraft.Server

Build FourKit Dedicated Server (Debug):

cmake --build --preset windows64-debug --target Minecraft.Server.FourKit

Build FourKit Dedicated Server (Release):

cmake --build --preset windows64-release --target Minecraft.Server.FourKit

Build everything (client + both server flavours):

cmake --build --preset windows64-release

Run executable:

cd .\build\windows64\Minecraft.Client\Debug
.\Minecraft.Client.exe

Run vanilla dedicated server:

cd .\build\windows64\Minecraft.Server\Debug
.\Minecraft.Server.exe -port 25565 -bind 0.0.0.0 -name DedicatedServer

Run FourKit dedicated server:

cd .\build\windows64\Minecraft.Server.FourKit\Debug
.\Minecraft.Server.exe -port 25565 -bind 0.0.0.0 -name DedicatedServer

Notes:

  • The CMake build is Windows-only and x64-only.
  • Contributors on macOS or Linux need a Windows machine or VM to build the project. Running the game via Wine is separate from having a supported build environment.
  • Post-build asset copy is automatic for Minecraft.Client in CMake (Debug and Release variants).
  • The game relies on relative paths (for example Common\Media\...), so launching from the output directory is required.

Troubleshooting

  • 'vswhere.exe' is not recognized: harmless warning. This appears if you ran vcvars64.bat from a plain command prompt instead of Developer PowerShell for VS. The Visual Studio Installer's vswhere.exe lives at C:\Program Files (x86)\Microsoft Visual Studio\Installer\ and is not on the default PATH. Use the Developer PowerShell shortcut, or open the repo folder directly in VS (which handles the dev env for you).
  • .NET 10 SDK not found at configure time: install the x64 SDK from https://dotnet.microsoft.com/download/dotnet/10.0 and re-run CMake configure (Project > Configure Cache in VS, or cmake --preset windows64 from a shell).
  • Server starts but logs hostfxr_initialize_for_dotnet_command_line failed: the runtime/ folder next to Minecraft.Server.exe is missing or stale. Rebuild the Minecraft.Server.FourKit target (which re-stages runtime/), or do a clean rebuild of Minecraft.Server.