Scripting allows for fine-tuned manipulation of dialogue text, both NPC and Player related. It allows, for example, to remove all vowels from all dialogue in the game.

File Structure

The .yml section for this editing type is scripts:

scripts:
  - Script1
  - Script2
  - ...

Each Script object is defined as follows:

script: myScript.lua
speaker: 0x198BA|Skyrim.esm
target: 0x14|Skyrim.esm
type: 0

Let's break things down:

• script: The script file which contains the replacement function.
  • Relative to Data/SKSE/DynamicDialogueReplacer/Scripts (i.e. the Scripts folder next to where you should place the .yml file).
• type: The dialogue type (NPC Response/Player Dialogue) at which the script is called
  • One of the following:
    • 0 - Always execute the script for any dialogue
    • 1 - Only execute the script for player dialogue (Topics)
    • 2 - Only execute the script for NPC dialogue (Topic Info Responses)
• speaker: Only execute the script when this actor is talking / being talked to by the player
  • Default: 0
• target: Only execute the script when this actor is being talked to
  • Default: 0

Lua Scripts

Editing of dialogue is done using Lua-Scripts. If you are unfamiliar with Lua you can take a look their documentation here: https://www.lua.org/manual/.

Script files should contain a replace(str) function, taking the current line as an argument and returning the replacement:

function replace(text)
  -- edit text here
  return text
end

Scripts are executed consecutively, meaning the result of the first script will be the input of the second one and so forth.

Another interesting detail is that script instances preserve their environment. Meaning you can utilize stateful operations, such as counting how many times a replacement operation has been executed:

counter = 0 -- Initialize a counter variable

function replace(text)
  counter = counter + 1
  return tostring(counter) -- Display how often this function has been called
end

Standard Library Functions

Lua scripts have access to the following parts of the Lua standard library:

• Basic Functions
• Package/Module Functions
• String Manipulation Functions
• Table Functions
• Math Functions

You can find documentation on all of these in the Lua documentation (https://www.lua.org/manual/).

Additional Functions & Properties

These are functions & properties DDR provides, allowing limited interaction with Skyrim/DDR:

Functions

• get_formid(formid: Number, modname: String) -> Number
  • Full formid of the object with formid in modname
  • 0 otherwise
• has_keyword(formid: Number, keyword_name: String) -> Number
  • 1 if the object referenced by formid has a keyword with the editor id keyword_name
  • 0 if it does not
  • -1 if the formid is invalid or the object is now a valid keyword-object (eg Statics)
• is_in_faction(formid: Number, faction_formid: Number) -> Numbe
  • 1 if the object referenced by formid is in a faction with the id faction_formid
  • 0 if it does not
  • -1 if either of the forms does not exist or is of incorrect type
• has_magic_effect(formid: Number, mgeff_formid: Number) -> Number
  • 1 if the object referenced by formid has a magic effect with the id faction_formid
  • 0 if it does not
  • -1 if either of the forms does not exist or is of incorrect type
• get_relationship_rank(formid1: Number, formid2: Number) -> String
  • "kLover"
  • "kAlly"
  • "kConfidant"
  • "kFriend"
  • "kAcquaintance"
  • "kRival"
  • "kFoe"
  • "kEnemy"
  • "kArchnemesis"
  • "" if formid1 or formid2 does not exist or is not an actor
• get_sex(formid: Number) -> Number
  • 0 if the actor is male
  • 1 if the actor is female
  • -1 if the form does not exist or does not reference an actor
• get_name(formid: Number) -> String
  • the name of the object
  • "" if the form does not exist (or has no name)
• send_mod_event(event: String, strArg: String, numArg: Number, formid: Number) -> Void
  • sends a mod event of type event_str with strArg, numArg and the form referenced by formid
  • Use with "RegisterForModEvent" in a Papyrus script
• log_info(message: String) -> Void
  • prints a log info into the DynamicDialogueReplacer.log file
• log_error(message: String) -> Void
  • prints an error into the DynamicDialogueReplacer.log file

Properties

• context: The context of the conversation
  • 1 for Topics
  • 2 for NPC Dialogue
• speaker_id: The actor currently speaking (or currently in conversation with the player)
• target_id: The actor that is being spoken to