Modding TAXINAUT

TAXINAUT is written in Java so to be able to mod TAXINAUT you have to learn a little bit about programming in Java. The goal is to get you setup with a working starting point, that is: A Java developement environment called Eclipse, and a mod for TAXINAUT, loaded into it, that you can thinker with.

There are 3 videos

1. The basics of Java (watch here)
2. Programming in Java with Eclipse (watch here)
3. Adding a planet to TAXINAUT (watch here)

This is the accompanying webpage to these videos containing some of what I say there together with links to tools and other resources used in these videos

1. The basics of Java (video 1)

View the video for this here.

What is Java

Java is a programming language and runtime environment that's been around since the 90s. It tried to free developers from the shackles of a particular platform like Windows through its "write once, run anywhere" promise which guaranteed developers that the same code written on one platform would run as is on all other supported platforms. It also introduced automatic memory-management which greatly reduces the complexity of programming and thus the possibility of bugs. Java is not the same as Javascript.

There are 4 components to creating and running a Java program:

1. The source-code: A set of plain text files (like you type in notepad) with a .java extension containing the program code in the Java Programming Language.
2. An application called a compiler which is used to convert the .java source files into .class files.
3. The resulting Java .class files: these are the finished application files that you give to your customer (like .exe and .dll files for regular Windows applications).
4. An application called the Java Virtual Machine or JVM which is used to run the .class files in a similar way that a video-player applications runs .mp4 files.

The source-code we will create ourselves using notepad. The compiler and JVM are part of a Java Development Kit (JDK) which is just a set of applications you can download for free from several sources. For this demonstration I will use the openJDK.

In the video I have setup a command-prompt that can use the compiler (javac) and the JVM (java) that came with the JDK.

There is no need for you to download a JDK or do anything I do in this video yourself: in the second video we will download and install a different application called Eclipse to run and create Java applications with. Eclipse includes a JDK and is much more comfortable to use. I only do it this way here to demonstrate the bare-bones of what is needed to develop Java applications in an attempt to demystify the process.

If you're nonetheless interested, the openJDK can be obtained somewhere through here or maybe more specifically here or here.

Creating an application in Java

In applications there are types of things. For example in TAXINAUT there are things that are a type of ship, things that are a type of planet, things that are a type of NPC and so on.

In Java a type of thing is called a class. And each of these classes is represented by a .class file. So somewhere in the TAXINAUT install directory you'll find: ship.class, planet.class, NPC.class and many more.

Each of these .class files was created with a compiler from a plain text .java file with the source-code for that class in it. So in my TAXINAUT project directory there is: ship.java, planet.java, NPC.java, etc.

We're going to create an application that has people in it. People are a type of person so for that we will create a class called Person. We do this by creating a text file called Person.java in notepad and we're going to type the source-code for the Person class into it.

In the video I go through this in steps and explain more about what the code means.

class Person {

	public static void main(String[] args) {
		Person p1 = new Person("Lois");
		p1.sayHelloTo("Jasper");
		Person p2 = new Person("Clark");
		p2.sayHelloTo("Pierre");
	}

	String name;

	Person(String s) {
		name = s;
	}

	void sayHelloTo(String other) {
		System.out.println("Hello " + other + " I'm " + name);
	}

}

We then compile Person.java into Person.class as follows:

javac Person.java

Now that we have a Person.class file we can run that with our JVM as follows:

java Person

The JVM (java) will look for a function called "main" in the Person class and execute the code in that function resulting in the following output:

Hello Jasper I'm Lois
Hello Pierre I'm Clarke

2. Programming in Java with Eclipse (video 2)

View the video for this here.

Eclipse

In the previous video I used a set of command-line tools called the JDK to compile and run our Person Java application. These tools are however very bare-bones and don't provide much extras. So, instead we will start using a much more comfortable application called Eclipse. Eclipse is an Integrated Development Environment or IDE for programming in Java and contains the editor (previously we used notepad), the compiler (previously we used javac) and many other tools all under one user-interface.

You can download the latest version of Eclipse, for free, from the Eclipse Foundation website at https://www.eclipse.org/downloads/.

The following instructions are for how things were in June 2023, Eclipse verion: 2023-06 (4.28.0); things might be different now.

1. Download and run the installer.
2. A popup will show: Click "Eclipse IDE for Java Developers".
3. You can change the installation folder etc. but I would leave things as they are: Then click "INSTALL".
4. A license confirmation shows: click "Accept".
5. If it says the "Installation process is taking longer than usual", don't worry.
6. If a popup comes up asking "Do you trust unsigned content from unknown origin" just tick the checkbox on the listed types and click "Trust Selected".
7. Click "LAUNCH" or double click the Eclipse shortcut on your Desktop
8. A popup will appear asking you to "Select a directory as workspace"; this will be the directory where your project files like .java source files and .class files will reside. Either note the directory so you can find it later or pick a directory you like.

The rest of the instructions are in the video. Here are links to the materials used in the video:

• game.src.zip The source-code discussed in the video and also printed below.
• gamelib.jar The "game library" used.
• gamelib documentation.
• Java API documentation.
• gamelib.src.zip Not needed but if interested: the source-code for the "game library".

What follows is the source-code that's discussed in the video:

package net.mosgrom.modvid.game;

import net.mosgrom.modvid.gamelib.Space;

public class Game {

	public static void main(String[] args) {
		Space space = new Space();
		PlayerShip player = new PlayerShip();
		space.addShip(player);
		NPCShip npc1 = new NPCShip();
		space.addShip(npc1);
		NPCShip npc2 = new NPCShip();
		space.addShip(npc2);
	}
	
}


package net.mosgrom.modvid.game;

import java.awt.Color;
import java.awt.Graphics;
import java.awt.event.MouseEvent;
import java.awt.event.MouseListener;

import net.mosgrom.modvid.gamelib.Ship;
import net.mosgrom.modvid.gamelib.Space;


public class PlayerShip extends Ship implements MouseListener {
	
	@Override
	public void shipAdded(Space s) {
		s.addMouseListener(this);
	}
	
	@Override
	public void update(Graphics g) {
		updateLocation();
		g.setColor(Color.YELLOW);
		g.fillRect(location().x, location().y, 32, 32);
	}
	
	@Override
	public void mouseClicked(MouseEvent e) {
	}

	@Override
	public void mousePressed(MouseEvent e) {
	}

	@Override
	public void mouseReleased(MouseEvent e) {
		setCourse(e.getPoint(), 0.1);
	}

	@Override
	public void mouseEntered(MouseEvent e) {
	}

	@Override
	public void mouseExited(MouseEvent e) {
	}

}


package net.mosgrom.modvid.game;

import java.awt.Color;
import java.awt.Graphics;
import net.mosgrom.modvid.gamelib.Ship;
import net.mosgrom.modvid.gamelib.Space;


public class NPCShip extends Ship {

	Space space;
	
	@Override
	public void shipAdded(Space s) {
		space = s;
	}
	
	@Override
	public void update(Graphics g) {
		if (destinationReached()) {
			setCourse(space.randomLocation(), 0.2);
		}
		updateLocation();
		g.setColor(Color.red);
		g.fillOval(location().x, location().y, 32, 32);
	}

}

3. Adding a planet to TAXINAUT (video 3)

View the video for this here.

Modding overview

TAXINAUT mods consist of Java class files and resources like image and sound files. All mods have a unique name and numeric id called mod-name and mod-id. To install a mod its files are placed under the mod directory of your TAXINAUT installation-directory (I will refer to the TAXINAUT installation-directory as taxi-dir).

For more information on how to find your taxi-dir go here.

In this demonstration I will be creating a mod with mod-name "example" and mod-id 101. The mod will add a planet to TAXINAUT called "Domo" and give the player an item (called "domocast") that teleports them to Domo when clicked. Your installation of TAXINAUT comes with the source-code and resources for this mod in:

taxi-dir\doc\mod\example\

Starting a new mod project

To start a new mod you need 4 things:

• mod-id: This is a unique numeric id that TAXINAUT (and you) will require to distinguish between mods. The example mod discussed here uses 101. For your own mod you can start with 102. If you have a mod you want to share with others I would recommend you register it with the TAXINAUT MOD REGISTER so you can "reserve" a unique mod-id and mod-name.
  
  
• mod-name: This is a unique name made up out of just lower-case letters and perhaps a digit at the end. It must be the same as the Java package name for your mod's classes.
  
  
• A new Eclipse mod project. The video shows in detail how to set this up.
  
  
• mosgrom.jar: This is a Java class-library that comes with your installation of TAXINAUT. It provides the libraries needed to create TAXINAUT mods. You can find it at:

  taxi-dir\doc\mod\mosgrom.jar

  I recommend you create a copy in your mod project directory and then add it to the project's build-path. The video shows in detail how to do this.
  You might also want to look at the (very rudimentary) documentation for some of the classes in mosgrom.jar. It also comes with your installation of TAXINAUT at:

  taxi-dir\doc\mod\javadoc\index.html

  You should be able to just double-click the index.html file to open it in your browser.
  
  
  Note that mosgrom.jar, its documentation or anything else from the TAXINAUT installation folder is NOT TO BE SHARED (even with other owners of TAXINAUT). DO NOT package mosgrom.jar or anything else from TAXINAUT with your mod and put it up for download somewhere. See the EULA (especially section 2.7.) for more details on what you can and cannot do with mods.

The main module

Every TAXINAUT mod must define a Main class:

package taximod.mod-name;

import net.mosgrom.taxi.module.BaseModule;

public class Main extends BaseModule {

	@Override
	public int id() {
		return mod-id;
	}

}

The rest is shown in the video.

Installing a mod

To use mods You will need to enable mods in TAXINAUT. You can find the setting in your TAXINAUT SETTINGS under "TOOLS". It's called "Allow mods" and should be set to "YES".

There are 3 types of files in a mod:

• modules
• plugins
• data

Modules

These are class files that once loaded always remain in memory. This includes the Main class for your mod and things like equipment and other items that your mod adds to TAXINAUT. All Module classes must be defined somewhere under package:

package taximod.mod-name;

taxi-dir\mod\mod\

package taximod.mod-name.foo;

class Bar {
}
	

taxi-dir\mod\mod\taximod\mod-name\foo\

taxi-dir\mod\mod\

Plugins

These are class files that are loaded when needed and immediately removed from memory once TAXINAUT is done with them. Think of these as scripts. This includes things like loader-plugins that define and add the various planets, NPCs, items, etc. that are part of your mod, dialog-plugins and UI-plugins. All plugin classes must be defined somewhere under package:

package taxiplg.mod-name;

taxi-dir\mod\plg\

Data

These are resource files like images and sounds. Data is placed under:

taxi-dir\mod\dat\mod-id\

Example

For our example mod its installation would be as follows:

taxi-dir\mod\mod\taximod\example\Domocast.class
taxi-dir\mod\mod\taximod\example\Main.class
taxi-dir\mod\plg\taxiplg\example\ItemsLoader.class
taxi-dir\mod\plg\taxiplg\example\Setup.class
taxi-dir\mod\plg\taxiplg\example\SetupsLoader.class
taxi-dir\mod\plg\taxiplg\example\SiteSetsLoader.class
taxi-dir\mod\plg\taxiplg\example\SitesLoader.class
taxi-dir\mod\dat\101\dome.png
taxi-dir\mod\dat\101\domecasticon.png
taxi-dir\mod\dat\101\pyramid.png

taxi-dir\mod\mod\example.jar
taxi-dir\mod\plg\taxiplg\example\ItemsLoader.class
taxi-dir\mod\plg\taxiplg\example\Setup.class
taxi-dir\mod\plg\taxiplg\example\SetupsLoader.class
taxi-dir\mod\plg\taxiplg\example\SiteSetsLoader.class
taxi-dir\mod\plg\taxiplg\example\SitesLoader.class
taxi-dir\mod\dat\101\dome.png
taxi-dir\mod\dat\101\domecasticon.png
taxi-dir\mod\dat\101\pyramid.png

How to install a TAXINAUT mod is shown in more detail in the video.

Packaging a mod

There are currently no standards or tools for packaging TAXINAUT mods. I would recommend that you put all your mod files in a .zip file that mirrors the structure in which they should be placed under the taxi-dir\mod directory. So for our example mod the root directory of the zip file would be as follows:

mod\taximod\example\Domocast.class
mod\taximod\example\Main.class
plg\taxiplg\example\ItemsLoader.class
plg\taxiplg\example\Setup.class
plg\taxiplg\example\SetupsLoader.class
plg\taxiplg\example\SiteSetsLoader.class
plg\taxiplg\example\SitesLoader.class
dat\101\dome.png
dat\101\domecasticon.png
dat\101\pyramid.png

mod\example.jar
plg\taxiplg\example\ItemsLoader.class
plg\taxiplg\example\Setup.class
plg\taxiplg\example\SetupsLoader.class
plg\taxiplg\example\SiteSetsLoader.class
plg\taxiplg\example\SitesLoader.class
dat\101\dome.png
dat\101\domecasticon.png
dat\101\pyramid.png