Revision as of 20:38, 23 March 2023

Modding

Even though Stoneshard does not have integrated modding support it is still possible to mod the game via external tools, such as UndertaleModTool[1], which allows one to dig into GameMaker Studio game files.
It is also possible to share modded games by sharing the difference between the modded game files compared to the vanilla ones, this is usually done with Delta Patcher[2] software to avoid piracy.

What is required?

Other than a working PC. It is advised to:

Download and use the Bleeding Edge[3] of UndertaleModTool.
Have basic knowledge of coding.
Have an understanding of how GameMaker Studio works

OK but how do I actually mod the game?

Once you have downloaded UndertaleModTool, create a copy of your game files from "SteamLibrary\steamapps\common\Stoneshard" to keep the original's integrity.
Open the "data.win" with the tool. There you can find all the game's objects, be it Scripts, Sprites, GameObjects, or else, create new or edit existing ones. Note that UndertaleModTool is very limited, and you might encounter some files that it can't decompile.
Of course, not everything can be edited that way. for example, as GameMaker Studio saves audio files outside its data.win file, to edit those you will need to add extra files to the game folder.

Tips and tricks

How do I find a specific thing?

In the top left of the window, under "Scripts" and "Builtin Scripts", "Search.csx" can be found. It is a very helpful script that allows you to search any text in all of the scripts.

What if I can't decompile a script?

Always remember that you can still see and edit the assembly code of the script. it might be harder to understand and edit but it could also make an impossible task into a possible one.

Is there a way to debug?

As the debugger in UndertaleModTool does not work with Stoneshard. using the "scr_actionsLogUpdate()" script is an excellent way to achieve a similar result. but that won't work for edits to stuff as the main menu does not include the game's actions log.

I am stuck, Where can i get help?

It depends on what problem you are facing. but both the UndertaleModTool community and Stoneshard modding community are very welcoming and you are advised to visit both at their Discord servers.

Step By Step Example Mod

For this example, we will create a mod that will replace the regular apple from the second floor of the Black Boar Inn with a modded golden apple.

Creation of the sprites

exporting sprites

editing sprites to match the art style

We are going to need to create two sprites.
One for when the new golden apple is on the ground and one for when it is in the player's inventory.
To make the sprites look fitting for the game's art style, in this example, we take the sprites of the apples and recolour them with colours from the sprite of the golden nugget.
To export the images we can go into the sprite pages, by searching their name on the left panel and exporting with the "export all frames" button.
Before we add the new sprites into the game we must first understand the hierarchy and structure of sprites in GameMaker Studio. In GameMaker Studio each gameobject takes its sprite from a sprite file that, takes its sprite from a "texture page item" file that, takes its sprite from an "embedded textures" file, a file that includes a map of multiple sprites. gameobject > sprite > texture page item > embedded textures.
Knowing all that, we need to create a new image that will include both our sprites. It is better to make the image's size a number which is a power of two, in this example 32 by 32 pixels.

making a map of both sprites

Now, add one new embedded texture, two new texture page items and, two new sprites. To do that we need to right-click each category from the left panel and click "add".

adding a new texture page item

the blue areas represent from where in the embedded texture to take the sprite and the red the size of the sprite. for now, fill the red all the same.

Once you have added the new pages, you must first import the new map to the embedded texture. then add the embedded texture to both texture page items and set their borders as in the picture. only once you have done all that you can add the new texture page items to the sprite files.
The sprite files also need to be set up as seen in the picture.

1) the name of the sprite.
2) the size of the sprite.
3) the borders of the sprite. useful if you have empty space to the left and to the right of the sprite.
4) the image of the sprite, where you need to put the texture page item.
5) the mask of the sprite, you can just take the ones from the normal apple sprites.
6) for now just set it up as in the image, almost all of the sprites are set up this way.

Creation of the object

Now that we can safely add the sprites to the new object it is about time we make them.
First, we need to add two new object pages, just like we added the new pages for the sprites, and set them up.

the red areas represent where changes are needed.

It is useful to look at another existing object and to copy how it is set from. So just copy from the corresponding object, the one that will fit the o_inv_apple to o_inv_golden_apple and o_loot_apple to o_loot_golden_apple. Remember to drag and drop the new sprites and not the old ones!
Once we have set up the gameobjects it is time we add scripts to them. In this example, we won't really need to write anything new, but we will need to change a few things.

how to add a new script to a gameobject

As you can see there are many places to add scripts to for each gameobject, each of them trigger at another point, but for now, we are once again only going to copy from the existing apple objects.
To add a new script you need to double-click where you want to add it, and then click on the + sign to the right then double-click to edit.

For o_loot_goloden_apple you just need to copy the scripts from the "create" and "preCreate" types of scripts, but for o_inv_goloden_apple it is a bit more complicated.
For the inventory version, other than the "create" and "preCreate" scripts, you also need to add three different scripts under "other", note that before you click the little + you are going to want to change their subtypes to "User3", "User0" and, "user14". This is because what the code you have just copied, "event_inherited()", does is essentially inheriting the code from their parent object, in this case from o_inv_food, and if the subtypes would have been different the game wouldn't know what script it is supposed to inherit.
In addition to that, we also need to change the "create" script. The last line should be changed to "scr_consum_atr("golden_apple")". The explanation will come up soon.
Now, even thought the gameobjects are complete, you might have noted that nowhere we saw anything about what an apple actually does, not the effects of being eaten nor how much it is worth.
This is because Stoneshard likes to store stats like those in "tables". so we need to find two tables, one that store the text (in many languages) for the name of the apple, and one that stores more important stuff, like the effect of eating the apple or how much times it takes to rot.

It is recommended to save at this point because opening those tables can be very long and may even freeze UndertaleModTool if handled incorrectly.

Those tables are located at "gml_GlobalScript_table_Consumable_Parameters" and "gml_GlobalScript_table_consumables"
To make more sense of what you are seeing you can convert them into sheets via external tools, as seen in the images below.

Sheet made from gml_GlobalScript_table_consumables

sheet made from gml_GlobalScript_table_Consumable_Parameters

Note that WHERE you put your new entry inside the tables is VERY important, going back to the edit we made to the "create" script of o_inv_goloden_apple, the number that was before we changed it to text, what slot from the table the script takes its data from, this is why if you are going to add something in the middle of the table without knowing how it works can cause in all of the other items in the game to read from the wrong place, or to just crash the game.
The reason why we changed the number to text is that we do know what number inside the table our new entry represents. luckily the devs added a way for the script to handle strings as well, as long as it fits the name that we put as our first string in the text we added to the tables.
Of course, you can edit the text and the stats of the new golden apple as you see fit with those entries.

an image of where to put the new text in gml_GlobalScript_table_Consumable_Parameters

an image of where to put the new text in gml_GlobalScript_table_consumables

Adding the golden apple instead of the regular one

To replace the regular apple we must first find what spawns it.
For that we need to open the "room" for the second floor of the Black Boar Inn, its name is "r_taverninside2floor"

The room of the second floor of the Black Boar Inn

Under layers > foregroundInstances we can find an instance of "o_loot_marker", an object that spawns items.

But if you look inside that object it seems like there is nothing in there that helps us! It is full of generic stuff. But we do see what creates the loot, it is "gml_RoomCC_r_taverninside2floor_22_Create". So we should double-click and open that. In the object you will see two lines.The first line in this script represents what is the chance of the item of spawning, this time 100%. But the second line is more interesting "loot = choose(2025)", What do you think "2025" represent?

the script of gml_RoomCC_r_taverninside2floor_22_Create

Each object in GameMaker studio has an id, it can be seen in the downright corner of the objects' page with UndertaleModTool.

And it seems like 2025 is the ID of the regular o_loot_apple. So all we need to do is open our new o_loot_golden_apple, see what is its ID, and replace "2025" with the number we have found.
That is it! if you have done everything correctly you should have a golden apple instead of a regular one. If not, feel free to ask for help.