Radish Trial 7 Advanced Communities
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.
- 1 Trial 7 - Objectives
- 2 Some background Information
- 3 Variety via weighted Actionpoints
- 4 Spawning without Actionpoints
- 5 Phase Decorators
- 6 Smarter Communities
- 7 Custom Scriptclasses for Actors
- 8 Using Facts
- 9 Adding Dialogues to Actors
- 10 Tips Community Definitions
- 11 Tips Scripting
- 12 Tips Radish Quest UI (radui)
- 13 Tips Questgraph
- 14 Tips Sublime Editor
Trial 7 - Objectives
The basic communities you learned to define allow to turn a static world into a more lively area. However it's also possible to use more advanced settings to get finer control over communities. This trial will concentrate on tweaking communities based on the community phase, specifying some different reactions of non-friendly communities to the player and using scripts to get even more control over some actor events.
Your task is to:
- create an area guarded by one or more monsters which pursue the player only within a specified area, they should have some schedule in the area (e.g. eating, sleeping, etc)
- create another area with animals or monsters that respawn in waves after some time and guard their area but do not pursue player
- a third community of humanoid actors should guard an area and pursue the player only to a certain range
- one of the communities should spawn at defined spawnpoints (one or multiple)
- setup a spawntime table for a community
- use different of the available initializers for specific phases/actors of a community
- use custom scripted initializer for at least one community to init some attributes of the spawned actors that cannot be defined in the community definition (e.g. random level?)
- pick one type of monster/animal from the defined community and display a small HUD notice with a "killed"-counter on every kill of that monster/animal
Some background Information
In trial 3 the core principles of the game’s community system were introduced: actors, phases, timed schedules with associated actionpoints. This already allows to define a multitude of different npcs with individual behaviour to populate an area and make it appear lively. But there are a couple of additional community options enabling to customize communities via phase decorators, define the (re)spawning of actors and some “ai” settings to make communities appear more dynamic in their behavior.
In addition, it is also possible to assign dialogues for direct interaction with the player to specific community actors (via questgraph) or to hook into some actor script events (via custom actor classes) to advance quest progression.
A small reminder: communities can only be defined manually directly in the yml definition files. However the Radish Quest UI in-game mod can be used to verify the phases of an encoded community interactively.
Variety via weighted Actionpoints
So far one drawback of the timed actor schedules from trial 3 is the repetitiveness of the sequence. However, to allow for a little more variety multiple actionpoints can be assigned for the same time of a schedule in the community definition, e.g.:
With this the actor will randomly choose one of the three actionpoints at 11:00. If a little more control is desired a bias can be assigned to one or more actionpoints via
The higher the weight the more probable it will get picked by the actor.
It is also possible to define an
actionpoint set (meaning multiple actionpoints with the same name) in a layer definition like this:
and use it in the community definition like one actionpoint so the actor will pick one random specific actionpoint from the set, e.g.
Spawning without Actionpoints
It is not necessary to define actionpoint schedules for every community actor. Especially for animals or simple monsters the option to use a plain waypoint defined in a layer as a
spawnpoint is convenient:
In the example above one deer will be spawned directly at the location of the waypoint and follow its default idle behavior. Spawning at spawnpoints can be combined with a timetable, extended to spawn more actors at once and even define automatic respawning with some respawn delay time:
respawn setting is not set to
true and the actors are killed they will not respawn anymore (not even on the next day at the same time).
Defining multiple timed entries is also possible but if the subsequent quantity is lower some actors will be despawned instantly - visible for the player.
As with actionpoint sets using a
waypoint set (multiple waypoints with different positions but the same name) can and should be used as spawnpoint, especially if multiple actors are spawned.
For every phase a flag
spawn_hidden can be set to spawn actors hidden from the players camera (default is false), like this:
However, in general, it is a good idea to hide the spawnpoints within foliage and terrain or the respawns may become visible (when the flag is set to
false) or slightly irritating if actors pop out of nowhere when the camera slightly moves back.
Phase decorators enable to adjust minor settings or complex behavior (see section about Smarter Communities) for individual phases of actors. Since the radish modding tools support a couple of decorators and every decorator has its custom settings it is higly recommended to use sublime as an editor and to install the radish modding tools sublime support package (from the download section).
Aside from a dedicated syntax coloring for community files it also contains many auto completions for decoraters and provides lists of valid entries for some of the options (see this short example video).
Adjusting Actor Attributes
A couple of basic phase decorators were already used in the downloadable trial 3 example community, namely the
Decorators are initialized every time at the beginning of the phase but their settings are not necessary reset after switching to the next phase. In the above example the changed appearance in phase1 will carry over to phase2 (if phase2 is activated next).
Keep in mind that with the
add_tags decorator tags are added to the actor and do not overwrite previous tags. So tags added in multiple phases will accumulate and will remain until the community actor is explicitly despawned via questgraph and not via automatic despawn-respawn based on player distance to the actor (which is merely a performance optimization).
Additional simple phase decorators allow to change the
attitude of actors (change them into enemies, friends or any of the other available attitudes), to set their
immortality state (e.g.
invulnerable, etc.) or to change their
Be aware that for some actors the level can be changed only if they are already spawned. It seems the actors entity template setting does override this decorator upon initial spawning - do test this first if you want to use it.
Adding Loot and Equiping Items
A particularily useful decorator is the ability to add one or multiple items to an actor. The decorator also allows to equip the first (!) item of a list or to add one random item from the list:
The listed item references need to be valid, meaning either a reference to a radish item definition yml entry (this will get checked by the encoder) or an unchecked reference to a vanilla itemname (prefixed with
~) found in one of the vanilla xml item definitions.
Be aware that
equip does not mean
hold and only attaches the item to an entity slot. It’s also a little tricky to equip items, especially vanilla items. For example the item definition specifies an
equip_slot (see item definition xmls) which the actor entity must also have, meaning such a slot must be present in the actor template.
Unfortunately even the adding of (vanilla) items as loot is not as straightforward as it may seem. Many item definitions assign semantic tags which specify some of their characteristics, e.g.
NoShow, etc. All these tags have to be “compatible” to make items usable as loot: make sure to test in-game if the looting really works.
Custom Scriptbased Decorators
In addition to the predefined decorators with specific functionality supported by the radish encoder it is also possible to set a custom, generic, scriptbased decorator which will get called when the phase starts:
The value for this setting is simply a name of some custom scriptclass that has to be provided in the
mod.scripts/local/ folder of the project (important!), e.g:
Init function any custom script functionality can be defined which makes it very flexible to tweak community actors for a specific phase. Just make sure the custom decorator class is derived from
Aside from the basic decorators to tweak some actor attributes the community game system also supports phase decorators which can significantly change the behavior of the actors. The key difference to time based actionpoint schedules is a higher degree of freedom the games community system can leverage for the actors behavior. As a result the community acts more dynamic, e.g. actors can roam or guard defined areas on their own.
A couple of these decorators are also supported by the radish modding tools.
Reacting to Rain
A specialized decorator (which can only be turned on globally and not for specific phases) enables actors to react to rainy weather conditions. If the option is active the actor will interrupt its current behavior (e.g. actionpoint) whenever it starts to rain and search for some predefined shelter actionpoint in the near vicinity. As soon as the rain stops it will continue its previous work (click on image for short example video).
The flag has to be activated in the actors section of a community definition for every actor:
Be aware that reactions to rain does not work for every vanilla actor (e.g. animals) because the actor entity templates require dedicated AI elements which handle the rain events. But it seems at least for all humanoid actors (man, woman, child, dwarf) these are defined.
The default parameters (setup in
CRainActionPointSelector of actor entity templates) make the actor to look for actionspoints with a specific tag (either
rain_shelter_dwarf) with a distance lower than 30 meters to its current position.
This means additional custom rain actionpoints can also be defined, e.g. like this:
The selection, positioning and previewing of the rain actionpoints can be done interactively in the Radish Quest UI in-game mod. However only actionpoints from the
rain_shelter_dwarf categories get picked up (by the corresponding actor types).
One interesting decorator, especially for animals and monsters but also for human camps or posts, is the
guard area decorator.
Basically, an area is assigned in a community phase to an actor and the actor will attack enemies trespassing that area. Unlike a normally spawned actor an actor with an assigned guard area will only attack the enemy if it is in its line of sight and it enters the guarded area. In addition the trespassing enemy cannot bait the guard actor to pursuit it indefinitely. Instead, after stopping the pursuit the actor returns to the guard area again even if the trespasser is directly in front of it.
The most simple definition looks like this:
Additionally, there are two pursuit strategies that can be defined for guarded areas:
- pursuit range
- and pursuit area
The pursuit range is defined in meters and the game uses this strategy with a default value if no pursuit area is defined. But the range can be increased or decreased explicitely like this:
A more customizeable option is to define a specific pursuit area which may be more adequate depending on the terrain the guard area is located in, e.g.:
Both, the guarded and the (optional) pursuit areas have to be defined as “normal” triggerareas in Radish Quest UI and are referenced by the hub-id and their respective names as seen in the above example definitions.
While guard areas offer a simple solution to automatically protect a defined area by actors, a more dynamic option is to use a
Actors with a wanderarea decorator use the referenced area to autonomously roam inside the area, sometimes stopping for a while. Depending on their type they either attack enemies they detect (e.g. predators) or flee from the detected enemy and return after a while.
The most simple wanderarea decorator referencing a generic trigger area can be added like this:
There are a couple of settings which can be customized, for example the movement type:
The distance setting seem to affect group dynamics which is hard to explain and may even work differently for different actor types. It’s best to experiment with these settings or not define them and use the game’s defaults.
Overall this simulates a slightly more natural behavior of a community, especially for predator animals which start hunting prey within their wanderarea automatically.
Whenever actors should follow along a specific path (e.g. patrolling) the
wanderpath decorator can be used. A wanderpath is defined by a set of
wanderpoints which the actor is trying to reach one by one in the order of the defined sequence. At the end of the sequence the actor will continue the path in the reverse order until reaching the first wanderpoint again, and so on.
The wanderpoint sequence is defined as a set of layer wanderpoint entities and is only referenced in the community phase decorator of the actor:
The individual wanderpoints can be interactively created and positioned in Radish Quest UI in the waypoint category (see video). Every waypoint with its name prefixed with
wander. will be dumped as part of a wanderpoint sequence with the name of the waypoint set, e.g.:
Here, the last parameter defines a
radius around the wanderpoint the actor must enter to “reach” the wanderpoint and continue to the next point.
A useful variation of the default “follow-the-path-and-then-return-in-the-opposite-order” behavior is to define a circular path. The radish encoder generates a circular path if the last wanderpoint point equals the first wanderpoint in the sequence, e.g.:
The result will look like in this video.
As with wanderareas there are also a couple of additional settings that can be customized for
wanderpath decorators, for example the movement type:
All in all for bigger areas it’s probably a good idea to define a combination of different actors with
wanderareadecorators as well as some with actionpoint schedules to make the community act somewhat varied.
Wanderarea/path decorators are a good choice for actors with a small set of behaviors (e.g. animals or monsters) or if roaming/patrolling of an area is their main purpose. But they do not support the usage of actionpoints which limits the illusion of natural behavior traits of more complex humanoid actors.
As a more dynamic alternative to static actionpoint schedules the
dynamicwork phase decorator allows to define a list of actionpoint categories and actionpoint tags. These settings are used as filter conditions for actionpoints from all of the currently useable ones: an actor will randomly pick one actiopoint from the filtered set (category and tag must match!), move to the actionpoint, play the associated actionpoint animation and randomly select a new actionpoint from the set to move on.
Dynamic work decorators can be defined like this:
The set of matching actionpoints can be created and interactively positioned in Radish Quest UI however the appropriate filter tag has to be defined manually in the dumped layerdefinition, e.g:
There are also a couple of additional settings for dynamic work decorators:
restrict_to_area is an additional filter condition to reduce the set of used actionpoints even more: all conditions have to match for an actionpoint and it has to be within the area to be considered by the actor.
With an appropriately sized set of available actionpoints
dynamicworkdecorators enable a reasonably dynamic community behavior.
However there are also some drawbacks of the
dynamicwork decorator. For instance, the length of stay for one actionpoint is solely defined by the actionpoint animation and is not controlable, e.g. some animations are much longer than others and it may seem the actor is not moving on.
A (seemingly) bigger drawback is a deferred activation of new community phases for these actors (e.g. with other dynamicwork categories or static actionpoints): the actor does not immediately change its behavior but continues to select actionpoints matching the previously active dynamicwork settings. Only after respawning of the actor the new phase settings will be picked up.
Although this is a limitation mod authors should be aware of it is also not as bad as it sounds: by default all community actors are despawned when the player moves a little farther away and respawned as soon as the player returns. However, for example switching between day and night cycle phases will not work properly if the player stays in the vicinity of the community.
The deferred activation of subsequent phases also applies for wanderarea decorators.
Custom Scriptclasses for Actors
Although the scriptbased phase decorator is fairly generic as it enables to manipulate the actor’s settings via scripts it is only called when a phase starts. But sometimes it may be necessary to hook into other events of specific actors to perform some scriptbasd tasks, e.g. when the actor dies or gets damage, etc.
While the following information is not strictly tied to the radish community definitions it is useful to know how to create new templates with a custom class as it also enables to implement some quest conditions that can be used in the questgraph. More on this in the next section.
Directly manipulating the scriptclasses of vanilla actors is an option but comes with considerable drawbacks, especially for a conflict-free installation of the mod. As seen in trial 5 it is fairly easy to “extend” vanilla entity templates with new functionality. This includes creating a completely new entity template for an actor with just a different main class but all the settings, behaviors, ai, etc. inherited from the base actor template. For example the following definition:
will create a new entity template in the entities project folder named
rad_wraith_minion that can be referenced in a radish community definition without worrying about the final entity template path, like this:
Now a custom script class named exactly as in the entity template definition (
CRadWraithMinion in the example) has to be added to the
mod.scripts/local/ folder of the project for this actor to be able to spawn. In the class only the desired event hook methods need to be overwritten (meaning defined with the same method name). In those methods some custom functionality can now be added without changing the rest:
The previous section mentioned creating new conditions that can be checked in the questgraph to advance some quest progress or simply change some aspects of the world.
The game uses a
facts database (a key-value database) to store various information about the current state of the game. Those state information (like completed quest, visited npc, etc.) are called
facts and are created/updated/deleted in various places (scripts, scenes, questgraph, etc.). The fact db is stored in the savegame and restored when a savegame is loaded.
Since arbitrary facts can be created via scripts this can be used to push some (basic) information from scripts to the questgraph. For example a simple actorclass-specific “alive”-counter can be added to the above custom actor class like this:
Everytime an actor with this class is spawned the
rad_guardwraiths fact value will be increased by one (value of the second parameter). In addition if any actor with this class dies, the value of
rad_guardwraiths will be decreased by one.
Important: Make sure used fact names are always unique, e.g. by prepending the modid.
Now, such a fact can be used as a condition gate in the questgraph, e.g. to trigger a scene or progress the quest:
Adding Dialogues to Actors
Topic of trial 4 was the creation of interactive dialogue scenes but the scenes were always started explicitely via scripts and only for testing. However starting scenes like this in a quest where the player has to initiate a dialogue with a specific actor by talking to the actor is not a viable option. Instead the trigger to start a specific scene can be attached to one or more actors identified by a tag directly in the questgraph via the
interaction questgraph block.
Be aware that questgraph interaction blocks only attach a scene-trigger to actors. However the actual actor that is used in the scene is defined in the scene.
As an example: a scene with a dialogue between Ciri and the player can be attached to a random prologue peasant and will be started when the player “talks” to that peasant. The test scene definition
docs.scenes/test.examples contains more information on how a scene actor is searched by the game’s scene system (gameplay and normal scenes work the same way in this regard).
interaction block holds the questgraph signal until one or more actors with the specified tag are actually found and the scene is played after the “Talk”-interaction with the npc actor. After playback the scene is not attached to any of the actors anymore.
If a subsequent “Talk”-interaction should start the scene again, a dedicated loop in the questgraph has to be created. In most cases a circuit breaker to cut the loop at some point is advisable, e.g. a fact checking block like this:
But it is also possible to signal the questgraph a different output directly from the scene (e.g. from different dialog paths based on player choices or some facts checked). As mentioned in the third part of the scene tutorial (see docs.scenes/tutorial/) every exit-section of a scene definition can assign a case sensitive string value to the
output setting (default being
Output). After the scene ends this value is being picked up by the scene’s questgraph block and mapped to an equally named out-socket.
These custom sockets have to be added manually to the
interaction block via context-menu.
Likewise, multiple in-sockets can be defined in the graph to start the scene from a different scene part. In-sockets are mapped to different start-sections of the scene. The following scene definition snippet shows the corresponding section names and output settings to the above interaction block sockets:
This can be very useful for random or slightly less repetitive dialog openers/dialog paths.
In addition, gameplay scenes (no camera changes on playback, no interactive player choices) can be used in the questgraph the same way as normal scenes. For example to create simple oneliner replies to “talk”-interactions or complex multi actor dialogues which even include mimics and animations.
If it is required to directly start playing a scene without any player to npc interaction (e.g. upon entering some area) the
scene questgraph block can be used. As with
interaction blocks custom in- and out-sockets can be attached to the
scene block, too.
Tips Community Definitions
- phases defined in a community definition can have actionpoint timetables for individual actors but the phase itself cannot be activated at specific times. switching between complete phases can be accomplished by activating the phase in the questgraph, e.g. waituntil some time -> set phase 1 -> wait until some other time -> set phase 2 -> back to first waituntil, etc.
- a reminder: actionpoints and waypoints referenced in community definitions must be accessible (= layer must be active) when the phase is activated. otherwise the community may not spawn or not react as defined.
wanderareasdo have more settings than mentioned above which imply some control over idle and movement chance and duration as well, like this:
wanderarea: area: <wanderarea-reference> movetype: <walk|run|fastrun|sprint|absspeed> # speed: 1.0 # maxdistance: <50> # mindistance: <30> # idleDuration: 5 # idleChance: 0.3 # moveDuration: 5 # moveChance: 0.7
however for a couple of templates they did not show any (significant) effects. nevertheless these settings can be specified. maybe only a couple of actor templates do support these at all. test and decide for yourself.
- if custom script initializer do not seem to work, first make sure every custom scriptinitializer is really located in the
mod.scripts/local/<modid>/folder (or a subfolder). see below.
- be aware that npc do not move around but through new static entities that are placed as layer entities. npcs can only navigate on a navigation mesh that defines which areas are walkable or non-walkable on top of the default terrain navigation mesh. navigation meshes need to be created manually and will be part of another trial.
- make sure all custom classes for phase intializers and actor entity main classes are located in the
mod.scripts/local/<modid>folder. this ensures wcc has access while it cooks defined entities and communities. if these classes are not accessible by wcc it will silently remove the references from the cooked entities and these entities will not spawn or work correctly in-game!
- check the actor or CNewNPC classes to see what events can be hooked and what attributes can be adjusted on spawn.
Tips Radish Quest UI (radui)
- it is possible to switch between community mode and layer mode with a hotkey while being in the top most workmode (either layer over view or communities overview)
- snap-to-ground mode for entities is only used to make it easier to place entities in interactive placement mode in radui. it has no effect on the actual entities (being it actionpoints or other entities) once encoded
- actionpoints have an “ignore collisions” setting which makes actors to ignore collisionmeshes at the actionpoint. this is especially useful for actionpoints simulating interactions with other meshes, e.g. sit on a chair/bench, etc.
- dynamic communities add an important part to immersive environments. a good and convincing supplement are ambient sounds, e.g. crowd sounds, children playing, crickets, etc. ambient sound areas can be defined in radui as normal trigger areas by changing using the prefix
sound.for the area name. new options to choose sounds will appear.
- ambient area sounds with
EMin the name appear to be played only once
- additionally, well placed particles, e.g. flying butterflies can add further to the illusion. those can be setup as static entities with their names prefixed with
- radui allows to clone the currently selected layer entity. this makes it also easy to create multiple actionpoints or waypoints as a combined actionpoint or waypoint set.
- extracting or adding specific actionpoints or waypoints from/to a set is done by renaming the entity. if the name is unique it will be a standalone entity. if the name matches another entity name it will be combined to a set (this works only for actionpiints and way/wanderpoints)
- every waypoint can be used as spawnpoint.
- if an invalid scene name is set in the questgraph scene- or interaction-block the scene will NOT be found by wcc upon cooking. in this case the mod is NOT properly cooked! ALWAYS check the error for logs!
Tips Sublime Editor
- the sublime support package contains a set of autocomplete snippets for all supported community definition elements. autocompletion is always context sensitive: starting to type
new(instead of community-, actor- or phasenames),
settings(in place of
a..and others will bring up a menu with a selection of the snippets.
- switching between the placeholder fields of autocomplete snippets works with the
tabkey, but once cursor keys are used, it’s not possible tp switch between placeholders anymore.
- to activate syntax-coloring and snippet support for an existing community definition change the filetype (lower right corner like of the status bar in sublime) to
radish community definition
- valid values for
attitudesare autocompleted. However there is a very big list of attitudes and it seems it’s not a final list, so only a part of the list is autocompleted (which also means this is a free textfield and will also NOT be checked in the encoder!).