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 Nov 2, 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

Be aware of movement type priorities when a pawn has potential sources providing different movement types. The framework will always choose the assigned movement type with the highest 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: 1000

Adapted for land, these creatures navigate solid terrains with ease. While they can wade through shallow waters, deeper expanses prove challenging.

Notes:

  • This movement type is equivalent to the movement type used by all pawns in vanilla when Pathfinding Framework is not present. With Pathfinding Framework, all pawns use this movement type by default unless they are assigned another one.

Aquatic (PF_Movement_Aquatic)

Priority: 0

Aquatic creatures swim effortlessly through all bodies of water. However, they find themselves out of their element on land.

Notes:

  • If this movement type is assigned to human-like pawns, they will be unable to perform most of the actions expected from a colonist, as most benches cannot be placed in water.
  • Pawns with this movement type cannot be kept in pens.
  • Pawns with this movement type will only spawn in areas with access to water.

Magmatic (PF_Movement_Magmatic)

Priority: 1500 Born of fire and earth, these creatures roam the land and swim through molten lava with ease, yet they have an innate aversion to water.

Notes: Currently this movement type is only enabled with (and only supports) the following mods: Alpha Biomes, Biomes! Core and ReGrowth: Core. Please make a feature request if you find an unsupported mod.

Amphibious (PF_Movement_Amphibious)

Priority: 2000

Equally at home in water and on land, these versatile creatures transition seamlessly between aquatic and terrestrial environments.

Drilling (PF_Movement_Drilling)

Priority: 3000

Subterranean navigators, these creatures burrow through soil and sand. However, they steer clear of rocky terrains and water surfaces.

Notes:

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

Digging(PF_Movement_Digging)

Priority: 4000

Specialized for rapid movement beneath the surface, these creatures excel in sand and soil. On other terrains, they move similarly to their terrestrial counterparts.

Flying (PF_Movement_Flying)

Priority: 10000

Soaring above obstacles, these creatures have the skies as their domain, hovering gracefully over varied landscapes.

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>
  <ignoreColonyReachability>BOOLEAN</ignoreColonyReachability>
  <ignoreAvoidWander>BOOLEAN</ignoreAvoidWander>
</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.

  • ignoreColonyReachability: If this flag is set, animals with this movement type will be able to spawn in points from which it is not possible to reach the colony.

  • ignoreAvoidWander: When this flag is set, the pawns ignore the "avoidWander" value of vanilla terrains.

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 are unsupported and could 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. Here is an overview of each terrain tag added by the framework and the vanilla terrains it affects. For brevity, mods with additional terrains supported by Pathfinding Framework are not listed here.

  • PF_TerrainTag_Gravel: Gravel

  • PF_TerrainTag_Ground: MossyTerrain, Soil, SoilRich

  • PF_TerrainTag_Mud: MarshyTerrain, Mud

  • PF_TerrainTag_Sand: Sand, SoftSand

  • PF_TerrainTag_WaterChestDeep: WaterMovingChestDeep

  • PF_TerrainTag_WaterDeep: WaterDeep, WaterOceanDeep

  • PF_TerrainTag_WaterShallow: Marsh, WaterMovingShallow, WaterOceanShallow, WaterShallow

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.

LocomotionGraphicExtension

Applies a graphic change when the pawn is moving at one of the listed locomotion types. One use of this extension is making flying creatures change their graphic when they move fast, to make them flap their wings. This extension must be placed in the PawnKindDef of the pawn, and is incompatible with human-like pawns. This extension assumes that the PawnKindDef has the same graphics for all of its life stages.

Example

<modExtensions>
	<li Class="PathfindingFramework.LocomotionGraphicExtension">
		<locomotionUrgencies>
			<li>Jog</li>
			<li>Sprint</li>
		</locomotionUrgencies>
		<bodyGraphicData>
			<texPath>BiomesIslands_Things/Pawn/Animal/Seagull/SeagullFlying</texPath>
		</bodyGraphicData>
		<alternateGraphics>
			<li>
				<texPath>BMT_Prehistoric/Aquatic/Thalattosuchus/SeagullFlyingB</texPath>
			</li>
		</alternateGraphics>
	</li>
</modExtensions>

XML fields description

  • locomotionUrgencies: List of urgencies that will be affected by this extension. The valid locomotion types, ordered from slower to faster, are Amble, Walk, Jog and Sprint.

  • bodyGraphicData: 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.

  • alternateGraphics: List of graphical data. It must have the same number of elements as the parent PawnKindDef or it will be ignored.

LocomotionMovementExtension

Applies a movement speed multiplier when the pawn is moving at one of the listed locomotion types. One potential use of this extension is making flying creatures move faster when they are using one of the faster modes, making them faster as they fly. This extension must be placed in the PawnKindDef of the pawn.

Example

<modExtensions>
	<li Class="PathfindingFramework.LocomotionMovementExtension">
		<locomotionUrgencies>
			<li>Jog</li>
			<li>Sprint</li>
		</locomotionUrgencies>
		<moveSpeedMultiplier>4</moveSpeedMultiplier>
	</li>
</modExtensions>

XML fields description

  • locomotionUrgencies: List of urgencies that will be affected by this extension. The valid locomotion types, ordered from slower to faster, are 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. Must be smaller or greater than 1.0.

TerrainTagGraphicExtension

Pawns with this extension can change their graphic depending on the terrain tag they are on. This can be used to make amphibious creatures have a different submerged graphic when they are swimming, or give digging creatures a special underground sprite when they are moving through sand. This extension must be placed in the PawnKindDef of the pawn, and is incompatible with human-like pawns. This extension assumes that the PawnKindDef has the same graphics for all of its life stages.

Examples

<modExtensions>
	<li Class="PathfindingFramework.TerrainTagGraphicExtension">
		<terrainTags>
			<li>PF_TerrainTag_WaterShallow</li>
			<li>PF_TerrainTag_WaterChest</li>
			<li>PF_TerrainTag_WaterDeep</li>
		</terrainTags>
		<bodyGraphicData>
			<texPath>BMT_Prehistoric/Aquatic/Thalattosuchus/ThalattosuchusSubmergedA</texPath>
		</bodyGraphicData>
		<alternateGraphics>
			<li>
				<texPath>BMT_Prehistoric/Aquatic/Thalattosuchus/ThalattosuchusSubmergedB</texPath>
			</li>
		</alternateGraphics>
	</li>
</modExtensions>

XML fields description

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

  • bodyGraphicData: 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.

  • alternateGraphics: List of graphical data. It must have the same number of elements as the parent PawnKindDef or it will be ignored.

Clone this wiki locally