HOW-TO: Create an encounter with NPC merchant

Open

Here’s how you can create an encounter with a merchant - an NPC who you can interact with.

You can find merchants entity templates which makes them easier to find and use multiple times.

Merchant entity templates

Open the Asset Browser and go to the following location:

• \\depot\living_world\dialogue\generic_merchants\entities\

Here you can find each of the main merchant types from the game (weapons dealer, herbalist, innkeeper etc.).

Open

If you open one of these entity templates, you will notice in their properties that each one of them has a predefined scene that they use when interacted. You can check that after opening the entity template: click on the background of the graph, then go to Node properties tab and expand the W3MerchantNPC section (the entity originates from the W3MerchantNPC Entity Class).

You can see the scene in the StoryScene field: the scene will be played each time the player interacts with the merchant. You can see how the scene’s graph is assembled by opening it:

These nodes represent the dialoglines and dialog choices for the player. This graph can also refer to Scripts like the ShowMeGoods that can helps to initialize the merchant mechanic.

These dialoglines and its sections (represented by the nodes) can be seen in the Screenplay tab.

Learning about Encounters

There are two ways to spawn merchants into the world:

• using Encounters for more generic NPCs found throughout the living world.

• using Communities for merchants who have a bigger role to play in a quest.

Encounters are using up SpawnTrees that define which entities will spawn in the area. Take a look at this SpawnTree which uses a generic merchant, here:

• gameplay\community\community_templates\novigrad\homestead\homestead_ursten.spawntree

You can study these SpawnTrees and create your own based on their structure if you see something similar to what you need.

In this example you can see that our merchant is placed in during the day:

Table of contents:

This exact SpawnTree is used on the Novigrad level (levels\novigrad\novigrad.w2w).

Open that level and in its Scene Panel on the right, find the following path:

• levels\novigrad\communities\homestead\ursten\exterior

In this layer, you can see that there’s a CEncounter called enc_com_hs_ursten. By right clicking on it and select Show Resources you can see that it’s using the exact spawntree that we have observed before:

So based on the what we have learned:

• we need an encounter placed in a layer that includes the spawntree file in its structure.

This spawntree is responsible for defining the exact entities which will spawn in that area, which conditions need to be met and what time period they are supposed to be spawned.

Add custom merchant Encounter

Create a layer in your level, then right-click on the level preview select Gameplay > Area > Add Encounter Area.

Resize it to cover quite a large part of the map using the Vertex edit tool.

Make sure that it’s quite high and isn’t floating above the terrain.

Now, we need to place an ActionPoint where our NPC will be spawned.

ActionPoints can also define the work routines (Animation sets) that an NPC will perform once inside in the area.

Jobs define a set of animations that an NPC will perform and in what way. In this case, it defines a sequence where the NPC performs a “playing_with_coig_bag” enter animation, then starts the “money_counting” animation looped a couple of times then it ends the sequence with the final “counting_money_end” animation.

Open

Add an ActionPoint component (CActionPointComponent) into an entity template that holds the reference to the Job tree.

This entity template then can be placed into a layer having the action point ready to be referenced in one of our encounters (Spawn Trees).

Let’s test this.

Go to gameplay\community\actionpoints\work\ or gameplay\community\actionpoints\marketplace\ in the Asset Browser.

(The letters in the file names tell you which NPCs can use the actionpoint: “m” means man, “d“ means dwarf, “w“ means woman).

Select and drag the desired Actionpoint Entity into the World View (level preview).

Then open the Actionpoint in the Scene Panel and add a tag to its properties (CNode > tags)

Next you will need to create a new SpawnTree Asset file that later will be used for the encounter.

1. In the Asset Browser right click in a folder of your choosing to display Options Menu. Choose Create > Spawn Tree.
   
   

2. Add a descriptive name such as encounter_merchant_test.

3. Open the new Spawn Tree file to setup the creature definitions table.
   
   

The process is explained below.

Referencing NPC Entities

First, we need to reference all NPC Entities that will be used by the Encounter.

That is where the creature definitions table will be put to use.

1. L.Click on the plus sign (that says Add Creature Definition) above the Creature definitions table to add new entries.

2. Name your entities. Definition Names are used to identify the Entity in the Spawn Tree.

3. Search for entity templates in the asset browser (characters → npc entities), select them, and then press the green arrow in the desired row to paste the reference to the template.
   
   

4. You can leave “Forced appearance” and “Override” box as default.

   1. Forced appearance can set the exact look (appearance) we want to use on an entity from the list of appearances defined inside of it’s Entity Template.

   2. Override grants the permission to override the creature definition from the included templates it might has.

5. At Tags Make sure you have it set to generic_merchant_nomansland_armor.

   1. With Tags, we can determine what is the exact tag that will be assigned to the Entity as soon as it’s spawned, so that later we can reference it by it’s tag. When the player will interact with the NPC, the scene will play and it needs the exact reference for the Shop mechanism to work.

   2. To get the tag value, locate the NPC’s entity template and open it. Inside the entity template editor, you can click on the background of the Graph editor panel. This will populate the Node properties tab. Inside the properties panel, scroll all the way down to W3MerchantNPC section then toggle down the MerchantNPCEmbeddedScenes where you can see what is the exact scene file it uses:
      
      

      
      Open up the scene file and head over the Definitions tab. Here, under the Actor Tags column you can find what is the exact tag value that you need to use for the merchant interaction scene to work.
      
      

      
      This is the exact tag that is used for the script that’s being called during the execution of the scene graph (Script [ShowMeGoods]):
      
      

       

6. Total Spawn Limit” and “Max Spawned At Once” are not used in this example, but they are usually used in hostile encounters, or for groups of animals. Total spawn limit controls how many of that entity can exist using the spawn tree. Max Spawned At Once controls how many of that entity can be spawned at the same time (0=infinite).

7. Repeat step 1. to 5. until you have all your entities listed that you want to use for the SpawnTree.

    

Spawn Tree setup

We can start setting up the Spawn Tree.

Spawn Trees usually start with either a Parallel node or Selector Node:

• Selector - action only spawns the first branch/tree to the left.

• Parallel - action spawns all trees it has been assigned.

For our Encounter, we will use the Parallel Node. In the Spawn Tree visual scripting environment (VSE), R.Click and select .

Next, we need to setup the Spawn Entries:

1. R.Click on the Parallel Node to display Context Menu.

2. L.Click “Add Spawn Entries”.

3. Each Spawn Entry can be customized to control when and how a spawning will occur.

For instance, the Spawn Tree might choose different Actionpoints/Entities for Day as opposed to Night:

In our example, one Spawn Entry will be created.

Multiple types of Entry nodes can be added to SpawnEntries - each Entry is usually dedicated to one NPC:

For our example, only Work Smart AI will be used.

Next, create Entries for all NPCs added during Setup. This time it’s only going to be one Add Work Smart AI Entries node.

Customizing entries

There are many ways to customize Entries with quite a few properties. We have collected what are the most important ones for the initial setup:

• Quality Min / Max:
  How many NPCs the Encounter will Spawn.

• Creature Definition:
  This uses the Name chosen during NPC Entity Setup.

• tagToAssign:
  Make sure you have it set to generic_merchant_nomansland_armor.

• appearanceName:
  This controls what the entity will look like in-game. If not set, the appearance will be randomised.

• Group:
  Determines the Entry NPC's priority to spawn. “ESG_Quest” is the most important, will spawn always. “ESG_OptionalCommunity” is the least important, will only spawn if all other, entities could spawn.

• apTag:
  Reference to the Actionpoint Tag given during Setup.

• Spawn Params:
  visibility - When NPCs are allowed to Spawn. Default is Hidden with 0 delay. But most of the time it’s recommended to use ALWAYS.

• Work Categories:
  Defines the categories Actionspoints require. These can be checked by going to the Asset Browser and seeing which directory they’re in (for example: work, resting, rude, sleeping). In this example, we’re going to set “work_man” because the actionpoint is in the work directory, and the entity we’re using is a man.

Make sure that you have the mentioned properties set so that your properties list for the Work Smart AI Entries looks like the this (after selecting the node):

Generating entries

Once we have finished customizing, we can start generating the entries. R.Click on the Work Smart AI Node → Generate Entries. Repeat until all entries have been generated.

When that’s done, the Spawn Tree is ready to be included into our encounter.

Include Spawn Tree in Encounter

Back in the Editor’s main window go to the Scene Panel and right-click on the Encounter Area → Edit Spawn Tree.

An Encounter Editor - which looks very similar to the Spawn Tree Editor - should open, where an empty Spawn Tree should be visible for your new encounter.

To include your existing Spawn Tree:

1. R.Click → Add SelectPhase.

2. L.Click the Select Phase Node’s three dots. Now another node named “Default Phase None” should appear.

3. R.Click “Default Phase None” → Include File.

Set the Include File Node to reference the custom Spawn Tree in the Asset Browser by selecting your spawn tree in the Asset Browser and clicking the green arrow in the “spawnTree” field.

If the last couple of steps have been followed correctly, your included Spawn Tree should now be visible.

And that’s it - you have a new encounter which spawns the NPCs that you have defined!