TREX v2.1
Waiting for Terraria process...
Please launch Terraria or tModLoader
01 System Prerequisites & Dependencies
Required execution libraries, environments, and development references.
1. Runtime Environments & System Libraries
Visual C++ 2015–2022 Redistributable: The C++ bootstrapper module strictly requires the MSVC runtime (x86 for Vanilla; x64 for tModLoader).
DirectX End-User Runtimes (June 2010): Required for low-level Direct3D font and graphics rendering in XNA / FNA game frameworks.
.NET Framework (Vanilla Terraria): .NET Framework 4.0 ~ 4.8 runtime environment.
.NET Desktop Runtime (tModLoader 1.4.4+): .NET 6.0 / .NET 8.0 Desktop Runtime (x64 architecture).
2. Build & Compilation References
C++ Native Layer (Bootstrapper): Win32 COM interfaces and
<mscoree.h> (ICLRRuntimeHost) for Vanilla; Microsoft CoreCLR headers <nethost.h>, <coreclr_delegates.h>, and hostfxr.dll for tModLoader.C# Managed Layer (TREX.dll):
0Harmony.dll (LibHarmony 2.3+ with CoreCLR / 64-bit support), game assemblies (Terraria.exe or tML references), and Microsoft.Xna.Framework.dll / FNA.dll.External Controller (WinForms):
System.Management for querying WMI to inspect command lines of target processes.02 Injection Lifecycle & Hook Mechanics
Three-tier black-box injection lifecycle: Process Attachment, CLR Hosting, and IL Patching.
STAGE 1 Native Injection via Win32 Remote Thread
The external injector retrieves a valid process handle using
OpenProcess. It allocates memory inside the target virtual address space via VirtualAllocEx and writes the full path of Bootstrapper.dll via WriteProcessMemory. A remote thread is spawned with CreateRemoteThread calling LoadLibraryA, forcing the native C++ DLL into the target game address space.
STAGE 2 CLR Activation & Managed Hosting
Upon entering
• Vanilla: Employs COM interfaces with
• tModLoader: Hooks into the already active CoreCLR instance using
DllMain, the native loader activates the managed payload.• Vanilla: Employs COM interfaces with
ICLRRuntimeHost::ExecuteInDefaultAppDomain to load TREX.dll directly into the default application domain.• tModLoader: Hooks into the already active CoreCLR instance using
hostfxr's load_assembly_and_get_function_pointer to resolve and invoke the managed entrypoint pointer directly.
STAGE 3 Game Logic Hooking via Harmony
The managed entry method (e.g.
Loader.Init) instantiates Harmony to intercept game functions (e.g., Main.DoDraw for UI rendering, Player.ItemCheck for interaction mechanics, and Projectile.Update). Custom GUI overlays, hitboxes, and timing routines are seamlessly bound into the game's internal frame cycles.
03 Vanilla vs. tModLoader Architecture Migration
Key structural differences and the complete 3-step refactoring workflow.
| Specification | Vanilla Terraria | tModLoader (1.4.4+) |
|---|---|---|
| Process Architecture | 32-bit (x86) | 64-bit (x64) |
| Target Executable | Terraria.exe |
dotnet.exe (or tModLoader.exe) |
| Target .NET Runtime | .NET Framework 4.0 / 4.8 | .NET 6.0 / .NET 8.0 (CoreCLR) |
| C++ Bootstrapper API | ICLRRuntimeHost (mscoree.dll) |
nethost / hostfxr |
STEP 1 Refactoring the Managed Core (TREX.csproj)
• Target Framework: Update
• Update Harmony: Upgrade to LibHarmony 2.3+ for full CoreCLR 64-bit support.
• Unmanaged Calling Convention: Decorate the entrypoint method with
• API Migration: Replace deprecated 1.4.4+ game fields (e.g.
<TargetFramework> from net48 to net6.0-windows (or netstandard2.0).• Update Harmony: Upgrade to LibHarmony 2.3+ for full CoreCLR 64-bit support.
• Unmanaged Calling Convention: Decorate the entrypoint method with
[UnmanagedCallersOnly] to allow the 64-bit native loader to execute the function directly without wrapper delegates.• API Migration: Replace deprecated 1.4.4+ game fields (e.g.
Main.fontItemStack) with modernized tModLoader asset accessors (e.g. FontAssets.MouseText.Value).
STEP 2 Rebuilding the Native Bootstrapper (Bootstrapper.dll)
• Platform Architecture: Switch the Visual Studio build configuration from
• Modernize CLR Activation: Remove legacy
Release | Win32 (x86) to Release | x64.• Modernize CLR Activation: Remove legacy
mscoree.dll COM initializers. Implement Microsoft CoreCLR hostfxr resolution: locate the active CoreCLR module handle, invoke load_assembly_and_get_function_pointer, pass TREX.Loader, TREX type definitions, and call the entrypoint directly.
STEP 3 Updating the External Injector GUI
• Dynamic Process Resolution: Instead of hardcoding
• 64-bit Compilation: Build the WinForms injector in
• Directory Deployment: Ensure the binary runtime directory bundles the x64
• Execution Privileges: Always run the executable as Administrator to ensure sufficient security token permissions to access target memory.
Terraria, query system process command lines via System.Management to identify dotnet.exe instances running tModLoader parameters.• 64-bit Compilation: Build the WinForms injector in
x64 (or Any CPU with Prefer 32-bit disabled) to interact with 64-bit processes cleanly.• Directory Deployment: Ensure the binary runtime directory bundles the x64
Bootstrapper.dll, .NET 6 compiled TREX.dll, and 64-bit 0Harmony.dll.• Execution Privileges: Always run the executable as Administrator to ensure sufficient security token permissions to access target memory.
TREX v2.1-Release
x64 Windows Standalone • Embedded runtime bundle