HUD, hints and books

Client scripts can draw on this player's screen using the game's own HUD.

Messages

// client
const { Hud } = kcds.ui;

Hud.showNotification('The gates close at dusk.');
Hud.showBanner('Welcome to Kuttenberg', 5000);
Hud.showTutorialHint({
  title: 'Fishing',
  text: 'Stand at the water and cast.',
  durationMs: 10000,
});

The HUD also has the game's perk, combo, reputation and XP notices, such as notifyPerk and notifyXp, and its tutorials through showTutorial(name). These calls return false when there is no HUD, such as in the main menu or during a level load.

Hiding parts of the HUD

// client
kcds.ui.Hud.setHudPart('Compass', false);

Parts include Compass, Stats, QAMWeapon, QAMFood, Subtitles, InfoText, GameLog, Hints, DialogLeft, DialogRight, Cursor, Crime, Wanted, Buffs, Trespassing and Vignette; see Hud for all. A part stays hidden while any resource hides it.

Screen effects

// client
const { Hud } = kcds.ui;

Hud.startEffect('screenBlood', { amount: 0.6 }, { fadeInMs: 200, durationMs: 1500, fadeOutMs: 800 });
Hud.startEffect('colorGrade', { saturation: 0.3, brightness: 0.9 }); // grey and gloomy

The effects are colorGrade, blur, ghosting and screenBlood. They combine, and end when your resource stops or the level changes.

"Press [key] to ..." hints

kcds.ui.ActionHint adds a prompt:

// client
kcds.ui.ActionHint.create(
  { key: 'primary_action', text: 'Ring the bell', mode: 'hold', holdDuration: 2 },
  () => {
    kcds.core.Events.toServer('ringBell');
  },
);

Keys: a hint sits on one of the game's controls: primary_action, attack_special, torch, companion_interaction, distract or jump. Or it can use script_action, a free key KCDS keeps for scripts (U). The newest hint on a control is the one shown.

An enabled hint takes over its key. The game's action on that key does not run, so E puts down no sack and starts no talk. The game's prompts on that key (Talk, Loot, Pickpocket behind a player) are not drawn next to it. A disabled hint takes nothing.

Presses: one press calls the handler once. A hint appearing while the key is still held waits for the next press, for example "Release" right after "Put in the pillory". kcds.world.World.addInteraction behaves the same.

A press and a hold on one key

Press hints and hold hints stack separately, so a key can have both, as the game's prompts do. The newest of each shows. Letting go before holdDuration runs the press hint, and a full hold runs the hold hint. E, X and the special attack key draw both. Other keys draw only the hold hint, but both still work.

// client
const { ActionHint } = kcds.ui;
const { Events } = kcds.core;

ActionHint.create({ key: 'companion_interaction', text: 'Untie' }, () => {
  Events.toServer('untie');
});
ActionHint.create(
  { key: 'companion_interaction', text: 'Lead on a rope', mode: 'hold', holdDuration: 1 },
  () => Events.toServer('lead'),
);

Drawing hints yourself

ActionHint.shown() lists all hints the HUD is drawing, including the game's prompts, as { key, map, text, mode, enabled, progress }, with text in the player's language. ActionHint.shownKeys() and ActionHint.isKeyInUse(key) tell which keys a hint is waiting on, and actionHintsChanged fires when the set changes. So a resource can hide the game's hints and draw its own:

// client
kcds.ui.Hud.setHudPart('Hints', false);

kcds.core.Events.on('actionHintsChanged', () => {
  console.log(JSON.stringify(kcds.ui.ActionHint.shown()));
});

While the player lies knocked out or fainted, the game's world hints, such as loot or picking up a body, are not drawn. Your hints and those of the pause screen still are.

kcds.ui.Web.anyFocused() says whether any resource's shown page has the keyboard and mouse.

Books and letters

// client
kcds.ui.Book.open({ style: 'letter', pages: ['To the burgrave,\nthe grain did not arrive.'] });

style is 'book', 'plainBook' or 'letter'. Book.write(true) lets the player write on a page, firing bookTextChanged, and Book.image(path) puts a picture your resource ships on a page.

The character's remarks

In the game, the player's character remarks on things, such as horse commands, an empty pot or photo mode, in Henry's voice regardless of who plays. On KCDS these stay silent, and each fires monologueSuppressed with the line in the player's language, so you can show it your own way:

// client
kcds.core.Events.on('monologueSuppressed', (text, textKey) => {
  if (text) {
    kcds.ui.Hud.showNotification(`(you think) ${text}`);
  }
});

Hud.setInnerVoice(true) lets the game voice and caption them on this player's screen, with no event. Hud.innerVoiceOn() reads the setting.

Story cutscenes

A quest plays story cutscenes, including fades and time skips, when the player walks into a trigger. In the game's cutscene state the player loses control, the world clock can stop and the quest's scenery loads, so on KCDS they do not play. The quest carries on as if they had, and each one fires storyCutsceneSuppressed with its name from the game's cutscene table:

// client
kcds.core.Events.on('storyCutsceneSuppressed', (cutscene) => {
  console.info(`skipped the cutscene ${cutscene}`);
});

Hud.setCutscenes(true) lets them play on this player's screen for the session, with no event. Hud.cutscenesOn() reads the setting. A skipped cutscene never plays afterwards. The player's own fast travel, sleep and waiting are a different kind of scene and always play.

Map and compass

Waypoints and events: WorldMap.getWaypoint(), shiftWaypoint(position), clearWaypoint() and setMapCategory('Shrine', false), with the events mapOpened, mapClosed and mapWaypointSet.

Fog of war: by default the server lifts the fog and discovers all locations as the world loads. WorldMap.clearAllFog() clears fog again if a level load brought it back. A server with revealMap off keeps the fog, and WorldMap.clearFog(position) clears it around a point with the game's reveal radius, as if walking there. A resource tracking where a character has been calls this after loading the character.

Discovery: WorldMap.discover(id) silently marks a place as discovered, with no toast or XP. The id comes from locationDiscovered or poiDiscovered. Call this after loading the character, if your resource keeps their discoveries. Marking a point of interest fires poiDiscovered, but a location fires nothing.

Others: kcds.ui.Compass.visible = false hides the compass, and kcds.world.Travel.active is true during fast travel. Map icons for everyone come from the server; see Markers and blips.

Reference: Hud, ActionHint, Book, WorldMap, Compass, Travel.