Database¶

In the previous tutorial we allowed events to change the information displayed by the plugin, however the plugin would forget this information when it was shut down and restarted. In this section we cover saving information for use between gameplay sessions.

Previous tutorial¶

Events

This tutorial assumes you have already completed the previous tutorial, and have a main.lua file with UI elements, config lookup, and event subscription in which to copy snippets of code.

Objectives¶

• Creating a database
• Retrieving and saving variables
• Using and updating variable

The database¶

Each plugin has access to a database called PersistentDB where it can store information between sessions. This means that a plugin does not have to forget everything between the times that the game client is started or stopped. The database is separated per plugin, so information saved by one plugin cannot be seen or overwritten by any other plugin.

In computer terms: variables in the plugin are stored in memory, but variables in the database are written to a file. This means that the database is more secure, but slower to read and write information. Therefore there will always be a tradeoff between which is used for any given action.

In this example, we will be using the database to track the number of times that the stray dog has been petted, so that it doesn't reset to 0 between the times that the plugin is enabled.

Creating the variable¶

Variables in the database are much like variables used by Lua in general because they are accessed by a name. The following example will attempt to retrieve that variable called databaseNumber from the database, and use it within the plugin under the name numberOfPets. Note that creating and retrieving a variable needs to happen earlier in the lua script than anywhere that uses that variable. Since we intend to track the number of times that the stray dog has been petted, we need to place this code before section 12 that subscribes to the event for petting the dog. Thankfully, code section 5 is empty due to changing the behaviour of the button, so this code can be inserted into section 5.

-- Code section 5 version 3
-- Start a persistent counter for number of pets
local numberOfPets = PersistentDB:Get("databaseNumber") or 0

The or 0 at the end of this line handles the case where the variable databaseNumber was not found in the database. This will happen the first time that the plugin is installed, as no value has been saved into the database yet. In this case, we simply need to say that we start the tracker at the number 0.

Using the variable¶

Now that numberOfPets is present as a variable available to the plugin, we need a way to update the value of the variable (when the stray dog is pet) and a way to make use of that value (to update the UI). To increment the counter and display it, change code section 12 as follows:

-- Code section 11 version 2
-- Check every minimenu interactions with dogs
local function checkForMinimenu(event)
    if event.entry.npcData~=nil and event.entry.npcData.entity.config.name==strayDogName and event.entry.verbText=="Pet" then
        numberOfPets = numberOfPets + 1
        myText.content = formatStr("You have pet the dog<br>It is happy<br>Your streak is {}",numberOfPets)
    elseif event.entry.npcData~=nil and event.entry.npcData.entity.config.name==strayDogName and event.entry.verbText=="Shoo away" then
        numberOfPets = 0
        myText.content = "You have shoo'd the dog<br>You monster<br>Your streak is 0"
    end
end
Event.MiniMenuEntrySelected.Subscribe("minimenuEvent",checkForMinimenu)

This makes two changes to the minimenu event callback function:

1. When the pet option is selected, the number of pets is incremented and displayed.
2. When the shoo option is selected, the number of pets is reset to zero.

Saving the variable¶

To save the variable back into the database, the command is simply PersistentDB:Set("databaseNumber",numberOfPets). But when do we run this save function? We want it to happen when you close the plugin or client, so we will put it inside of an event that happens when we want the save to happen.

The plugin API also allows you to define a function PluginShutdown() that will be run whenever the plugin is disabled, including when the client closes. This is similar to an event, in that it is triggered automatically when the shutdown occurs, but it does not need to be subscribed to. Instead, simply naming the function PluginShutdown() will mean that it is run when the plugin is shut down.

-- Code section 12
-- Shutdown function that saves the database
function PluginShutdown()
    PersistentDB:Set("databaseNumber",numberOfPets)
end

However this does rely on the plugin being shutdown in a controlled manner. Logging out of the client, closing it without logging out, or even force closing the client via task manager will all still save the value to the database, but if the client crashes then the database will not be saved and the information will be lost. Perhaps you can think of a way to change this tutorial plugin so that it will save the database even if the client crashes?

Next tutorial¶

Developer cheats

Resources¶

• Persistent DB