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!

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!

generatedTargets > createEntity > query

• type: What is type of thing being created? (Individual, town, item, site, etc.) For NPCs and specific monsters, use INDIVIDUAL.
• baseTag: Is this a human, a goat, a drauven haunt?
• inRelationTo: A role that several other fields can be set based on. (see: cloneRelatedEntity, setGender, setAttraction, setClass, setAge)
• cloneRelatedEntity: If true, this will create a clone of the inRelationTo Role. This can be used to, for example, put a clone of a hero on the enemy side.

• setGender: INDIVIDUAL: Male or female. Can also be random, or chosen based on the gender or attraction of the inRelationTo role.
• setAttraction: INDIVIDUAL: Men or Women. Can also be random (normal), or chosen based on the gender of the inRelationTo role.
• setClass: INDIVIDUAL: Farmer, warrior, hunter, or mystic. Can also be any, any non-farmer, or the same as the inRelationTo role.
• setAge: INDIVIDUAL: Some general age brackets. Can also be sameAs or closeTo the inRelationTo role.
• exactAge: INDIVIDUAL: An exact numeric age.
• setName: A specific name. Overrides default name generation.
• setEquipment: Create this entity with a certain type or tier of clothes, weapons, etc.
• primaryStoryStat: If set and the query is human, the human will be very likely to have this as their primary personality stat. (Only use this with personality stats, like GOOFBALL)
• looksSimilarTo: An individual that the generated entity should look similar to (i.e. family members)

• itemId: ITEM: A specific item to spawn. (Overrides itemCategory and itemTier)
• itemCategory: ITEM: Picks a random item of the given item category.
• itemSubCategory: ITEM: Picks a random item of the given item subcategory.
• itemElement: ITEM: Gives the item this element.
• itemTier: ITEM: Picks a random item of the given tier. (Can be used in conjunction with itemCategory)
• owner: Generally for items. Who owns this item?

• nameAlgorithm: Used for sites, and maybe could be used to override default names?
• siteTemplateId: SITE: What kind of environment? (cave, forest shrine, library, etc.)
• siteMissionPlanId: SITE: The Mission Plan id for the created site.
• exactSiteTemplate: SITE: An exact template for the site.
• tileId: Overland tile to place this entity on.
• overlandLocation: Overland tile to place this entity on, based on the tile another role is on (this takes precedence over the location of inRelationTo)

• threatFlavor: THREAT: The type of monster card to spawn.
• applyCalamities: If this is a monster, apply relevant calamity buffs to it.
• aspectValues: Apply the given aspect values to the created entity.
• coordinates: used when generating scenery
• biome: used when generating a detached (fake?) overland tile
• findExisting: If true, the result may be an entity that is already present in the game world.
• customPersonality: Specify this entity's personality
• customHistory: Specify this entity's history

generatedTargets > createEntity

• useExisting: Gets an existing entity from the given role, rather than generating a new one. This can be used instead of query.
• stationQuery: Create entity based on a station query (henge, outfitter, windmill, etc)
• addAspects: Additional aspects to add, if any
• control: who controls the entity
• controlRelativeTo: Set entity control relative to this role (i.e. will be the ally or enemy of this role, depending on what control is set to)
• additionalOutcome: An outcome to apply to this entity upon creation. This is useful for doing things like adding gear (AddGear) to an individual or modifying their stats (ModifyStats). (Note that you can use a DoAll Outcome to execute multiple Outcomes here.)
• setLocation: Should this entity be placed on the mission map? (Only works if placeOnMap is true, a Mission is taking place, and this is in an Outcome)
• setLocationType: If setLocation is true, how should the entity be spawned relative to this Outcome's target? (closestPossible is used for things like large pets, which spawn into the mission next to a hero)
• placeOnMap: Should this entity be placed on the Mission/Overland map? (Mission map if setLocation is true, Overland map otherwise)

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?
• prompt: If the user needs to make a choice, this is where the event text will go.
• promptText: localized targeting prompt (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
• 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.
• 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.
• 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.

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.