Gameable Engine

Set up talking characters ​

Goal ​

Get a game ready for talking characters (AI NPCs with a persona and a voice, running on Convorcher, the hosted conversation service): the relay that keeps the API key on the dev server, and the page side that plays the voice, moves the face, shows subtitles and a talk box, and passes everything to the game as conversation-events. Done once per game; then Write a character's story and Talk to a character.

Files you will edit ​

  • vite.config.ts
  • src/main.ts

Steps ​

  1. The key. The API key from your Gameable account (Account → Developers) goes in .env.local, never in src/: GAMEABLE_API_KEY=aos_.... In the Gameable sandbox it is already set: skip this step.

  2. The relay. vite.config.ts turns on talk (the third-person template already does):

    ts
    plugins: [gameable({ talk: true })],

    The dev and preview servers then serve <base>talk/ (the conversation and the microphone's transcription), with the key kept on the server, and every src/<id>.story.yaml is a character the game can talk to.

  3. The page. In src/main.ts, after bindFeatures and before createEngineAdapter:

    ts
    import { talkingCharacters } from 'gameable/conversation';

const talk = talkingCharacters({
  audio: engine.get('audio'),
  characters, // the character bridge: the face moves with the voice
  emit: (event) => adapter.events.push(event),
  names: { guard: 'Brannoc' }, // optional: the name the talk box shows for an id (else the id)
});

    and in createEngineAdapter's options, hand the game's conversation commands to it:

    ts
    conversation: (command) => talk.handle(command),

    While a conversation is open, talkingCharacters shows a talk box at the bottom of the page: the character's subtitles, a field to type in (typing never moves the player) and a microphone button (push to talk).

Verify ​

  • npm run dev logs gameable: talk: the relay is at /talk/ (under the base).
  • Without the key it logs talk needs GAMEABLE_API_KEY, and the game still runs.

See also ​