Skip to content

Save files and persistence

Rift saves your game to a database, but you never write SQL or any code that touches it. If you’ve used an ORM, it works like one. Rift stores your components as tables, loads and saves them for you, and updates old saves when you change your components. That last part is called a data migration. You choose what a character saves. Mark a component class with @Persistent, and each field you want to keep with @Persist. Components and systems are covered in The Rift ECS.

scripts/pets/pet.rift
import rift.ecs.Component
import rift.ecs.Persist
import rift.ecs.Persistent
public enum class Species { CAT, DOG, PARROT }
@Persistent
public class Pet(
@Persist var name: String = "",
@Persist var species: Species = Species.CAT,
) : Component()

Saved classes go in a library file, marked public. A script that uses one imports it by name, like any other file:

scripts/pets/pet_names.rift
import pets.Pet
on_login { player ->
val pet = player.findComponent<Pet>() ?: return@on_login
player.message("Your ${pet.species.name.lowercase()} ${pet.name} waves.")
}

Only classes marked @Persistent are saved, and only their @Persist fields. When the player logs in, each saved field goes back into the constructor parameter with the same name. If a saved field isn’t a constructor parameter, it has to be a var.

scripts/pets/pet.rift
@Persistent
public class Pet(
@Persist var name: String = "",
@Persist var species: Species = Species.CAT,
) : Component() {
@Persist var tricksLearned: Int = 0
}

A @Persistent class with no @Persist fields still remembers that the character had it. They get it back at login, just without any values.

Leave @Persist off a field when your systems can rebuild it, or when it only matters for this session. @Synced fields, the values shown in the player’s client, work the same way. They only survive a logout if they’re also @Persist.

scripts/pets/pet.rift
@Persistent
public class Pet(
@Persist var name: String = "",
@Persist var species: Species = Species.CAT,
) : Component() {
// rebuilt every session, not saved
var followingOwner: Boolean = true
}

A component class without @Persistent is never saved, whatever its fields carry.

A field, a list or a map can hold your own class when that class is marked @PersistentValue. Its @Persist fields are saved as part of the component that holds it.

scripts/pets/pet_collection.rift
import rift.ecs.Component
import rift.ecs.Persist
import rift.ecs.Persistent
import rift.ecs.PersistentValue
import pets.Species
@PersistentValue
public class OwnedPet(@Persist val name: String = "", @Persist val species: Species = Species.CAT)
@Persistent
public class PetCollection(
@Persist val pets: MutableList<OwnedPet> = ArrayList(),
) : Component()

Some things belong to the realm rather than to any character, like a clan, a shared bank or a ban list. These are kept in a server plugin’s worldRecords, so this code lives in a server plugin. ClansPackage is that plugin’s public package object. A record class is a plain @Persistent class, not a component, and each record is stored under a text key.

src/main/rift/clans/clans.rift
import rift.ecs.Persist
import rift.ecs.Persistent
@Persistent
public class ClanRecord(@Persist val name: String = "", @Persist val members: List<String> = emptyList())
public val clans = ClansPackage.worldRecords.collection<ClanRecord>()
public fun foundRiftClan() {
clans.put("rift", ClanRecord("Rift", listOf("avatar-1")))
}
public fun riftClan(): ClanRecord? = clans.get("rift")

A server plugin can only see its own records. Saving and renaming work the same for records as for components.

A character is saved:

  • when the player logs out or disconnects
  • on a fixed interval while they play
  • when the realm switches off

To change a character before the realm’s last save, use on_realm_stop.

Add a SaveNow component to a character, and they’re saved at the end of the tick. Use it after anything a player can’t afford to lose, like a rare drop.

scripts/drops/rare_drops.rift
on_world_item_option(Assets.Item.bones, "Take") { subject ->
subject.message("You found a rare bone.")
subject.addComponent(SaveNow())
}

You can also call subject.save(). Only characters can be saved this way. If you add SaveNow to anything else, like an NPC or an object, it logs an error and the component is removed.

Add a new @Persist field and every save gets it. Change or rename a field and Rift notices, then runs a data migration for you automatically.

scripts/pets/pet.rift
// before
@Persistent
public class Pet(
@Persist var name: String = "",
@Persist var species: Species = Species.CAT,
) : Component()
// after: name renamed to nickname, level added. Nothing else to do.
@Persistent
public class Pet(
@Persist var nickname: String = "",
@Persist var species: Species = Species.CAT,
@Persist var level: Int = 1,
) : Component()

Enum values work the same way:

scripts/pets/pet.rift
// before
public enum class Species { CAT, DOG, PARROT }
// after: every saved PARROT is now PARAKEET
public enum class Species { CAT, DOG, PARAKEET }

If Rift can’t tell what you meant, Forge asks you. You can also tell it in code with the old name: @Persist(was = "name").

If you remove a field, an enum value or a component that saved characters still have, the realm won’t start. It tells you what’s missing and how many saved values use it. Forge then asks what those values should become, either another name that exists now or the default. It keeps your answer with your game, so every realm running it does the same thing when it starts.

scripts/pets/pet.rift
// before: 3 characters have a PARROT
public enum class Species { CAT, DOG, PARROT }
// after: Forge asks whether the 3 saved PARROT values become CAT, DOG or the default
public enum class Species { CAT, DOG }

If no saved character has what you removed, the realm starts and logs a single line. If you answer “the default” for a removed component, it stays in the save database, and characters log in without it. Changing a field’s type asks the same question, but the only answer is the default. The old values are kept aside, and characters get the field’s default.

scripts/pets/pet.rift
// before
@Persist var level: Int = 1
// after: Forge asks, and the saved levels become the default
@Persist var level: String = "novice"

Before Rift changes anything that’s already saved, it makes a copy of the save database next to it, named saves.db.before-…, and keeps the five newest copies. Adding fields doesn’t make a copy. The engine and each server plugin handle their own saved components, so Forge only asks you about yours.

Each realm keeps its saves in its own SQLite database, saves.db, in the realm’s saves folder (SAVE_PATH, by default data/saves/). Realms never share one. Inside, each saved component class and record class gets its own table, named after the class, so Pet is stored as pet. Each saved field is a column. Enum values are stored by name, so reordering an enum never changes a save. If a build can’t read a saved component back, it’s left as it is, and nothing writes over it until a build that can read it comes along.