Effects

This page contains some of the more technical aspects of creating Effects. It ties in closely with Comic Editor Reference and Story Inputs and Outputs. In some Effects, you may want to know about certain Expressions for calculating values via functions or information from the game.

Note that the comic editor has buttons that can add some of these things (New Story Role, New Target, New NPC, and New Choice), so if you've used that, you're already familiar with some of this!

(For a more general overview of how effects relate to other parts of Wildermyth, see the Data Format Overview)

Overview

Effects are how things happen. An effect represents a trigger or ability that can have multiple targets and multiple outcomes. If all targets are present, the ability is valid and the outcomes are executed. Effects (especially abilities) are sometimes attached to entities via aspects.

The main kinds of effects are:

Events

Events are encounters or stories that happen due to specific in-game triggers. These triggers include things like arriving at a hostile site (ENCOUNTER_HEROES_ARRIVE_HOSTILE_SITE), winning a mission (ENCOUNTER_MISSION_VICTORY), or a specific plot event (PLOT_ARRIVE). Events are generally used to tell a story of some kind, and thus are almost always accompanied by comics. Most of the work in creating comics can be done in the Comic Editor. Events also often make Outcomes happen, which can mean things like granting resources or relationship points, applying a Theme or Aspect to a hero, starting a Mission, causing another event to happen, or a lot of other things.

Abilities

Abilities are things heroes and monsters can choose to do during missions. This includes everything from moving, to attacking, to interfusing. All abilities use the special "ABILITY" type. They all have Outcomes that determine what the ability does, which generally includes things like making an attack roll, dealing damage, moving, adjusting stats in some way, or modifying scenery on the map. These generally don't include comic panels, though there are exceptions (see callDownVolleyOfArrows).

Abilities are attached to entities via aspects. For example, if you look at the "human" aspect, you'll notice it has all the standard abilities humans have: run, openDoor, waitEndTurn, etc.

Tidings

Tidings are events that happen during the Interval after a chapter that show what heroes did during the years of peace. These are generally just comic stories, though they can also have other Outcomes (like granting resources) if desired. These are separated into several different categories, listed on the Tidings page (along with a guide on how to make one).

General

• id: unique identifier for Effects. Aspects use this id to specify what effects they cause.
• name: Short static name, appropriate for ability bar
• longName: Full or long name, could be static or dynamic, using role tags, i.e. The battle of <site>. If null, short name will be used.
• blurb: Tooltip description. May use role tags.
• type: When does this effect trigger? Special case: Ability and OverlandAbility cause buttons to appear in the action bar. Other types are triggered automatically when needed.
• verb: what kind of action is this? Is it a Job?
• expressions: A map of expressions that can be used in the Effect. For example, events often use expressions to sort heroes by stats, in order to select a volunteer for a particular role.

Info

• sourceFile: What file is this Effect from?
• modId: What mod is this Effect from?
• author: Who wrote this Effect? If this is a comic, this name will show up next to the Effect name.
• STUB: for developer-facing documentation, or to note unimplemented but intended functionality.
• sort: when there are multiple effects in the same category, they will be executed in ascending sort order.
• aiPriority: AI will try to execute effects with the highest aiPriority.
• aiAbilityType: Used to tell AI to use this ability in a certain way
• tags: tags are used for things like defend keys, are analogous to aspects that apply to effects.
• followupIds: Will potentially show these followups (tidings) during the interval between chapters.
• debug: If true, this effect will be logged when executed.
• declaredEncounterResults: Some events provide encounter results. These must be declared, or it's a validation error. Declaring results allows us to easily validate villain plots in turn.
• hideWikiLink: If true, the link to the wiki page for this Effect won't be shown
• customWikiName: If set, the wiki link will point to this link instead of the event's name. Useful for multi-part events that should probably link to the same wiki page.

Ability

• icon: Icon to show for this ability in the ability bar
• category: control what color to assign in the UI
• strictlyBetterThan: Notes that this ability is strictly better than these other abilities. This is used by the UI (and AI) to suppress those abilities when this ability is available. For example, Guard is strictly better than Wait (ok well maybe it's Just Better, not Strictly, if last hits are important?) so we suppress Wait when Guard is possible.
• priority: used for sorting in the UI. higher priority means first.
• showSiteBanner: Show a site banner for this job
• showInCharacterSheet: If true, this ability will show up in the character sheet's combat tab, as well as hero/monster tooltips
• onlyShowIfPossibleInCharacterSheet: If true, (and showInCharacterSheet is true) this ability will show up in the character sheet's combat tab, as well as hero/monster tooltips, but ONLY if it's currently possible to execute this ability
• extraUI: Extra and override information related to the UI shown for this ability (useful when damage or range isn't showing up automatically for the ability, either because it doesn't deal any damage (e.g. bogmoor's Noxious Tongue), the damage isn't dealt immediately (e.g. Jumpjaw), or for some other reason
  • overrideDamageShown: Overrides the damage shown in tooltips
  • overrideDamageType: If overrideDamageShown is set, shows it as this damage type
  • overrideShredShown: If overrideDamageShown is set, overrides the shred shown in tooltips
  • overrideRangeShown: Overrides the range shown in tooltips
  • overrideMinRangeShown: If overrideRangeShown is set, overrides the min range shown in tooltips
• hideOnAbilityBar: If true, this ability won't show up on the Ability Bar. Useful for AI-only abilities.
• showDescriptionInTooltip: If true, tooltips including this ability will show its description. Useful for explaining more complex abilities.
• specialAnimationEffect: Should there be a specific effect on the ability use animation?
• specialAnimationExpression: Any float that goes along with the special effect (like "Bloodrage (+2)" needing to pass in the "2")
• customSpecialAnimationEffect: Allows for a custom special animation effect when used in a roll effect like DAMAGE_ROLL or DEFENSE_ROLL. Useful for showing extra damage or defense provided by an effect, e.g. "Bloodrage (+2)"
  • text: Text to display as a special effect. This can include parameters in the form of {0}, {1}, etc.
  • parameters: Values to replace the parameters in the text field. ex: putting COUNT.target here could make the text "Targets ({0})" show up as "Targets (2)"
  • scriptName: The animation script to use for the special effect
  • textColor: The text color for the special effect
• disallowStunt: If true, this ability and any abilities branching from it won't use stunt. Useful for things like Guardian and Sentinel.
• specialTreatment: Special cases for certain events
• cooldown: How many times can this ability/event happen per game/mission?
• checkCooldownAfterTargetNumber: Check whether the cooldown is satisfied after the given target.
• labor: jobs take time and effort to complete.
  • days: How many days to complete this job?
  • mustBeLocalToParticipate: If false, participants can contribute to this job even when they're not at the job site.
  • allParticipantsMustBePresent: If true, all participants must be present before work can progress.
  • minParticipantsPresent: The minimum number of participants that must be local in order for work to progress.
  • role: The role that labor participants get stored in
  • speedFactor: How fast a unit contributes to the job, where a speedFactor of 1 takes the number of days listed.
  • helperContributionSpeed: Each additional participant's contribution is multiplied by this number (generally used to produce diminishing returns)
• resourceCosts: jobs may also consume resources.
• jobType: Is this a special type of job? (e.g. a capstone mission)
• encounterScore: Encounters with higher scores will always happen instead of ones with lower scores, if possible.
• encounterWeight: How likely is it for this encounter to happen vs other encounters with the same score? i.e. A weight of 2 is twice as likely as a weight of 1.
• encounterEnabled: If this is a procedurally chosen event, this must be true in order for it to be chosen.
• onlyShowForNewSites: If true, this event will only fire if the site hasn't already been cleared before. Useful for Mission Victories
• jobCanBeCancelled: If false, this job can't be cancelled once started. (Heroes can still be switched off of this job, but the job banner will stay there)
• jobNotificationInfo: Details about what an overland notification should show when this job (if it's a job) is completed
• suppressNotification: Should this effect not produce notifications? This will suppress things like job and Mission ("attack") notifications
• suppressFriendlyFireWarning: If true, the game will not warn the player if an action is predicted to possibly hurt allies.
• branchableAbilityType: If not null, this ability can be branched to from other abilities (like Guard, for example)
• musicOverride: If this effect causes a StoryDialog to pop, override its music. Can also put an empty string to not switch to any music.

Implications

Implications are for events only. They are executed right before the event is posted to the player. They can be used to execute arbitrary "setup" outcomes, or to create things like NPCs, Monsters, items, and more!

generatedTargets

• role: The role to assign the created entity to
• npcId: This is a global ID that can be used to remember NPCs and find them later. Make it unique!
• createEntity: Details about what to generate. (See Outcomes.Spawn.createEntity)

Some Specific Use Cases

Cloning a Role

Useful when you want to put someone from your party on the enemy team during a mission. This way, they won't actually die. The clone will have the same weapons and be (basically) indistinguishable from the original. Set inRelationTo to the role you want to clone (either from a target or a previous implication), and cloneRelatedEntity to true.

You can also make changes to it, like using setAge to make an older/younger version of the person, or using setName to make their name be something different.

Targets

Targets will usually be the bulk of the Roles you use in an event. Many of these are "injected" from wherever the event is happening, like the party, foes, and site being injected from the overland map to a mission. Below are some general explanations, filters, and methods of selection you can use in events, as well as some common specific use cases.

General

• role: This is the way selected entities are stored and accessed. Each role is just a name assigned to the selected entities, which can be used to access them in comics and Outcomes. Sometimes, you may find that the predefined roles that show up when you create a new event (self, company, overlandTile, site, party, etc.) and the roles that are generated for heroes via the comic editor (bookish, snark, leader, etc.) are enough. However, you can always add targets with other roles if necessary.
• template: All targets have a template. The template sets some basic properties, which can then be overridden or changed. Templates make it easy to put together common functionality.
• STUB: for developer-facing documentation, or to note unimplemented but intended functionality.
• type: What type of entity are we looking for? An indiviudal? A piece of Scenery? A site?
• promptText: localized targeting prompt for slots dialog (e.g. "select the ally who will do the thing")
• promptScript: If the user needs to make a choice, this designates the comic nodes displayed before the choice nodes.
• options: List of choices for the player to make. Choices have tags that are used by outcomes to control what happens.
  • id: The ID of this choice. Will be referenced in the outcomes.
  • description: some text, etc., to display for this choice.
  • script: Comic nodes to display for this choice
  • extraData: Some choices also allow us to enter custom data, like naming the company or renaming a site
  • ifTargetIsPresent: This option is only valid if the target role is present
  • enabled: If false, this choice won't be displayed
  • uiCancel: This option is a dummy, only present to allow the UI to cancel the ability use

How many, and how to choose them

• choose: If there are multiple potential matches, how will decide which of them to target? The default is ONE, which means that if there is exactly one, pick it automatically, if there is more than one, the player (or something else) must pick, and if there are none, we fail and this effect can't execute.
• slots: Party slot information (for selecting parties)
  • min: Minimum number of heroes required
  • max: Maximum number of heroes
  • hint: A hint to the UI to pre-fill slots with this role
  • preFill: How should heroes be chosen to prefill the slots dialog?
  • requiredRoles: These roles are required, and can't be removed from their slots
  • specialSelectionInfo: Can be used to show additional selection information to help the player decide who to choose
    • aspect: If the hero has this aspect, show the customText on their button (e.g. show "Bard" on heroes with the Bard ability when recruiting)
    • customText: Custom text to show on the buttons of specified heroes
    • customTextTooltip: Tooltip that will be shown if the custom text is hovered over
• scoreFunction: When choose=BY_SCORE, this score function is used to pick from among multiple potential matches.
• scoreThreshold: when choose=BY_SCORE, scoreFunction must be at least this value for this to match
• chooseAllMinimum: There must be at least this many matches for this target
• chooseAllMaximum: There can be no more than this many matches for this target
• allowDuplicates: This target can be shown multiple times in a single comic panel

Cost that must be paid

• cost: A special outcome that is tested along with this target (usually ActionPoints for abilities)
• timeCostPerStep: Path motion time cost - special case for now

Feedback to player

• showAnyway: Whether to show this ability in the action bar, if this target cannot be satisfied.
• alwaysSelect: whether the player must always select the target, even if there is only one match. Example: for attacks, we make the player click on the enemy because that feels good.
• missionFeedback: Feedback shown to the player in a mission
  • orientTo: Face this figure toward the given Role
  • suggestionScript: Script for possible choices for this ability
  • hoverScript: Script for the hovered choice, if any
  • selectedScript: Script for the selected choice, if any (if null and hoverScript exists, hoverScript will be used instead)
  • rangeFeedback: Tile feedback shown within the range of this ability
  • rangeFeedback2: Special range feedback for if there won't be any actions left after this one
  • suggestionFeedback: Tile feedback shown on possible selectable tiles/entities
  • suggestionFeedback2: Special suggestion feedback for if there won't be any actions left after this one
  • hoverFeedback: Tile feedback shown on hovered tile/entity
  • applyRoleFootprint: If set, the footprint of this role will be applied to tile feedback. Useful when providing feedback that involves moving multi-tiled entities, so the feedback shows the full entity footprint size instead of just the origin tile. (Often used with AbilityTarget.roleMustFit)
  • feedbackSource: Overrides the source of the feedback. This is useful for AOE attacks, like splinterblast. This can usually be left null for direct attacks.
  • showMovementFeedback: Should FEEDBACK_MOVEMENT and FEEDBACK_MOVEMENT_PREDICTION effect feedback be shown for this target? Should generally be true if this target is a movement destination. (e.g. Zealous Leap)
  • movementFeedbackRoleOverride: If showMovementFeedback is true, this will override the role that we're showing movement feedback for. (If null, uses the relativeTo role by default)
• overlandFeedback: Feedback shown on the Overland map
• cardChoice: Special case choices
• aiHints: Hints used to tell AI what the best choice is
  • scoreNearbyFoe: For all foes within foeRange from this location, add this to the score of this selection
  • foeRange: scoreNearbyFoe will be added for each foe within this range
  • foeMaxRange: If not null, foes between foeRange and foeMaxRange will add to the score based on a lerp from scoreNearbyFoe to zero. Useful when further away foes should contribute less to the score.
  • scoreNearbyFriend: For all friends within friendRange from this location, add this to the score of this selection
  • friendRange: scoreNearbyFriend will be added for each ally within this range
  • fullInferLookAhead: Actually try choosing each of the targets, do an infer, and return the ai priority as the score.This can be expensive, so be careful!

Domain: What should we match? What will we consider?

• injectedRole: Match a role from the external context of this action. Useful for actions that operate in a known context, such as the DEFENSE action or boosts.
• fromRoles: Combine potentially multiple roles that have been matched, in order to filter them further and select amongst them. For example, this lets us apply filters to scenery and fire, and then combine those to pick one "thing" to interfuse.
• pathFrom: used to automatically infer a path from some source to a destination
• pathTo: used to automatically infer a path from some source to a destination.
• relationship: match entities that are related to the parent via a specific aspect.
• legendId: match a specific legend
• matchSpecial: a "special" one-off sort of domain.
• line: targets are to be matched on a line between two other existing roles. (Also see manifold)
• manifold: defines a manifold between a source and a destination, with variable thickness.
• onTile: search tile contents only

Filter: Tests that we apply to each potential match

• aspects: A list of aspects the target should have, by id. This can be used to check foe flavor (drauven, gorgon), hero aspects (humanFemale, mystic), and anything else that's an aspect.
• aspectValues: An extended version of aspects. Allows for forbidding aspects, checking aspects relative to a different role, and setting a min and max value the aspect must be within.
  • id: The aspect id
  • forbidden: If true, this aspect must NOT exist
  • relativeTo: Match a relationship aspect between the target and the given role (i.e. the aspect has a parameter storing the given entity id) (ex: see how sentinelAttack checks the "sentinelAttackedThisTurnBy" aspect to make sure it doesn't target an enemy it already attacked this turn)
  • minValue: The aspect value must be at least this much
  • maxValue: The aspect value can be at most this much
• relativeTo: This target might be defined relative to another target. For example you might want to target an opponent's weapon, or to define a range based on the first target of the ability.
• notAlreadyMatchedAs: Exclude anyone who is already matched as one of these roles.
• alreadyMatchedAs: The entity in question must also be in one of these roles.
• minRange: min range relative to parent, 0 if not specified.
• range: The target must be within <range> of the parent target on the map.
• themes: Tests the eligibility or existence of a theme
  • eligibleForTheme: Must be able to get the given theme (no conflicting themes)
  • hasTheme: Must have the given theme
  • eligibleForPiece: Must be able to get the given theme piece
  • hasPiece: Must have the given theme piece
  • mustHaveRelevantInjury: Must have a relevant injury for the given theme piece
  • mustBeEligibleForAdditionalPiece: Must be eligible for an additional theme piece
• verbIs: when matching an ability, the verb must be one of these
• abilityHasTag: when matching against an ability, the ability must have this tag.
• abilityDoesNotHaveTag: when matching against an ability, the ability must not have this tag. used in stealth, so that non-"sneaky" abilities trigger the end of stealth.
• abilityDefenseTag: when matching against an ability, the ability must have this defense tag. ex: Archery requiring the "range" defense tag
• stationAspects: This target must contain one of these Stations
• overlandTileBiomes: This target must contain an aspect for one of these biomes
• lineOfSight: what kind of line-of-sight test to enforce for targets on the map?
• adjacentTo: tile must be adjacent to at least one matched target
• tileFilter: special filter to use when matching a tile
• tileFilterRange: For each potential tile, require that all tiles within this range of it also match tileFilter. (Useful for abilities like mysticArches, where we want adjacent tiles to be walkable)
• roleMustFit: If not null, this entity's footprint must fit with its origin on the given tile. (Useful for abilities that might move multi-tile footprint entities, often used with MissionFeedback.applyRoleFootprint)
• footprintWithinRange: Include all locations that would result in any part of this footprint being within the range.
• footprintWithinRangeCompletely: If true, footprintWithinRange must always be completely within the range. For multi-tiled entities, if true the range will shrink, if false the range will grow.
• spawnEntitySize: The footprint size, if spawning an entity. This will filter out any spaces that don't have enough room.
• spawnEntityIgnore: These roles will be ignored when determining whether or not there's enough room to spawn an entity. Useful for transformations!
• canPath: Can the entity path to the given role, or can the given role path to this tile, within the given cost limit?
• test: In order to be a valid target, the entity must pass a test. This is in the form a > b or something like that.
• a: used with "test"
• b: used with "test"
• overlaps: required or forbidden regions that overlap our footprint
• isJobResource: Is this target a resource for a job? JobResources can only be assigned to one job at a time.
• relativeToLocation: When computing range and line of sight, pretend the relativeTo entity is located here, instead of its present actual location. Useful for predicting who we can attack after a move.
• allowCustomText: when true, slightly relaxes the equality check on Action.Target matches in order to allow custom user text to be used.
• forbidJobIds: Won't match a tile if any of the listed job ids are on it.
• threatFlavorExists: The given threat flavor must be in the current game.

Specific Use Cases

overlandTile

• Biome (Filter > overlandTileBiomes): If set, the tile must be one of the given biomes to succeed. This includes things like hills, swamp, forestDeciduous, lake, etc.

site

• Station (Filter > stationAspects): If set, the site must be one of the given stations to succeed. This includes things like earthworks, mine, cave, tower, etc.

party

• Number of Heroes (How Many > chooseAllMinimum/Maximum): If set, and if choose = ALL, the party must have at least chooseAllMinimum members, and at most chooseAllMaximum members. (Note that this could also be used for other roles, like using with company for an event that requires a certain number of total heroes).

foes

• Flavor (Filter > aspects): Add the flavor name (drauven, cultist, thrixl, gorgon, morthagi) to specify that the event should only happen for that type of monster. Note that this only checks for that type of monster; if you want to set the type of monster for a mission, take a look at Combatants.

Outcomes

These are things that happen! This can be starting a Mission, adding an aspect to an individual, showing a comic, and tons of other things.

A lot of stuff falls into this category, so it has its own page: Outcomes

For some less technical descriptions, take a look at the Types of Outcomes we support.