Storyboard UI

The mod is intended as a supporting mod for the w2scene encoder from the radish modding tools. It enables the interactive setup of a *rough* scene draft consisting of multiple shots which include camera setup, arrangement of multiple actors, preview and assignment of actor animations, mimics and look-ats. The shot collection can be logged as a scene definition, manually tuned and used as input for the w2scene encoder.


Main Features

• setup of multiple custom defined shots (including renaming and reordering)
• free, interactive camera setup (positioning/rotation, FOV and (partly) DOF configuration)
• all templates from the game (vanilla + both expansions!) are usable (actors, monsters, animals, spawnable items)
• all animations and mimics from the game (vanilla + both expansions!) are usable (automatically filtered by compatibility)
• free, interactive per shot positioning/rotation of all assets
• dynamic and static look-ats for actors
• previewing asset effects (contribution by @nikich340)
• assigning voicelines from a prefiltered set to actors
• actor, item and voicelines list are extendable with custom templates and voicelines
• logging of storyboard definitions to scriptlog in a format usable in the w2scene encoder
• storyboard settings are automatically saved on mod exit and restored on next start
  

Please note: the showcase videos present a best case scenario where (almost) all used settings of the shots are converted (more or less) correctly to a w2scene!

Make sure you read the "Known Issues" section before reporting problems!

Usage
The mod depends heavily on the usage of hotkeys! There is a context sensitive online help popup with all usable hotkeys for the current context (translations are welcome!). The default hotkey for the help is F12 once the Storyboard UI is started. Watch the videos and make sure you make yourself familiar with the hotkeys from the help!

Since version 0.8 the mod can be started/maximized via hotkey (default F7) or with "sbui" in the console. The time of day is saved and frozen on opening the Storyboard UI and restored once you minimize or quit the mod.

Short Overview
At startup the Overview (Mode) of the SBUI is active. You can see and add/delete/reorder or select active shots. Every shot can have its own settings defined in different "workmodes" like Camera-, Placement-, Animation-, Mimics-, Look-at- and Voiceline-Mode. You can switch freely between the workmodes for the currently selected shot. An exception is the Asset Mode which manages the set of available assets for all shots at once (and not per shot).

Every workmode has different functionality and its own hotkeys. A short info about the workmode and all available hotkeys are described in the help popup. The functionality / hotkeys may differ after selecting an asset which is also reflected in the help popup.

The help popup is kind of broken and uses only the upper part of the window for text. Make sure you scroll to the bottom to see the complete text.

@iotech kindly provided an overview over the shortcuts for version v0.7. You can find it HERE (or in the images section). Please note: v0.8 changed some hotkeys!

Adding custom templates
The mod contains all paths of spawnable ingame (w2ent) templates. It's possible to add custom/new w2ents paths to the selection list via script. Open the file

mods/modStoryboardUi/content/scripts/local/mod_additional_templates.ws

and add your templates as described in the comments:


Adding additional/custom voicelines
The mod contains a fixed set of voicelines for some main npcs. It's possible to add other/new lines to the selection list via script. Open the file

mods/modStoryboardUi/content/scripts/local/mod_additional_voicelines.ws

and add your selected lines as described in the comments:


Adding additional/custom animations and effect references
It's also possiblle to reference custom animations and effects via provided scripts. See
mods/modStoryboardUi/content/scripts/local/mod_additional_animations.ws
and
mods/modStoryboardUi/content/scripts/local/mod_additional_effects.ws

Note: These are only references to custom animations and effects. The animations and effects have to be added with other tools, e.g. Wolvenkit for animations and radish modding tools for custom effects.

Deleting existing storyboard
The mod restores and saves the current storyboard definitions on every start/exit. If you want to discard the storyboard you can use the console command:

sbui_clear_board

There will be a notification after deleting the board.

Setting/changing specific origin coordinates
This is required if you want to use multiple separate storyboards in the same w2scene. In this case all separate storyboards must have the same reference origin to calculate the used positions of assets/cameras. This is useful when tuning different sections of a longer w2scene - but it requires to merge the logged definitions by hand into the final scene description.

To start with specific origin use the console command:

sbui_with_origin(x, y, z, pitch, yaw, roll)

The origin will be overridden for an existing storyboard and initialized to this origin for a new storyboard.

How to upgrade
1. Uninstall mod and all previous SBUI input.settings sections
2. Reinstall and upgrade the dependencies

How to install
1. Install the dependencies (modBootstrap v0.4+, radish seeds v0.4+ and modSharedImports v0.6+) first
2. Unzip package into your witcher game directory (so dlc folder content from package goes into witcher 3/dlc folder and mod folder content from
package goes into witcher 3/mod folder)
3. Add content from "mods/modStoryboardUi/modStoryboardUi.input.settings" from the downloaded package into the input.settings file in your "Documents/The Witcher 3/input.settings" to the end of the file (it will be reordered after startup anyway)
4. (optional) If you want to start SBUI via hotkey, add the following line to your bootstrap registry:

    add(modCreate_StoryBoardUi());

5. Install the radish modding tools if you want to create w2scenes which are playable in the game

Important:
- make sure you start the game with "-debugscripts" or otherwise no values will be logged!
- verify that the scriptslog.txt is created in your "Documents/The Witcher 3" directory and contains output after you quit the game
- the scriptslog.txt will be recreated on every game start! Make sure you save your logged values before you start the game again!


How to uninstall
1. Delete the mods/modStoryboardUi and the DLC/DLCStoryboardUi folder
2. Search and remove ALL sections starting with MOD_StoryBoardUi* and all its entries from your "Documents/The Witcher 3/input.settings".


Known Issues
Listmenu

• selecting with page up/down does not move the list if selection moves to item not displayed in current scroll position. reason: it's a hacked vanilla game menu - this functionality does not exist for now. no workaround.
• clicking with mouse to select disables selection with enter/space. workaround: close and reopen listmenu again.
• sometimes the string indicating the filter is not shown in the listview although the list is still filtered. workaround: filter again
  

Asset Mode

• automatic camera adjustment: adding some items does not adjust camera correctly (some items are defined by layers which are loaded/spawned too late for camera adjustment)
• automatic camera adjustment: on changing templates the camera does not adjust correctly to size of asset (too far/near). Some meshes have wrong bounding box information - fix not possible.
• automatic camera adjustment: on switching to asset mode for actor with moving animation the camera changes to starting position of the set animation but actor then moves out of camera. workaround: camera uses selected actor head position on selection time -> wait until animation ends and switch to another actor and back again to readjust camera.
• many items don't spawn at all. reason: the available list of items is not cleaned for "usable" items. It's (nearly) the complete list of w2ents in the game. Also the availability *may* (?) depend on current world hub.
• some items are actually actors, they are not friendly, attack the (hidden) player and the storyboard breaks. reason: same as above - list not cleaned up.
• newly added actors are spawned in the air and fall to ground/water. reason: all assets are spawned in the vicinity of the player along a line (4m apart). this will be their starting/default position. workaround: quit sbui, move the player, make sure there is enough free space and restart sbui. remove/add asset and move after spawning to the desired position.
  

Placement Mode

• snap to ground pulls asset to ground level only if it is not too high. workaround: adjust manually height manually first to reduce height distance
• moving some objects is not interactive (e.g. rabbits hanging, log). no known workaround.
  

Animation Mode

• toggle special cam: animation moves actor out of camera view. workaround: retoggle special cam once more to readjust camera.
• list contains many dupe animations in different categories. reason: different actor skeletons have animations with the same name BUT different lengths. It's extremely unreliable to automatically extract the correct skeleton category from template path. BUT the w2scene encoder requires the correct number of animation frames (or the anim will be clipped in the scene!) so choose ALWAYS the correct (or best fitting) category!
• monster/animal starts running away after a couple of seconds. workaround: there is probably an animation from different actor category active. reset animation to none and assign a compatible animation.
• not ALL horse entities support animations. no known workaround.
  

Mimics Mode

• mimics animation and voice line can be assigned to the same actor in the same shot but cannot be played back simultaneously in the in-game storyboard. it works in w2scenes, though. no known workaround - duplicate shot with mimics only to preview the animation.
  

Look-at Mode

• sometimes look-ats switch between "eye-only" look-at and look-at with active body rotation. this seems to be coupled with the idle animation and the rotation distance to the look-at point (which can change with idle animation). no workaround available - in w2scene this *should* be more fluent.
  

Voiceline Mode

• contains only voicelines from main characters. reason: it's intentional as there are too many lines in the game and loading them all makes the voiceline mode slow. Workaround: add lines you want to use like described above into the file.
• searching for words does not match a voicelines even if the word is used in the line. Reason: same reason as above - too many too long lines make the loading/filtering slow. Therefore the provided strings are cut after a fixed number of characters (roughly a little more what you see in the menu). Workaround: don't use this for search, instead search the textfiles and add lines you want to use as described above.
• some lines are from a different actor than the category they are in. reason: the assignment to actor was made automatically by extracting tag from the used audio filename. some filenames contained multiple tags and the list is not cleaned up.
  

Camera Mode

• movement: sometimes the camera keeps moving even if the hotkeys are released. it happens most often when multiple keys are pressed simultaneously. workaround: press movement keys again for a short time (same direction?) to stop movement.
• DOF: doesn't work at all (no visible blur). reason: the ingame preview works only if no additional envs are blended (limitation of used preview method). workaround: disable *all* active envs (including additional envs set by vanilla game in certain areas!).
• DOF: changing dof does not blur near distance. no workaround - it just doesn't seem to work with the used method.
• DOF: auto dof for actor is not correct. reason: a simple and totally inadequate algorithm is used for this... (aperture settings unknown)
  

Created w2scene

• rotation of actors with animations sometimes differ slightly (as in example video). reason unknown. it *seems* to be connected with defined look-ats which adjust the rotation either ingame or in scene (?)
• some animations (especially combat anim) make weird turn arounds, etc. in w2scene not seen in ingame storyboard. reason: combat animations contain "rotate to target" events (and other) which change the movement direction of animation towards a target. as scenes have no target the resulting "direction to target" seems to be aligned with camera direction (?). no workaround (only possible way: cloning of animation files and removing all rotate events).
  

Thanks:
@erxv for creating a prototype which was the initial seed for this mod and for some additional bugfixes and testing
@nikich340 for contributions