CCDirectLink - User contributions [en]

CrossCode Modding Tutorial

2020-12-23T16:10:29Z

Keanucode: Ported 2767mr's tutorial.

This page contains the steps on how to create your very first CrossCode mod. (header WIP, ask 2767mr)

= Installing CCLoader =

⚠ '''Due to DRM it is not possible to mod Xbox Game Pass or Microsoft Store versions of the game.'''

See [[CCLoader#Installation]]

= Installing NW.js =

== Requirements ==

* [[Locations_of_CrossCode_files#Game_files_folder|CC installation folder]]
* [https://nwjs.io NW.js SDK zip]

⚠ '''The game uses an outdated version of NW.js, so you might want to use version <code>0.30.5</code> to avoid accidentally using features not yet available in CrossCode.'''

== Steps ==

# Open the nwjs-sdk zip
# Open the folder so you can see the <code>nw.exe</code> file

[[File:nwjsRoot.png|class=block-img]]

# <li value=3>Extract/drag all files into the [[Locations_of_CrossCode_files#Game_files_folder|CC installation folder]] and replace existing files when prompted.</li>
# Delete <code>CrossCode.exe</code>
# Rename <code>nw.exe</code> to <code>CrossCode.exe</code>
# Open the game
# Press F12 to open the Chrome DevTools
# Click the <code>Console</code> tab
# In the top bar, click <code>top</code>
# Choose the second entry in the dropdown list
# You can now enter commands into the console

= Making a mod =

== Requirements ==

* [[CCLoader#Installation|Installing CCLoader]]
* [[Locations_of_CrossCode_files#Game_files_folder|CC installation folder]]

== Steps ==

# Open the [[Locations_of_CrossCode_files#Game_files_folder|CC installation folder]]
# Open <code>assets</code> -> <code>mods</code>
# Create a new folder for your mod. In this example, we are going to use <code>myMod</code>
# Create a new file called <code>package.json</code>

This file is used to tell CCLoader how to load your mod. It contains the internal name (<code>name</code>), the in-game displayed name (<code>ccmodHumanName</code>), the version number (<code>version</code>) and dependencies (<code>ccmodDependencies</code>). Only <code>name</code> and <code>version</code> are required.

=== Example <code>package.json</code> ===

<syntaxhighlight lang="json" line="line">
{
"name": "my-mod",
"ccmodHumanName": "My Mod",
"version": "1.0.0"
}
</syntaxhighlight>

# <li value=5>Find a file to modify</li>

In this example we will do a simple palette swap of Lea. You can find her sprites in <code>assets/media/entity/player/move.png</code>

# <li value=6>Copy the file to your mod</li>

In order for CCLoader to pick up the file from the mod it needs to be inside the mod folder with the same name as the original. This means that <code>assets/media/entity/player/move.png</code> turns into <code>assets/mods/myMod/assets/media/entity/player/move.png</code>.

⚠ '''Do not publish original CrossCode files in your mod.'''

# <li value=7>Edit the file</li>

In this example I am using Paint.NET to swap Lea's red clothes for green ones:

[[File:leaRecolor.png|class=block-img]]

# <li value=8>Restart the game and test your mod</li>

[[File:leaRecolored.png|class=block-img]]

= Editing JSON =

Often it is not enough to just edit png files to make mods. Changing sizes, making new entities or maps require one to edit or create new JSON files. This guide shows you how to work with JSON files in your mod.

== Requirements ==

* [[CrossCode Modding Tutorial#Making a mod|Making a mod]]

== New JSON files ==

Adding new JSON files does not require any special attention. Simply put the file into the correct folder and CCLoader will pick it up automatically.

== Existing JSON files ==

Editing existing JSON files is problematic in a few cases. Now only are these files pretty big but there are also a lot of instances where multiple mods want to modify the same file. In that case simply replacing the entire file doesn’t work.

Instead you can use a mechanism called patches. These are files that only record the changes made to the original file, allowing multiple mods to apply patches to the same file. They work similar to file replacements as they require you to use the same name as the original file. The difference is that they append a <code>.patch</code> to the filename and use special sytanx exmplained in more detail on [[Patching]].

In order to work with JSON files it is recommend to beautify them before using them. You can use [https://beautifier.io/ beautifier.io] to do that for you.

In this example we will make a patch that will increase the damage Lea does. This information can be found in <code>assets/data/players/lea.json</code>. Once beautified one can easily see the value we want to modify.

<syntaxhighlight lang="json" line="line">
{
"character": "main.lea",
"sheet": "player",
"headIdx": 0,
"class": "SPHEROMANCER",
"stats": {
"hp": {
"base": 200,
"increase": 2000,
"variance": 0.1
},
"attack": {
"base": 20,
"increase": 200,
"variance": 0.9
},
...
</syntaxhighlight>

Now we want to somehow change <code>stats.attack.base</code> to <code>200</code>. For that we first create a patch file <code>assets/mods/myMod/assets/data/players/lea.json.patch</code>

🚀 '''Tip: Most editors will not recognize these files as JSON by default. Almost all popular editors include a feature to manually set which type of file you are currently editing.'''

First you can begin the file with <code>[]</code> to signal that this file is using the “Patch Step” format:

<syntaxhighlight lang="json" line="line">
[

]
</syntaxhighlight>

Next we insert a step that navigates into the <code>attack</code> object:

<syntaxhighlight lang="json" line="line">
{
"type": "ENTER",
"index": ["stats", "attack"]
}
</syntaxhighlight>

Now we can overwride a value:

<syntaxhighlight lang="json" line="line">
{
"type": "SET_KEY",
"index": "base",
"content": 200
}
</syntaxhighlight>

At the end, we navigate back to the root of the document. In this case it is not required but will make future additions a lot easier.

<syntaxhighlight lang="json" line="line">
{
"type": "EXIT",
"count": 2
}
</syntaxhighlight>

At the end we end up with this <code>lea.json.patch</code> file:

<syntaxhighlight lang="json" line="line">
[{
"type": "ENTER",
"index": ["stats", "attack"]
}, {
"type": "SET_KEY",
"index": "base",
"content": 200
}, {
"type": "EXIT",
"count": 2
}]
</syntaxhighlight>

= Making a JavaScript mod =

Although the game provides a very powerful JSON scripting system it is sometimes required to add new puzzle elements or edit internal workings of existing ones. For this one needs javascript mods.

== Requirements ==

* [[CrossCode Modding Tutorial#Making a mod|Making a mod]]

== Entry points ==

In order to load a JavaScript file, there needs to be an entry in the <code>package.json</code> of the mod. There are multiple possible values here that reference different points in time at which a mod is loaded. Furthermore there is an entry called <code>plugin</code> which combines all these entry points.

For example, if we want to double all gained CP points we need to add a script:

<syntaxhighlight lang="json" line="line">
{
"name": "my-mod",
"ccmodHumanName": "My Mod",
"version": "1.0.0",
"plugin": "plugin.js"
}
</syntaxhighlight>
{|
!width="100%"| ⚠ If you use entry points other than <code>plugin</code> you should always set <code>"module": true</code> as well.
|}

== Mod loading stages ==

=== Prestart ===

This is the entry point you usually want to use. At this point, most of the game code is loaded but almost none of it executed yet. This makes it the perfect chance to change how the internals work.

=== Preload ===

At this point none of the game has been loaded yet. This means that while nothing has loaded yet but one can use this to set up libraries or use some JavaScript black magic.

=== Postload ===

Here some of the game code has been loaded, however pretty much nothing has been executed yet. Specifically, none of the resources have been been loaded yet, making it possible to intercept and work with them.

=== Main ===

This stage, which has been called “main” for legacy reasons, executes code as soon as the title menu start playing. This allows mods to use code that may have not been executed yet in the prestart stage, though it should be avoided is easily possible.

== Plugin ==

While using loading stages directly in the <code>package.json</code> directly executes the code in a script the plugin combines multiple stages at once. Every plugin defines an exported JavaScript class that is used to execute the code.

Since we defined the file as <code>plugin.js</code> above we create a new file <code>assets/mods/myMod/plugin.js</code>:

<syntaxhighlight lang="js" line="line">
export default class MyMod {
prestart() {
//Prestart code will go in here.
}
}
</syntaxhighlight>
The advantage of using plugins over direct stages is that the constructor of the plugin receives an object as argument which can be used to find out which folder the current mod is stored in.

🚀 '''Tip: A plugin can also be used to write async code in a loading stage, blocking all other mods from loading until it has finished.'''

Now that we can execute code in the prestart stage, we need to find out how to double the CP points. If we look into the <code>assets/js/game.compiled.js</code> file we can find out that there is a class called <code>sc.PlayerModel</code> which contains a function

<source lang="ts">public addSkillPoints(points: number, element: number, all: boolean, extra: boolean): void</source>
We now want to manipulate <code>addSkillPoints</code> so that <code>points</code> are doubled. For that we can use the <code>inject</code> function. This is a function that exists on all classes that allows you to add and overwrite existing functions. Furthermore, inside that function you can use <code>this.parent(...)</code> to call the original functon.

We can use this to make a mod that doubles all CP:

<syntaxhighlight lang="js" line="line">
export default class MyMod {
prestart() {
sc.PlayerModel.inject({
addSkillPoints(points, element, all, extra) {
this.parent(points*2, element, all, extra);
}
});
}
}
</syntaxhighlight>

This example mod can be found on GitHub.<ref>https://github.com/CCDirectLink/CrossCode-Modding-Tutorial/tree/master/example</ref>

= Share your mod =

== Requirements ==

* [[CrossCode Modding Tutorial#Making a mod|Making a mod]]

== Steps ==

# Open your mod folder that contains the <code>package.json</code> file
# Select all files/folders needed for the mod
# Create a zip archive from these files. On Windows you can do this using right click > send to > zip-archived folder

You can already share this file

<ol start="4" style="list-style-type: decimal;">
<li>Rename the .zip file to .ccmod</li></ol>

This allows other users to simply drag the file into the mods folder and not have to worry about extracting it

== Publish on the official list ==

Since the process of approving a mod for the official list is a bit complicated (and is likely to change in the future) the best way is to:
* Publish your source code on [https://github.com/ GitHub]
* Make sure you have a correct version number
* Create a [https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/managing-releases-in-a-repository Github Release] - you can upload your .ccmod file there
* Message (an admin) on the [https://discord.gg/TFs6n5v CrossCode Modding Discord] to add your mod to the list

== References ==

<references />

[[Category:Modding guides]]

File:LeaRecolored.png

2020-12-23T16:07:22Z

Keanucode:

File:LeaRecolor.png

2020-12-23T16:07:13Z

Keanucode:

2020-08-14T08:30:58Z

Keanucode: Attempt to fix the discussions button.

{| class="wikitable infobox-table" style="width: 21em;"
! style="white-space: nowrap;" | Homepage
| [[github:CCDirectLink/CCInjector]]
|-
! style="white-space: nowrap;" | Author
| [[github:ac2pic]] aka Emileyah
|-
! style="white-space: nowrap;" | Written in
| JavaScript
|-
! style="white-space: nowrap;" | License
| MIT
|-
! style="white-space: nowrap;" | First appeared
| 2019-05-19
|-
! style="white-space: nowrap;" | Stable release
| N/A
|-
! style="white-space: nowrap;" | Preview release
| N/A
|-
! style="white-space: nowrap;" | Current status
| Discontinued
|}

WIP

[[Category:Modloaders]]

MediaWiki:Citizen-footer-tagline

2020-08-13T15:24:36Z

Keanucode: Automated year display on footer.

MediaWiki:Citizen-footer-tagline

2020-08-13T15:22:43Z

Keanucode: Added copyright to footer.

MediaWiki:Citizen-footer-desc

2020-08-13T15:02:47Z

Keanucode: Created page with "The CrossCode Modding Wiki."

The CrossCode Modding Wiki.