Editing Inter-mod Communication

[[Category:Scripting]]
[[Category:Papyrus]]
=Overview=
This page covers the basics of how to communicate between two mods when one of them may or may not actually be installed or activated.

'''Warning''': Uninstalling mods while keeping with the same save game is not supported. If a user uninstalls a mod, they must go back to a save created before the mod was installed in the first place.

=What Not To Do=
First off, what ''not'' to do. When you refer to another script in your own script, you add what is called a "dependency". In other words, your script is now dependent on that other script existing. By extension, your script is now ''also'' dependent on any scripts that other script is as well. For example, if you have an ObjectReference property, you are now dependent on ObjectReference. But you are ''also'' dependent on Form (the parent of ObjectReference), Keyword (used as a function parameter a few times), and other scripts as well.

If one or more of the scripts you are dependent on do not exist, then your own script may be flagged as "invalid" and will refuse to run.

As such, in order to prevent your script from suddenly not working when a mod you want to talk to is not installed, you must no longer depend on it. Several functions have been created to let you interact with other scripts without depending on them. However the downside is these functions are clunkier to use, and the compiler cannot check your code, nor do any auto-casting that might be necessary. The upside, of course, is that now you can talk directly to another mod's scripts without worrying about your own scripts failing to work if that other mod is not installed.

=How To Talk To Another Mod=
==How To Determine If A Mod Is Installed==
As most of the functions here will error if called on scripts that do not exist, you'll want to make sure the script you are interested in does exist by checking to see if the mod it comes from is available. This is relatively simple, as you just need to call [[IsPluginInstalled - Game|IsPluginInstalled]], passing in the name of the esp or esm you are interested in.

Example:
<source lang="papyrus">
bool modInstalled = Game.IsPluginInstalled("SuperCoolWeapons.esp")
if modInstalled
  ; Do cool stuff! Like grab a fancy stick from it
endIf
</source>

Of course, the game allows the user to make a save at any time, and to install mods between different runs of the game. So you probably won't want to just check once and keep the value around forever. You will probably want to take advantage of [[OnPlayerLoadGame - Actor|OnPlayerLoadGame]] to update your "is mod installed" value every time the player loads their game from a save.

Again, note that uninstallation of mods while using the same save is ''not'' supported - so you shouldn't have to worry about your flag ever going false once it's set to true.

===See Also===
*[[IsPluginInstalled - Game]]
*[[OnPlayerLoadGame - Actor]]

==How To Get A Form From Another Mod==
Now that you've determined that another mod is installed, assuming you want to do something other than just call global functions they provide, you'll need to grab a form from it. You obviously cannot use a property set in the editor in your mod, because that would add a dependency between your two mods in the esp or esm itself.

So if you do want to get a form from the mod, you'll need to know the form ID of the form you are interested in. This is typically listed in the CK. Once you have the form ID, pass it off to the [[GetFormFromFile - Game|GetFormFromFile]] function, along with the plugin name, to get access to the form.

Example:
<source lang="papyrus">
Form newCompanionForm = Game.GetFormFromFile("SpecialCompanion.esp", 0x00015A4F)
Actor newCompanion = newCompanionForm as Actor
if newCompanion
  ; We've got ahold of the new companion from that other mod, maybe we can give them one of our special armor pieces?
endIf
</source>

You'll note that the form ID used in the above example has the top two digits as "00", when most commonly in the CK the form ID will start with a different number. The top two digits of the form ID are based off of the mod's position in the load order, and so they are ignored by the GetFormFromFile function.

===See Also===
*[[GetFormFromFile - Game]]

==How To Communicate With Another Mod==
There are a few ways to communicate with the other mod via Papyrus - functions, properties, remote events, and custom events, covered below.
===Functions===
One of the most common ways you will communicate with another mod is via calling functions that it provides. There are several functions provided, depending on what function you want to call and how you want to call it. Note that the compiler cannot do any type checking, or auto-casting for you, and so you will have to spend a little more effort calling the function then you might otherwise have to do with a normal function call.

Note that you will have to make sure that your parameter types match ''exactly''. No passing an int when they want a float, or an Actor when they want an ObjectReference. You'll have to pre-cast the parameters yourself. Also, you'll want to make sure you're pointing at the right script before you call a member function, but since you can't cast (that would add a dependency), there is a [[CastAs - ScriptObject|CastAs]] function to do that for you.

Because of the complexity, you may want to make wrapper functions that hide most of the code from the rest of your script, as shown below.

As an example, let's assume the other mod has a script like this:
<source lang="papyrus">
Scriptname BeginningFantasyCharacter extends Actor

Function ActivateCrystal(ObjectReference aCrystal, int aiManaCost) global
  ; code here
EndFunction
</source>

In order to call that function, maybe passing in a special crystal you made in your mod specifically for interacting with this mod, you would do the following:
<source lang="papyrus">
; A helper function to make it easier for my mod to call a function in the BeginningFantasy mod
Function ActivateBFCrystal(Actor aCharacter, ObjectReference aCrystal, int aiManaCost) global
  ; We can't use the normal "as" operator, because that would add a dependency on the other mod.
  ; So instead we use the CastAs function to make sure we're pointing at the right script.
  ScriptObject bfCharacter = aCharacter.CastAs("BeginningFantasyCharacter")
  
  ; Make sure we have a script to call a function on
  if bfCharacter
    ; Now build a parameter list. We don't have to do any casting because we're just passing
    ; in our own parameters which are already the right types. If they weren't, we'd have to
    ; manually cast
    Var[] params = new Var[2]
    params[0] = aCrystal
    params[1] = aiManaCost
    bfCharacter.CallFunction("ActivateCrystal", params)
  endIf
endFunction
</source>

There are also functions for calling global functions, and "NoWait" versions that don't wait for the called function to return, so your code will run in parallel with theirs (but you won't be able to get a return value from them).

====See Also====
*[[CallGlobalFunction - Utility]]
*[[CallGlobalFunctionNoWait - Utility]]
*[[CallFunction - ScriptObject]]
*[[CallFunctionNoWait - ScriptObject]]
*[[CastAs - ScriptObject]]

===Properties===
Of course, another thing you may want to do is access properties on a script on the other mod. This is slightly easier than calling a function, but it still falls under the same restrictions as calling a function with regards to setting a property value, and the object you call the property on.

As such, it is recommended you write wrapper functions to hide the uglier code.

For example, assume the mod you want to talk to has a script like this:
<source lang="papyrus">
Scriptname BeginningFantasyVendor extends Actor

float Property StoreOpenTime Auto
float Property StoreCloseTime Auto
</source>

You may want to write a wrapper function as follows to set these properties:
<source lang="papyrus">
Function SetBFVendorStoreHours(Actor aVendor, float aOpenTime, float aCloseTime)
  ; We can't use the normal "as" operator, because that would add a dependency on the other mod.
  ; So instead we use the CastAs function to make sure we're pointing at the right script.
  ScriptObject bfVendor = aCharacter.CastAs("BeginningFantasyVendor")

  ; Now set the properties, again, we don't need to cast because our parameter values are
  ; already the right types
  bfVendor.SetPropertyValue("StoreOpenTime", aOpenTime)
  bfVendor.SetPropertyValue("StoreCloseTime", aCloseTime)
endFunction
</source>

Of course, there is also a function to get a property value, and a "NoWait" version of set property value if you don't care to wait for the value to be changed.
====See Also====
*[[GetPropertyValue - ScriptObject]]
*[[SetPropertyValue - ScriptObject]]
*[[SetPropertyValueNoWait - ScriptObject]]
*[[CastAs - ScriptObject]]

===Remote Events===
Remote event registration doesn't depend on scripts that your mod won't have access to, as the only events are native ones that come with the game. As such, remote event registration can be done normally, once you have the source form via [[GetFormFromFile - Game|GetFormFromFile]].

====See Also====
*[[Remote Papyrus Event Registration]]
*[[GetFormFromFile - Game]]
*[[RegisterForRemoteEvent - ScriptObject]]

===Custom Events===
And the final way you will usually talk to another mod is via custom events. There is a catch, however, as custom events require you to add a dependency on the script the event comes from. We can get around this limitation with a "throwaway" script. One that we write and add to our mod, and then talk to via the above CallFunction/SetProperty/etc functions so we don't have a dependency on the throwaway script. Because we don't have a dependency on it, when the game fails to load that script because the mod it depends on is missing, we won't be adversely affected. That throwaway script will then talk directly to our script when it receives the event in question.

So here's an example of a script custom event that we may want to listen for:
<source lang="Papyrus">
Scriptname BeginningFantasyCharacter extends Actor

CustomEvent SummonCasted
</source>

To listen for the event, create the following "throwaway" script that is attached to the same form as your script which you really want to receive the event:
<source lang="Papyrus">
Scriptname BFSummonEventRelay extends ObjectReference

Function RegisterForSummon(Actor aCharacterWhoSummons)
  BeginningFantasyCharacter eventSource = aCharacterWhoSummons as BeginningFantasyCharacter
  if eventSource
    RegisterForCustomEvent(eventSource, "SummonCasted")
  endIf
EndFunction

Event BeginningFantasyCharacter.SummonCasted(BeginningFantasyCharacter aSender, Var[] aArgs)
  ; Now to relay the event to the other script on the same ref as we are
  MySpecialObject targetObj = ((self as ObjectReference) as MySpecialObject)
  targetObj.BFSummonCasted(aSender, aArgs)
EndEvent
</source>

And finally the script that receives the event:
<source lang="Papyrus">
Scriptname MySpecialObject extends ObjectReference

Event OnTriggerEnter(ObjectReference aActionRef)
  ; Use CastAs to get the throwaway script without a dependency
  ScriptObject relayScript = CastAs("BFSummonEventRelay")
  Actor actorThatEntered = aActionRef as Actor

  if relayScript && actorThatEntered
    ; And now tell the throwaway script to register for the custom event
    Var[] params = new Var[1]
    params[0] = actorThatEntered
    relayScript.CallFunction("RegisterForSummon", actorThatEntered)
  endIf
endEvent

Function BFSummonCasted(ScriptObject aSource, Var[] aArgs)
  ; We get called when our throwaway script gets the event
  ; So do something special since they casted a summon inside this trigger
endFunction
</source>

====See Also====
*[[Custom Papyrus Events]]
*[[RegisterForCustomEvent - ScriptObject]]