Watching and reacting

Reading a value redraws the component when the value moves. A watch runs a handler instead, and redraws nothing.

Read, or watch

useServerState(X) makes the render depend on X:

src/watch.ts2

const poison = useServerState(Varps.POISON);

useWatch(X, handler) runs the handler when X moves, and the handler writes the label:

src/watch.ts2

useWatch(Varps.POISON, (event) => { writePoison(event.component); }, poisonLabel);

src/watch.ts2

const writePoison = (into: ComponentId): void => {
  const poison = useServerState(Varps.POISON);
  into.text = poison > 0 ? `Poison: ${poison}` : 'Poison: none';
};

Call the same function from onLoad so the label is right before the value first moves:

src/watch.ts2

onLoad={(event) => { writePoison(event.self); }} />

A watch that feeds a cell

A watch handler may call a setter, for something a read cannot show, such as how often the value moved:

src/watch.ts2

const [changes, setChanges] = useState(0);
useWatch(Varps.POISON, () => { setChanges(changes + 1); });

What you can watch

One source, or a list of sources of one kind: game variables, skills, inventories, or the client’s occasions below. useWatch([A, B], handler) watches both; write one useWatch per kind.

Where a watch lives

A watch is bound on a host, the component’s own root unless the third argument names another. Bind it on the label it rewrites, named with createRef:

src/watch.ts2

const poisonLabel = createRef('docs-watch:poison');

A watch under a hide does not fire; see Timers.

Occasions with nothing to read

The client announces ten things that are not values. Engine names them, and a watch can wait for each:

	fires when
Engine.SUB_CHANGE	any sub-interface opens or closes, anywhere
Engine.DIALOG_ABORT	the server aborts the current dialogue
Engine.CONTENT_CHANGE	the client’s content changes
Engine.CHAT	a chat message arrives
Engine.FRIENDS	the friend list moves
Engine.CLAN	the friends-chat channel moves
Engine.CLAN_SETTINGS	clan settings move
Engine.CLAN_CHANNEL	the clan channel moves
Engine.MISC	the client’s miscellaneous update runs
Engine.STOCK	the Grand Exchange offers move

The handler receives only event.component and reads whatever it needs.

When a redraw is the answer

A handler can set a text, a colour or a hide, but it cannot add or remove a component. When the change is to what exists, redraw instead:

• useRerenderOn(occasion, host?) redraws the component when the client announces occasion.
• useOnResize(ref) redraws the component when the game window resizes ref.

	what happens
useWatch(X, handler)	your handler runs
useRerenderOn(X)	the whole render runs again

The reference has a page for each: useWatch, useRerenderOn, useOnResize and the ten occasions under Engine.