A modular, high-performance runtime modding framework and injection engine for Vanilla Terraria 1.4.5.8 / 1.4.5.7 with zero tModLoader dependency and 100% vanilla disk integrity.
-
Zero tModLoader Dependency & 100% Vanilla Integrity:
- Operates directly on the official release of Vanilla Terraria 1.4.5.8 / 1.4.5.7 (Steam & GOG).
- Original
Terraria.exeremains 100% untouched and unmodified on disk (SHA256 verified). - Clean execution boundary: launch
TerrariaModded.exeto play with mods, orTerraria.exefor pure vanilla gameplay.
-
Harmony Patch Isolation & Conflict Management:
- Centralized patch manager (
IPatchManager) wraps Harmony 2.4.2, tracking every prefix, postfix, and transpiler by mod ID. - Granular runtime unpatching: disabling or unloading a mod cleanly restores the original IL without affecting other active mods.
- Centralized patch manager (
-
Topological Dependency Resolution (Kahn's Algorithm):
- Supports mandatory dependencies (
dependencies), optional dependencies (optionalDependencies), load-ordering (loadBefore,loadAfter), and explicit conflict prevention (incompatibleWith). - Automatically calculates optimal load order and detects circular dependency cycles before mod execution.
- Supports mandatory dependencies (
-
Fault Isolation & Safe Mode Protection:
- If a mod throws an unhandled exception during initialization or loading, the fault is isolated, the mod is marked as
Faulted, and its patches are unapplied without crashing the host game.
- If a mod throws an unhandled exception during initialization or loading, the fault is isolated, the mod is marked as
-
Large Address Aware (4GB Virtual Address Space):
- Launcher is compiled with the PE
IMAGE_FILE_LARGE_ADDRESS_AWARE(0x0020) flag, giving the 32-bit engine the full 4GB virtual address space required to eliminateOutOfMemoryException.
- Launcher is compiled with the PE
-
Early Graphics Initialization Guard:
- Includes built-in engine patches protecting early display mode setup from pre-render
GraphicsDevicerace conditions.
- Includes built-in engine patches protecting early display mode setup from pre-render
| Mod | Capabilities & Mechanics | Documentation |
|---|---|---|
| OreCascade | Instant chain-mining for ores and gemstones using iterative Breadth-First Search (BFS), strict vein isolation, and legitimate vanilla drop preservation. | OreCascade README |
| AutoFishing | Intelligent automated casting, in-engine bite detection (ai[1] < 0), and reel-in execution synchronized with the 60 TPS game loop. |
AutoFishing README |
| FishingLinePlus | Multiple simultaneous functional fishing lines with angular velocity spread physics, dual-layer catch synchronization, and multi-catch mechanics. | FishingLinePlus README |
| TurboExtractinator | Accelerates Extractinator and Chlorophyte Extractinator processing speeds by a configurable multiplier (default 5x) with batch extraction support. | TurboExtractinator README |
| AutoBuff | Automatically consumes buff potions and food from inventory and Void Bag when buff durations expire, ensuring continuous uptime with zero waste. | AutoBuff README |
| AutoOpen | Continuous, rapid automated opening of grab bags, fishing crates, oysters, boss bags, lockboxes, and presents on hold-right-click (Extractinator-style). | AutoOpen README |
| AutoResearch | Automated Journey Mode item sacrifice/research upon inventory entry, preserving 100% of vanilla quantity requirements with zero manual sacrifice clicks. | AutoResearch README |
| PiggyVault | Void Bag-like auto-pickup, direct crafting, quick actions, and info accessory capabilities directly for the Piggy Bank. | PiggyVault README |
| TurboBucket | Instant 60 TPS liquid bucket pouring, continuous flow, and accelerated bottomless bucket operations. | TurboBucket README |
| BossCursor | Real-time directional indicator arrows and boss head icons pointing toward active bosses and mini-bosses with proximity scaling. | BossCursor README |
# Compiles solution (Release|x86), executes all 391 tests, and builds distribution
powershell -ExecutionPolicy Bypass -File "build_dist.ps1"# Copy the compiled distribution package into your Terraria folder:
Copy-Item -Path "dist\*" -Destination "D:\Jogos\Steam\steamapps\common\Terraria" -Recurse -Force- Modded Experience: Launch via
TerrariaModded.exe(or your desktop shortcut). - Pure Vanilla: Launch
Terraria.exedirectly.
Located at TMC/config/core.json:
{
"LogLevel": "Info",
"DiagnosticBannerOnStartup": true
}| Option | Type | Default | Description |
|---|---|---|---|
LogLevel |
string |
"Info" |
Logging verbosity: "Trace", "Debug", "Info", "Warn", "Error", "Fatal". |
DiagnosticBannerOnStartup |
bool |
true |
Displays startup diagnostic banner with active mod counts and versions. |
terraria_mod_core/
├── build_dist.ps1 # Automated build, test runner, and distribution packager
├── LICENSE # MIT License
├── TerrariaModCore.sln # Visual Studio Solution (.NET Framework 4.8 / x86)
├── README.md # Master English Documentation
├── README_pt-BR.md # Master Brazilian Portuguese Documentation
│
├── docs/ # Extended Technical Documentation
│ ├── ARCHITECTURE.md # Technical design, memory layout, and patch isolation
│ ├── MODDING.md # Developer guide for creating TMC plugins
│ ├── COMPATIBILITY.md # Hook matrix and runtime version verification
│ ├── CONFIGURATION.md # Configuration reference for Core and all mods
│ ├── TESTING.md # 391-assertion automated test suite breakdown
│ └── TROUBLESHOOTING.md # Diagnostics for memory, graphics, and runtime errors
│
├── src/
│ ├── TerrariaModCore.API/ # Public Modding API (Contracts, Interfaces, Types)
│ │ ├── IMod.cs # Lifecycle interface (Initialize, Load, Unload)
│ │ ├── IModContext.cs # Mod sandbox context
│ │ ├── IPatchManager.cs # Central Harmony patch registration interface
│ │ ├── IConfigManager.cs # Generic JSON configuration manager
│ │ └── TerrariaModCore.API.csproj
│ │
│ ├── TerrariaModCore/ # Core Host Engine (Runtime Injector & Lifecycle)
│ │ ├── ModEngine.cs # Mod discovery, dependency resolution, and execution
│ │ ├── Patching/ # Harmony patch manager & core compatibility fixes
│ │ ├── Dependencies/ # Kahn's topological sort & cycle detection
│ │ └── TerrariaModCore.csproj
│ │
│ ├── TerrariaModCore.Launcher/ # Modded Bootstrapper (TerrariaModded.exe)
│ │ ├── Program.cs # Dynamic AssemblyResolver & entry point
│ │ ├── App.config # Server GC and 64-bit object allocation settings
│ │ └── TerrariaModCore.Launcher.csproj
│ │
│ └── mods/ # Included Production Plugins
│ ├── OreCascade/ # VeinMiner / Ore Excavator plugin
│ ├── AutoFishing/ # Smart fishing automation plugin
│ ├── FishingLinePlus/ # Multi-line / multi-bobber fishing plugin
│ ├── TurboExtractinator/ # High-speed Extractinator acceleration plugin
│ ├── AutoBuff/ # Automatic buff & potion replenishment plugin
│ ├── AutoOpen/ # Rapid container & grab bag opener plugin
│ ├── AutoResearch/ # Automated Journey Mode research plugin
│ ├── PiggyVault/ # Piggy Bank Void Bag capabilities plugin
│ ├── TurboBucket/ # High-speed liquid bucket pouring plugin
│ └── BossCursor/ # Directional arrow & boss head pointer plugin
│
└── tests/
└── TerrariaModCore.Tests/ # 391-Assertion Automated Test Suite
├── Program.cs # Standalone test runner
├── DependencyResolverTests.cs # Dependency ordering & cycle tests
├── PatchManagerTests.cs # Harmony prefix/postfix/unpatch tests
├── FaultIsolationTests.cs # Crash containment & SafeMode tests
├── ConfigManagerTests.cs # Config serialization & GameVersionChecker tests
├── OreCascadePluginTests.cs # BFS vein-mining & pickaxe power tests
├── AutoFishingPluginTests.cs # Fishing state machine & bite detection tests
├── FishingLinePlusPluginTests.cs # Spread physics & multi-catch tests
├── TurboExtractinatorPluginTests.cs # Speed scaling & batch extraction tests
├── AutoBuffPluginTests.cs # Potion selection & buff replenishment tests
├── AutoOpenPluginTests.cs # Grab bag opening & extractinator-style tests
├── AutoResearchPluginTests.cs # Journey Mode sacrifice & inventory scan tests
├── PiggyVaultPluginTests.cs # Piggy Bank pickup, crafting, and action tests
├── TurboBucketPluginTests.cs # Instant bucket pouring & sponge tests
├── BossCursorPluginTests.cs # Boss detection, proximity, and pointer tests
└── ModCoexistenceTests.cs # 16 multi-mod coexistence scenarios
The repository is guarded by a comprehensive 391-assertion automated test suite:
# Build and execute the standalone test suite directly:
dotnet build tests/TerrariaModCore.Tests/TerrariaModCore.Tests.csproj -c Release -p:Platform="x86"
& "tests/TerrariaModCore.Tests/bin/Release/TerrariaModCore.Tests.exe"- Master Technical Specification: Formal architectural and technical specification.
- Technical Architecture & Design: Runtime injection, memory model, and patch isolation.
- Dependency & Environment Requirements: System prerequisites, .NET toolchains, packages, and mod manifest dependencies.
- Mod Developer Guide: Complete walkthrough for building custom TMC plugins.
- Compatibility & Patch Matrix: Intercepted IL methods and version validation.
- Configuration Reference: Settings and presets for host and all plugins.
- Testing Strategy: 391-assertion automated test breakdown.
- Troubleshooting Guide: Resolution for memory limits, startup issues, and log telemetry.
MIT © th3sull1van