Radish Trial 4 Scene Basics

From Nexus Mods Wiki
Revision as of 19:54, 1 May 2022 by Culorin (talk | contribs) (Added pointer to a CDPR talk on W3's scene system.)
Jump to: navigation, search
The trial of the radishes is meant as a guided, self-learning tutorial without step-by-step instructions. Instead it focuses on exploratory learning by actively using the tools to solve increasingly challenging tasks.

See forum post for more information about the trials.

Trial 4 - Objectives

At this point you have set up at least one basic quest and some communities but interactions between player and actors are still missing. This trial concentrates on the creation of simple scenes that can be used in quests to allow interaction with actors (e.g. quest givers) and adaptation of the questflow based on choices the player makes in the dialogs. To reduce the complexity this trial will focus only on the basics and on a fast tweak-encode-test cycle for scenes. More advanced features (storyboard sections, custom audio, ...) and connecting with a quest/community will be picked up in later trials.

Your task is to:

  • make a new custom in-game scene which can be played multiple times on demand (either by script or a hotkey)
  • multiple actors (at least player and another actor) should be present and active in the scene
  • try to vary the camera framing a little during the dialog
  • use some basic animations, e.g. some gestures for actors while speaking
  • there should be at least one choice section with different dialog flow based on the players choice

Some background Information

The trial 4 and 6 articles will give you a rough overview of The Witcher 3's scene system. For more insight you might take a look at this developer talk:


In-game Scenes

Scenes can be roughly divided into two categories: dialogue scenes with player some interactions that (may) influence the progress of quests


and cinematic scenes that are used to present some questspecific progress and most of the time don’t allow (m)any interaction from the player, aka cutscenes.


Depending on the category there is a different focus in the creation process: in the first case the dialogue and especially the different paths and outcome of the coversation have to be considered. While cutscenes also may contain dialogue they are mostly about the visual presentation. Of course these two aspects can be mixed in one scene, too.

Dialog Scenes

Like the questgraph containing specific questblocks and directed links between those blocks a branching dialog can be thought of as a directed graph, too. But in this case the blocks are actually complete dialog ‘sections’ that span more than one spoken line.

The important thing about dialog sections is: every “normal” section can only advance to exactly one other dialog section and does not allow any interaction from the player (aside skipping the complete section). However there are also special dialog ‘choice sections’ that present a couple of options for the player to choose from. Depending on the choice a different dialog section can be defined as the next section. Unless there is a timeout defined choice sections block the scene until the player makes his choice.

The radish modding tools do not contain a visual editor for dialogs: the dialog has to be defined in a specific yml text format and afterwards encoded with the radish w2scene encoder. In the ‘docs.scenes/tutorial’ directory (in the radish tools package) is an extensive tutorial. It explains the most important concepts and describes the format used for radish tools scene definitions based on an example in detail.

The tutorial concentrates on the creation of dialog type scenes but you have to understand these general concepts before creating advanced dialog scenes or cinematic type scenes as well. Do not skip this valuable information!

Storyboard UI (SBUI)

The mentioned tutorial only briefly dives into defining the visual presentation of scenes in the definition format. (Nowadays) it is much easier to setup a scene with actors, animations and camera shots roughly with the Storyboard UI mod in-game and tweak the dumped definition afterwards.


An emphasis on the visual presentation (among other things) will be the aim of the advanced scene trial. Nevertheless at least some basic camera switching and actor animations are usefull/required for simple dialog scenes as well.

SBUI dumps the scene definition into the witcher script log with the prefix [W2SCENE]. The prefix has to be removed before the definition can be encoded. See below for a semi-automatic definition extraction from logs (which is also useful for all other dumped definitions).


One important thing is to understand the relation between the dumped SBUI definition and the supported scene definition of the encoder as described in the tutorial:

SBUI is setup as a helper mod and cannot cover the full range of supported scene definition features.

For example it always creates a definition with only ONE dialog section named “section_storyboard_ui” (and a minimal proxy start section). Merging such a section with a manually created dialog definition requires some renaming according to the dialog section it is used for, because each section that is in the dialogscript is linked with a section in the storyboard part of the definition by its name.

In practice it’s best to think of preparing only specific sections of a scene in SBUI while the SBUI asset definition is used for the complete scene.

Another limitation is SBUI’s definition of a “shot”. In comparison to the scene definition format supported by the encoder it is too simplistic: for the encoder a shot is the duration between two camera switches and may contain multiple voicelines, multiple pause elements, multiple animations of actors, etc. In fact it can be just one shot for the complete scene. But SBUI can only attach only one voiceline, one animation (etc.) per actor per shot.

Even if this trial requires only a simple scene it is a good idea to keep these limitations in mind while creating the draft for the scene in SBUI.

String Id Space

As seen in the scene tutorial a scene also can generate new strings (if it’s not reusing already existing voicelines). For this to work it requires the definition of a valid id space. But using scenes in a radish project requires it to respect the projects string id-space.

It’s best to think of the string id-space as a container for the whole project: all strings in the quest (will get automatically generated with proper non overlapping ids) and all strings from scenes must be in the same id-space container. The encoders will checks this.

The default string-id is set to 9999 and is reserved for testing only: no mod should be published with this id-space as it will produce weird conflicts for mod users (wrong strings appearing). But it’s ok to use 9999 for local development and the trails.

To sum it up: make sure the string id-space set in settings.bat, the skeleton quest production settings and every scene is in sync.

Semi-Automatic Definition Extraction from Scriptlog

All in-game radish mods (e.g. SBUI, radish quest ui, envui, ..) dump the current setup as definitions into the scriptlog of the game after quitting the mod (or pressing the hotkey for log definitions). These definitions can be used as a basis for further manual tweaking or to manually incorporate/update only specific parts (e.g. a new camera definition or a new layer/entity from radui) into already existing definitions.  The dumped definitions have to be extracted from the log and the specific context dependent prefix (e.g. [W2LAYER] or [W2SCENE]) which marks the type of the definition has to be removed prior using them as “real”, encode-able definition.

The extraction and prefix removing can be automated by starting the “[i]watch.scriptlog.bat[/i]” in the project root folder. The watcher will check the scriptlog regularly and extract new definitions, cleanup the prefix and save them into the "**_tmp**" folder of the project.


All of the extracted definitions are always appended into the files so nothing is overwritten by accident. As long as the ‘watch.scriptlog.bat’ is running the extracted *_tmp* files are locked and cannot be edited or deleted. If you want to cleanup or delete the definitions the watcher has to be stopped first.

Fast Edit-Playback Cycle

Creating a scene almost always requires to test the playback within the game multiple times. The longer or more complex the scene definition gets the more important is a fast edit-encode-test cycle.

Plain scene playback does not require a quest because scenes can be started directly with scripts. This allows to create a dummy playback script and bind it to a hotkey to have an even faster playback. In combination with the modQuickStartupLastSave from trial 2 it’s a matter of starting the game and pressing a hotkey to review the current scene.

See the “Utility Scene Autostarter” info below for installation instruction of the example scene starter provided in the files section.

Scripts TMP Folder

The project template contains a special directory ‘mod.scripts-tmp/local’ that can be used to host temporary helper scripts. Dummy scripts are useful for tests but the quest should never depend on them as they should not be part of a published mod.

The full rebuild batch does not copy/update these temporary scripts into the game installation. There is a separate bin/deploy.tmp-mod-scripts.bat batch file (or the appropriate sublime build option) that is used for this. Temporary script get bundled as a separate, temporary mod and can be easily removed for the final testing of the mod.

Contrary to these temporary scripts all scripts that are somehow used in the quest definition (directly called from questgraph or new classes defined for entities, etc.) should be placed into the “mod.scripts/local/<modid>” directory. This will be the “main” script mod that is part of the published mod and also always deployed by the full rebuild batch.

Different Build Options

The project template contains predefined batch files that are setup to only encode and package the required parts of the file. But starting with a fresh project (and after reading and following the steps in the HOWTO.create.new.project.txt) the “full rebuild” has to be started first. It prepares (or updates) some initial files (like cook lists) and everything that is required in the project. After it is fully generated it’s possible to regenerate only specific parts of it (aka “patch” the deployed project). This is usually much faster.

However in the case of newly added scenes this is slightly more tricky: the above mentioned lists are generated by wcc based on the content of the quest definition. If the quest does not reference the scene wcc will not include the encoded scene file into the cook list and it will be missing in the packaged project.

So every time a *new* scene definition is created and placed into the definition.scenes directory it is also required to add a scene referencing questblock to the quest definition and to run the full rebuild (once). Afterwards it is possible to use the ***_patch-reencode-scene+restart.bat*** build option. For this trial (as it focuses on scenes only) you can also use the alternative described in the scene tutorial.

But for future scene creation a good rule of thumb:

if in doubt you can always run full rebuild to regenerate everything from scratch for the project.

Tips Storyboard UI (SBUI)

  • watch the showcase videos of sbui to get a feeling of the overall workflow with sbui but ignore the part after dumping the scenes as this is outdated with the new build pipeline
  • sbui also has a context sensitive hotkey help popup (F12)
  • you can quit sbui and restart it. it will restore the last used sbui definition. If you save the game after quitting sbui (and only *after* quitting) you can continue with the sbui definitions after loading the gamesave
  • some animations automatically attach items into the actor hands but they are not get removed after the animations. there is a hotkey in SBUI the remove all items from the current actor (see hotkeys)
  • generally prefer to use animations from the “dialog” category, especially animations with movement as those were specifically made for dialogs. other animations are also used in gameplay and might require some tweaking to behave correctly in encoded scene
  • in the encoded scene there is no snapping to ground, actor will even stand in mid air exactly like defined in sbui
  • mimics, look-ats, poses are not the focus of this trial
  • the camera mode has a rule-of-thirds overlay activated automatically. this will be useful for the advanced scenes trial. you can turn-off the overlay with a hotkey

Tips Scene Definitions

  • there are minimal test scene definitions for all supported features in the docs.scenes folder “test.examples” - a useful repository of working examples.
  • there will be another trial to see how the more advanced features work. concentrate on the dialog sections, the camera switching and only standard animations features.
  • if there is some stutter between different animations in the encoded scene it is most probably because the blend-in settings are not set properly. ignore this for now as this will be the focus in the advanced scenes trial.
  • if your actors start to smile like idiots you probably added mimics in sbui. mimic animation can be weighted, too and the default may be too strong in this case. as with the animation stutter ignore for now as this will be part of the advanced scene trial
  • it is better to define choice sections as a separate section: that way it is possible to define storyboard settings with a dedicated camera for it as well, e.g.
          - cam: [0.0, cam_5_important_choice]
  • make sure you are not using fade-out at scene ends - you will be stuck in a black scene with loading icon after playback
  • start and end sections are used to divert the questgraph flow (into and out of the scenes). this will be used in a later trial
  • do not forget to adjust the strings id-space to the value you set in the quest prod settings
  • don’t ignore any errors! most of the time there should be some information about the root cause in the lines above (e.g. string id errors)
  • although it is tempting to tweak some values to get things going you should prefer to get some more understanding what those values actually do first
  • there seems to be a bug in sbui with voicelines containing some funky characters or quotation marks which makes it cut the voiceline and break the dumped definition. keep an eye on the voicelines that get written into the script

Tips Build Pipeline

  • the radish build pipeline supports only scene definitions which are not split into multiple parts: every scene needs all of its content in one file
  • use an empty or existing quest project and put the scene to be encoded into the definition.scenes folder
  • the scene needs to have a ‘scene.’ prefix to be automatically encoded, so basically: scene.<some name>.yml
  • a “scene.<some_name>.yml” definition will be encoded as “dlc/dlc<MODNAME>/data/scenes/<some_name>.w2scene”. use this path if you want to playback the scene from scripts
  • scenes that are not referenced in the questgraph will be ignored by wcc even in a full-rebuild run. For this trial you can use the batch file from the scene tutorial.

Utility Scene Autostarter

  • add script into mod.scripts-tmp/local dir
  • add hotkey IK_F8=(Action=TMP_StartScene) in the [Exploration] section of the input.settings
  • add ‘modCreate_tmpSceneStarter()’ call in bootstrap registry for enabling autostart
  • the path to the scene is hardcoded in the scripts and needs to be adjusted every time a different scene should be played
  • make sure the setup path matches the scene location exactly