Skip to content
This repository was archived by the owner on Jun 27, 2024. It is now read-only.

Modding

Jump to bottom
José Ángel Soler Ortiz edited this page Oct 11, 2023 · 17 revisions

Pathfinding Framework is a mod for RimWorld that expands the pathfinding capabilities of pawns by allowing them to move using various movement types beyond just terrestrial movement. It aims to make these features available for the entire modding community, and this guide is meant as a quick introduction to the features in the framework. If you want to discuss it more or would like to ask questions, feel free to join the Discord server: https://discord.gg/HB3KyzStgp

You can find some useful commands and options in the Testing and troubleshooting page of the wiki.

Assigning Movement Types to Pawns

This section provides guidelines on assigning movement types to pawns. The movement types included in PF can be found below in the Predefined movement types section.

Single Movement Type Restriction

At a given moment, each pawn can be associated with only one movement type. If a pawn receives movement types from multiple sources, the framework will select the type with the highest priority.

Sources for Movement Types

Pawns can acquire their movement type from various sources. Here's a list of valid sources:

  • Race (ThingDef): The species or race of the pawn dictates its inherent movement behavior.
  • Hediffs (HediffDef): Any health conditions or body modifications (like bionics or injuries) can alter the pawn's movement abilities.
  • Worn Apparel (ThingDef): Equipment like clothing or armor can grant special movement capabilities. For instance, wearing flippers might enhance swimming speed.
  • Life Stage (LifeStageDef): A pawn's age or developmental stage can affect its movement. For example, a creature that is aquatic in its early life might eventually become an amphibian or flying animal.
  • Genes (GeneDef, Biotech Only): Genes can also determine a pawn's movement capabilities.

Examples

Note on Prioritization

Always be aware of movement type priorities, especially when a pawn has potential sources providing different movement types. To ensure consistent and predictable behavior, the framework will always choose the movement type with the highest assigned priority.

How to use

Any of the Defs mentioned above can get a mod extension called MovementExtension. When the pawn is assigned to any of the defs above, it will get the corresponding movement type.

Predefined movement types

The Pathfinding Framework comes with predefined movement types intended to cover most common scenarios.

Terrestrial (PF_Movement_Terrestrial)

Priority: 0

Terrestrial creatures are adapted to move on land. They can cross shallow water, but deeper bodies of water present a challenge to them.

Aquatic (PF_Movement_Aquatic)

Priority: 1000

Aquatic creatures can swim through deep water with ease, but are helpless on land.

Notes:

  • Pawns with this movement type cannot be kept in pens.
  • Pawns with this movement type will only spawn in areas with access to water.

Amphibious (PF_Movement_Amphibious)

Priority: 2000

Amphibious creatures can move easily on both water and land.

Drilling (PF_Movement_Drilling)

Priority: 3000

Drilling creatures dig through soil and sand but avoid moving over rock or water.

Notes:

  • Pawns with this movement type cannot be kept in pens.

Flying (PF_Movement_Flying)

Priority: 10000

Flying creatures can hover over most obstacles.

Notes:

  • Pawns with this movement type cannot be kept in pens.
  • Pawns with this movement type can ignore snow and other things on their path.

Defining new movement types

MovementDef is used to define a set of custom path costs and rules that dictate how pawns assigned to this movement type can move across the map. The XML structure allows modders to specify the behavior and costs associated with different terrains and conditions for a given movement type. For performance reasons, it is recommended to minimize the number of movement type definitions. If you feel that the movement type you want to add could be used in some other mods, please suggest it for inclusion in the framework.

Examples

https://github.com/joseasoler/Pathfinding-Framework/blob/main/1.4/Core/Defs/MovementTypes/PF_MovementTypes.xml

XML Structure

<MovementDef>
  <defName>PREFIX_YOUR_DEF_NAME</defName>
  <priority>VALUE</priority>
  <tagCosts>
    <TerrainTag>COST</TerrainTag>
    <!-- Add more terrain tags and their associated costs here -->
  </tagCosts>
  <defaultCost>PATH_COST_VALUE</defaultCost>
  <defaultCostAdd>VALUE</defaultCostAdd>
  <ignoreSnow>BOOLEAN</ignoreSnow>
  <ignoreThings>BOOLEAN</ignoreThings>
  <penAnimalsDisallowed>BOOLEAN</penAnimalsDisallowed>
  <manhuntersRequireWater>BOOLEAN</manhuntersRequireWater>
</MovementDef>

XML fields description

  • defName: The unique identifier for the movement type.

  • label: A user-friendly name for the movement type.

  • description: A brief description of the movement type.

  • priority: Used to choose when two or more movement types are available.

  • tagCosts: Maps terrain tags to their path costs in this movement type. Path cost values are defined in more detail below. The MovementDef must have at least one entry in this field.

  • defaultCost: Default path cost for terrains not present in other fields. Path cost values are defined in more detail below. This field is optional and defaults to no change.

  • defaultCostAdd: Value added to default cost for terrains not present in other fields. This field is optional and defaults to zero.

  • ignoreSnow: When set, this movement type will ignore snow path costs. This field is optional and defaults to false.

  • ignoreThings: When set, this movement type will ignore thing path costs except for impassable ones. This field is optional and defaults to false.

  • penAnimalsDisallowed: Marks this movement type as not intended for penned animals. This field is optional and defaults to false.

  • manhuntersRequireWater: When set, animals with this movement type can only appear as manhunters on world tiles with access to water. This field is optional and defaults to false.

Path costs

These values dictate how difficult it is for a pawn to traverse a terrain during pathfinding. Path costs can take any value equal or higher than zero, and less than 10000. High values do not really have an effect in-game and it is recommended to keep them below 500. You can check examples of good numerical values to use by checking the pathCostfields of the TerrainDef in the game.

There are also certain string values that have special features in-game, as seen in this breakdown:

  • Default: This value indicates that the default path cost for the terrain should be used. It doesn't impose any additional cost or restriction.

  • Avoid: This value suggests that the pawn should avoid this terrain if possible. It's not entirely impassable, but the pawn will treat it as a less desirable path.

  • Unsafe: The pawn considers this terrain to be unsafe. It will never enter unsafe terrain on its own, and it will actively seek safer terrain if it finds itself over unsafe terrain. Unsafe should only be used for terrains that are impassable in vanilla, or for marking all land terrain as unsafe. Other combinations will lead to pathfinding bugs.

  • Impassable: The terrain is entirely impassable for the pawn. The pawn will not consider this terrain as a valid path under any circumstance. This value should only be used for debugging purposes.

Available terrain tags

Terrain tags are used to categorize different terrains based on their characteristics. Since vanilla tags for natural terrains are not entirely appropriate for pathfinding purposes, Pathfinding Framework defines its own set of tags and patches it into RimWorld and a few mods that can add some natural terrain types.

These tags can be utilized to define terrain path costs in MovementDefs. Vanilla tags and tags from other sources are also fully supported. You can find out all existing terrain tags (both from PF and from other sources) by using the terrain tags debug output option in-game.

Additional mod extensions

Pathfinding Framework also contains some extra mod extensions which implement features useful for pawns with different movement types.

LocomotionExtension

When the pawn is moving at one of the listed locomotion types, it is possible to apply a movement speed multiplier or a graphics change. This extension is mostly thought for flying creatures, which are far faster and might flap their wings while flying.

Examples

https://github.com/biomes-team/BiomesIslands/blob/new_pathfinding_code/1.4/Defs/ThingDefs_Races/BiomesIslands_Races_Birds.xml#L236

XML fields description

  • locomotionUrgencies: List of urgencies that will be affected by this extension. Valid values are, in order from slower to fastest, Amble, Walk, Jog and Sprint.

  • moveSpeedMultiplier: A multiplier that adjusts the pawn’s movement speed while it is moving at one of the chosen locomotion urgencies. This field is optional and defaults to 1.0.

  • graphicData: Contains graphical data for the pawn when this locomotion extension is active. This field is optional.

TerrainTagGraphicExtension

Pawns with this extension can change their graphic depending on the terrain tag they are on. This can be used to make aquatic creatures have a different submerged graphic when they are swimming in deeper waters, or give digging creatures a special underground sprite when they are moving through sand.

Examples

https://github.com/biomes-team/BiomesIslands/blob/new_pathfinding_code/1.4/Defs/ThingDefs_Races/BiomesIslands_Races_Aquatic.xml#L117

XML fields description

  • terrainTags: List of terrain tags that will trigger a graphics change.

  • graphicData: Contains graphical data for the pawn when it is over a terrain with one of the defined tags. DrawSize and shader will be taken from the pawn's original graphic.

Clone this wiki locally