Modding:Pets

Index

This page documents how the game stores and parses data for pets. This is an advanced guide for mod developers.

Data Format

You can create and customize pets & pet breeds by editing the Data/Pets asset.

This consists of a string → model lookup, where...

  • The key is a unique string ID for the pet (not the pet breed). The vanilla IDs are Cat and Dog.
  • The value is a model with the fields listed below.

Basic info

field effect
DisplayName A tokenizable string for the pet type's display name (e.g. "cat" or "dog"). For example, the vanilla adoption events show this when Marnie asks if you want to adopt the cat/dog.

Audio & sprites

field effect
BarkSound The cue ID for the pet's occasional 'bark' sound.
ContentSound The cue ID for the sound which the pet makes when you pet it.
RepeatContentSoundAfter (Optional) The number of milliseconds until the ContentSound is repeated once. This is used by the dog, who pants twice when pet. Defaults to -1 (disabled).
EmoteOffset (Optional) A pixel offset for the emote drawn above the pet sprite, specified as an object with X and Y fields. For example, this affects the heart emote shown after petting it. Default none.

Events

field effect
EventOffset (Optional) The pixel offset for the pet when shown in events like Marnie's adoption event, specified as an object with X and Y fields. Default none.
AdoptionEventLocation
AdoptionEventId
(Optional) If both fields are set, the location and event ID which lets the player adopt this pet. This forces the event to play after 20 days if its preconditions haven't been met yet. Default Farm and none respectively.
SummitPerfectionEvent (Optional) How to render the pet during the summit perfection slideshow. If this isn't set, the pet won't be shown in the slideshow.

This consists of a model with these fields:

field effect
SourceRect The source rectangle within the pet's texture to draw.
AnimationLength The number of frames to show starting from the SourceRect.
Motion The motion to apply to the pet sprite.
Flipped (Optional) Whether to flip the pet sprite left-to-right. Default false.
PingPong (Optional) Whether to apply the 'ping pong' effect to the pet sprite animation. Default false.

Gifts

field effect
GiftChance (Optional) The random probability each day that the pet will give the player a gift from the Gifts list when they interact with the pet. Specified as a value between 0 (never) and 1 (always). Default .2 (20% chance).
Gifts (Optional) The list of gifts that this pet can give if the GiftChance is successful. Default none.

This consists of a list of models with these fields:

field effect
Id The unique string ID for this entry within the list.
QualifiedItemID The qualified item ID for the gift item to create.
Stack (Optional) The stack size of the gift item to produce. Default 1.
MinimumFriendshipThreshold (Optional) The friendship level that this pet must be at before it can give this gift. Defaults to 1000 (max friendship).
Weight (Optional) The option's weight when randomly choosing a gift, relative to other gifts in the list (e.g. 2 is twice as likely as 1). Default 1.

Behavior

field effect
Id The unique string ID for this entry within the list.
MoveSpeed (Optional) How quickly the pet can move. Default 2.
SleepOnBedChance
SleepNearBedChance
SleepOnRugChance
(Optional) The percentage chances for the locations where the pet will sleep each night, as a decimal value between 0 (never) and 1 (always). Each value is checked in the order listed at left until a match is found. If none of them match, the pet will choose a random empty spot in the farmhouse; if none was found, it'll sleep next to its pet bowl outside.
Behaviors The pet's possible actions and behaviors, defined as the states in a state machine. Essentially the pet will be in one state at any given time, which also determines which state they can transition to next. For example, a cat can transition from Walk to BeginSitDown, but it can't skip instantly from Walk to SitDownLick.

This consists of a list of models with these fields:

Required fields:
field effect
Id A unique ID for the state. This only needs to be unique within the pet type (e.g. Cat and Dog can have different behaviors with the same ID).
Direction:
field effect
Direction (Optional) The specific direction to face at the start of this state (one of left, right, up, or down), unless overridden by RandomizeDirection.
RandomizeDirection (Optional) Whether to point the pet in a random direction at the start of this state (overriding the Direction if specified). Default false.
IsSideBehavior (Optional) Whether to constrain the pet's facing direction to left and right while the state is active. Default false.
Movement:
field effect
WalkInDirection (Optional) Whether to walk in the pet's facing direction. Default false.
MoveSpeed (Optional) Overrides the pet's MoveSpeed field while this state is active. Default -1 (which uses the pet's MoveSpeed value).
Audio:
field effect
SoundOnStart (Optional) The audio cue ID for the sound to play when the state starts. If set to BARK, the pet's BarkSound (or breed's BarkOverride) field is used. Defaults to none.
SoundRange
SoundRangeFromBorder
(Optional) When set, the SoundOnStart is only audible if the pet is within this many tiles away from the player (SoundRange) or past the border of the screen (SoundRangeFromBorder). Default -1 (no distance check).
SoundIsVoice (Optional) Whether to mute the SoundOnStart when the 'mute animal sounds' option is set. Default false.
Behavior transitions:
field effect
AnimationEndBehaviorChanges
TimeoutBehaviorChanges
PlayerNearbyBehaviorChanges
RandomBehaviorChanges
JumpLandBehaviorChanges
(Optional) A list of possible behavior transitions to start when the criteria are achieved. If multiple transitions are listed, a random one will be selected. If omitted, it won't affect behavior transitions.

These are triggered when this behavior's animation finishes (AnimationEndBehaviorChanges), when the set duration ends (TimeoutBehaviorChanges), when the player is within 2 tiles of the pet (PlayerNearbyBehaviorChanges), randomly at the start of each frame based on the RandomBehaviorChangeChance field (RandomBehaviorChanges), and when the pet finishes a jump (JumpLandBehaviorChanges).

These consist of a list of models with these fields:

field effect
Behavior
LeftBehavior
RightBehavior
UpBehavior
DownBehavior
The ID of the behavior to start. The pet will check for a behavior field matching its current facing direction first, then try the Behavior. If none are specified, the current behavior will continue unchanged.
OutsideOnly (Optional) Whether the transition can only happen if the pet is outside. Default false.
Weight (Optional) The option's weight when randomly choosing a behavior, relative to other behaviors in the list (e.g. 2 is twice as likely as 1). Default 1.
Duration
MinimumDuration
MaximumDuration
(Optional) The millisecond duration until the pet transitions to a behavior in the TimeoutBehaviorChanges field, if set. You must specify either a specific duration, or an inclusive minimum-to-maximum range in which the game will choose a random duration. If omitted, the behavior won't have a duration limit.
RandomBehaviorChangeChance (Optional) The random probability at the start of each frame that the pet will transition to a behavior in the RandomBehaviorChanges field, if set. Specified as a value between 0 (never) and 1 (always). Default 0.
Animation and per-frame sounds:
field effect
Animation (Optional) The animation frames to play while this state is active. This consists of a list of models with these fields:
field effect
Frame The frame index in the animation. This should be an incremental number starting at 0.
Duration The millisecond duration for which the frame should be kept on-screen before continuing to the next frame.
HitGround (Optional) Whether to play the footstep sound for the tile under the pet when the frame starts. Default false.
Jump (Optional) Whether the pet should perform a small hop when the frame starts, including a 'dwop' sound. Default false.
Sound (Optional) The audio cue ID for the sound to play when the animation starts or loops. If set to BARK, the pet's BarkSound (or breed's BarkOverride) field is used. Defaults to none.
SoundRange
SoundRangeFromBorder
SoundIsVoice
See description for the equivalent behavior fields, but applies to the frame's Sound field instead.
Shake (Optional) The millisecond duration for which to shake the pet when the state starts. Default 0.
LoopMode (Optional) What to do when the last animation frame is reached while the behavior is still active. The possible values are Hold (keep the last frame visible until the animation ends), Loop (restart from the first frame), or None (equivalent to Loop). Default None.
AnimationMinimumLoops
AnimationMaximumLoops
(Optional) The minimum and maximum number of times to play the animation. Both must be specified to have any effect. The game will choose an inclusive random value between them. Both default to -1 (don't repeat animation).

Breeds

field effect
Breeds The cosmetic breeds which can be selected in the character customization menu when creating a save. This consists of a list of models with these fields:
field effect
ID The unique ID for the breed within the pet type.
Texture The asset name for the breed spritesheet for the pet's in-game sprite. This should be 128 pixels wide, and 256 (cat) or 288 (dog) pixels high.
IconTexture The asset name for the breed icon texture, shown on the character customization screen and in-game menu. This should be a 16x16 pixel icon.
IconSourceRect The icon's pixel area within the IconTexture, specified as an object with X, Y, Width, and Height fields.
BarkOverride (Optional) Override the pet's BarkSound field for this breed, if set.
VoicePitch (Optional) The pitch applied to the pet's bark sound, measured as a decimal value relative to 1. Defaults to 1.

Advanced

field effect
CustomFields The custom fields for this entry.

Spritesheet layout

Explanation

Each farm animal's spritesheet must have exactly 4 columns. The sprite size is expected to be 32x32.

The expected rows are:

  1. move down;
  2. move right;
  3. move up;
  4. move left
  5. unique animations 1;
  6. unique animations 2;
  7. unique animations 3;
  8. sleep and unique animations 4;
  9. unique animations 5

For example, the default layout is:

0 (move down 1) 1 (move down 2) 2 (move down 3) 3 (move down 4)
4 (move right 1) 5 (move right 2) 6 (move right 3) 7 (move right 4)
8 (move up 1) 9 (move up 2) 10 (move up 3) 11 (move up 4)
12 (move left 1) 13 (move left 2) 14 (move left 3) 15 (move left 4)
16 (unique) 17 (unique) 18 (unique) 19 (unique)
20 (unique) 21 (unique) 22 (unique) 23 (unique)
24 (unique) 25 (unique) 26 (unique) 27 (unique)
28 (sleep 1) 29 (sleep 2) 30 (unique) 31 (unique)
32 (unique) 33 (unique) 34 (unique) 35 (unique)

The rows for moving down, right, up, and left will be used when copy/pasting the Walk behavior from the cat, dog, or turtle. If you don't use that behavior, you can actually put things that aren't moving up, down, or left there. However, in the absence of any defined Behavior, the pet will still use frames 28 and 29 for sleeping, and when being pushed it will use frames 0, 4, 8, or 12 depending on which direction the player is pushing from (e.g. if pushing from the left in order to move right, the pet will face right, using frame 4).