Line 1: |
Line 1: |
− | {{upcoming|1.6}}
| |
− |
| |
| ← [[Modding:Index|Index]] | | ← [[Modding:Index|Index]] |
| | | |
− | ==From [[Modding:Migrate to Stardew Valley 1.6]]==
| + | This page documents '''tokenizable strings''', a built-in way to build display text which can contain any combination of literal text, translations, and placeholder values. |
− | ===Tokenizable string format===
| |
− | Stardew Valley 1.6 adds support for literal strings that contain tokens. These are only usable in specific fields (their docs will say 'tokenizable string' with a link to this section).
| |
| | | |
− | ====Literal text==== | + | ==Format== |
− | Previously you often needed to load text from a [[Modding:Modder Guide/Game Fundamentals#String keys|string key]] in data assets. With this new format, you can use the literal text directly in the asset instead (including Content Patcher tokens):
| + | ===Overview=== |
| + | You can only use tokenizable strings in data fields that specifically allow them (which will be indicated in the wiki docs). |
| | | |
| + | A tokenizable string can contain any combination of literal text and tokens ([[#Tokens|listed below]]). For example: |
| <syntaxhighlight lang="js"> | | <syntaxhighlight lang="js"> |
− | // before
| + | "Dialogue": "Welcome to Pierre's! How is [FarmName] doing?" |
− | "Dialogue": "Strings\\StringsFromCSFiles:ShopMenu.cs.11488", | + | </syntaxhighlight> |
| + | |
| + | When using [[Modding:Content Patcher|Content Patcher]], you can use its tokens anywhere in the string (including within square brackets); they'll be expanded before the game parses the string. For example, <code><nowiki>"{{Spouse}} would love [ArticleFor [SuggestedItem]] [SuggestedItem]!"</nowiki></code> would output something like "''Abigail would love an Apple!''". |
| | | |
− | // after: literal text supported
| + | ===Token format=== |
− | "Dialogue": "Welcome to Pierre's!",
| + | A ''token'' is a predefined placeholder which produces text, wrapped in square brackets. Token names are not case-sensitive, so <samp>[LocalizedText]</samp> and <samp>[LOCALIZEDTEXT]</samp> are equivalent. |
| | | |
− | // after: literal text with Content Patcher tokens
| + | For example, this will show a message like "''Welcome to Pierre's! This is raw text''": |
− | "Dialogue": "Welcome to Pierre's, {{PlayerName}}! {{i18n: translatable-text}}", | + | <syntaxhighlight lang="js"> |
| + | "Dialogue": "[LocalizedText Strings\StringsFromCSFiles:ShopMenu.cs.11488] {{i18n: some-translation}}" |
| </syntaxhighlight> | | </syntaxhighlight> |
| | | |
− | ====Tokens==== | + | ===Token argument format=== |
− | You can inject tokens using square brackets. For example, <code>"[LocalizedText Strings\StringsFromCSFiles:ShopMenu.cs.11488] This is raw text"</code> will show something like "''Welcome to Pierre's! This is raw text''". Token names are not case-sensitive.
| + | A token can optionally have arguments (which can in turn contain tokens). In the above example, the <samp>LocalizedText</samp> takes one argument (the translation key to display). Arguments are space-delimited, so you need to use <samp>EscapedText</samp> to pass an argument containing spaces: |
| + | <syntaxhighlight lang="js"> |
| + | "Dialogue": "[LocalizedText [EscapedText Strings\BundleNames:Quality Fish]]" |
| + | </syntaxhighlight> |
| | | |
− | Here are the supported tokens: | + | ==Tokens== |
| + | Here are the tokens provided by the base game: |
| {| class="wikitable" | | {| class="wikitable" |
| |- | | |- |
| ! token format | | ! token format |
| ! output | | ! output |
| + | |- |
| + | | <samp>[AchievementName {{t|id}}]</samp> |
| + | | The translated display name for an achievement from [[Modding:Achievement data|<samp>Data/Achievements</samp>]]. For example, <samp>[AchievementName 5]</samp> will output ''A Complete Collection'' in English. |
| |- | | |- |
| | <samp>[ArticleFor {{t|word}}]</samp> | | | <samp>[ArticleFor {{t|word}}]</samp> |
Line 52: |
Line 60: |
| |- | | |- |
| | <samp>[FarmerStat {{t|key}}]</samp> | | | <samp>[FarmerStat {{t|key}}]</samp> |
− | | The value of a [[#Stat changes for C# mods|tracked stat]] for the current player. See the [[#Game state queries|<samp>PLAYER_STAT</samp> game state query]] for a list of useful stats. | + | | The value of a tracked stat for the current player. See the [[Modding:Game state queries|<samp>PLAYER_STAT</samp> game state query]] for a list of useful stats. |
| | | |
| For example: | | For example: |
Line 59: |
Line 67: |
| | <samp>[GenderedText {{t|male text}} {{t|female text}}</samp> | | | <samp>[GenderedText {{t|male text}} {{t|female text}}</samp> |
| | Depending on the target player's gender, show either the male text or female text. If the text contains spaces, you'll need to escape them using <samp>EscapedText</samp>. | | | Depending on the target player's gender, show either the male text or female text. If the text contains spaces, you'll need to escape them using <samp>EscapedText</samp>. |
| + | |- |
| + | | <samp>[ItemName {{t|id}} {{o|fallback text}}]</samp> |
| + | | The translated display name for an item based on its qualified or unqualified item ID. For example, <samp>[ItemName (O)128]</samp> will output ''Pufferfish'' in English. |
| + | |
| + | If the item doesn't exist, it'll output {{o|fallback text}} if specified, else ''Error Item ({{t|id}})''. |
| |- | | |- |
| | <samp>[LocalizedText {{t|string key}}]</samp><br /><samp>[LocalizedText {{t|string key}} {{t|token values}}+]</samp> | | | <samp>[LocalizedText {{t|string key}}]</samp><br /><samp>[LocalizedText {{t|string key}} {{t|token values}}+]</samp> |
− | | Translation text loaded from the given [[Modding:Modder Guide/Game Fundamentals#String keys|string key]]. If the translation has placeholder tokens like <samp>{0}</samp>, you can add the values after the string key. | + | | Translation text loaded from the given [[Modding:Common data field types#Translation keys|translation key]]. If the translation has placeholder tokens like <samp>{0}</samp>, you can add the values after the string key. |
| |- | | |- |
| | <samp>[LocationName {{t|location ID}}]</samp> | | | <samp>[LocationName {{t|location ID}}]</samp> |
− | | The translated display name for a location given its ID [[#Custom locations|in <samp>Data/Locations</samp>]]. | + | | The translated display name for a location given its ID [[Modding:location data|in <samp>Data/Locations</samp>]]. |
| + | |- |
| + | | <samp>[MovieName {{t|id}}]</samp> |
| + | | The translated display name for a movie from [[Modding:Movie theater data|<samp>Data/Movies</samp>]]. For example, <samp>[MovieName spring_movie_0]</samp> will output ''The Brave Little Sapling'' in English. |
| + | |- |
| + | | <samp>[NumberWithSeparators {{t|number}}]</samp> |
| + | | Format a number with thousands separators based on the current language. For example, <samp>[NumberWithSeparators 5000000]</samp> will output ''5,000,000'' in English. |
| |- | | |- |
| | <samp>[PositiveAdjective]</samp> | | | <samp>[PositiveAdjective]</samp> |
Line 71: |
Line 90: |
| | <samp>[Season]</samp> | | | <samp>[Season]</samp> |
| | The current season name, like ''spring''. | | | The current season name, like ''spring''. |
| + | |- |
| + | | <samp>[SpecialOrderName {{t|id}}]</samp> |
| + | | The translated display name for a special order from [[Modding:Special orders|<samp>Data/SpecialOrders</samp>]]. If the special order is currently active, it'll show the same name shown in the quest log. For example, <samp>[SpecialOrder Caroline]</samp> will output ''Island Ingredients'' in English. |
| |- | | |- |
| | <samp>[SpouseFarmerText {{t|spouse is farmer text}} {{t|spouse is NPC text}}</samp> | | | <samp>[SpouseFarmerText {{t|spouse is farmer text}} {{t|spouse is NPC text}}</samp> |
Line 82: |
Line 104: |
| | | |
| The result will be identical for all queries with the same {{o|sync key}} during the given {{o|interval}} (one of <samp>tick</samp>, <samp>day</samp>, <samp>season</samp>, <samp>year</samp>), including between players in multiplayer mode. If omitted, they default to <samp>day</samp> and the shop ID respectively. | | The result will be identical for all queries with the same {{o|sync key}} during the given {{o|interval}} (one of <samp>tick</samp>, <samp>day</samp>, <samp>season</samp>, <samp>year</samp>), including between players in multiplayer mode. If omitted, they default to <samp>day</samp> and the shop ID respectively. |
| + | |- |
| + | | <samp>[ToolName {{t|id}} {{o|upgrade level}}]</samp> |
| + | | The translated display name for a tool, including its upgrade level if specified. For example, <samp>[ToolName (T)IridiumAxe]</samp> will output ''Iridium Axe'' in English. |
| |} | | |} |
| | | |
− | When passing an input argument for tokens like <samp>ArticleFor</samp>, the input can contain its own nested tokens. For example, <code>"[ArticleFor [SuggestedItem]] [SuggestedItem]"</code> would output something like ''an Apple''.
| + | ==Extensibility for C# mods== |
− | | + | C# mods can define custom tokens by calling <code>TokenParser.RegisterParser("tokenName", ...)</code>. To avoid conflicts, custom token names should apply the [[Modding:Common data field types#Unique string ID|unique string ID]] conventions. |
− | If you're using [[Modding:Content Patcher|Content Patcher]], you can use its tokens anywhere in the string (including within square brackets); they'll be expanded before the game parses the string. For example, <code><nowiki>"{{Spouse}} would love [ArticleFor [SuggestedItem]] [SuggestedItem]!"</nowiki></code> would output something like "''Alexa would love an Apple!''".
| |
− | | |
− | ====Extensibility====
| |
− | C# mods can define custom tokens by calling <code>TokenParser.RegisterParser("tokenName", ...)</code>. To avoid conflicts, prefixing custom condition names with your mod ID (like <samp>Example.ModId_TokenName</samp>) is strongly recommended. | |
| | | |
| [[Category:Modding]] | | [[Category:Modding]] |