State.encode
luastra/stateState.encode(version: number, fields: Fields): string
Serializes a finite field map together with an explicit positive version into Luastra's deterministic snapshot format. The output is suitable for host storage and can be compared or migrated predictably.
Before you use it
Add luastra/state to this module's dependencies in luastra.json, then import it with require("luastra/state"). No capability is required for encoding, decoding, or migration. Persistence additionally needs luastra/host plus storage.get and storage.set.
How it fits
State operations run synchronously over bounded string fields. Encode before storage; after a read, decode or migrate and branch on success before mutating trusted application state.
When to use it
Use State.encode immediately before Host.storageSet when small application state must survive restarts. Persist only bounded non-secret data and increment the version whenever the stored schema changes incompatibly.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| version | number | Positive schema version written into the snapshot envelope. |
| fields | Fields | Bounded serializable string field map representing current application state. |
Returns
string — the validated canonical string produced by this operation.
What happens next
A deterministic encoded snapshot or a tagged success/failure result.
Failures and fixes
Malformed data, wrong versions, missing migration steps, excessive size, or non-string fields remain explicit failure branches. Do not silently replace corrupt security- or domain-sensitive values with defaults.
Availability
Public-source alpha API in 0.5.0-alpha; persistence support is host-dependent.
Focused example
local State = require("luastra/state")
local snapshot = State.encode(1, { score = tostring(score), screen = "game" })Continue with a complete recipe
This checked recipe uses State.encode inside complete authored files with the required manifest, test, and run steps.
Open persist and restore state recipe