Mod Creation/Migrating from Scripts and Extensions: Difference between revisions

no edit summary
(Migrating your script or extension to the new mod format? Use these guidelines for a frustration-free experience.)
 
No edit summary
Line 2: Line 2:


== Metadata ==
== Metadata ==
Whether the mod being migrated was a userscript or extension, the majority of metadata that was previously defined in the respective locations (userscript comment block or extension <code>manifest.json</code> file) will instead be entered in the mod.io profile page for the mod. This includes the name, author (the uploading mod.io account), description, tags, and versioning.
Whether the mod being migrated was a userscript or extension, the majority of metadata that was previously defined in the respective locations (userscript comment block or extension <code>manifest.json</code> file) will instead be entered in the mod.io profile page for the mod. This includes the name, author (the uploading mod.io account), description, tags, and versioning.


Line 7: Line 8:


=== Userscript ===
=== Userscript ===
Userscripts should define a single <code>"load"</code> property within the manifest, with a string value pointing to the script's location relative to the <code>manifest.json</code> file. For example, given the following folder structure:
Userscripts should define a single <code>"load"</code> property within the manifest, with a string value pointing to the script's location relative to the <code>manifest.json</code> file. For example, given the following folder structure:


Line 14: Line 16:


The <code>manifest.json</code> should simply be:
The <code>manifest.json</code> should simply be:
  <nowiki>{
  <nowiki>{
   "load": "script.js"
   "load": "script.js"
Line 19: Line 22:


=== Extension ===
=== Extension ===
Extensions that previously defined icons in the manifest should now define a single value for the <code>"icon"</code> property instead. This icon file will be used in-game and displayed no larger than 38px x 38px by default.
Extensions that previously defined icons in the manifest should now define a single value for the <code>"icon"</code> property instead. This icon file will be used in-game and displayed no larger than 38px x 38px by default.


Line 33: Line 37:


And a previous <code>manifest.json</code> of (irrelevant properties stripped):
And a previous <code>manifest.json</code> of (irrelevant properties stripped):
  <nowiki>{
  <nowiki>{
   "icons": {
   "icons": {
Line 46: Line 51:


The new <code>manifest.json</code> would be:
The new <code>manifest.json</code> would be:
  <nowiki>{
  <nowiki>{
   "icon": "my-icon-48.png",
   "icon": "my-icon-48.png",
Line 52: Line 58:


== The "Loading Loop" ==
== The "Loading Loop" ==
Both userscripts and extensions would often end up with a ''funky'' loop that is some variation of the following in order to wait until the game has loaded into a character to perform actions:
Both userscripts and extensions would often end up with a ''funky'' loop that is some variation of the following in order to wait until the game has loaded into a character to perform actions:
  <nowiki>var loadInterval = setInterval(() => {
  <nowiki>var loadInterval = setInterval(() => {
   var isGameLoaded = window.isLoaded && !window.currentlyCatchingUp;
   var isGameLoaded = window.isLoaded && !window.currentlyCatchingUp;
Line 63: Line 71:


With the new mod system's context API, that's no longer necessary. Instead, the script should use a game lifecycle hook, with the most comparable being <code>onInterfaceReady</code>:
With the new mod system's context API, that's no longer necessary. Instead, the script should use a game lifecycle hook, with the most comparable being <code>onInterfaceReady</code>:
  <nowiki>mod.register(ctx => {
  <nowiki>mod.register(ctx => {
   ctx.onInterfaceReady(() => {
   ctx.onInterfaceReady(() => {
Line 73: Line 82:


== Loading Packaged Resources ==
== Loading Packaged Resources ==
This section is specific to extensions, as this isn't a concept (commonly) supported in userscripts. If the extension being migrated over contained scripts, stylesheets, images, audio, or other files that weren't automatically loaded as part of the <code>content_scripts</code> but utilized during runtime, chances are those resources were retrieved using the <code>browser.runtime.getURL</code> (or <code>chrome.runtime.getURL</code>) method. Instead, the migrated mod should rely on the new mod context API's method, <code>getResourceUrl</code>. This method takes in a string value that is the requested resource's location relative to the manifest.json (root) of the mod package.
This section is specific to extensions, as this isn't a concept (commonly) supported in userscripts. If the extension being migrated over contained scripts, stylesheets, images, audio, or other files that weren't automatically loaded as part of the <code>content_scripts</code> but utilized during runtime, chances are those resources were retrieved using the <code>browser.runtime.getURL</code> (or <code>chrome.runtime.getURL</code>) method. Instead, the migrated mod should rely on the new mod context API's method, <code>getResourceUrl</code>. This method takes in a string value that is the requested resource's location relative to the manifest.json (root) of the mod package.


Line 88: Line 98:


And assuming <code>entryScript.js</code> was loaded as part of the manifest's <code>"load"</code> property, the <code>entryScript.js</code> could retrieve and use or load the <code>icon.png</code> and <code>helper.js</code> with the following:
And assuming <code>entryScript.js</code> was loaded as part of the manifest's <code>"load"</code> property, the <code>entryScript.js</code> could retrieve and use or load the <code>icon.png</code> and <code>helper.js</code> with the following:
  <nowiki>mod.register(async (ctx) => {
  <nowiki>mod.register(async (ctx) => {
   var iconUrl = ctx.getResourceUrl('assets/icon.png');
   var iconUrl = ctx.getResourceUrl('assets/icon.png');
Line 100: Line 111:


== Next Steps ==
== Next Steps ==
Hopefully the mod has been successfully migrated and is working with the new mod system at this point. But that's only the beginning - explore all of the new APIs and techniques available to you in the other Official Mod Making Guides:
Hopefully the mod has been successfully migrated and is working with the new mod system at this point. But that's only the beginning - explore all of the new APIs and techniques available to you in the other Official Mod Making Guides:
* [[Mod Creation/Getting Started]]
* [[Mod Creation/Getting Started]]
91

edits