Difference between revisions of "Skald Documentation"

From Nexus Mods Wiki
Jump to: navigation, search
Line 320: Line 320:
 
Should not concern you. Unless you plan to make a movie.
 
Should not concern you. Unless you plan to make a movie.
  
 +
 
  
 
== Items ==
 
== Items ==
Line 326: Line 327:
  
 
 
 
 
 +
[[Category:Documentation]]

Revision as of 11:47, 7 February 2020

Skald is a powerful tool mainly used for creating Dialogs and various text data for the games

It may also be used for:

  • viewing and setting some DB data (souls, inventories, items)
  • defining characters
  • run analyses of designed content
  • organizing and setting voice-overs
  • viewing translations

Skald also plays crucial part in scripting of the game content. This is where you can condition dialogs, setup skill checks, run dialog exist scripts, setup objective messages, set objective states etc.

Global controls

When you run Skald for the first time will see this welcome window.

Start-up

Sk1.png

If you setup the local Database properly, you should see the modding DB here. Select it and Skald will load all the DB data it needs.

 

Header

Skald1 2.png

1. Shows an overview of all errors, warnings and unprocessed notes in the currently open subchapter.
2. You can switch between edit mode (WHS language) and translation mode (any other language).
3. You can only add new content when in edit mode. You can filter out “Projects” which is yet another organization layer and change the DB if you so desire.
4. Shows Skald controls

Main tabs

File

Skald2.png

Lists Chapters and Subchapters. Double-clicking on a subchapter opens it.

NOTE: The read-only mode checkbox is set to TRUE by default and represents global settings which overrides the “Open” command on subchapters. Any subchapter you open will be open in read-only mode. You should turn the checkbox off. If you still want to open ONE subchapter in read-only, there is a dedicated button in the right panel.

Subchapters are also frequently called quests but don’t necessarily need to represent one. A subchapter can be assigned a FlowGraph quest, in which case the subchapter truly becomes a quest in the game.

There is a subchapter name filter at the top.

You can add new chapters by clicking “New”

Quests

Skald4.png

Quests tab offers an alternate and more detailed view at the quests/subchapters.

To load the detailed data, click the Reload button, and it will take its time to extract all the stats and data from all the quests.

Another look at Subchapters with additional info.

 

Design

Skald3.png

This is the main window for writing the quests and dialogs where you will probably spend 90% of the time when working with Skald. It provides detailed view of the content of a subchapter. You can check, create and edit dialogs, objectives, quest logs,  gameplay descriptions, parts of game logic etc.

You can pretty much ignore the top ribbon. It contains some actions for adding basic elements.

Left pane

Left pane simply lists all the elements of 3 major “section” types (gameplay, branched dialog, cutscene) in order of appearance in the document.
You can change the order by drag and dropping any instance of these types there.

RTENOTITLE

 

Middle pane

This is where all the writing happens. The controls are designed in such a way that you should be able to use only keyboard to write all the content.
A new document requires that you first click the “Quest” button in the top ribbon.
After that, all you need to do is writing, pressing Enter, and selecting and confirming (with Enter) the next options in the automatically generated menus.

Example of writing a new quest and its first content:

Skald6FIN.png

 

 

Section-type elements

Quest

Mandatory element. Gives name to the subchapter.

Quest can have these properties:

  • Link to a FlowGraph (FG) Quest object
    • If the Skald quest is linked to an existing FG Quest, the FG Quest name is prefilled by autocomplete in all dialog entry conditions in this subchapter. This speeds up autocomplete of FG Objectives that belong to that quest.
  • Name – name of the quest that appears in the log if the quest is ever started
  • Description – description of the quest that appears in quest log as the initial description
Gameplay

Skald8.png

GAME section is used for gameplay descriptions, quest design etc. Can carry information on location and gameplay type.

Should contain:

  • Game action paragraphs - Each paragraph can have assigned its own gameplay type, time-flow type, and approx. duration. These data may be useful for content analysis.

May contain:

  • Linear dialogs­
  • Objectives
  • Triggers and Tutorials - special types of non-dialog text data holders.
Scene

Skald9.png

"Scene" is a shorthand for cutscene. This section is tailored for writing scripts for movie sequences in movie industry standard formatting. It supports general descriptions in elements of the type Scene Action and linear Dialogs. It can also contain elements of type Objective, Title, Description.

 

Br. Dialog

Skald7.png

(Some topics are covered in more detail in Dialog System documentation.)

Br. Dialog stands for Branched Dialog. This Skald section supports writing, conditioning and scripting of dialogs with branching decisions.

You should first understand the architecture of the Dialog System (see documentation). In short, each sequence knows which topic follows. And each topic knows which sequences can be selected from it.
Therefore the dialog systems only knows topics and sequences (with responses) and relations between them.

In order to visualize such dialogs in more digestible way Skald has its own set of extra DB objects:
Br. Dialog sections, Linear Dialogs, Decisions, GOTOs, Sequence Ends.

Properties of any Dialog:

  • Dialog type - normal, greeting, ending, monolog, ingame, ingame monolog, denial. These types affect how the dialog system treats the dialog or where it’s applied. Greetings are automatically attempted at the start of any dialog. Endings are the same but used at the end. Ingame types skip creation of dialog cameras.
  • Priority - a valid dialog with non-zero priority is played automatically after dialog interaction with an NPC is started. You enter the dialog root only when all the valid applicable dialogs have priority 0. Dialogs with higher priority take precedence over dialogs with lower priority.
    Warning: if a priority dialog ends with END TOPIC and is not invalidated at its end it will get repeated. You can run a risk of being stuck in a non-escapable dialog loop.
  • Production status - aids with production process from writing, script implementation to recording.
    Only texts of dialogs which are in ScriptApproved or Done states will be exported.
  • Allow greeting - allows to suppress automatic greetings if any of this dialog’s root topic’s sequences are valid.
     

Key elements in Dialogs:

Response

Must contain:

  • ROLE
  • dialog line

A valid empty line can be created using angle brackets (example: <dont show this text>)

May contain:

  • Parenthetical
    Is created automatically when you write “(“, and is ended with “)”
    Parentheticals are used for directions for VO (mood description), explaining technical role of empty responses etc.
    Parentheticals are also used for creating “empty responses”. Empty responses typically serve a purely technical purpose.
  • Command
    Commands are used for additional settings. When you write “!” a command menu appears and you can select your command. Commands are used for setting mood (face expression), setting dialog animation (full-body animation excluding face), setting custom camera, setting dynamic “point at” animation, setting dynamic “look at” target, setting non-default hearing distance, and setting additional roles (for silent participants, who need to be part of the dialog for technical reasons).
    It is also used for including topics from other dialogs via topic aliases. Unless the included dialog end with END DIALOG (which end the dialog altogether) the original dialog is resumed after the included one is finished.
  • Direction
    Directions are used as a visually distinct in-line notes apparatus. Typically they are used for pointing out and describing critical design directions or implications (like, what will happen if the player chooses this topic, what objective should be updated, under which conditions in, laymen’s terms, is this topic valid etc.)
    Although it may no seem so direction is part of the following response, and a topic with a single response, that only features a direction, will appear in the game as an empty response with undefined strings.

Properties:

  • A response always belongs to a sequence (defined by sequence ID). Sequence is the smallest part of a dialog in terms of logic and control (i.e. you cannot run a script in the middle of a sequence or jump into a middle of it)
  • Response has its own sequence line ID. Voice over is paired with this ID.
  • The dialog line has a string ID. This represensts the ID of the string in WHS language. It can be localized (DB table string_localized with unique IDs)
  • Fixed language = used for responses in languages like Hungarian which excludes them from localization for they should stay the same in all language versions of the game.
  • Volume = can override how loud the voiceover should be. Does not affect the distance from which you can hear it. This is set by !Hearing command. A response can be a whisper (volume) and heard at longer distances (hearing) at the same time.
Decision/Topic

Decision is a Skald’s element and is almost equivalent of Dialog System’s Topic. Decisions are points of decision and points of return for GOTOs. A decision marks an end to a dialog Sequence and must be followed by at least one Sequence (in which case it works a sequence splitter).

Each dialog features an invisible Decision 0, which is equal to the root Topic of the dialog.

Properties:

  • You can set Label to a decision for better orientation in more complex br. dialogs. (instead of auto-generated obtuse A.B.C.D.E.F... you can have a meaningful name like "final decision")
  • You can set properties of the Topic when a decision is selected:
    • Time Limit. You can set on the decision object. This gives the player limited time to select the options. In seconds.
    • Alias. A topic Alias is a human-readable equivalent to Topic ID. Topic Alias must be globally unique. Most if not all systems support calling Topic via Alias instead of Topic ID.
    • Priority. Overrides the order of listing of sequences in dialog when player faces a decision. By default, topics with lower ID are selected first and their sequences are listed in order of appearance in Skald. Higher priority = higher listing.
      Notice: priority applies to entire topic. If you wan to move a particular sequence higher you must change the order of the sequence in Topic/Decision.
    • Topic role. By default, it doesn’t matter which role follows right after decision. If the dialog system runs into a decision with more than one valid sequence the player always chooses. If you want to create an illusion of the NPC making the decision, set the NPC’s role as Topic Role on this Topic. In such case the NPC will choose a random option (from the pool of valid ones).
GOTO

A GOTO simply points to a Decision/Topic which follows after a Sequence. It is the Skald’s counterpart of the Dialog System’s field “next” in DB table sequence which stores the next Topic ID.

Sequence Ends

A sequence that is not followed by any other dialog content must be terminated by an END. There are 3 types:

  • END DIALOG - ends the entire dialog interaction with the NPC and player is back in the game world
  • END TOPIC - forces the dialog to go back to dialog root. Dialog root is what you see right after starting a dialog with an NPC. This is where the (End dialog) option is autogenerated by the dialog system. Dialog root is the list of all root Topics (=Decision 0) from all Skald dialogs which are valid (dialog conditions are TRUE) and where all dialog participants have their role (typicaly NPC’s role and player’s role).
  • END WITH CUTSCENE - same as END DIALOG but also starts a fader (black screen). It works in tandem with MBT trees - CutsceneAutomaton tree, or FaderBarrier node, or IntermissionGate. These systems can end the fader. It is used for transitions dialog -> cutscene, dialog  -> fast travel, dialog -> custom fader and similar.

 

Sequence

Sequence is a non-zero set of responses from the first one to the next decision or sequence end. It is the smallest logical unit in terms of the underlying Dialog System.
Properties applied to sequences:

  • Entry condition - makes the sequence in its topic accessible in dialog if the condition is TRUE.
  • Objective action - sets a specified objective to specified state (if the state transition is possible). Is applied at the end of the sequence.
  • Exit script - runs a LUA script. Is applied at the end of the sequence.
  • Reputation change - the player get a hit or gain to the personal reputation with the NPC. Is applied at the end of the sequence.
  • UI prompt - this is the text you can select when interacting in a dialog in game.
  • Skill check + difficulty - Skill checks apply either an indicative Icon to the dialog option or a true test. (more in Dialog System)
  • Cooldown - defines for how long the sequence is invalid (despite possibly true condition) after it was used. Used for auto-disabling of a sequence (cooldown -1) or for optimizing repetition frequency of often re-used sequences (combat barks, greetings etc.)
  • Input - used in setting up shops.

 

Other elements

Linear dialog

Linear dialog is an alternative tool for creating dialogs. This tool does not support creation of decisions, i.e. you can only create singular dialog sequences. Other than that, under the hood there is no technical difference between branched dialogs and linear dialogs. Whatever applies to a sequence, root topic, and dialog as a whole applies to linear dialog as well.

 

(Skald) Objective

Skald10.png

A Skald Objective element is different from an FG Objective object. FG Objectives are used for scripting logic and to hold a big part of the game state. FG Objectives can be seen in the journal, in objective updates in HUD and in the game’s journal as they go through various states. In order to show that data in a form legible by humans, they have to be linked to a Skald Objective element (If an FG Objective isn’t linked to a Skald Objective, you will see ‘@’ instead of actual words in the game). The Skald Objective element holds all this text data.

For more detail see documentation of objectives/quest system.

Properties:

  • UI name - this is the name which is shown in the game’s UI. It is only shown when the FG Objective is set to Hidden=0. The text must also be properly exported to appear in the game so the Production status must be ScriptApproved or Done.
  • Quest objective - the linked FG objective
  • Objective started/completed/failed - update messages to show in games UI as the objective transitions to different states. When empty option is selected, the UI message is suppressed altogether. <default> options show “Objective started”, “Objective completed”, and “Objective failed” respectively.
  • Logs - textx which should be logged in the journal quest log as you walk through the game and objectives change their states.
  • Save - if set to TRUE the objective requests a save creation (to create auto-save) when the objective transitions to the completed state.
  • Permanent - if true the save will be permanent. There are 4 types of saves.
    • Exit save - single slot. Created after Save & Quit.
    • Manual saves - there is almost no limit how many manual svaes you can create
    • Auto-saves - a set of several slots which keep getting overwritten in a carousel manner (oldest is overwritten in next attempt)
    • Perma-saves - Avoid them if possible. There is a hard-coded limit to number of these slots. They are reserved for start states of Main Quests. As long as the number of possible perma-saves doesn’t exceed the limit all the perma-saves are kept for the entire duration of the gameplay. The only exception is if you play through the same perma-save creating point in the same playline. In that case the perma-save will be overwritten with a newer version of the same save-point. If you exceed the limit the system should start behaving as a carousel.
Trigger

A generic element where you can store any text that is supposed to be shown in the game but doesn’t belong to any other type of text data. For example, if you want to have an interactive trigger (these names have no relation) in the game which shows the player a UI prompt “[E] Inspect corpse”, you can store the string “Inspect corpse” in the Skald Trigger element for easier access.

 

Tutorial

Same as trigger but is intended to holds texts for use in Tutorial windows.

 

Right pane

Skald11.png

The right pane uses 2 presets:

  • Design (default) - hides proprties exclusively used for scritping
  • Script - shows proprties exclusively used for scritping

Right pane is a place for showing and setting properties of selected elements. It also contains some useful tools. Some tools and all the proeprties are context-dependent.

Tools:

  • Dialogue Player = a tool where you can manually simulate the flow of the dialog.
  • Navigation = shows the current topic and its immediate subtopic in UI prompt forms
  • Objective actions editor = you can edit objective actions here
  • Link = contains a URL. If entered into browser Skald will open a new instance, open the correct subchapter, and focus on the correct element within it. Each elelement has its own URL.
  • Sequence = contains fields for specifying:
    • Entry condition
    • Exit script
    • UI prompt
  • Translations = contains all translations of this element's text
  • Comments/Notes = Offers a rich asynchronic feedback and communication tool. Comments can be rated by other users. Notes, additionaly, can be agreed/completed or disputed/refused. No Quest should be left with unprocessed notes.
  • Move Sequence = commands to move the sequence to other place within the sctructure of the dialog.
  • Quest Objective = Allows linking to an FG objective and setting the properties of its Skald counterpart.
  • Location = If a location is set to the element a tool bearing the location's name will be created. It shows the location's place on the map.
  • Quest Info = Link the subchapter to an FG Quest and set up the quest's name here

Translations

You can see all strings in the DB and view their translations.

Dialogues

Another view of all dialogues. Should not concern you.

Characters

A place where you define Characters (soul vs character vs role/metarole documentation).

Roles

Lists all the existing roles. Should not concern you much.

Souls

Lists all the existing souls. Should not concern you much, as souls are created in the Sandbox Editor >> NPC Editor.

If you use Statistics override or Skills override to setup custom soul stats, you have to run Storm so that it processes the new override rules and writes correct data to the soul tables in DB.

Locations

Lists all defined locations.

Map

Shows the main map. You can check placement of some of the content here.

Voices

Lists all voices. One voice actor may represent multiple voices, but typically one actor means one voice. Should not concern you much if you don’t plan to add new voice overs.

Responses

Lists all individual dialog line strings. Should not concern you much. Useful when searching for a line based on its alias or when you are making a VO.

Cutscenes

Should not concern you. Unless you plan to make a movie.

 

Items

Lists all items from the DB. Allows you to write in item name and item description, and to edit some of the item properties.