How to setup an attachment

Learn how to make a basic attachment class and add it to a ship

Introduction

Say you want to store data on a particular ship, for example a boolean value on whether its in "turbo mode".

To store this data, you need an attachment. (Why?)

Luckily, setting one up is relatively straightforward.

Steps

Setup a public, final class

The attachment class must be public (so it can be registered), and final (so it cannot be extended).

To make a kotlin class final, simply omit the open keyword

package my.packagename

class MyAttachment()

package my.packagename;

public final class MyAttachment {
    public MyAttachment() {}
}

Add information to the class

Now that you have your class, lets make it actually useful by adding the boolean we want to store.

We can do this by simply storing it in a property and adding a constructor parameter.

package my.packagename

class MyAttachment(var turboMode: Boolean)

package my.packagename;

public final class MyAttachment {
    public boolean turboMode;

    public MyAttachment(boolean turboMode) {
        this.turboMode = turboMode;
    }
}

Keep in mind these values may be accessed on different threads, often the gamethread and/or the physics thread. You may need to make it volatile or a Concurrent class.

Registering the class as an attachment

Attempting to add the attachment to a ship will crash if the attachment has not been registered beforehand.

It's recommended to register your attachments in your mod's constructor.

import org.valkyrienskies.mod.common.vsCore

fun init() {
    vsCore.registerAttachment(MyAttachment::class.java)
}

public MyMod() {
    ValkyrienSkiesMod.getApi().registerAttachment(MyAttachment.class);
}

Adding the attachment to a ship

Now that you have your attachment class registered and ready to go, it's time to add it to a ship.

You can only add attachments to LoadedServerShips. You may need to use getLoadedShipManagingPos instead of getShipManagingPos, or do a (safe) cast.

ship.setAttachment(MyAttachment(true)) // turboMode = true

ship.setAttachment(new MyAttachment(true)); // turboMode = true

Getting the attachment from a ship

A LoadedServerShip is also required for getting your attachment back, for example to check the turboMode of a ship.

ship.getAttachment<MyAttachment>()

ship.getAttachment(MyAttachment.class);

Updating the attachment of a ship

To update the data of an attachment, simply get the attachment, change the value you want to change, then add back the attachment with the updated instance.

For example, to toggle the value of our turboMode:

val attachment = ship.getAttachment<MyAttachment>() 
    // make a new attachment if the ship didn't have one before
    ?: MyAttachment(true) 

attachment.turboMode = !attachment.turboMode
ship.setAttachment(attachment)

MyAttachment attachment = ship.getAttachment(MyAttachment.class);
if (attachment == null) {
    // make a new attachment if the ship didn't have one before
    attachment = new MyAttachment(true);
}
attachment.turboMode = !attachment.turboMode;
ship.setAttachment(attachment);

Last modified: 03 June 2026