Skip to content

Wiki

Jump to bottom
RadionWave edited this page Apr 15, 2026 · 3 revisions

Dialog & Animation Framework

An Arma 3 SQF script for creating in-game dialog boxes, playing sequential animations, and managing audio playback. Designed for mission makers who want to add cinematic conversations and cutscenes to their missions.

Features

  • Dialogue Sequences — Play full cinematic sequences (animations, audio, dialog) with a single function call.
  • Dialog System — Display a styled talk box with character name, portrait, and colored text based on unit faction.
  • Animation Sequencing — Play a list of animations on a unit sequentially with automatic duration calculation.
  • Audio Playback — Play sounds in 3D space or as UI sounds, with volume and distance control.

Dependencies

  • CBA_A3 — Community Base Addons for Arma 3

Installation

Step 1 — Copy files

Copy the functions/ and rsc/ folders into your mission directory.

Step 2 — Edit description.ext

Add the UI resource includes and function registrations to your description.ext:

#include "rsc\BaseControls.hpp"
#include "rsc\RscTalkBox.hpp"

class CfgFunctions
{
    class AR
    {
        class Animations
        {
            file = "functions\Animations";
            class getAnimationDuration {};
            class playAnimation {};
        };
        class Audio
        {
            file = "functions\Audio";
            class playAudio {};
        };
        class Dialogs
        {
            file = "functions\Dialogs";
            class showDialogue {};
            class createTalkBox {};
            class playSequence {};
            class playNextSegment {};
            class onLoad {};
            class onUnLoad {};
        };
    };
};

Step 3 — Set up init.sqf

This step is critical. Add the following CBA event handler to your mission's init.sqf. This registers the event that allows the talkbox to be displayed on the correct clients in multiplayer:

["AR_showDialogue",
    {
        _this call AR_fnc_createTalkBox;
    }
] call CBA_fnc_addEventHandler;

This event handler runs on every machine (server and all clients) at mission start. When ar_fnc_showDialogue triggers the AR_showDialogue event, each target client receives it and calls AR_fnc_createTalkBox locally to display the RscTalkBox on their screen.

Without this line, the talkbox will not appear on any client in multiplayer.

Step 4 — Verify

  1. Launch the mission in the Eden Editor.
  2. Open the debug console and run:
private _segments = [
    ["Hello world!", "", []]
];
[player, player, "", "", _segments] call ar_fnc_playSequence;

If the dialog box appears at the bottom of the screen, the framework is installed correctly.

Quick Start

private _segments = [
    ["Hey you! Stop right here!", getMissionPath "sounds\talk_1.ogg", ["Acts_PercMstpSlowWrflDnon_handup2c"]],
    ["Sergeant, a new recruit is here!", getMissionPath "sounds\talk_2.ogg", ["Acts_listeningToRadio_In", "Acts_listeningToRadio_Loop", "Acts_listeningToRadio_Out"]],
    ["Alright, go right there.", getMissionPath "sounds\talk_3.ogg", ["Acts_Pointing_Back"]]
];

[allPlayers, _unit, getMissionPath "images\head.jpg", "Miller", _segments] call ar_fnc_playSequence;

That's it. The framework handles animation timing, audio playback, dialog display, and auto-close automatically.

Functions

Sequences

ar_fnc_playSequence

Plays a full dialogue sequence on a unit, including animations, audio, and talkbox display. Each segment is played sequentially with automatic timing between them. This is the main function mission makers should use.

Author: RadionWave
Public: Yes

# Parameter Type Default Description
0 _targets Object, Group, or Array objNull Target player(s) who will see the talkbox
1 _unit Object objNull The AI unit performing the dialogue
2 _customImage String "" Path to the portrait image
3 _customName String "" Custom name to display instead of the unit's name
4 _segments Array [["", "", []]] Array of dialogue segments (see below)
5 _nameColor String "" Hex color for the unit name (optional)
6 _textColor String "" Hex color for the dialogue text (optional)
7 _is3D Boolean true Whether to play audio in 3D space (optional)
8 _volume Scalar 1 Audio volume 0–1 (optional)
9 _distance Scalar 100 Max audible distance in meters (optional)

Return value: None

Segment format: Each segment is an array of 3 elements:

# Element Type Description
0 _dialogueText String Text to display in the talkbox
1 _audioFilePath String Path to the audio file to play
2 _animationSequence Array Array of animation class names

Targets: The _targets parameter accepts multiple types:

Type Behavior
Single player (player) Only that player sees the talkbox
Group (group player) All players in the group see the talkbox
Array ([player1, player2]) All players in the array see the talkbox
allPlayers Every connected player sees the talkbox

Examples:

// Simple single-segment dialogue
[
    allPlayers,
    _unit,
    getMissionPath "images\head.jpg",
    "Miller",
    [["Hello soldier!", getMissionPath "sounds\hello.ogg", ["Acts_PercMstpSlowWrflDnon_handup2c"]]]
] call ar_fnc_playSequence;

// Multi-segment dialogue with custom colors
private _segments = [
    ["First line of dialogue.", getMissionPath "sounds\line1.ogg", ["Acts_handup"]],
    ["Second line of dialogue.", getMissionPath "sounds\line2.ogg", ["Acts_Pointing_Back"]]
];

[allPlayers, _unit, getMissionPath "images\head.jpg", "Cpt. Harris", _segments, "#FF0000", "#FFFFFF"] call ar_fnc_playSequence;

// Custom audio settings (low volume, short range)
[allPlayers, _unit, "", "Whisperer", _segments, "", "", true, 0.3, 20] call ar_fnc_playSequence;

ar_fnc_playNextSegment

Internal recursive function that plays a single dialogue segment and schedules the next one using CBA_fnc_waitAndExecute. Do not call directly.

Author: RadionWave
Public: No — called internally by ar_fnc_playSequence.

Dialogs

ar_fnc_showDialogue

Sends the talkbox display command to the target clients via the AR_showDialogue CBA event. This is the network layer used internally by playNextSegment. You generally don't need to call it directly.

Author: RadionWave
Public: No

# Parameter Type Default Description
0 _targets Object, Group, or Array objNull Target player(s) who will see the talkbox
1 _unit Object objNull Source unit of the dialog
2 _text String "" Text to display
3 _customImage String "" Path to a custom portrait image
4 _nameOverride String "" Custom name to display instead of the unit's name
5 _duration Scalar 0 Duration in seconds before auto-close (0 = no auto-close)
6 _unitCustomColor String "" Hex color for the unit name
7 _textCustomColor String "" Hex color for the dialog text

Return value: None

ar_fnc_createTalkBox

Creates and displays the RscTalkBox UI overlay on the local machine. Called by the CBA event handler registered in init.sqf. Do not call directly.

Author: RadionWave
Public: No

Side color defaults: If no custom color is specified, the unit name color is determined automatically by faction:

Side Color Hex
BLUFOR (NATO) Blue #004C99
OPFOR (CSAT) Dark Red #800000
Independent (AAF) Green #008000
Civilian Purple #660080
Default Gold #B29900

ar_fnc_onLoad

Handles the onLoad event for the RscTalkBox dialog. Stores the display reference in uiNamespace for later access.

Author: RadionWave
Public: No — called automatically by the dialog system.

ar_fnc_onUnLoad

Handles the onUnLoad event for the RscTalkBox dialog. Currently a placeholder for future cleanup logic.

Author: RadionWave
Public: No — called automatically by the dialog system.

Animations

ar_fnc_playAnimation

Plays a list of animations on a unit sequentially. Uses switchMove for the first animation and playMove for subsequent ones, allowing the engine to queue them natively.

Author: Archer

# Parameter Type Default Description
0 _unit Object objNull Unit to animate
1 _animationList Array [] Array of animation class names (strings)

Return value: Scalar — Total duration of all animations in seconds.

Example:

private _duration = [
    _unit,
    ["AinvSrasWpstHnon", "AmovPercMstpSlowWrflDnon"]
] call ar_fnc_playAnimation;

ar_fnc_getAnimationDuration

Returns the duration of a single animation state by reading its speed from CfgMoves.

Author: Archer
Public: No — used internally by ar_fnc_playAnimation.

# Parameter Type Default Description
0 _animation String "" Animation class name from CfgMoves > States

Return value: Scalar — Duration in seconds. Returns 0 if the animation is not found or its speed is zero.

Audio

ar_fnc_playAudio

Plays a sound from a unit in 3D space or as a UI sound.

Author: Archer

# Parameter Type Default Description
0 _unit Object objNull Unit to play sound from (3D mode only)
1 _sound String "" Sound file path or classname
2 _is3D Boolean true true for 3D positional audio, false for UI sound
3 _volume Scalar 1 Volume level (0–1)
4 _distance Scalar 100 Maximum audible distance in meters (3D mode only)

Return value: Scalar — Duration of the sound in seconds.

Example:

private _soundDuration = [
    _unit,
    getMissionPath "sounds\voiceline_1.ogg",
    true, 1, 100
] call ar_fnc_playAudio;

UI Layout — RscTalkBox

The dialog box is rendered as an RscTitles overlay positioned at the bottom of the screen. It consists of:

  • A semi-transparent black background (alpha 0.75)
  • A character portrait on the left (control IDC 6000)
  • A structured text area on the right for the name and dialog (control IDC 6001)

The dialog fades in over 0.5 seconds, stays for up to 60 seconds (or auto-closes based on the duration parameter), and fades out over 0.5 seconds.

Full Examples

Single sequence

private _segments = [
    ["Hey you! Stop right here!", getMissionPath "sounds\talk_1.ogg", ["Acts_PercMstpSlowWrflDnon_handup2c"]],
    ["Sergeant, a new recruit is here!", getMissionPath "sounds\talk_2.ogg", ["Acts_listeningToRadio_In", "Acts_listeningToRadio_Loop", "Acts_listeningToRadio_Out"]],
    ["Alright, go right there.", getMissionPath "sounds\talk_3.ogg", ["Acts_Pointing_Back"]]
];

[allPlayers, _unit, getMissionPath "images\head.jpg", "Miller", _segments] call ar_fnc_playSequence;

Two characters talking

// First character speaks
private _segmentsOfficer = [
    ["Halt! Identify yourself.", getMissionPath "sounds\officer_1.ogg", ["Acts_PercMstpSlowWrflDnon_handup2c"]],
    ["Command, we have a visitor.", getMissionPath "sounds\officer_2.ogg", ["Acts_listeningToRadio_In", "Acts_listeningToRadio_Out"]]
];

private _durationOfficer = [allPlayers, _officer, getMissionPath "images\officer.jpg", "Lt. Harris", _segmentsOfficer] call ar_fnc_playSequence;

// Second character responds after the first finishes
private _segmentsRecruit = [
    ["Sir, Private Davis reporting for duty.", getMissionPath "sounds\recruit_1.ogg", ["Acts_PercMstpSlowWrflDnon_handup2c"]]
];

[{
    [allPlayers, _recruit, getMissionPath "images\recruit.jpg", "Pvt. Davis", _segmentsRecruit] call ar_fnc_playSequence;
}, [], _durationOfficer] call CBA_fnc_waitAndExecute;

Authors

  • RadionWave

Clone this wiki locally