Dialectic Modders Guide

NPC Biography Data Mods

The Dialectic game plugin scans Data/Dialectic for files ending in _bios.csv. Matching files up to 10 MB are uploaded to DialecticServer automatically.

A mod can therefore ship a file such as:

Data/Dialectic/my_companion_mod_bios.csv

Biography CSV Format

Download the current example from Configuration - NPC Biographies. Columns are positional and follow this order:

npc_name,core,worldknowledge_tags,npc_static_bio,personality,appearance,relationships,occupation,skills,speechstyle,goals,voiceid,gender,race,refid

npc_name and core are required. Use underscores in names, such as doc_mitchell. Relationship seeds must be JSON objects, for example:

{"Player":{"aff":25,"type":"professional"}}

Optional sample biography packages may also be offered on the Dialectic Nexus Mods page. They are not required, and anything you install from there is picked up through the same _bios.csv rules described above.

Matching Actors

Use the Fallout reference or base form ID in refid when a stable ID exists. Name matching is still useful for generic actors, but unique form IDs avoid collisions between NPCs sharing a display name.

Runtime telemetry supplies current race, gender, voice type, inventory, equipment, factions, skills, SPECIAL, health, action points, and other changing state. Do not use the biography CSV as a replacement for live actor data.

Descriptions

The Descriptions page accepts structured records for items, locations, races, factions, and other world data. Description-only context filters can limit nearby items and inventory entries to records with useful authored text.

Use the page's upload, merged-data, and database verification controls to confirm imported rows.

World Knowledge

World Knowledge stores reusable Fallout lore topics in the server database. NPC profile tags determine which subjects a character can draw from, while context settings control whether the selected knowledge enters prompts.

Package knowledge through Dialectic's current World Knowledge records and upload flow.

Voice Mapping

Data/Dialectic/fallout_builtin_voices.csv maps Fallout voice types to audio already installed under Data/Sound/Voice. Dialectic never ships extracted game audio.

A biography can provide a voiceid override, but it should identify a real installed voice type or a voice configured in TTS Studio.

Public Event API

When Dialectic is installed, any Fallout: New Vegas or Tale of Two Wastelands mod can make a Dialectic NPC speak, react, or follow by dispatching an xNVSE custom event on that actor's reference. Dialectic listens for a fixed list of event names, so a script only needs the reference itself. There are no server calls to write and no changes to Dialectic.esp.

Send an event with DispatchEventAlt on the actor that should respond:

; Contextual line, no string needed
npcRef.DispatchEventAlt "DialecticComment"

; Scene direction for a spoken reaction
npcRef.DispatchEventAlt "DialecticReact", "Alarm!"

Replace npcRef with the actor reference that should answer. Dialectic never substitutes the crosshair target or the nearest NPC.

Speech And Conversation Events

• DialecticSpeakExact, string required: speaks the supplied text exactly, through the actor's own text-to-speech voice. No LLM turn runs, and nothing is written to conversation memory.
• DialecticComment, no string: the actor makes a brief contextual observation in character. Generated actions are disabled for this line.
• DialecticReact, string required: the text is scene direction rather than dialogue, and the actor answers with a brief spoken reaction, for example "React with alarm to the nearby explosion." Generated actions are disabled.
• DialecticAsk, string required: sends the text down the normal player-input conversation path for that actor.
• DialecticOpenPrompt, no string: opens the text prompt with the same actor kept as the submit target.

Follower Events

• DialecticRecruit, no string: deterministically recruits the actor, who then starts following the player.
• DialecticDismiss, no string: dismisses the current teammate.
• DialecticWait, no string: puts the current teammate into Dialectic's persistent Wait Here lifecycle.
• DialecticResume, no string: resumes the actor, and only works while Dialectic is tracking that actor in Wait Here.

Contract And Safety

• Actor reference: the calling reference is authoritative, with no crosshair or nearest-NPC substitution.
• String length: a required string must be 1 to 1000 bytes after trimming.
• Actor state: the actor must be alive, loaded, eligible, and in the player's current scene.
• Contextual gates: comment and reaction still respect the menu, dialogue, combat, activity, and busy gates.
• Conversation ownership: ask and open prompt never replace a conversation owned by another actor.
• Follower state: dismiss, wait, and resume need a current teammate, and resume also needs a tracked Wait Here.
• Name collisions: if another plugin already registered one of these event names, Dialectic logs the collision and does not attach that handler.
• Fixed allowlist: these event names are the whole API. There are no arbitrary server endpoints, action names, JSON payloads, or remote actor selection.

Action Editor

The server Action Editor controls the prompt definition and response contract for an action. The game plugin must also implement the same action name and all required parameters.

Actions involving AI packages or factions may require records in Dialectic.esp. Add those records in GECK or xEdit, expose their form IDs to the runtime, and include cleanup behavior that restores the actor afterward.

Action Contract

• Prompt: tells the model when and how the action can be used.
• Parameters: identify speaker, target, item, location, amount, or other structured values.
• Plugin action: must match the native dispatcher name exactly.
• Return result: reports success or a concrete failure reason to the server.
• Event text: records the completed action without leaking internal form IDs into player-facing prose.

Testing A Data Mod

1. Install the data mod through Mod Organizer 2.
2. Start DialecticServer and Fallout.
3. Check dialectic.log for the detected _bios.csv file and upload result.
4. Open NPC Biographies and verify the merged profile.
5. Activate the actor and inspect the AI Response prompt before testing dialogue or actions.

Per-NPC Plugin Data

Server plugins can keep their own data with an existing NPC record. Each plugin uses a separate name so it does not overwrite another plugin’s data.

• API: Use the server’s NpcMaster methods getPluginData, setPluginData and deletePluginData. Read the per-NPC data contract before using them.
• Scope: This is a server-side API, not a public HTTP endpoint or game command. It does not automatically add data to prompts.
• Saved state: The data follows NPC history and playthrough saves under their normal restore rules.

Biography Voice Filters

Biography data can supply voice-filter presets as well as written character traits.

• Authoring: Add the optional tts_filter_preset column to biography CSV imports. Choose a value from the editor’s Voice Filter list; custom filter expressions are not accepted. The value seeds new NPCs and does not overwrite existing NPC voice choices. Append the column after refid (column 16). An explicitly blank value means none.
• Keep them separate: A voice filter changes the sound of the selected voice; it does not replace the character’s voice ID.
• Preview: Check the result with the voice tools.

External Actor Speech

Use actor-bound requests when another mod asks a specific NPC to comment or react. Keep the existing public xNVSE event API as the game-side entry point.

• Contextual speech: The comment and reaction requests identify the NPC by name and FormID. A reaction also needs an instruction.
• Contract: Follow the external request schema. Use the media schema for exact NPC speech.