-
-
Notifications
You must be signed in to change notification settings - Fork 36
[upcoming] 2.1 What are modifications
Modifications are plugins that can alter the assembly at either runtime or at patch time, and can be written in various languages.
Patch modifications are small plugins that each can modify parts of the source assembly before it is saved to disk and later used to produce a NuGet package. They can add extra meta data such as IL, Members, C# code via MonoMod patching or by manual use of Mono.Cecil.
OTAPI's NuGet package is primarily built using a collection of patch time modifications that can be found entirely in the OTAPI.Scripts directory.
Runtime modifications are also small plugins that modify the runtime experience of the assembly, but are unable to easily alter the source assembly on disk (outside of MonoMod runtime IL hooks).
These scripts are loaded into the AppDomain when Terraria starts, and can alter the runtime experience by subscribing to ModFramework events, OTAPI patch time-injected callbacks, or Terraria runtime events (generated dynamically from the Terraria assembly, as OTAPI.Runtime.dll).
OTAPI has a few small runtime examples that can be found in the Client Launcher, Server Launcher, or in the Runtime examples.
Supports: Declaratively define meta data, Patch time events, Runtime events
Plugin Directory: /modifications
ModFramework uses the modifications directory to look for .dll plugins to load upon startup of patch and runtime events. Your assembly will then be piped to both ModFramework and MonoMod.
ModFramework will allow your plugin to register a static method decorated with a ModificationAttribute which can be used to hook into ModFramework events.
MonoMod will allow you to declare C# to be merged into the final assembly, or to describe MonoMod patches to rework the Terraria assembly.
See OTAPI C# Library examples here
See ModFramework plugin for CSharp Scripts(Roslyn) here
See ModFramework plugin for JavaScript here
See ModFramework plugin for Lua here
Supports: Declaratively define meta data, Patch time events, One file format
Plugin Directory: /csharp/plugins/toplevel
Top Level Scripts are one file scripts with minimal C# which can be used to hook in to the patch events, and/or even define extra C# members and have them merged into the final assembly.
See OTAPI's patch examples here.
Read more from Microsoft about top level scripts.
Supports: Declaratively define meta data, One file format
Plugin Directory: /csharp/plugins/patches
The patches directory provides a wrapper around MonoMod patches, while only needing to write a single .cs file. They are essentially compiled on load to a C# dll and loaded into MonoMod.
See OTAPI's patch examples here.
Supports: Declaratively define meta data, Patch time events, Runtime events, One file format
Plugin Directory: /csharp/plugins/shims
The shim directory is essentially just a folder based structure, each that can contain one or more files that will be compiled into a single assembly and then loaded as a normal C# dll/assembly through MonoMod.
See OTAPI's shim examples here.
Supports: Runtime events, One file format
Plugin Directory: /csharp/plugins/scripts
Scripts are csharp (.cs) files that are loaded at runtime and can attach to the runtime hooks. These files have hot reload support which can speed up your development.
See OTAPI's Script examples here.
Supports: Defining metadata using Mono.Cecil, Patch time events, Runtime events, One file format, ES6 modules
Plugin Directory: /clearscript
Warning: Runtime & patch api may not be fully completed.
Use javascript for creating patch or runtime modifications. These scripts can import CLR assemblies using the AddHostObject import, and is also able to attach to most .NET events using ClearScript's event connections.
ModFramework.Modules.ClearScript is used to load these modules and is built using Microsoft.ClearScript.
Patch scripts examples
Server runtime example
Client runtime example
Supports: Defining metadata using Mono.Cecil, Patch time events, Runtime events, One file format, ES6 modules
Plugin Directory: /lua
Warning: Runtime & patch api may not be fully completed.
Use .lua files to create a patch or runtime modifications. The ModFramework.Modules.Lua module is built on NLua and is still early on in its development.
Patch scripts examples
Server runtime example
Client runtime example