HOWTO create a new mod
This text assumes some knowledge about C# or other .NET languages. If you don't know any of those, learn it first. This will make everything easier both for you and for the person you'll be asking dumb questions to.
And no, no complete source files will be listed here. We don't want to spoon-feed you, because you're supposed to learn! (And besides, the 'example mod' exists.)
You will notice that the Prism API is highly "symmetrical", i.e. it's structured (more or less) the same for every type of Item/NPC/Tile/BGM/... This is done on purpose, as this makes it easier to use it: if you know one part of the API, you know all parts. The Item, NPC, ... classes from Terraria are 'hidden' to remove some internal clutter. Mods should use ItemDef etc. to definie entities. (The 'raw' classes are still used in behaviours, though).
Every 'object definition' has the following things associated to it:
- An internal name. This should be unique per mod, and it is automatically namespaced under the mod.
- A
TDef, an object definition. This object contains the stats etc. of the object. - A
TBehaviour, an object behaviour. This object contains hooks so custom code can be executed when the modder wants. It is instantiated usingTDef.CreateBehaviour. - A
TRef, an object reference. These are (relatively type-safe) objects that can resolve to aTDef.
As explained in the README, the manifest.json defines the mod. Define the following fields:
-
internalName: the name used by Prism internally to identify the mod. This MUST be unique! To avoid naming collisions, you could prefix it with eg. your name. -
displayName: the name the user will get to see. Can be anything. -
author: your name (optional). -
version: the version of the mod (optional). This must follow the SemVer format. -
description: a description of what the mod does (optional).
These shouldn't be a problem. Now add the following two fields as well:
-
asmFileName: the file name of your mod's DLL, relative to themanifest.jsonfile. -
modDefTypeName: the full type name of the class that derives fromPrism.API.ModDef. It must have a public constructor with no parameters. This is used as the "entry point", see the next section for more info.
As explained earlier, every mod needs a class that derives from Prism.API.ModDef. You need to add one override method: CreateContentHandler. This method MUST NOT return null. Preferably, return a newly created instance of a class that derives from Prism.API.ContentHandler (see the next section).
ModDef also contains some overridable methods that can be useful to load and unload resources.
This class is used by Prism to get all entity definitions defined by the mod. It contains a lot of protected virtual Dictionary<string, TFoo> GetFoos()-like methods that are used to supply those defs. (The keys of the dictionaries are the internal names of the entities.)
This API is made such that one can return a hardcoded Dictionary, or read the definitions from a bunch of JSON files, etc.
A ContentHandler also contains two methods to read resources:
-
GetResource<T>: read a resource file on disk, relative to themanifest.jsonfile. -
GetEmbeddedResource<T>: read a resource that is directly embedded in the assembly of the mod.
If you're using big wave files, use DynamicSoundEffectInstance instead of SoundEffect or SoundEffectInstance as the generic parameter to the GetResource methods, as it will lazily read chunks, thus using less RAM.
All boilerplate is now set up, and you can start creating entity definitions and return those from the GetFoos methods in the ContentHandler. See the 'example' mod for more details.
Create a folder under Documents\My Games\Terraria\Prism\Mods (preferrably with the same name as the mod's internal name, but this isn't obligatory), and put the manifest.json file, the mod's assembly and whatever resource files you have in there.
If that's done, launch Prism, and your mod will be loaded (or it'll display an error if something went wrong).