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/
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
Code: Select all
java -Dgame_dir=/path/to/theotown/directory -jar theomlinit-0.0.2.jar
Setting up Starloader-launcher manually
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
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
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
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
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
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
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.