Set up contextual Banter

Get a working contextual line in the included Dungeon Market sample, then create your own exchanges and connect them to gameplay moments. Banter is authored content plus an initialized runtime host; creating an asset alone does not make it play.

First, see Banter working

1. Let the DGS 4.0 project finish importing. In the Unity menu, open Tools > Beka Forge > Banter > Getting Started.
2. Under Open the sample, click Open 2D Market Demo. The window opens Assets/Beka Forge/Dialogue Graph System/Samples/2DMarketDemo/Scenes/MarketDemo.unity.
3. Press Play. Follow the scene guide and talk to the merchant. At the welcome and later market milestones, contextual Banter lines appear in the subtitle UI. Press R to reset the sample and try again.

Checkpoint: the line appears when its market trigger is submitted. The sample uses authored fallback text and subtitle presentation; it has no recorded Banter voice and does not demonstrate the optional Banter HUD.

Try your own exchange in the working sample

Use this path for your first custom Banter. The sample already supplies actors, subtitles, a profile, and a runtime host, so you can focus on the content. Save a copy of the sample assets before editing them.

1. Exit Play Mode. In Assets/Beka Forge/Dialogue Graph System/Samples/2DMarketDemo/Banter/Exchanges/, right-click and choose Create > Beka Forge > Banter > Exchange. Name it MyMarketGreeting.
2. Select it. Give it a title, keep it enabled, and set its content revision to 1. Set the trigger to market.welcome and the category to Reaction.
3. Add a role with RoleId merchant and required CharacterID market-merchant. Add a second role with RoleId player and required CharacterID market-player. These exact character IDs match the sample's registered actors.
4. Add a line using Speaker Role merchant and your own Fallback Text, then a reply using Speaker Role player. Click Generate Missing Stable IDs, then Validate Exchange. Save the asset.
5. Select Assets/Beka Forge/Dialogue Graph System/Samples/2DMarketDemo/Banter/MarketBanterCollection.asset. Add your exchange once to its Exchanges list. Temporarily disable the sample's built-in Welcome exchange so this trigger has one eligible greeting. Validate the selected collection.
6. Open MarketDemo.unity and enter Play Mode again. Move to the merchant and press E to talk. The sample submits market.welcome when its merchant-talked state changes.
7. Look for your authored text in the contextual subtitle area. Press R to reset the sample, then talk again. Exit and re-enter Play Mode after changing the collection so the host initializes from the latest assets.

Checkpoint: your two-line exchange appears from the existing market trigger. Restore the built-in Welcome exchange and remove your test exchange from the sample collection when you have finished experimenting.

Create a small authoring kit

The fastest safe start is the built-in kit. It creates three validated authoring assets in a folder you choose; it does not create scene objects, register actors, or initialize runtime playback.

1. Open Tools > Beka Forge > Banter > Getting Started.
2. In New kit folder name, enter a new folder name, such as TownBanter.
3. Click Choose parent and create kit, then select an existing parent folder inside your project's Assets folder. The destination must be new.
4. Wait for the window to report Created and validated. Use Ping Exchange and the other Ping buttons to locate the created assets.

Checkpoint: the folder contains a BanterExchangeSO, a BanterCollectionSO, and a BanterDirectorProfileSO. The example exchange has two fallback-only lines and generic roles. Replace them with your own authored content before wiring a game host.

Author one useful exchange

Select the Exchange asset and edit its Inspector. For a first greeting, use a distinct trigger such as town.merchant.greeting, category Reaction, topic town.greeting, and a positive selection weight. Keep the exchange enabled.

1. In Identity, give the exchange a clear title and description. Keep contentRevision at 1 or higher.
2. In Trigger / Selection, enter the trigger key your gameplay code will submit. Use Ambient only for the reserved ambient trigger; for a one-time world reaction, Reaction is a straightforward choice.
3. In Roles, add a role for each speaker. Each role has a RoleId, for example merchant and player. When the role is bound to a DGS character, its requiredCharacterId must match that character asset's exact CharacterID.
4. In Lines, add at least one line. Choose its Speaker Role from the roles above and enter non-empty Fallback Text. Add another line if you want a short back-and-forth. Audio clips and localization variants are optional for this subtitle-first first pass.
5. Click Generate Missing Stable IDs. This fills blank exchange and line IDs while preserving nonblank IDs. It is Undo-supported and does not save the asset for you.

Put it in a collection and validate it

1. In the Project window, choose Create > Beka Forge > Banter > Collection.
2. Name the collection, add your Exchange once to exchanges, and use Generate Missing Collection ID if its stable ID is blank.
3. Select the Exchange and click Validate Exchange in its Inspector. Fix each reported issue, then validate again.
4. Select the collections your host will use. Return to Tools > Beka Forge > Banter > Getting Started and click Validate selected collections, or open Tools > Beka Forge > Banter > Catalog Validation to configure the full ordered collection set explicitly.

Checkpoint: the exchange validator reports clean content, and catalog validation reports clean results for the exact collections you supplied. A clean single-exchange result does not validate other collections the host may load.

Connect a request to gameplay or dialogue

A dialogue graph and contextual Banter solve different jobs. DGS dialogue owns an authored conversation, its choices and graph actions. Banter is a separate, queued contextual exchange that your game requests at a moment such as opening a gate, finishing a quest step, or leaving a conversation. A graph action handler can submit a Banter request, but the request still needs an initialized Banter host and registered actor identities.

For a first project integration, copy the wiring pattern from MarketDemoBanter.cs and its scene builder. The host initializes a BanterCompositionRoot with its director, foreground bridge, profile, collections, audio/subtitle collaborators, actors and context. Wait until root.IsReady before submitting a request.

Once your own host has completed that setup, this is the request shape used by the current runtime API:

using BekaForge.DGS.Banter.Assets;
using BekaForge.DGS.Banter.Contracts;
using BekaForge.DGS.Banter.Integration;
using UnityEngine;

public static class MerchantBanterRequests
{
    public static void RequestGreeting(BanterCompositionRoot root)
    {
        if (root == null || !root.IsReady)
        {
            Debug.LogWarning("Banter is not initialized yet.");
            return;
        }

        var result = root.SubmitSelectionRequest(new BanterRequestSubmission(
            triggerKey: "town.merchant.greeting",
            category: BanterExchangeCategory.Reaction,
            originActorId: "town-player",
            targetActorId: "town-merchant-01",
            deduplicationKey: "merchant-greeting:" + Time.frameCount,
            zoneId: "town-square"));

        if (!result.IsAccepted && result.Status != BanterRequestSubmitStatus.Coalesced)
            Debug.LogWarning("Banter request was not accepted: " + result.Failure);
    }
}

Change the trigger and actor IDs to the exact values your exchange, scene registration and request use. A request being accepted means it entered the Banter selection queue; it does not prove that a line matched, that voice played, or that a listener heard it.

When a DGS graph was drafted with AI, review and apply that graph in the DGS editor, then wire the graph's gameplay event to your Banter request where appropriate. AI authoring does not automatically generate or initialize Banter assets. See AI authoring in DGS and Creating a dialogue graph.

Common problems

Keep exploring

• Create a DGS dialogue graph
• Connect graph actions to gameplay code
• Use the optional AI authoring workflow
• In the installed module: Banter/Documentation/QUICKSTART.md, AUTHORING.md, and Samples/2DMarketDemo/README.md.

Source basis: this page follows the current DGS 4 Banter Getting Started window, exchange/collection inspectors, Banter composition APIs, and the included Dungeon Market sample. The sample's subtitle text is not a human audio test.