Value¶

A node in the accessor tree: what you get from indexing your data, e.g. Data[player].Coins or data.Inventory.Sword. Every field is a Value; container fields also expose their children as Values.

The method set is contextual: all fields have Get/Set/Update/ Observe/Changed; number fields add Increment/Decrement; boolean fields add Toggle; array fields add Insert/Remove/…; dictionary fields add Remove/Count/…; Scribe.Timed fields add SetTimed/ExtendTimed/Active. On the client, Set writes are local-only (optimistic UI).

Reserved names

Because method names live on the node, a template field named Get, Set, Count, Remove, etc. is unreachable through the typed accessor. Scribe warns about this in Studio.

Core¶

.Get¶

Value.Get() → T

Returns a copy of the field's current value.

.Set¶

Value.Set(value: T, replicate: boolean?) → T

Writes a new value (validated and clamped per the declarator). Fires Changed, replicates, and returns the stored value. Pass replicate = false to keep the write server-only.

.Update¶

Value.Update(transform: (current: T) -> T, replicate: boolean?) → T

Reads the current value, passes it to transform, and writes the result: a convenient read-modify-write.

.Clone¶

Value.Clone() → T

A deep copy of the value (for tables/buffers you intend to mutate locally).

.Default¶

Value.Default() → T

The field's declared default (a deep copy for tables/buffers, the real datatype for datatype fields). Read-only schema metadata, so it works on the client and server and before data loads. Handy for "reset to default" flows and diffing against the current value.

.Observe¶

Value.Observe(callback: (value: T) -> ()) → () -> ()

Calls callback immediately with the current value, then again on every change. Returns a disconnect function. The go-to for driving UI.

.Changed¶

Value.Changed(callback: (new: T, old: T) -> ()) → () -> ()

Like Observe but fires only on change (no initial call), with both the new and old values. Returns a disconnect function.

Numbers¶

.Increment¶

Value.Increment(amount: number, meta: EconomyMeta?) → number

Number fields only. Adds amount and returns the new value. Pass false instead of meta to keep the write server-only.

Pass an EconomyMeta table to auto-emit an economy event (AnalyticsService:LogEconomyEvent): the currency is this field's name, the ending balance is the post-change value, and TransactionType, ItemSku, and per-currency custom Fields come from the table. Increment defaults the flow to Source.

Data[player].Coins.Increment(50, {
    TransactionType = Enum.AnalyticsEconomyTransactionType.Gameplay,
    ItemSku = "quest_daily_01",
    Fields = { Location = "Lobby" },
})

.Decrement¶

Value.Decrement(amount: number, meta: EconomyMeta?) → number

Number fields only. Subtracts amount and returns the new value. Like Value.Increment but the economy flow defaults to Sink. See the Economy Analytics guide.

.Min¶

Value.Min() → number?

Number fields only. The declared minimum (Scribe.Int(0, { Min = 0 })), or nil if unbounded. Read-only metadata from the shared schema, so it works on both the client and the server, and even before data has loaded. Handy for driving slider ranges or validation off the single source of truth.

.Max¶

Value.Max() → number?

Number fields only. The declared maximum, or nil if unbounded. See Value.Min.

Booleans¶

.Toggle¶

Value.Toggle(replicate: boolean?) → boolean

Boolean fields only. Flips the value and returns the new one.

Arrays & Dictionaries¶

.Insert¶

Value.Insert(value: T, index: number?, replicate: boolean?)

Array fields only. Inserts value (at index, or appended).

.Remove¶

Value.Remove(index: number?, replicate: boolean?) → T?

Array fields only. Removes and returns the element at index (or the last), or nil if empty. (On a dictionary field, Remove(key) deletes that key.)

.RemoveValue¶

Value.RemoveValue(value: T, replicate: boolean?) → (T?, number?)

Array fields only. Removes the first element equal to value, returning it and its former index.

.Find¶

Value.Find(value: T) → number?

Array fields only. The index of the first matching element, or nil.

.Has¶

Value.Has(value: T) → boolean

Array fields only. Whether value is present.

.OnInsert¶

Value.OnInsert(callback: (value: T, index: number) -> ()) → () -> ()

Array fields only. Fires when an element is inserted, with the value and the index it landed at. Returns a disconnect function.

.OnRemove¶

Value.OnRemove(callback: (value: T, index: number) -> ()) → () -> ()

Array fields only. Fires when an element is removed, with the removed value and its former index. Returns a disconnect function.

.OnKeyAdded¶

Value.OnKeyAdded(callback: (key: K, value: T) -> ()) → () -> ()

Dictionary fields only. Fires when a key is added, with the key and its new value. Returns a disconnect function.

.OnKeyRemoved¶

Value.OnKeyRemoved(callback: (key: K, value: T) -> ()) → () -> ()

Dictionary fields only. Fires when a key is removed, with the key and its former value. Returns a disconnect function.

.Count¶

Value.Count() → number

Array/dictionary fields. The number of elements/keys.

.Clear¶

Value.Clear(replicate: boolean?)

Array/dictionary fields. Removes all entries.

Timed¶

.SetTimed¶

Value.SetTimed(value: T, seconds: number, replicate: boolean?)

Scribe.Timed fields only. Sets value for seconds, after which it auto-clears back to the declared default (firing Changed). Durations floor to 1 second (a once-per-second sweep checks expiries) and cap at a finite ~126 years, so SetTimed(value, math.huge) means "effectively permanent". Note that a later plain Set does NOT cancel the running timer: the field still resets to its default when the timer lapses. To make a timed value permanent, re-issue SetTimed(value, math.huge).

.ExtendTimed¶

Value.ExtendTimed(seconds: number, replicate: boolean?)

Scribe.Timed fields only. Adds time to a running timer.

.Active¶

Value.Active() → (boolean, number?)

Scribe.Timed fields only. Whether the timer is active, and the seconds remaining.