Patching - Revision history

Lexisother: Change heading sizes

2023-05-26T16:18:04Z

Change heading sizes

← Older revision		Revision as of 18:18, 26 May 2023
Line 9:		Line 9:
	There is more than one way to patch the game. This page will walk you through the various ways to patch.		There is more than one way to patch the game. This page will walk you through the various ways to patch.

	~~<hr>~~		== Asset Replacement ==

	= Asset Replacement =

	This is the most basic type of patching (anyone can do it).		This is the most basic type of patching (anyone can do it).
Line 17:		Line 15:
	This is a standard modloader feature that allows you to replace any file the game loads with your own.		This is a standard modloader feature that allows you to replace any file the game loads with your own.

	== Process ==		=== Process ===

	Inside your mod folder, create a folder called <code>assets</code>.		Inside your mod folder, create a folder called <code>assets</code>.
Line 49:		Line 47:
	* Used faceless Lea mod for some of the demonstration		* Used faceless Lea mod for some of the demonstration

	= JSON Patching (Object Patching) =		== JSON Patching (Object Patching) ==

	Note: This requires some know of the JSON format and some programming concepts		Note: This requires some know of the JSON format and some programming concepts
Line 61:		Line 59:
	You need to have file extensions visible in order to modify it.		You need to have file extensions visible in order to modify it.

	== Process ==		=== Process ===

	Let's say you want to patch a file <code>assets/data/test.json</code> with this as the contents:		Let's say you want to patch a file <code>assets/data/test.json</code> with this as the contents:
Line 102:		Line 100:
	Weakness: - Inability to removal properties - Arrays are hard to patch		Weakness: - Inability to removal properties - Arrays are hard to patch

	= Patch Steps =		== Patch Steps ==

	Patch Steps is another way to perform json file Patching. It is more powerful than Object Patching.		Patch Steps is another way to perform json file Patching. It is more powerful than Object Patching.
Line 120:		Line 118:
	</syntaxhighlight>		</syntaxhighlight>

	~~== Appliers ==~~		Below is a list of all the valid patch steps.

	~~An Applier~~ is a ~~Patch Step command~~.

	~~== Patch Step Appliers ==~~

	=== ENTER ===		=== ENTER ===

Lexisother: /* CALL */ Move the note to a real note

2023-05-25T20:08:06Z

CALL: Move the note to a real note

← Older revision		Revision as of 22:08, 25 May 2023
Line 925:		Line 925:
	This step allows you to call a custom step.		This step allows you to call a custom step.

	First, you define a custom step. ~~In a CCLoader2 mod:~~		First, you define a custom step.

			{{Note
			\|text=The following code must be ran BEFORE prestart! That being during plugin, preload, or postload.
			\|type=reminder
			}}

	<syntaxhighlight lang="js">		<syntaxhighlight lang="js">
	~~// NOTE: This MUST be done BEFORE prestart! That being: plugin, preload, postload~~
	simplifyResources.patchSteps.callable.register("YOUR_ID", (state, args) => {		simplifyResources.patchSteps.callable.register("YOUR_ID", (state, args) => {
	console.log(args);		console.log(args);

Lexisother: Move codeblocks to the not-deprecated syntaxhighlight

2023-05-25T13:41:16Z

Move codeblocks to the not-deprecated syntaxhighlight

Show changes

Lexisother: Add documentation for the CALL step

2023-05-25T13:16:27Z

Add documentation for the CALL step

@@ Line 922: / Line 922: @@
+}
 </source>
 === DEBUG ===

Lexisother: Add MERGE_CONTENT step

2022-10-01T12:04:54Z

Add MERGE_CONTENT step

← Older revision		Revision as of 14:04, 1 October 2022
Line 819:		Line 819:

	{ "alias-a": 2, "alias-b": [3], "alias-c": { "d": 4 } }		{ "alias-a": 2, "alias-b": [3], "alias-c": { "d": 4 } }

			=== MERGE_CONTENT ===

			With the following data:

			<source lang="js">
			{
			"a": 1,
			"b": 2
			}
			</source>

			And the following patch step:

			<source lang="js">
			{
			"type": "MERGE_CONTENT",
			"content": {
			"a": 3,
			"c": 4
			}
			}
			</source>

			<code>MERGE_CONTENT</code> would modify the data to be:

			<source lang="js">
			{
			"a": 3,
			"b": 2,
			"c": 4
			}
			</source>

			For an array, it would work the same way - effectively acting as multiple <code>ADD_ARRAY_ELEMENT</code> steps being executed at the end of the array.

	=== PASTE ===		=== PASTE ===

Lexisother: Capitalize all step names

2022-10-01T11:59:05Z

Capitalize all step names

← Older revision		Revision as of 13:59, 1 October 2022
Line 128:		Line 128:
	<source lang="js"></source>		<source lang="js"></source>

	=== ~~Enter~~ ===		=== ENTER ===

	This changes the context of a patch.		This changes the context of a patch.
Line 200:		Line 200:
	</source>		</source>

	=== ~~Exit~~ ===		=== EXIT ===

	For every <code>ENTER</code>, there should be at least one <code>EXIT</code>.		For every <code>ENTER</code>, there should be at least one <code>EXIT</code>.
Line 460:		Line 460:
	</source>		</source>

	=== ~~Import~~ ===		=== IMPORT ===

	This is the contents of <code>assets/data/test.json</code>:		This is the contents of <code>assets/data/test.json</code>:
Line 614:		Line 614:
	Note: "index" and "path" options are optional.		Note: "index" and "path" options are optional.

	=== ~~Include~~ ===		=== INCLUDE ===

	The purpose of <code>INCLUDE</code> is to allow external Object Patching or PatchSteps to be performed.		The purpose of <code>INCLUDE</code> is to allow external Object Patching or PatchSteps to be performed.
Line 783:		Line 783:
	</source>		</source>

	=== ~~Copy~~ ===		=== COPY ===

	This is the contents of <code>assets/data/test.json</code>:		This is the contents of <code>assets/data/test.json</code>:
Line 888:		Line 888:
	</source>		</source>

	=== ~~Debug~~ ===		=== DEBUG ===

	<source lang="js">		<source lang="js">
Line 902:		Line 902:
	This PatchStep turns Debug Mode on or off.		This PatchStep turns Debug Mode on or off.

	=== ~~Comment~~ ===		=== COMMENT ===

	Debug mode must be on for this PatchStep to work.		Debug mode must be on for this PatchStep to work.

Dmitmel: Imported from https://github.com/CCDirectLink/documentation/blob/master/patching.md

2020-08-17T21:50:41Z

Imported from https://github.com/CCDirectLink/documentation/blob/master/patching.md

New page

<big>'''NOTE:''' This article needs editing!!!</big>

= What is patching? =

In the scope modding, patching is changing the original game content in any way.

= How do I patch game files? =

There is more than one way to patch the game. This page will walk you through the various ways to patch.

<hr>

= Asset Replacement =

This is the most basic type of patching (anyone can do it).

This is a standard modloader feature that allows you to replace any file the game loads with your own.

== Process ==

Inside your mod folder, create a folder called <code>assets</code>.

[[File:Mod-assets-folder.png|class=block-img]]

Decide what file you want to replace. For this tutorial, I will be showing you how to replace Lea's portraits.

Find the original relative path to asset of interest.

[[File:Lea-face-path.png|class=block-img]]

All you have to do is now mimic the folder structure.

In this example, two folders need to be created.

Inside the <code>assets</code> folder in your mod, create a <code>media</code> folder. Inside the <code>media</code> folder, create a <code>face</code> folder.

Finally, add the file you want to replace (your own <code>lea.png</code>).

It should end up looking something like this.

[[File:Faceless-mod-path-example.png|class=block-img]]

[[File:Faceless-mod-folder-contents-example.png|class=block-img]]

That is it!

You can find more examples in the [[github:CCDirectLink/CCAssetSwaps]] repo.

* Used faceless Lea mod for some of the demonstration

= JSON Patching (Object Patching) =

Note: This requires some know of the JSON format and some programming concepts

As the majority of the game assets are json files, this is really useful to know about.

What this allows you to do is modify any json file without doing a file replacement.

The same ideas apply as assets override, except the file will have <code>.patch</code> added to the full file name.

You need to have file extensions visible in order to modify it.

== Process ==

Let's say you want to patch a file <code>assets/data/test.json</code> with this as the contents:

<source lang="js">
{
"storage" : {
"level": 100,
"xp": 500
}
}
</source>

Your mod is located at <code>assets/mods/my-mod/</code>

You would create a file with the filepath <code>assets/mods/my-mod/assets/data/test.json.patch</code>

To replace "storage.level" with 200, <code>test.json.patch</code> would look like this:

<source lang="js">
{
"storage" : {
"level": 200
}
}
</source>

To add "storage.name":

<source lang="js">
{
"storage" : {
"name": "Shizuka"
}
}
</source>

Object patching is useful for adding new properties and modifying existing ones.

Weakness: - Inability to removal properties - Arrays are hard to patch

= Patch Steps =

Patch Steps is another way to perform json file Patching. It is more powerful than Object Patching.

The only difference between Object Patching and Patch Steps is the format of the <code>.patch</code> file.

We will be using the same sample json file used to demonstrate how Object Patching works.

Location: <code>assets/data/test.json</code>

<source lang="js">
{
"storage" : {
"level": 200
}
}
</source>

== Appliers ==

An Applier is a Patch Step command.

== Patch Step Appliers ==

<source lang="js"></source>

=== Enter ===

This changes the context of a patch.

<source lang="js">
[{
"type": "ENTER",
"index": ["storage"]
}]
</source>

or

<source lang="js">
[{
"type": "ENTER",
"index": "storage"
}]
</source>

would change the internal view of:

<source lang="js">
{
"storage" : {
"level": 200,
"saves": [{
"data": "blob"
}]
}
}
</source>

to

<source lang="js">
{
"level": 200,
"saves": [{
"data": "blob"
}]
}
</source>

<source lang="js">
[{
"type": "ENTER",
"index": ["storage", "saves", 0]
}]
</source>

would change the internal view of:

<source lang="js">
{
"storage" : {
"level": 200,
"saves": [{
"data": "blob"
}]
}
}
</source>

to

<source lang="js">
{
"data": "blob"
}
</source>

=== Exit ===

For every <code>ENTER</code>, there should be at least one <code>EXIT</code>.

<code>EXIT</code> undos an <code>ENTER</code>.

<source lang="js">
[{
"type": "EXIT"
}]
</source>

is equivalent to

<source lang="js">
[{
"type": "EXIT",
"count": 1
}]
</source>

For demonstration purposes, this is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"storage": {
"user": {
"name": 20
}
}
}
</source>

and this is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "ENTER",
"index": ["storage", "user"]
}, {
"type": "EXIT",
"count": 2
}]
</source>

The first step will produce the internal result of:

<source lang="js">
{
"name": 20
}
</source>

The second step will undo the first leading to the initial state.

<source lang="js">
{
"storage": {
"user": {
"name": 20
}
}
}
</source>

=== SET_KEY ===

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"storage": {
"user": {
"name": 20
}
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "SET_KEY",
"index": "storage"
}]
</source>

This is the result:

<source lang="js">
{}
</source>

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"storage": {
"user": {
"name": 20
}
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "SET_KEY",
"index": "storage",
"content": 2
}]
</source>

This is the result:

<source lang="js">
{
"storage": 2
}
</source>

=== INIT_KEY ===

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"storage": {
"user": {
"name": 20
}
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "INIT_KEY",
"index": "storage",
"content": {
"a": 2
}
}]
</source>

Nothing will change to the data because "storage" already exists.

Changing <code>assets/mods/my-mod/assets/data/test.json.patch</code> to:

<source lang="js">
[{
"type": "INIT_KEY",
"index": "storage2",
"content": {
"a": 2
}
}]
</source>

would result in:

<source lang="js">
{
"storage": {
"user": {
"name": 20
}
},
"storage2": {
"a": 2
}
}
</source>

=== REMOVE_ARRAY_ELEMENT ===

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": [1,2,3]
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "REMOVE_ARRAY_ELEMENT",
"index": 0
}]
</source>

Applying the patch will result in this:

<source lang="js">
{
"a": [2,3]
}
</source>

=== ADD_ARRAY_ELEMENT ===

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": [1,2,3]
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "ENTER",
"index": "a"
},{
"type": "ADD_ARRAY_ELEMENT",
"content": 4
}, {
"type": "ADD_ARRAY_ELEMENT",
"index": 0,
"content": 0
}, {
"type": "EXIT"
}]
</source>

After the first step, the internal state will be:

<source lang="js">
[1,2,3]
</source>

After the second step, the number 4 will be pushed to the end of the array:

<source lang="js">
[1,2,3,4]
</source>

After the third step, the number 0 will be added to the start of the array:

<source lang="js">
[0,1,2,3,4]
</source>

The last step will revert the value of focus to the initial object:

<source lang="js">
{
"a": [0,1,2,3,4]
}
</source>

=== Import ===

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": {
"b": 2
}
}
</source>

This is the contents of <code>assets/data/test2.json</code>:

<source lang="js">
{
"b": {
"a": 2
},
"c": {
"a": 3
},
"d": 4
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "IMPORT",
"src": "data/test2.json"
}]
</source>

This is equivalent to:

<source lang="js">
[{
"type": "IMPORT",
"src": "game:data/test2.json"
}]
</source>

The first step would load <code>assets/data/test2.json</code> then merge it with the current value resulting in this:

<source lang="js">
{
"a": {
"b": 2
},
"b": {
"a": 2
},
,
"c": {
"a": 3
},
"d": 4
}
</source>

If <code>assets/data/test2.json</code> had patches associated with it, it would be applied before being merged.

Another feature is loading json files inside the mod directory and merging. No patches to the loaded file will be done if <code>mod:</code> is specified.

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": {
"b": 2
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "IMPORT",
"src": "mod:patches/data/test.json",
"path": ["1", "2", "3"],
"index": "y"
}]
</source>

This is the contents of <code>assets/mods/my-mod/patches/data/test.json</code>:

<source lang="js">
{
"1": {
"2": {
"3": 4
}
}
}
</source>

First it will load <code>assets/mods/my-mod/patches/data/test.json</code>.

Then it will walk the path specified.

Initial loaded file internal representation:

<source lang="js">
{
"1": {
"2": {
"3": 4
}
}
}
</source>

After entering "1":

<source lang="js">
{
"2": {
"3": 4
}
}
</source>

After entering "2":

<source lang="js">
{
"3": 4
}
</source>

After entering "3":

<source lang="js">
4
</source>

Finally, it will add a key "y" with the value that resulted from the path walk (4).

So the overall result will be:

<source lang="js">
{
"a": {
"b": 2
},
"y": 4
}
</source>

Note: "index" and "path" options are optional.

=== Include ===

The purpose of <code>INCLUDE</code> is to allow external Object Patching or PatchSteps to be performed.

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": {
"b": 2
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "INCLUDE",
"src": "mod:patches/data/test.json",
}]
</source>

This is the contents of <code>assets/mods/my-mod/patches/data/test.json</code>:

<source lang="js">
{
"1": {
"2": {
"3": 4
}
}
}
</source>

This is like setting the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code> to:

<source lang="js">
{
"1": {
"2": {
"3": 4
}
}
}
</source>

However, <code>INCLUDE</code> is used as an organization method.

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": {
"b": 2
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "INCLUDE",
"src": "mod:patches/data/test.json",
}, {
"type": "SET_KEY",
"index": "b",
"content": [1,2,3]
}]
</source>

This is the contents of <code>assets/mods/my-mod/patches/data/test.json</code>:

<source lang="js">
[{
"type": "ENTER",
"index": ["a"]
}]
</source>

This results in:

<source lang="js">
{
"a": {
"b": 2
},
"b": [1,2,3]
}
</source>

Think of PatchStep files as its own room. What include does is generate a new room to perform some special operation. Rooms do not intefere with each other, they just modify the data.

=== FOR_IN ===

This PatchStep is useful for combining repeated set of PatchSteps with only slightly variations in input.

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "FOR_IN",
"keyword": "__INDEX__",
"values": [1,2,3,4],
"body": [{
"type": "SET_KEY",
"index": "__INDEX__-id",
"content": "__INDEX__"
}]
}]
</source>

This results in:

<source lang="js">
{
"1-id": "1",
"2-id": "2",
"3-id": "3",
"4-id": "4"
}
</source>

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "FOR_IN",
"keyword": {
"name": "__NAME__",
"id": "__ID__"
},
"values": [{
"name": "Bob",
"id": 1
},{
"name": "Joe",
"id": 2
}],
"body": [{
"type": "SET_KEY",
"index": "__NAME__",
"content": "__ID__"
}]
}]
</source>

This results in:

<source lang="js">
{
"Bob": "1",
"Joe": "2"
}
</source>

=== Copy ===

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": 2,
"b": [3],
"c": {
"d": 4
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "FOR_IN",
"keyword": "__VAR__",
"values": ["a", "b", "c"],
"body": [{
"type": "ENTER",
"index": "__VAR__"
},{
"type": "COPY",
"alias": "alias-__VAR__",
}, {
"type": "EXIT"
}]
}]
</source>

Nothing will change. All this will do is create an internal key-value storage that looks like this:

{ "alias-a": 2, "alias-b": [3], "alias-c": { "d": 4 } }

=== PASTE ===

This command relies on COPY.

This is the contents of <code>assets/data/test.json</code>:

<source lang="js">
{
"a": 2,
"b": [3],
"c": {
"d": 4
}
}
</source>

This is the contents of <code>assets/mods/my-mod/assets/data/test.json.patch</code>:

<source lang="js">
[{
"type": "FOR_IN",
"keyword": "__VAR__",
"values": ["a", "b", "c"],
"body": [{
"type": "ENTER",
"index": "__VAR__"
},{
"type": "COPY",
"alias": "alias-__VAR__"
},{
"type": "EXIT"
},{
"type": "SET_KEY",
"index": "__VAR__"
}]
}, {
"type": "SET_KEY",
"index": "saved",
"content": {}
}, {
"type": "ENTER",
"index": "saved"
}, {
"type": "FOR_IN",
"keyword": "__VAR__",
"values": ["a", "b", "c"],
"body": [{
"type": "PASTE",
"alias": "alias-__VAR__",
"index": "__VAR__"
}]
}]
</source>

This is the result:

<source lang="js">
{
"saved": {
"a": 2,
"b": [3],
"c": {
"d": 4
}
}
}
</source>

=== Debug ===

<source lang="js">
[{
"type": "DEBUG",
"value": true
}, {
"type": "DEBUG",
"value": false
}]
</source>

This PatchStep turns Debug Mode on or off.

=== Comment ===

Debug mode must be on for this PatchStep to work.

<source lang="js">
[{
"type": "DEBUG",
"value": true
},{
"type": "COMMENT",
"value": "This is a comment"
}, {
"type": "COMMENT",
"value": {
"data": 3
}
}]
</source>

This will first display <code>This is a comment</code> in the DevTools console. It will then display <code>{data: 3}</code>.

[[Category:Modding guides]]