PlayerPrefs and SaveData

Polygon Engine stores project data in one 8,192-byte Memory Card block on Port

1. Editor Play Mode uses a JSON mirror with the same fixed entry and string limits. Use PlayerPrefs for typed gameplay settings and progress; use SaveData when a system deliberately needs raw string storage.

Limits

Item	Limit
Total entries	32
Physical key	31 bytes plus terminator
Value	63 bytes plus terminator
Memory Card allocation	One block
Active card	Port 1

For PlayerPrefs, use keys of up to 28 bytes and strings of up to 61 bytes. These limits count UTF-8 bytes, so accented characters can use more than one byte. Typed and raw values share the same 32-entry store.

PlayerPrefs

SetInt, SetFloat, and SetString return false when a value cannot be encoded. Their getters accept an optional default. HasKey, DeleteKey, and DeleteAll manage only PlayerPrefs entries; DeleteAll does not erase raw SaveData keys. Save flushes the complete store.

function CompleteChapter(gameObjectId)
  if not PlayerPrefs.SetInt("chapter", 2) or not PlayerPrefs.Save() then
    Log.Print("Save failed: " .. SaveData.GetLastError())
  end
end

function Start(gameObjectId)
  local chapter = PlayerPrefs.GetInt("chapter", 0)
  local volume = PlayerPrefs.GetFloat("volume", 1.0)
  local language = PlayerPrefs.GetString("language", "en")
end

SaveData

Method	Purpose
SaveData.Write(key, value)	Changes one raw string value in memory.
SaveData.Read(key)	Returns a raw string or nil.
SaveData.Delete(key)	Removes one key in memory; returns true even if it was absent. Call Flush to persist the deletion.
SaveData.Flush()	Persists the complete in-memory store.
SaveData.Clear()	Clears all typed and raw entries in memory.
SaveData.Reload()	Reads the platform store; check success before using the result.
SaveData.GetLastError()	Returns the latest persistence diagnostic.

Always check the results of writes, PlayerPrefs.Save, SaveData.Flush, and SaveData.Reload. Show a player-facing success or failure state, and never assume a card is present, formatted, writable, or has a free block.

Use View > Save Data Simulator to inspect payload usage and simulate an absent, full, or corrupt card before building. Configure a unique Save File ID and a readable Display Title in Project Settings for your game.

Saving and loading progress

Setters change the current values. Call PlayerPrefs.Save() or SaveData.Flush() to save them, and check the result before showing a success message. If saving fails, offer a retry and keep the player's progress available.

Use SaveData.Reload() when the player chooses to load their last save. Check its result before moving the player or applying saved settings. A successful load replaces unsaved changes. The Two-Room Relay tutorial shows a complete save, load, reset, and retry flow.

Testing a Memory Card

In DuckStation, enable a Memory Card in Slot 1 and select a writable card file. A new save needs one free block. Use the same card when reopening the game; per-game card settings can select a different file after changing the disc title. Do not format a card that contains saves you want to keep.

On PS1, saving and loading are synchronous and can take a few seconds. The runtime pauses CD-XA music during card access and restarts the track afterward. Wait for the success or failure message before removing the card or resetting the console. You do not need to stop music from your save script.

If saving fails, read SaveData.GetLastError() immediately, before another SaveData call changes the diagnostic. Check Slot 1, available space and write access, then offer a retry. A working Play Mode save does not verify the emulator's Memory Card configuration.