Mod Game Data Storage

Mods can store data about a game in one of four buckets, listed below.

Note that all of these are specific to just your mod. You will never see another mod's data in here and you can be sure that nothing you write will conflict with what another mod writes.

Mod.Settings

Mod.Settings should be used to store configuration options that players set when creating a game with your mod. Once a game is created, they can never be changed. They also get stored in templates.

All hooks can read from Mod.Settings, but the only place that it can be written to is in the Client_SaveConfigureUI hook.

Mod.PublicGameData

Mod.PublicGameData is used to store information about a game that everyone can see (all players in the game plus spectators). It can be read and written from any server hook. It can be read from any client hook except Client_PresentSettingsUI, Client_PresentConfigureUI, and Client_SaveConfigureUI. It can never be written to from any client hook.

Note that Mod.PublicGameData must be a lua table, and when writing to it, you must assign a table directly in instead of changing something in the table. For example:

Wrong:

 Mod.PublicGameData.someField = 'hello'

Right:

 local publicGameData = Mod.PublicGameData
 publicGameData.someField = 'hello'
 Mod.PublicGameData = publicGameData

Mod.PrivateGameData

Mod.PrivateGameData is identical to Mod.PublicGameData in every way except that it cannot be read from any client hooks. This is useful if you want private information that players should not know about.

Mod.PlayerGameData

Mod.PlayerGameData is used to store data that only one player in the game will be allowed to view. This is a table indexed by player ID. For example, to store private information about a player whose ID is 12345, a mod could do this in a server hook:

 local playerGameData = Mod.PlayerGameData;
 playerGameData[12345] = { Secret='attack jim' }
 Mod.PlayerGameData = playerGameData;

This would store data that would only be delivered to player 12345. While server hooks must specify the player ID when writing to Mod.PlayerGameData, client hooks only deal with a single player (the signed in player on the client), so the extra index is not necessary. Therefore, clients can read it as such:

 if Mod.PlayerGameData.Secret == 'attack jim' then ...

Note that the information placed into the player index must be a table, and like Mod.PublicGameData the final table must be written into Mod.PlayerGameData for it to persist correctly.

Mod.ClientStorage

Mod.ClientStorage is a table that client hooks can read and write. It's saved on the player's device.

Use it to remember things about a game for the player, such as:

• a display preference
• whether you've already shown them a message
• what they last saw

It works like the other tables. Reading it returns a copy, so changes to the copy aren't saved until you assign a table back to it:

local storage = Mod.ClientStorage;
storage.TimesOpened = (storage.TimesOpened or 0) + 1;
Mod.ClientStorage = storage;

Assign nil to delete everything your mod stored for the game.

Mod.ClientStorage is different from the other game data storage tables in these ways:

• It's on the device. Nothing is sent to the server. Other players can't see it, and it isn't shared between the player's devices.
• It's separate for each game, each signed-in player and each mod. Nothing your mod stores in one game is visible in another game.
• It's only available in a game. Using it outside one is a mod error, for example in Client_PresentConfigureUI, Client_SaveConfigureUI or Client_CreateGame.
• It's only available in client hooks. Server hooks can't read it, not even in single-player games.
• It isn't permanent. The device keeps it for the 15 games most recently opened that a mod stored something in, and deletes it for older games. Players can also lose it by clearing their browser's data or reinstalling the app. Mods should always work with an empty table.

Limits:

• It must be a table, or nil. Assigning anything else is a mod error.
• It can be up to 32,000 characters once serialized. Assigning a bigger table is a mod error.
• After a failed assignment, what was stored before is unchanged.

See Also

• Mod Developers Guide