Skip to content

text-operations.md

Latest commit

 

History

History
248 lines (195 loc) · 5.99 KB

text-operations.md

File metadata and controls

248 lines (195 loc) · 5.99 KB
Raw

← author guide

Text operations let you change a text field based on its current value, instead of just setting the new value. For example, you can append or prepend text without removing the current text.

They're set using the TextOperations field for an EditData or EditMap patch.

Contents

Example

Before we delve into the specifics, here's a quick example of how text operations work.

First, here's how you'd add an NPC gift taste without text operations:

{
   "Action": "EditData",
   "Target": "Data/NPCGiftTastes",
   "Entries": {
      "Universal_Love": "74 446 797 373 279 127 128" // replaces current value
   }
}

This is pretty simple, but unfortunately it overwrites any previous values. That will remove any changes from other mods or in future game updates. So instead, we can use the Append operation to add new gift tastes without changing the other values:

{
   "Action": "EditData",
   "Target": "Data/NPCGiftTastes",
   "TextOperations": [
      {
         "Operation": "Append",
         "Target": ["Entries", "Universal_Love"],
         "Value": "127 128",
         "Delimiter": " " // if the field isn't empty, add a space between the old & new text
      }
   ]
}

See the next section for more info on each operation type and their expected fields.

Format

Common fields

All text operations have these basic fields:

field purpose
Operation

The text operation to perform. See the sections below for a description of each operation.
Target

The specific text field to change, specified as a breadcrumb path. Each path value represents a field to navigate into. The possible path values depend on the patch type; see the TextOperations field in the EditData or EditMap docs for more info.

This field supports tokens and capitalisation doesn't matter.

Append

The Append operation adds text at the end of the current field, with an optional delimiter between the old and new text.

This expects these fields:

field purpose
 

See common fields above.
Value

The text to append. Like most Content Patcher fields, whitespace is trimmed from the start and end; use the Delimiter field if you need a space between the current and new values.

This field supports tokens and capitalisation doesn't matter.
Delimiter

(Optional) The characters to add between the current and new text. If you don't specify the delimiter, it'll default to / (most assets) or ^ (Data/Achievements).

For example, let's say the field contains A/B and you're appending C. Here's the result for different delimiters:

delimiter result
not specified A/B/C
"Delimiter": "/" A/B/C
"Delimiter": " " A/B C
"Delimiter": "" A/BC

If the field is empty, the delimiter is ignored:

delimiter result
"Delimiter": "/" C

For example, this adds two item IDs to the list of universally loved gifts:

{
   "Action": "EditData",
   "Target": "Data/NPCGiftTastes",
   "TextOperations": [
      {
         "Operation": "Append",
         "Target": ["Entries", "Universal_Love"],
         "Value": "127 128",
         "Delimiter": " "
      }
   ]
}

Prepend

The Prepend operation adds text at the start of the current field, with an optional delimiter between the old and new text.

This is exactly identical to the Append operation otherwise.

RemoveDelimited

The RemoveDelimited operation parses the target text into a set of values based on a delimiter, then removes one or more values which match the given search text.

This expects these fields:

field purpose
 

See common fields above.
Search

The value to remove from the text. This must match the entire delimited value to remove, it won't remove substrings within each delimited value.

This field supports tokens, and capitalization does matter.
Delimiter

The characters which separate values within the target text.

For example, let's say the target text contains A a/B/C. Here's how that would be parsed with different delimiters:

delimiter value 1 value 2 value 3
"Delimiter": "/" A a B C
"Delimiter": " " A a/B/C
ReplaceMode

(Optional) Which delimited values should be removed. The possible options are:

mode result
First Remove the first value which matches the Search, and leave any others as-is.
Last Remove the last value which matches the Search, and leave any others as-is.
All Remove all values which match the Search.

Defaults to All.

For example, this removes prismatic shard (item 74) from the list of universally loved gifts:

{
   "Action": "EditData",
   "Target": "Data/NPCGiftTastes",
   "TextOperations": [
      {
         "Operation": "RemoveDelimited",
         "Target": ["Entries", "Universal_Love"],
         "Search": "74",
         "Delimiter": " "
      }
   ]
}

See also