TheoTown modding crash-course

[Wekabu city]

!	Message from: blueflower
	We do allow modding of the game on the desktop version, only. You furthermore may not circumvent protection measurements of the game. See our EULA for more information: viewtopic.php?t=17318

A note upfront

As someone who loves to mod games that practically don't have a modding scene I am aware that some may be unaware of what modding is. Most believe that it is only more or less fraudulent alteration of game behaviour with the goal of piracy in mind. While certainly modding is almost always a grey-area in a legal sense it often can be more tame. This guide is intended for that more tame version. It definitely can be used to circumvent all anti-piracy measures in place, but if you need to use this guide for that purposes you probably can't do what you want to do, but I digress.

Furthermore, this guide only applies to Desktop users. Mobile users are out of luck.

Choosing the mod loader

As you may know, TheoTown is written in Java. For many that is perceived as the end of the world, but we know better. Java's modding ecosystem is one of the most developed thanks to Minecraft and OSRS and most likely it wouldn't be wrong to choose a mod loader from one of these two worlds. However I personally deem them to be unsuited for our purpose. Fabric's loader (which can be used to launch other games) was something arcane when I began my adventures so I don't use it. Modlauncher on the other hand is an undocumented nightmare and even though it could be used to mod other games I really don't believe that anybody does so. As such I'll use the Starloader-launcher (https://github.com/Starloader-project/Starloader) which while it is meant to run galimulator it can run any jar. But just so everybody is aware of it: I have written that application myself alongside most other mod launching equipment we will use here. That makes me feel more comfortable in my adventures, but that might not apply to you.

Alternatively you could be working without a mod loader but I recommend against doing so as that severely impacts multi-mod compatibility.

Choosing your Java

The game's developers recommend using the java from https://java.com but I heavily recommend against using it. That site only hosts Java 8 or older releases which are out-of-date. The Starloader-launcher however requires Java 11 at least, Java 17 or later being recommended. So how do you get that Java? Well there are a few options, some of which I will list for convenience:

• Jetbrains runtime (has DCEVM, but significantly harder to install): https://github.com/JetBrains/JetBrainsRuntime
• Azul Zulu (has JFX, but might be harder to install): https://www.azul.com/downloads/
• Adoptium (plain & simple): https://adoptium.net/

Linux users beware: Your stock OpenJDK from your distro vendor may not work with libGDX (which is used by TheoTown). I recommend using any of the three options listed above, though Azul Zulu has been a particular favourite of mine. This is definitely the case for Fedora (most likely all RHEL distros), and possibly for Ubuntu.

If you intend on using the Jetbrains runtime you must include the java binary on your PATH - the same applies to the other variants, but their installers should handle that process for you.

Another note to linux users (especially Fedora ones): You may need to use "alternatives" to switch your java. Adoptium and Azul Zulu's RPM builds should configure alternatives for you, for the Jetbrains runtime you must configure alternatives in order for it to detect that Jetbrains runtime installation. Alternatives is nice, because it basically nullifies all the nonsense with PATH Windows users need to do.

(Linux only) Setting up Starloader-launcher with TheoMLInit

TheoMLInit is a nice tool that installs Starloader in an instant. It can be downloaded from https://github.com/Geolykt/TheoMLInit/r ... tag/v0.0.2 and is run through

Code: Select all

java -jar theomlinit-0.0.2.jar

or

Code: Select all

java -Dgame_dir=/path/to/theotown/directory -jar theomlinit-0.0.2.jar

.

Setting up Starloader-launcher manually

!	Message from: Wekabu city
	The contents of this section are only known to work when using the ELF format which is used by Linux. While I guess that the same applies to other formats used by Windows or MacOS, that may not actually be the case. And no, you cannot change the format of a binary to be an ELF binary - at least not by any means that I can confirm to be sensical.

Sadly setting up the launcher by hand is a lot harder than doing it with automated tools, but should you be using non-linux platforms you have little alternatives. First of all you need to go to your Theotown installation directory. It can be found by opening Steam, right clicking Theotown, clicking "Properties..." then on "LOCAL FILES" and lastly on "Browse...". In there you copy over the Starloader-launcher fat-jar. The one we need can be downloaded through https://geolykt.de/maven/de/geolykt/sta ... 21-all.jar - the filename must stay "launcher-20221221-all.jar". Furthermore you need to copy over TheoMLInit (in our case https://github.com/Geolykt/TheoMLInit/r ... -0.0.2.jar) to the same directory, renaming it to "TheoMLInit.jar". Then you need to change your TheoTown64 executable (if you are still on x86_32 I am sure java won't run, so you are out of luck for now). Editing it's contents manually can be very nerve-racking as it is a binary file and you may need to fiddle with using different encoding types in order for it to work. More specifically you need to replace any mention of "TheoTown66.lby" to "TheoMLInit.jar". Once you have done that you need to create a "config.json" file in your installation directory (next to the TheoTown64 binary and the Starloader jar). It's contents is as follows:

Code: Select all    Reset

{
  "classPath": [
    "launcher-20221221-all.jar",
    "TheoTown66.lby"
  ]
}

JSON checker

Check

Output: Select all

...

Installing mods

Mods can be installed by copying them over into the "mods" directory (which should be created by launching the game, if it isn't your Starloader installation may be broken).

Creating mods

!	Message from: Wekabu city
	The described process is incomprehensible to anyone without java knowledge. I recommend against creating Theotown mods should you not have previous experience with java.

Mods can be created by creating extensions. I am too lazy to describe the entire workflow considering that 0 people will do that, but basically you need to extend the "de.geolykt.starloader.mod.Extension" class, which is your entrypoint. In order for the mod to be loadable you need to create an "extension.json" within your mod jar. It will look like follows:

Code: Select all    Reset

{
  "entrypoint": "my.nice.mod.MyExtension",
  "name": "MyMod",
  "version": "0.0.1-SNAPSHOT",
  "dependencies": [ "Dependency1", "Dependency2", "Dependency3" ]
}

JSON checker

Check

Output: Select all

...

Unless you love working with OW2 ASM you probably want to use Sponge's Mixin framework. The Starloader-launcher has built-in support for it. To declare a mixin confiugration you can use the "mixinConfig" field in the extension.json. An example using that field is:

Code: Select all    Reset

{
  "entrypoint": "my.nice.mod.MyExtension",
  "name": "MyMod",
  "version": "0.0.1-SNAPSHOT",
  "mixinConfig": "mod-mixins.json",
  "dependencies": [ "Dependency1", "Dependency2", "Dependency3" ]
}

JSON checker

Check

Output: Select all

...

This declares that the "mod-mixins.json" resource within the jar is a Mixin configuration. A mixin configuration looks as follows:

Code: Select all    Reset

{
  "required": true,
  "minVersion": "0.8",
  "package": "my.nice.mod.mixinpackage",
  "target": "@env(DEFAULT)",
  "compatibilityLevel": "JAVA_11",
  "mixins": [
    "MixinClass1",
    "MixinClass2"
  ]
}

JSON checker

Check

Output: Select all

...

As mentioned before you can also work with OW2 ASM Bytecode. To register an ASM Transformer simply call "net.minestom.server.extras.selfmodification.MinestomRootClassLoader.getInstance().addTransformer(myTransformer);" as early as possible, preferably in the static-init block.


The maven coordinates for the dependencies are as follows:

• https://geolykt.de/maven - hosts the starloader jars as well as potemkin theotown jars
• https://repo.spongepowered.org/maven - hosts the mixin jars
• de.geolykt.starloader:launcher:20221221 - current latest launcher release
• de.geolykt:theotown:1.10.93p (classifier: "potemkin") - current Theotown potemkin release

The theotown potemkin jars do not have a maven-metadata.xml and as such you cannot make use of version ranges when working with them.

You can automatically generate potemkin jars yourself by running TTDeploy. It writes a potemkin jar to your mavenLocal as well as writing generated sources to mavenLocal (Quiltflower is used as a decompiler in that process). The coordinates of the written jars follows the pattern "de.geolykt:theotown:gameVersion", where as "gameVersion" is the theotown version extracted from the theotown jar. The potemkin jars themselves may not be legally distributable in certain jurisdictions, where as in others they are. Contact your lawyer before publishing them. Furthermore it should go without saying that the generated soruces jars should not be published whereever you are. The potemkin jars only provide the minimally needed facade needed in order for compilation to succeed, that is only the method declarations are present, the method bodies are empty (kinda as if all methods were abstract).

Already existing mods

Mods prefixed with "(*)" are experimental prototypes, they are only useful for aspiring modders or very curious people.

• (*)Authentic Surfaces

[Rad]

You finally did it, Congrats.

[Wekabu city]

To be fair I knew about this for over a year now. It's just only now that I've written the needed tooling (more specifically TheoMLInit) for it to work.


That being said, running a mod loader is one thing, actually writing mods is another. And I believe that latter may as well never happen due to the complexity of Theotown's codebase. (The best documentation are the lua bindings which you can cross-check with the lua documentation, but even then
the lua documentation is lacking by enormous proportions)

[Rad]

Well you will go down in Theotown history