Skip to content

Getting Started

Jump to bottom
aquafir edited this page Feb 16, 2024 · 9 revisions

Install

The minimum you need is:

  • Debug ACE installation with ModManager (added to ACE 5/25/2023)
    • Mods work on Release builds, but building a mod referencing a Release build of ACE has had issues. Thanks to Bradley of Sundering for confirming.
  • Visual Studio Community (or IDE of choice)
    • .NET desktop development workload
    • ASP.NET and web development (optional)

Recommended:

Setup

  • Extract the contents of ACE.BaseMod-master from this repository.
  • Open ACE.BaseMod.sln with Visual Studio

If you use a different directory than C:\ACE\Server for your server or want a different mod folder than C:\ACE\Mods\ you may need to change the template (video) or the settings. If you use the defaults you can skip these steps.

  • Set the ModsDirectory set in your Config.js file:
 ...
 "DatFilesDirectory": "C:\ACE\Dats\",
 "ModsDirectory": "C:\ACE\Mods\",
 ...
  • Double-click ACE.BaseMod
  • Update the build path so mods go in a folder matching their name in the mods folder: <OutputPath>C:\ACE\Mods\$(AssemblyName)</OutputPath>
    • Find-ReplaceAll the HintPath so mods are referencing your server's assemblies: C:\ACE\Server\ --> C:\My\Server\

Export (video) the BaseMod template so it shows up as a new project type in Visual Studio:

  • Project->Export Template->ACE.BaseMod selected->Next->Finish

Creating a Mod (Video)

  • Ctrl+Shift+N or File->New->Project
  • Search for ACE.BaseMod (or whatever template you're using)
  • Next-> Name it what you want ->Create

Now that you have a mod you're ready to add a patch or command.

Add a Patch

You may want to open the ACE repo or check out the list of members of interest to find something you want to patch.

If you have the Harmony extension installed creating a patch is as simple as:

  • Right-click the member you're interested in patching.
  • Choose Annotated Prefix or Annotated Postfix to copy the appropriate Harmony annotations to your clipboard.
  • Paste that in your mod.

Example Videos

  • Postfix does something after a method
  • Prefix does something before a method.
    • If it is bool and returns false it will skip the patched method.
    • You can also have a void prefix
  • For either type of patch if you want to modify the value of a parameter mark it with the ref keyword.

Categories

  • Any class with a [HarmonyPatch] will have annotated patches within it added if PatchAll() is being used.
  • By default PatchAllUncategorized() is used, which will ignore anything with a category:
    • [HarmonyPatchCategory("categoryName")]
    • See Balance for an example of selectively applying patches.
  • PatchClass has a region called Patches with a commented-out prefix.

Add a Command

Commands can be added with the same annotations they are in ACE. Add command below to PatchClass (or wherever) to add a hello command (related video/sample) :

[CommandHandler("hello", AccessLevel.Player, CommandHandlerFlag.None, 0, "")]
public static void HandleFixBusy(Session session, params string[] parameters)
{
	if (session?.Player is null)
		ModManager.Log("Hello, world.");
	else
		session.Player.SendMessage($"Hi, {session.Player.Name}");
}

Meta.json

You, or a server operator using a published mod, can control some behavior of mods through Meta.json. By default everything is enabled:

  • Enabled determines if the mod is initialized
  • HotReload will reload your mod when you rebuild it
  • RegisterCommands determines if commands found in the mod will be added

Add your name/description if you'd like. If support for conflicts or dependencies are added in the future this is where they'll be.

Settings.json

BaseMod uses some simple JSON serialization to add persistent settings.

  • Add properties to Settings.cs
  • When you start the mod, if Settings.json is missing, it will be created with the default values
  • A FileWatcher detects changes and Starts/Shutsdown the PatchClass instead of the entire Mod
  • If the mod is making changes to the settings and needs to save them out, call SaveSettings() in Shutdown()
  • You can open Settings.json with the command /mod s [part of mod name]

Dependencies

You are able to use things like NuGet packages. The best approach still needs to be looked into, but one way to do it is:

  • Add a package to your mod. Do not copy on build.
  • Add the same package to ACE and build.

Debugging

Debugger is likely going to disconnect any active clients, but if you need to step through what is happening in a mod, you can trigger the debugger by calling Debugger.Break()

Clone this wiki locally