Persistent Variables

Persistent Variables

Variables can be saved by simply using by persistent() to declare the variable. Once this is used any value that is set to that variable will be saved across sessions. This is using Kotlin's property delegation to control the variable's setter and save it to the file system.

Basic Usage

var someStringVariable by persistent("Some String")

println(someStringVariable)

someStringVariable = "Some Other String"

The first time this code is run, it will print out Some String, however, the second time it is run and all times after that, it will print out Some Other String. Some String is simply the default or initial value that this variable will have. Once the variable is set, it will have that variable even between sessions.

Supported Types

This persistence functionality does not yet support full serialization of objects and currently only supports the main primitive types and strings:

• String
• Int
• Long
• Float
• Double

Instanced Persistence

If you need to save a variable inside an object and that object will have many different instances, then this persistence functionality needs some kind of ID to identify which instance it is a part of.

class SomeClass(string: String) {
    // This will cause issues if there are multiple instances of this class
    private var variable by persistent(string)

    fun setValue(string: String) {
        variable = string
    }

    override fun toString() = variable
}

fun main() {
    Game.configure {
        setFullscreen(false)
    }

    val class1 = SomeClass("class1")
    val class2 = SomeClass("class2")

    class1.setValue("assigning class1 again")
    
    println(class1)
    println(class2)

    Game.terminate()
}

The intended behaviour here is for class1 to print out assigning class1 again while class2 prints out class2. But if you run this code you will find that both classes print out assigning class1 again. This is because the persistence has only saved 1 variable under SomeClass.variable, if there are 2 classes it still assumes that they both contain the same variable. To fix this, an ID can be assigned to the variable and this will allow the persistence to distinguish between them. The ID has to be in the form of a string. The following code should now print out the values as expected:

fun main() {
    Game.configure {
        setFullscreen(false)
    }

    val class1 = SomeClass("class1", "1")
    val class2 = SomeClass("class2", "2")

    class1.setValue("assigning class1 again")

    println(class1)
    println(class2)

    Game.terminate()
}

class SomeClass(string: String, id: String) {
    private var variable by persistent(string, instance = id)

    fun setValue(string: String) {
        variable = string
    }

    override fun toString() = variable
}

Storage

All this data is saved on the user's machine. The default location for the data is in a folder called Mechanica in the AppData folder. The full path in windows should be something like: C:/Users/<UserName>/AppData/Roaming/Mechanica/<package>/res/data where UserName is the windows user name and package is the name of the package where the main method was called which went on to invoke the persistence.

Inside this folder there should be a json file which represents all the different variables that were persisted.