Aurora Toolset

Table of Contents

Use these instructions to import files from BioWare's Aurora Toolset (Neverwinter Nights 1 & 2) into the Dialogue System.

Aurora Toolset Projects

Preparing Modules for Import

The Dialogue System can import content from Aurora Toolset dialogue & journal files. You will need to use ModPacker or the Ruby-based nwn-lib tools to convert your .mod file(s) into XML files.

Note About Special Characters: If your text uses special characters, make sure to save your files as UTF-8 to preserve them. Alternatively, you can set the encoding type in the import window. You can use a text editor such as Notepad++ to convert to UTF-8, or a command line tool such as iconv, or an online tool such as: https://subtitletools.com/convert-text-files-to-utf8-online

What Is Imported

This data is imported:

  • All conversation trees, including language localization.
  • The ShowOnce flag is observed.
  • All <StartXXX> formatting tags (<StartAction>, <StartCheck>, <StartHighlight>)
  • All predefined tokens (e.g., <FullName>)
  • All custom tokens (e.g., <CUSTOM1234>)
  • Journal entries.

What Is Not Imported

This data is not imported:

  • Scripts (active conditions and action scripts, see Scripts and Quest Updates below)
  • Other types of module files such as areas and module info files

Actors

A dialogue database contains a list of actors. Typically, one actor is the player character and the rest correspond to NPCs in the game. Each conversation has two default actors, referred to as the actor and conversant. Imported conversations will be assigned actors. The importer allows you to add and assign actors to conversations if you don't want to use the defaults.

If your conversations involve multiple actors, overriding the Speaker field for an entry, the speaker's tag should be present as one of the actors listed in this section.

Tokens and Variables

Predefined and custom tokens will be added to the dialogue database's Variable[] Lua table. References to tokens in dialogue text will be replaced with [lua()] tags that return the associated variable.

You are responsible for setting the values of the variables that represent predefined and custom tokens.

<StartXXX> Tags

Formatting tags will be replaced with [em#]...[/em#] emphasis tags (see Markup Tags). You can adjust the colors of the emphasis tags in the dialogue database's Emphasis Settings (see Database).

Scripts and Quest Updates

Imported entries that have scripts and quest updates will contain the name of the script or quest as a comment inside the corresponding Dialogue System field. You can tick a checkbox in the importer window to get a report of all lines that have unimported scripts and quest updates.

The Aurora importer does not translate NWN scripts. Instead, the Convert Scripts To pop-up allows you to specify how to handle them:

Setting Description
Lua Comments Add a Lua comment with the script's name.
Custom Lua Function Add a call to a Lua function named NWScript() that you must define.

The settings are described in more detail below.

Lua Comments

This setting adds scripts as Lua comments inside the corresponding fields of the dialogue entry.

  • Active Condition Scripts: The dialogue entry's Condition field will be set to true with a comment for the name of the NWN script (e.g., true ---gen_cond_01).
  • Action Scripts: The dialogue entry's Script field will be set to a comment containing the name of the NWN script (e.g., ---gen_script_02).
  • Quest Updates: The dialogue entry's Script field will be set to a comment containing the quest name (e.g., ---Kill 5 Rats).

Custom Lua Function

This adds scripts as calls to an external Lua function bool NWScript(string). You are responsible for writing this function and registering it with the Lua environment. Use the template in Template ► Scripts ► Aurora ► TemplateNWScript.cs to get started.

Aurora Toolset Import Window

To bring your Aurora Toolset XML files into Unity, use the Aurora Toolset import window. This creates a dialogue database asset out of a set of XML dialogue files.

  1. Generate XML files from your .mod:
    • Using ModPacker:
      ModUnpacker yourfile.mod gffdir
      GffToXml xmldir gffdir\*
    • Using Ruby nwn-lib: ModUnpacker is unable to convert some conversations containing special characters. You can use nwn-lib to generate the intermediate files instead of ModUnpacker:
      ruby nwn-erf -f yourfile.mod -x
  2. In Unity, select Tools → Pixel Crushers → Dialogue System → Import > Aurora (Neverwinter Nights). This will open a window similar to the one shown below. You can click the '?' buttons for help on each section.
  1. Open the Actors foldout and click the '+' button to add any actors (NPCs) that you want to assign to conversations. Otherwise they will be assigned the default actor 'NPC'. After assigning dialogue files, you can click Load from Dialogue Files to tell the importer to retrieve actor tokens from all of the dialogue files and automatically populate the actor list. You can reassign conversations' actors in the Dialogue Editor after conversion.
  2. In the Dialog Files foldout, click the '+' button to add dlg.xml files to the list to be imported. You can assign actors or leave them with the defaults. Use the '+*' button to add all of the dlg.xml files in a folder.
  3. In the Journal Files foldout, click the '+' button to add jrl.xml files to the list to be imported. Use the '+*' button to add all of the jrl.xml files in a folder.
  4. Open the Languages foldout if your conversations use localization and you want to use a different language code name for a language ID number. The importer will only add localized fields for languages that are actually used within each conversation.
  5. Open the Variables foldout if your conversations use custom tags. Click Load from Dialog Files. This will identify what custom tags are used and add them to the list. You can then keep the name as defined in the NWN conversation or rename it. These names will be added to the Variable[] table (see Logic & Lua), and imported lines of dialogue will reference them.
  1. (Optional) You can save and load importer settings in the Profiles tab. This makes it convenient to switch between different sets of NWN source files that will be imported into different dialogue databases.
  2. In the Save As section:
    • Set Output Folder and Database Filename to the path and name of the dialogue database asset that you want to create.
    • If you tick Overwrite, the importer will automatically overwrite any existing version of this asset.
    • Set Encoding to the format of the files that you'll be importing.
    • Set Convert Script To to the method you want to use for handling scripts. (See Scripts and Quest Updates.)
    • If you tick Report Scripts/Quests, the conversion process will log any conversations and lines that have Condition scripts, Action scripts, or quest updates.
  3. Click Import to create the dialogue database, or Clear to clear all settings.

<< Import & Export