defineEngineHooks

defineEngineHooks declares, once for the whole project, the handlers the client runs by name — the world-map element events — and the names of the assets it loads. Engine hooks is the Learn page.

defineEngineHooks(hooks: EngineHooks): EngineHooksDeclaration

Reference

defineEngineHooks(hooks)

src/engine-hooks.ts2

export default defineEngineHooks({
  worldmapElementHover: (e) => mapElementHovered(e.element, e.x, e.y),
  worldmapElementLeave: (e) => mapElementLeft(e.element),
  worldmapElementOp1: (e) => mapElementTravelled(e.element, e.coord),
  assets: {
    music: { title: 'scape main' },
    sprites: { logo: 'logo' },
  },
});

Parameters

• hooks: An object with any of:

  • worldmapElementOp1 … worldmapElementOp5: A world-map element’s five options.
  • worldmapElementEnter, worldmapElementLeave, worldmapElementHover: The pointer entering, leaving and resting on one.
  • assets: The names the client loads by name — binary, sprites, fonts, worldmap, music, each a group of named entries. A key left out keeps the client’s default; null skips an asset the client can do without.

  Each hook is an arrow over its event, which carries element (the map element), coord (where it sits), and, on enter, leave and hover only, x and y (the pointer).

Returns

A declaration, exported as the file’s default. A hook left out runs nothing.

Caveats

• One per project. Its source is a project of its own.
• A hook runs outside every component. No cell (TS2E355), no event.self, no markup. A hook calls a function that writes cells; a component somewhere reads them.
• x and y are filled on enter, leave and hover only; reading them in an option hook is refused (TS2E354).
• It is available in the extended dialect only (TS2E350).

refused/define-engine-hooks.ts2

export default defineEngineHooks({
  worldmapElementHover: (e) => {
    const [, setHovered] = useState(0);                              // whose state?
    setHovered(e.element);
  },
});

Usage

Writing cells from a hook

src/map-tooltip.ts2

/** The map element under the pointer, or -1. */
export const hoveredElement = sessionState(-1);
export const hoveredX = sessionState(0);
export const hoveredY = sessionState(0);

src/map-tooltip.ts2

export const mapElementHovered = (element: Int, x: Int, y: Int): void => {
  const [, setElement] = useState(hoveredElement);
  const [, setX] = useState(hoveredX);
  const [, setY] = useState(hoveredY);
  setElement(element);
  setX(x);
  setY(y);
};

Troubleshooting

useState is component state, and an engine hook runs outside every component

Move the write into a function the hook calls, as mapElementHovered is, and read the cell in a component.