Skip to content

Action Specs

Jump to bottom
Sheep-y edited this page Feb 4, 2021 · 7 revisions

This page is for mod authors. The system is in development; you are welcomed to give suggestion or contribute code.

Action mods are mods that have the "Actions" field, which will be processed by Action Handler mods. Action is supported since Modnix 3.

For example, the Scripting Library (C#) mod will process actions that have the "Eval" field and run it as C# script, such as the Laser On Fire mod.

Table of Contents

Actions

Actions are json objects. Most actions are processed by Action Handlers, in a data structure defined by them.

Actions are handled in order of declaration, subject to Phase and OnError. 

   { Actions:
     [{ "Action" : "Default", "OnError": "continue" },
      { "Eval": 'GetDef<TacticalItemDef>( "NJ_Gauss_PDW_WeaponDef" ).SetDamage( 25 )' },
      { "Eval": 'GetDef<ShootAbilityDef>( "RageBurst_ShootAbilityDef" ).ExecutionsCount = 50' }]
   }

The mod above declares three actions, one Default followed by two Eval. The Default action set the OnError field of the two Eval actions, then the Eval actions will be executed by the Scripting Library mod.

The first Eval set the basic PDW's per-shot damage to 25. The second Eval set Rage Burst to 50 shots per use, i.e. it will empty the clip of unmodded weapons. (Like how it was when the game was first released.)

Any modder can develop handlers, which are like normal mods. They handlers may support a different syntax, and do different things like overriding art assets.

The names of top-level action fields are case-insensitive. i.e. the above example may be written as
[{ action: "", onerror: "" },{ eval: ... },{ eval: ...}].

This name normalisation does not apply to non-top level fields.

Action.Include

  • Field: "Include", "Property" (optional)
  • Type: string
  • Default: null

The value of this field must be a path to a file, relative to the current action file. The included file must be in the same folder or in a subfolder.

If this action have the "Property" field (also case insensitive), it is a property include. The action will use the file's string content as its own property. Specifically:

  1. have its Property field removed.
  2. have current defaults (see below) applied.
  3. read the file and put it in the field specified by the Property field (pre-deletion).

If this action does not have the "Property" file, it is an action include. The included files must be a json array containing more actions, and these actions will replace the current action. Defaults (see below) are processed normally, as the files are stiched into one stream of actions.

Property Include Example: 

   // mod_info.js
   { Actions:
     [{
       "Script": "JavaScript"
       "Include" : "script.js",
       "Property" : "Eval",
     },]
   }

   // script.js - these lines will become the "Eval" property
   let Ares = Repo.get( WeaponDef, "PX_AssaultRifle_WeaponDef" );
   console.log( "Original = {0}", Ares.Damage() ); // Get damage
   Ares.Damage( 30 ); // Set damage

Action Include Example: 

   // mod_info.js
   { Actions:
     [{ "Action" : "Default", "Phase" : "GameOnShow" }
      { "Include" : "Stacktrace.js" },
      { "Action" : "Default", "Phase" : "GameOnHide" },,
      { "Include" : "Stacktrace.js" },]
   }

   // Stacktrace.js - this action will be executed twice, each at a different phase.
   [{ "Eval": 'Api("stacktrace")' }]

   // A better solution would be to say "Phase":"GameOnShow,GameOnHide".  But this is just an example.

Action.Phase

  • Field: "Phase"
  • Type: string
  • Default: "GameMod"

A comma-separated, case-insensitive list of Mod Phases this action should run at.

Sine Actions are added in Modnix 3, they will not run at Init, Initialize, and the MainMod phase.

Action.OnError

  • Field: "OnError"
  • Type: string
  • Default: "Log, Stop"

A comma-separated, case-insensitive list of directives on how to process error caused by this action.

Logging directives:

  • log - Log the error at Error level. This is the default if no logging directives are present.
  • error - Log at Error level.
  • warn - Log at Warning level.
  • info - Log at Info level.
  • silent - Do not log the error.

When there are multiple logging directives, the highest level will take effect.

Process directives:

  • stop - Abort action execution of this mod for the current phase execution. This is the default unless the others are specified.
  • skip - Skip to next Action.
  • continue - Try next Handler until all have been tried.

When have multiple process directives, "continue" overrides the others, and "skip" overrides "stop".

Default Action

  • Field: "Action"
  • Value: "Default"

Any Action that have the "Action" field equals to "Default" will be handled by Modnix.

Its non-Action fields will be copied to all Actions declared after it, typically Phase and OnError, without overwriting declared fields.

The Default Action takes precedence over Phase. Phase will be regarded as a field to be copied, rather than a limit on the Default.

Technically, this Action causes Modnix to copy its fields to all subsequence Actions. This Action will then be removed.

Action Handler

Action Handlers are DLL mods that expose the ActionMod method.

They are called for each mod actions that are not handled by Modnix (e.g. Include/Default). When there are multiple handlers, they are called in the same order as mod load orders, for each action, until one of them returns that the action is done.

The ActionMod method may have these parameters. Other parameters will be passed the default parameter value, or the type's default value.

IDictionary< string, object >, any name
This param will be passed the Action object.
string, any name
This param will be passed the id of the Action mod.
Func< string, object, object >, any name
This param will be passed the API delegate of the Action Handler mod, i.e. this is your api, not the api of the source mod.

The ActionMod method must return true, false, or an Exception. Other returned values will be regarded as false.

true
The Action is done. No more Handler will be called for this Action for current phase execution.
false
The Action is not done and will be passed to next Handler.
Exception
The Action triggered an error when being handled. What happens next depends on its OnError field value. The Exception may also be thrown instead of returned.

When you design an Action Handler, please avoid conflict with existing handlers.

Note that Actions does not need to be flat. Action Handlers may define their own data structure, within the limit of json.

Clone this wiki locally