Library and examples for communication between ClueKeeper and Zappar
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
src
.gitignore
README.md

README.md

ck-zappar-library

Library and examples for communication between ClueKeeper and Zappar

Installation instructions

  • Open a zap within ZapWorks Studio
  • Create a new script by right clicking on the root node (or anywhere else in the node hierarchy), then select New --> Script --> blank
  • Rename the script node from script0 to cluekeeper
  • Paste the entire contents of the src/cluekeeper.ts file into your new cluekeeper script.
  • IMPORTANT! Always be sure the cluekeeper script node is the first node below root. This is necessary to ensure that the cluekeeper script loads before any other scripts that might want to use the library.

Usage instructions

  • Within your other script files import the CK library by adding this line:
    const CK = symbol.nodes.cluekeeper.CK;
  • Then you can use CK library methods listed below.

Supported Methods

Method Description
getTeamId(): string Returns a unique identifier for the team.

Usage:
CK.getTeamId();
canSubmit(): boolean Returns true if players can submit a string as a start code or solution. This corresponds to when the submit button is enabled.

Usage:
CK.canSubmit();
isSolved(): boolean Returns true if this clue has been solved.

Usage:
CK.isSolved();
getLaunchContext(): LaunchContext Returns the context (i.e. clue start, clue content, hunt start, etc.) and corresponding state in which this zap was launched.

See the LaunchContext definition below for details.

Usage:
const launchContext = CK.getLaunchContext();
if (launchContext.type == CK.LaunchContextType.CLUE_START) {
  // do stuff
}

Note: This feature is only available to players using app version 1.18.0 and higher.
getHuntState(): ClueState Returns a ClueState object representing the hunt state.

See the ClueState interface below for details.

Usage:
const huntState = CK.getHuntState();
const huntTitle = huntState.title;

Note: This feature is only available to players using app version 1.18.0 and higher.
getClueStates(): ClueState[] Returns an array of ClueState objects. The objects in the array will be in the same order as the default clue order for the hunt.

See the ClueState interface below for details.

Usage:
const clueStates = CK.getClueStates();
const firstClueTitle = clueStates[0].title;
playAlertSound(): void Plays a sound to get the user's attention. This is the same sound used when a new message becomes available, a clue opens, or a clue nears expiration.

Usage:
CK.playAlertSound();
playExpireSound(): void Plays the sound used to indicate that a clue or the hunt has expired.

Usage:
CK.playExpireSound();
playHintSound(): void Plays the sound used to indicate that a new free hint is available.

Usage:
CK.playHintSound();
playSolveSound(): void Plays the sound used to indicate that a clue was solved successfully.

Usage:
CK.playSolveSound();
submitString(guess: string): void Submits a start code or solution to the ClueKeeper app. The response will be the same as if submitted manually via the submit button.

Usage:
CK.submitString("ABC");
submitStringAndRelaunchOnSuccess(guess: string, deepLink?: string): void Submits a solution to the ClueKeeper app, then launches a new zap if the guess is correct.

If a deepLink for the subsequent zap is not present, the current zap will be relaunched with isSolved() returning true.

This feature is only available for clue solves (not clue starts).

Usage:
CK.submitStringAndRelaunchOnSuccess("ABC");

Note: This feature is experimental and likely to change.
showInfoDialog(title: string, text: string): void Shows a standard system dialog using the given title and message. Both title and message are interpreted as HTML.

Usage:
CK.showInfoDialog("Title of dialog", "Message of dialog");
close(): void Closes the zap.

Usage:
CK.close();
closeAndContinue(): void Closes the zap and navigates the player to the next appropriate screen, using the same logic as the confirmation dialog presented when a clue is solved. For example, in a linear hunt the next screen is the next clue, while in a scramble the next screen is the clue list.

If the clue has not been solved or the hunt is not in progress, this behaves the same as close().

Usage:
CK.closeAndContinue();

Supporting Types

Type Definition
ClueState This interface represents the state of a given clue (or hunt).

See getClueStates() (or getHuntState()).

interface ClueState {
  title: string;
  isStarted: boolean;
  isInProgress: boolean;
  isSolved: boolean;
  isFinished: boolean;
  miniStates?: ClueState[];
}
LaunchContextType This enum represents the possible contexts from which a zap can be launched.

enum LaunchContextType {
  NONE,
  HUNT_START,
  CLUE_START,
  CLUE_CONTENT,
  PREMETA_CONTENT
}
LaunchContext This interface represents the launch context and state from which a zap was launched.

See getLaunchContext().

interface LaunchContext {
  type: LaunchContextType;
  state?: ClueState;
}

Examples

To get started with this library, you can view some of the included examples:

Example File Description
hunt-state.zpp Shows how to access and use the hunt state, clue states, and launch context.
submit-string.zpp Shows how to submit a string for a clue start or clue solution from within a Zap.

Instructions for using examples:

  • Download the .zpp file you want from the examples directory.
  • In ZapWorks Studio, select OPEN PROJECT --> IMPORT A ZPP FILE, then select the .zpp file.
  • Publish the zap and test within ClueKeeper as normal.