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.
import rift.ecs.Componentimport rift.ecs.Persistimport rift.ecs.Persistent
public enum class Species { CAT, DOG, PARROT }
@Persistentpublic 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:
import pets.Pet
on_login { player -> val pet = player.findComponent<Pet>() ?: return@on_login player.message("Your ${pet.species.name.lowercase()} ${pet.name} waves.")}Saving a component
Section titled “Saving a component”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.
@Persistentpublic 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.
Keeping state out of saves
Section titled “Keeping state out of saves”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.
@Persistentpublic 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.
Saving values inside a component
Section titled “Saving values inside a component”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.
import rift.ecs.Componentimport rift.ecs.Persistimport rift.ecs.Persistentimport rift.ecs.PersistentValueimport pets.Species
@PersistentValuepublic class OwnedPet(@Persist val name: String = "", @Persist val species: Species = Species.CAT)
@Persistentpublic class PetCollection( @Persist val pets: MutableList<OwnedPet> = ArrayList(),) : Component()Saving things no character owns
Section titled “Saving things no character owns”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.
import rift.ecs.Persistimport rift.ecs.Persistent
@Persistentpublic 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.
When saves happen
Section titled “When saves happen”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.
Saving on demand
Section titled “Saving on demand”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.
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.
Renaming or adding a field
Section titled “Renaming or adding a field”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.
// before@Persistentpublic class Pet( @Persist var name: String = "", @Persist var species: Species = Species.CAT,) : Component()
// after: name renamed to nickname, level added. Nothing else to do.@Persistentpublic class Pet( @Persist var nickname: String = "", @Persist var species: Species = Species.CAT, @Persist var level: Int = 1,) : Component()Enum values work the same way:
// beforepublic enum class Species { CAT, DOG, PARROT }
// after: every saved PARROT is now PARAKEETpublic 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").
Removing a field or a value
Section titled “Removing a field or a value”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.
// before: 3 characters have a PARROTpublic enum class Species { CAT, DOG, PARROT }
// after: Forge asks whether the 3 saved PARROT values become CAT, DOG or the defaultpublic 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.
// 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.
Where saves are stored
Section titled “Where saves are stored”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.