Skip to content

API Specs

Jump to bottom
Sheep-y edited this page Jan 31, 2021 · 10 revisions

This page is for mod authors.

DLL mods may have a parameter of type Func<string,object,object> in their initialisers. If found, it will be passed a delegate to serve as the api.

Example: 

   public void MainMod ( Func<string,object,object> api ) {
      // Read mod config into a Newtonsoft JObject
      var conf = api( "config", typeof( JObject ) ) as JObject;
      // Get a list of Sheepy's mods
      foreach ( string id in api( "mod_list", "Sheepy." ) as IEnumerable<string> ) {
         // Log mod id and its version. "log" = action, "verbose" = spec.
         api( "log verbose", id + " " + api( "version", id )?.toString() );
      }
   }

First parameter is the action and an optional specifier, while second parameter and return value varies by action. The name does not matter, but should contains "api" for future compatibility.

Do not put the api parameter in Init() or Initialize(). PPMLs do not expect it, and may fail to run, even if it defaults to null. (Default parameter does not work this way.)

Calling the api should never throw exception (with few exceptions). When a call runs into issues, Modnix will log the problem and return null (Modnix 1/2) or an Exception object (Modnix 3+).

Since Modnix 2.5, api calls may be prefixed with '@' or vertical tab '\v' to suppress error logging. The first is PHP syntax, while the second is backward compatible with old Modnix.

All native APIs listed here are thread-safe. Extensions added by mods may or may not be thread-safe.

Table of Contents

api_add

Register an api extension.

  • Action : "api_add"
  • Spec : Name of api to add.
  • Param : Delegate
  • Return : true on success

This action registers an api, allowing it to be called by other mods like a Modnix api. 

   // Register "ApiFunction3" method as "your.api3", that receives two params and returns a bool.
   api( "api_add your.api3", (Func<string,object,bool>) ApiFunction3 );

The parameter is a callback that is called whenever another mod call the api. Api is only called by other mods. Modnix itself does not call mod api.

If the callback have a string parameter, it will be passed the spec of the call, or empty string if there is none. If the callback have an object parameter, it will be passed the param of the call, or null if none is given. The callback will not be passed the api action, as it is assumed that it knows which action it registered.

Name requirements:

  • At least three characters.
  • Must contain at least a dot / period.
  • Must not contain space.

Parameter requirements:

  • Must be a Delegate, such as Func, Action, or Predicate.
  • Backing method must be static and non-abstract.
  • May have 0 to 2 input parameters, and must not be in, out, or ref.
  • May return void or any type.
  • If two parameters, the first must be string or object.
  • The last parameter must be object.

The registered methods do not have to catch Exceptions. Thrown exceptions will be caught, logged (may be), and returned. The method may also directly return an Exception for the same effect.

Real example: The Scripting Library mod registers the "eval.cs" API for evaluating C# scripts, and the pp.def / pp.defs API for looking up game data by guid, name, path, or type.

Compatibility:

  • Zero input parameter is allowed since Modnix 2.5.
  • Non-static/abstract methods and in/out/ref param disablled since Modnix 2.5.
  • Return value may be void or value type since Modnix 2.3, and can use compatible Action/Predicate.
  • Name must not contain space since Modnix 2.2.
  • Added in Modnix 2.

api_info

Query api information.

  • Action : "api_info"
  • Spec : ""
  • Param : string (Name of api to query)
  • Return : MethodInfo

This action returns the MethodInfo of a registered api. 

   // returns "ApiFunction2" following the api_add example
   ( api( "api_info your.api2" ) as MethodInfo ).Name

This can be used to find its name, owning class, return type etc.

Compatibility:

  • Return original method instead of wrapper methods since Modnix 2.3, when original is not exactly Func<string,object,object>.
  • Added in Modnix 2.2.

api_list

List api actions.

  • Action : "api_list"
  • Spec : ""
  • Param : null, string, or Regex
  • Return : IEnumerable<string>

This action returns a list of api. 

   // Find "*your.*" APIs
   api( "api_list", "your." ) as IEnumerable<string>
   // returns [ "your.api2", "your.api3" ]
  • Pass null to get full list.
  • Pass a string to get only ids containing the substring, case insensitive.
  • Pass a Regex to get only matching ids.

Other parameters returns null.

Native api goes first (in alphabetic order), then extensions (in no particular order). All apis actions are returned in lowercase.

If no matches, an empty enumerable will be returned.

Compatibility:

  • Added in Modnix 2.2.

api_remove

Unregister an api extension.

  • Action : "api_remove"
  • Spec : Name of api to remove.
  • Param : null
  • Return : true on success

This action allows the owner of an extension to unregistered it. 

   // Remove registered APIs. Does not need original method.
   api( "api_remove your.api2" );
   api( "api_remove your.api3" );

Compatibility:

  • Added in Modnix 2.

api_stack

Get Modnix API callstack.

  • Action : "api_stack"
  • Spec : "mod", "action", "command", "spec", "param", or ""
  • Param : null, Thread
  • Return : array

This action gets the Modnix API callstack for the provided thread, or the current thread if param is null.

The stack is arranged from bottom to top, i.e. [0] is nearest caller, [length-1] is topmost caller. Only Modnix API calls, which always happen through a mod, will show up in the stack. 

   // Get the last API caller's mod id
   ( api( "api_stack mod" ) as string[] )?[0]
   
   // Param of the nearest "foo.bar" call
   ( api( "api_stack" ) as object[][] )?.FirstOrDefault( e => e[2] == "foo.bar" )?[4]

The element type and content of the returned array varies by spec:

  • "mod" - Id of the caller mod.
  • "action" - The original (unprocessed) action+spec string passed to API.
  • "command" - The parsed action string.
  • "spec" - The parsed spec string, which may be blank but should never be null.
  • "param" - The param object passed to API.
  • "" - An object[5] of the above data, in this order.

If the given thread has no callstack, or the spec is unknown, null will be returned.

Compatibility:

  • Added in Modnix 3 Nightly 20200701.

assembly

Get the Assembly of a mod, the game, or a loader.

  • Action : "assembly"
  • Spec : ""
  • Param : null, string
  • Return : Assembly

This action gets the Assembly of the given mod, if and only if the mod has been loaded. 

   // Get a non-public game class for patching
   ( api( "assembly", "game" ) as Assembly )?.GetType( "AmplitudeWebClient" )
  • If param is null, the mod's own Assembly is returned.
  • If param is "loader" or "modnix", the modnix mod loader Assembly is returned.
  • If param is "ppml" or "phoenix point mod loader", the embedded PPML assembly is returned if it is loaded, otherwise null.
  • If param is "game" or "phoenix point", the game's Assembly-CSharp is returned.

If the mod has multiple assemblies, the first one loaded will be returned. If the mod has not been loaded or is not found, null will be returned.

Compatibility:

  • ppml assembly supported since Modnix 2.3

assemblies

Get all Assemblies of a mod.

  • Action : "assemblies"
  • Spec : ""
  • Param : null, string
  • Return : IEnumerable<Assembly>

This action gets all Assembly of the given mod, if and only if the mod has been loaded.

  • If param is null, the mod's own assemblies are returned.
  • If param is "modnix", the modnix mod loader Assembly is returned.
  • If param is "ppml" or "phoenix point mod loader", the embedded PPML assembly is returned if it is loaded, otherwise null.
  • If param is "loader", it returns the mod loader assembly and may be the PPML assembly.
  • If param is "game" or "phoenix point", the game's Assembly-CSharp is returned.

If the mod has not been loaded, or if the mod has no assemblies, an empty enumerable will be returned. If the mod is not found, null will be returned.

Compatibility:

  • "modnix" may also return ppml assembly before Modnix 2.4.
  • Mod not found will return empty enumeration before Modnix 2.3.2.
  • ppml assembly supported since Modnix 2.3, for "loader" and "ppml".
  • Added in Modnix 2.

config

Read config text or object from this mod's config file.

  • Action : "config"
  • Spec : "", "default", "delete", "save", "write"
  • Param : null, typeof( string ), Type, or any object
  • Return : deserialised object of same type

For "delete", "save", and "write", see below.

For the rest, this action will read config and shape it into the provided Type or object. The default type is specified by mod_info.js's ConfigType field. 

   api( "config", null ); // Read config as json and return an instance of ConfigType or JObject
   api( "config", new ModConf() ); // Read config as json, update the given ModConf instance, and return it.
   api( "config", typeof( ModConf ) ); // Read config as json and return a ModConf instance.
   api( "config", typeof( string ) ); // Read config as text and return it.
   api( "config", "default text" ); // Read config as text and, if not exists, return "default text".

If something goes wrong - locked file, syntax error, deserialisation error, create instance error - the action will return null. Easily caused by user edits. So make sure to handle null!

The "default" spec will load the default config instead of current config.

Compatibility:

  • "default" and "delete" added in Modnix 2.1.

config delete

Delete this mod's config file.

  • Action : "config"
  • Spec : "delete"
  • Param : null
  • Return : true, after config is deleted

If the mod has a config file, it will be deleted and return "true". If there is no config file, it will return "false".

Compatibility:

  • Added in Modnix 2.1.

config save

Save the provided object to the mod's config file.

  • Action : "config"
  • Spec : "save", "write"
  • Param : typeof( string ), or any object
  • Return : A Task that completes when the config is written.

If config action's spec is "save" or "write", the parameter object will be serialised as json (if not string) and written to the mod's config file. 

   api( "config save", "text to be written" );
   api( "config write", ConfigObjToBeSavedAsJson );

Both the serialisation and the write is done in a background thread, thus the provided object must not be modified after the call, including all objects that it references.

If parameter is null, nothing will be done and null will be returned. Otherwise, a Task will be returned that completes when the config is saved, or fails when the save process throws an error. Either way, you'll be free to change the config.

Compatibility:

  • Added in Modnix 2.

dir

Query mod folder.

  • Action : "dir"
  • Param : null or string (case-insensitive)
  • Return : string

This action returns absolute directory path as string. Parameter is case-insensitive.

  • null - return full directory path of the calling mod.
  • "mods_root" - return Mods folder.
  • "assembly-csharp", "managed" - return game dll folder.
  • "game", "phoenix point", "phoenix point" - return game folder.
  • "loader", "modnix" - return modnix loader folder (game dll folder in Modnix 1 & 2, game root folder in 3)
  • other string - find mod by id and return its directory, or null if not found.

Compatibility:

  • Added in Modnix 2.
  • "assembly-csharp" and "managed" params added in Modnix 3.

log

Add a string or object to mod log.

  • Action : "log"
  • Spec : "", "crit", "error", "warn", "info", "verbose", "flush"
  • Param : any object, Func<string>, or exception
  • Return : true

The provided object will be added to the log queue.

Its ToString will be asynchronously called in a background thread, and the result written to log with timestamp, message level, and mod id. Func<string> will also be resolved in the background thread, suitable for heavy string conversion.

When spec is unspecified (empty / null), message level is Error for Exception and Information for everything else.

Regardless of level, duplicate exceptions with same type, message, and stacktrace will be discarded.

"flush" is a special action that immediately format and write all queued entries. A note will be logged before the flush and the param, if any, will be included as the reason.

Technically, except for "flush", the api only check the first character of the spec. i.e. "log w" is the same as "log warn" and "log warning".

For high throughput logging, the logger action provides more control and is more efficient.

Compatibility:

  • Message level and "flush" specifiers added in Modnix 2.
  • Returns null instead of true in Modnix 1.

logger

Get a logger delegate.

  • Action : "logger"
  • Param : Type or string
  • Return : Action

This will return a delegate function to serve as a logger. 

   var log = api( "logger", "TraceEventType" ) as Action<TraceEventType,object,object[]>;
   log( TraceEventType.Verbose, "Time: {0}", DateTime.Now );

The parameter determines the type, and may be either the Type or the type's name. It must be either:

Other parameters will return null. The absent of a default is intentional.

You may cast and save the returned delegate, and call it to add entry to log queue.

  • The first param of the logger will have the specified type.
  • Second param is the message body, usually a parameterised string.
  • Third param is the parameters passed to run String.Format on the entry.

mod_disarm

  • Action : "mod_disarm"
  • Param : string
  • Return : true, false, or null

This action will find a mod of the given id and trigger its "DisarmMod" phase immediately. It will return true if a compatible mod is found and disarmed, false if found but is already disarmed, or null if it is not found or if it does not support disarming.

A disarmed mod is expected to undo its changes and cease to function. It is up to the mod to do that properly. See Mod Phases#DisarmMod for details.

Compatibility:

  • Added in Modnix 3.

mod_info

Query mod info

  • Action : "mod_info"
  • Param : null or string
  • Return : info object

This action will find a mod of the given id, or use the calling mod if null, and return its info object.

This object has the same fields as mod_info, and can be read with reflection.

Compatibility:

  • Mod not found return null since Modnix 2.5.1, before that this api would return the calling mod's info.

mod_list

Query list of mods.

  • Action : "mod_list"
  • Param : null, string, or Regex
  • Return : IEnumerable<string>

This action returns a list of id of enabled mods, which can be used in other queries.

  • Pass null to get full list.
  • Pass a string to get only ids containing the substring, case insensitive.
  • Pass a Regex to get only matching ids.

Other parameters returns null.

If no matches, an empty enumerable will be returned.

mod_rearm

  • Action : "mod_disarm"
  • Param : string
  • Return : true, false, or null

This action will find a disarmed mod of the given id and put it through past game phases immediately. It will return true if a disarmed mod is found and re-armed, false if found but is not disarmed, or null if it is not found or if it does not support disarming.

A compatible mod may be disarmed by calling the #mod_disarm API.

See Mod Phases#DisarmMod for details.

Compatibility:

  • Added in Modnix 3.

path

Query mod folder and mod paths.

  • Action : "path"
  • Param : null or string
  • Return : string

This action returns absolute file path as string. Parameter is case-insensitive.

  • null - return file path of the calling mod.
  • "mods_root" - return mod folder.
  • "assembly-csharp", "managed" - return file path of managed game code (Assembly-CSharp.dll).
  • "game", "phoenix point", "phoenix point" - return file path of game exe.
  • "loader", "modnix" - return file path of Modnix Loader.
  • other string - find mod by id and return its file path, or null if not found.

Compatibility:

  • "loader" and "modnix" param added in Modnix 2.
  • "assembly-csharp" and "managed" params added in Modnix 3.

stacktrace

  • Action : "log"
  • Spec : "", "crit", "error", "warn", "info", "verbose"
  • Param : null
  • Return : true

Log a stacktrace at the specified log level, default to "information".

Compatibility:

  • Added in Modnix 2.

version

Query game / loader / mod version.

  • Action : "version"
  • Param : null or string
  • Return : Version

This action try to find a matching mod and returns its version.

  • Pass null to get the version of the calling mod.
  • Non-nulls will be casted ToString.
  • Pass "game", "phoenixpoint", or "phoenix point" to get game version.
  • Pass "loader" or "modnix" to get Modnix version.
  • Other strings will be regarded as mod id.

If a mod is found but it has no version, it will default to "0.0.0.0". If the mod is not found, null will be returned.

Clone this wiki locally