useServerState

useServerState is a hook that reads a value the server owns — a game variable or a skill — and makes the component that read it follow the value.

useServerState(ref: ServerRef): Int

Reference

useServerState(ref)

src/status.ts2

export const StatusPanel = (): Component => {
  const poison = useServerState(Varps.POISON);
  const stamina = useServerState(Varbits.STAMINA_ACTIVE);
  const shown = useServerState(ItemVarps.SHOWCASED);

Parameters

• ref: A reference from a generated dictionary — a Varps.* entry, a Varbits.* entry, or a Skills.* entry. It must be a reference, not a number.

Returns

The current value, as an Int — unless the reference says what the variable holds, in which case it reads back as that. ItemVarps.SHOWCASED above is declared VarpRef<3997, 'item'>, so shown is an Item and goes into an item prop with no cast:

src/refs-interactivity-state.ts2

export declare const ItemVarps: {
  readonly SHOWCASED: VarpRef<3997, 'item'>;
};

Caveats

• Read-only. There is no setter. Change it through options.
• A plain number is refused (TS2E123).
• Reading in a handler is a read of the moment, and creates no dependency. Only a read while producing the markup does — in the markup, in a local above it, or in any function the render calls, however deep.
• A component under a hidden ancestor stops following its values until it is shown again, and catches up when it is. See How updates happen.
• Three other hooks follow a value differently: useSkill and useSkillBase read a skill boosted and unboosted; useServerStateOnce reads at build and never again; useWatch runs a handler and rebuilds nothing.

refused/use-server-state.ts2

const poison = useServerState(102);                                // a number, not Varps.POISON

Usage

Displaying a value

src/status.ts2

{poisoned()
  ? <Reading label="Poison" value={`${poison}`} color={0x3fbf3f} y={0} />
  : <Reading label="Poison" value="none" color={Colors.DIM} y={0} />}

Reading through a helper

src/status.ts2

const poisoned = (): Boolean => useServerState(Varps.POISON) > 0;

StatusPanel follows the variable through poisoned() without naming it.

Drawing an item from a variable

src/status.ts2

<sprite x="right" y="center" w={36} h={32} item={shown} itemCountMode="never" />

Reading a skill

src/once.ts2

const combatLevel = (): Int => {
  const attack = useSkill(Skills.ATTACK);
  const strength = useSkill(Skills.STRENGTH);

A Skills.* reference works with useServerState too, and does the same thing as useSkill.

Troubleshooting

My value never changes on screen

Check that the read is in the code producing the markup rather than in a handler.

Then check whether the component is visible. A hidden or clipped component stops following its values until it comes back.

I get an error about a reference

useServerState takes a dictionary reference, not a number. If you have an id, find it in the generated dictionary and use that entry — see Reading game data.

I want to change the value

You cannot. If the game should change, the player’s action has to reach the server, which is what options and click handlers are for. If you only want the screen to move early, see predictServerState. If the value is really yours rather than the game’s, use useState.