Skip to content

GraphQL Console

The GraphQL Console is an in-app tool for querying the connected runner directly. It is useful when you want to understand what the server knows about — which parties exist, what locations are active, who is in the jazz roster — without waiting for SSE events to surface that information.

It is also available as a standalone interactive playground at the /graphiql path on any runner URL (e.g. http://localhost:7321/graphiql).

Opening the console

Press `Ctrl+`` (Control and the backtick key) to toggle the console open and closed. It appears as a floating panel in the bottom-right corner of the window.

You can also close it by clicking the × button in the panel's title bar.

The console is available whenever Waldo is running, whether or not you are connected to a server. However, queries will only work when a connection is established — the Run button is disabled when you are not connected.

What you see

Preset queries — a dropdown at the top lets you load common queries instantly:

Preset What it shows
List Parties All parties currently registered on the server
World Locations Which parties are present at which locations
Venues Jazz venues available in the current scenario
Jazz Roster Current session musicians and their roles

Select a preset to load it into the editor, then click ▶ Run.

Query editor — a text area where you can write or edit any GraphQL query. The preset loads a starting point; you can modify it or write from scratch.

Run button — executes the current query against the connected server. Disabled when not connected or when a query is already in flight.

Connection status — a line below the Run button shows the current server URL, confirming which server will receive the query.

Results pane — the response appears as formatted JSON. Errors appear in red. The pane scrolls independently from the rest of the panel.

Example: checking parties before you join

If you connect to a server and are not sure whether anyone else is already in a party, select List Parties from the presets and run it. You will see something like:

{
  "parties": [
    {
      "id": "party-abc123",
      "display_name": "Session One",
      "realm_name": "kurzz",
      "human_members": [{ "id": "player-xyz" }],
      "ai_members": [{ "id": "velda" }, { "id": "kepler" }],
      "current_location_id": "perf-stage"
    }
  ]
}

This tells you a party called "Session One" exists, has one human member, two AI musicians (Velda and Kepler), and is at the performance stage.

Mutations

The console sends all requests to the same /graphql endpoint the rest of Waldo uses. That endpoint supports both queries (reading data) and mutations (actions like joining a party or starting an activity).

The preset queries are all read-only. If you write and run a mutation — for example, a joinParty mutation — it will execute against the live server. Use mutations with the same care you would use any action in the UI: they have real effects on the simulation.

When the console is most useful

  • Just connected and want to see what the server currently knows before any events have been pushed to your stores.
  • Something looks wrong — panels show stale or missing state; use the console to check the authoritative server data.
  • Learning the system — the GraphQL schema is self-documenting. The standalone /graphiql playground (available in your browser at the server URL) has a full schema explorer.
  • Debugging a scenario — check that venues, locations, and parties look right before starting an activity.

Running queries from your browser

If you prefer the full GraphiQL experience (with schema exploration, history, and a keyboard-friendly interface), open the runner's /graphiql path directly in a browser:

http://localhost:7321/graphiql

Replace the host and port with your runner's address. The in-app console and the browser playground query the same endpoint.