Give Feedback
0 of 0
About this mod
A categorized special items & powers tab that comes with some small behind-the-scenes utilities for content patcher mod authors.
- Requirements
- Permissions and credits
-
Translations
- Portuguese
- Changelogs
Special Power Utilities provides a way for modded players and mod authors to separate their Special Items & Powers tab into different mod categories so that you can see which mod adds what powers and view them separately from the powers present in the base game. As well, for mod authors, Special Power Utilities provides some new GameStateQueries, Tokens, and/or TriggerActions that may prove useful to you if you'd like to do more with powers than you otherwise could.
It is very important to note that Special Power Utilities is not intended to be a framework for adding more complex and advanced powers. While I would love this to be the case, due to the nature of how powers work and how they must be integrated into the game's code, you will still likely need to delve into C# yourself in order to create more advanced powers. If in the future I can figure out a way to make this easier to achieve for mod authors who only use Content Patcher, I will work to include it, but this is not guaranteed. The aim of this mod is to provide a (hopefully) nicer Special Items & Powers tab for modded players and make working with simpler powers a little bit easier for mod authors.
Installation
Usage For Players
Installing this mod will replace your current Special Items & Powers tab with one that supports categories. If you have another mod installed that adds a new special item or power, it will be placed in a new category on the left side, separate from the base game powers. Each mod that adds a special item or power will get its own category* on the side, with no limit to the number of categories. If a mod does not provide support specifically for Special Power Utilities, it will be assigned an icon to use. Nothing about how you unlock your powers will change, regardless of whether or not your other mods support Special Power Utilities; the only thing that will change is how you view them.
*Potentially. See the configuration section below.
Usage For Content Patcher Mod Authors
Usage for C# Mod Authors
There is no API currently available. However, it is planned to be included in a future update.
Configuration
SpecialPowerUtilities comes with three config options and each of them are explained below. It is recommended to use Generic Mod Config Menu for adjusting these values in game.
Mod Compatibility
Special Power Utilities should be compatible with any mod that adds a custom special item or power already, however it does completely replace the Special Items & Powers tab in your menu (even with EnableCategories disabled), so if another mod replaces the same menu, it will not be compatible. If you need to, you CAN toggle "UseVanillaMenu" on and go back to using the normal menu. Some features may not be visible, but they will still be functional.
It is very important to note that Special Power Utilities is not intended to be a framework for adding more complex and advanced powers. While I would love this to be the case, due to the nature of how powers work and how they must be integrated into the game's code, you will still likely need to delve into C# yourself in order to create more advanced powers. If in the future I can figure out a way to make this easier to achieve for mod authors who only use Content Patcher, I will work to include it, but this is not guaranteed. The aim of this mod is to provide a (hopefully) nicer Special Items & Powers tab for modded players and make working with simpler powers a little bit easier for mod authors.
Installation
- Install the latest version of SMAPI.
- Extract the mod into Stardew Valley/Mods.
- Run the game using SMAPI.
Usage For Players
Installing this mod will replace your current Special Items & Powers tab with one that supports categories. If you have another mod installed that adds a new special item or power, it will be placed in a new category on the left side, separate from the base game powers. Each mod that adds a special item or power will get its own category* on the side, with no limit to the number of categories. If a mod does not provide support specifically for Special Power Utilities, it will be assigned an icon to use. Nothing about how you unlock your powers will change, regardless of whether or not your other mods support Special Power Utilities; the only thing that will change is how you view them.
*Potentially. See the configuration section below.
Usage For Content Patcher Mod Authors
Spoiler:
If your mod does not add support specifically for Special Power Utilities, your mod will still function as normal for your users. Special Power Utilities does not alter the unlocked conditions of your powers in any way. However, you are able to designate a section for your mod if you so choose and assign it a custom icon that Special Power Utilities will utilize. If the IDs of your special items & powers follow the standard naming convention (i.e. they are prefixed with your mod ID) then Special Power Utilities will create a section for your mod automatically, but you will not get to choose the icon or how the name is displayed without specifying it on your end. The below example demonstrates how this is done:
Assuming that you only want a section for your mods and that your special items and powers all have their IDs prefixed with your mod ID, there is nothing else you need to do. Assuming you only add a category and do not use any of the GameStateQueries, TriggerActions, or Tokens added by Special Power Utilities, things will be functional even if your users do not have Special Power Utilities installed. Your special powers and items will be placed into the section you created automatically. However, if your special items and powers do not have your mod ID as a prefix, you do not need to change them, but will need to assign them to your new section manually using the CustomFields field of your powers. Again, see below for an example:
You will need to do this for every power that does not have your mod ID prefixed to its power name. Alternatively, you could rename e.g. "Power_One" to "{{ModId}}_Power_One" if you wanted to, but CustomFields is likely easier depending on how many places your power is used throughout your content.json or other code.
Special Power Utilities also offers the following new utilities (feel free to request more!):
Returns true if the Target Player has the specified power unlocked, false otherwise. Specifying a target player is required.
Example: PLAYER_HAS_POWER Current KeyToTheTown
Sets the specified power to be inactive for the Target Player. If no target player is specified, it defaults to Current. Please see below for what "Unavailable" means.
• Spiderbuttons.SpecialPowerUtilities/SetPowerAvailable [who] <powerID>
Sets the specified power to be available for the Target Player. If no target player is specified, it defaults to Current. Please see below for what "Available" means.
For checking whether or not a player has a specified power, similar to HasProfession. It also accepts an optional input argument of "Any," in which case it can check if any player has a specified power.
• Spiderbuttons.SpecialPowerUtilities/UnavailablePowers
For checking which powers are marked as unavailable for a player. Also accepts an optional input argument of "Any" for the same reason as above.
• Spiderbuttons.SpecialPowerUtilities/Placement/[ToPosition/BeforeID/AfterID]
Specifies where in the list of items/powers a power should be placed. Please see the example content pack; it works similar to Content Patcher's "MoveEntries."
Power Availability
With Special Power Utilities, special items and powers can now be marked as "unavailable" and will appear faded to the player on their special items and powers tab. Marking a power as "unavailable" does not do anything on its own—it would be up to you to determine what effects occur when a player's power is unavailable. It is intended for temporarily revoking the benefits granted by a power under circumstances you choose and then giving those benefits back later. It will not decrement any stats or remove any mail flags or anything like that. Players will still have the special items or powers unlocked (i.e. they will still meet the UnlockedCondition as described in the Data/Powers entry), but the effects of the special items or powers may just be temporarily suppressed. If a player uninstalls Special Power Utilities, their special items and powers will once more be made available to them.
It is important to note that setting a power from the base game (such as the Key to the Town) to be unavailable will do nothing on its own. Setting a power unavailable is simply setting a flag. Nothing will check that flag in the base game without you (or me) deeming it so, but for the base game powers, there are simply far too many places where each power would be checked for me to consider that a worthwhile time investment. Power (un)availability is intended for use with modded powers where you can precisely control these checks. Niche? Terribly. Useful to me? Surprisingly. Therefore, it's included, because why not.
Also, setting a power as available does not grant the player that power if they do not already have it. A power being available is not the same as a power being unlocked. If a player does not have a power but you set it to available, it simply means that it won't be unavailable when they do get it, but they will not get it before meeting the original unlock requirements.
I am not the best at writing documentation, I know, so I have also included an example Content Patcher mod in the optional files that will demonstrate how to use all of the above features (except for the trigger actions). However, if anything still remains unclear, please feel free to ask me and I will do my best to try and explain it better.
Show
If your mod does not add support specifically for Special Power Utilities, your mod will still function as normal for your users. Special Power Utilities does not alter the unlocked conditions of your powers in any way. However, you are able to designate a section for your mod if you so choose and assign it a custom icon that Special Power Utilities will utilize. If the IDs of your special items & powers follow the standard naming convention (i.e. they are prefixed with your mod ID) then Special Power Utilities will create a section for your mod automatically, but you will not get to choose the icon or how the name is displayed without specifying it on your end. The below example demonstrates how this is done:
"Changes": [
{
"Action": "Load",
"FromFile": "assets/TabIcon.png", // This can be any image so long as it is square. 16x16, 32x32, 64x64... etc.
"Target": "Mods/{{ModId}}/TabIcon"
},
{
"Action": "EditData",
"Target": "Spiderbuttons.SpecialPowerUtilities/PowerSections",
"Entries": {
"{{ModId}}": {
"SectionName": "Example Power Mod",
"IconPath": "Mods/{{ModId}}/TabIcon"
}
}
}
]
Assuming that you only want a section for your mods and that your special items and powers all have their IDs prefixed with your mod ID, there is nothing else you need to do. Assuming you only add a category and do not use any of the GameStateQueries, TriggerActions, or Tokens added by Special Power Utilities, things will be functional even if your users do not have Special Power Utilities installed. Your special powers and items will be placed into the section you created automatically. However, if your special items and powers do not have your mod ID as a prefix, you do not need to change them, but will need to assign them to your new section manually using the CustomFields field of your powers. Again, see below for an example:
"Changes": [
{
"Action": "EditData",
"Target": "Data/Powers",
"Entries": {
"Power_One": {
"DisplayName": "Power Two.",
"Description": "Lorem ipsum.",
"TexturePath": "LooseSprites\\Cursors",
"TexturePosition": { "X": 224, "Y": 320 },
"UnlockedCondition": "PLAYER_STAT Current Power_One 1",
"CustomFields": {
"Spiderbuttons.SpecialPowerUtilities/Section": "{{ModId}}"
}
}
}
}
]
You will need to do this for every power that does not have your mod ID prefixed to its power name. Alternatively, you could rename e.g. "Power_One" to "{{ModId}}_Power_One" if you wanted to, but CustomFields is likely easier depending on how many places your power is used throughout your content.json or other code.
Special Power Utilities also offers the following new utilities (feel free to request more!):
- GameStateQueries:
Returns true if the Target Player has the specified power unlocked, false otherwise. Specifying a target player is required.
Example: PLAYER_HAS_POWER Current KeyToTheTown
- TriggerAction Actions:
Sets the specified power to be inactive for the Target Player. If no target player is specified, it defaults to Current. Please see below for what "Unavailable" means.
• Spiderbuttons.SpecialPowerUtilities/SetPowerAvailable [who] <powerID>
Sets the specified power to be available for the Target Player. If no target player is specified, it defaults to Current. Please see below for what "Available" means.
- Content Patcher Tokens:
For checking whether or not a player has a specified power, similar to HasProfession. It also accepts an optional input argument of "Any," in which case it can check if any player has a specified power.
• Spiderbuttons.SpecialPowerUtilities/UnavailablePowers
For checking which powers are marked as unavailable for a player. Also accepts an optional input argument of "Any" for the same reason as above.
• Spiderbuttons.SpecialPowerUtilities/Placement/[ToPosition/BeforeID/AfterID]
Specifies where in the list of items/powers a power should be placed. Please see the example content pack; it works similar to Content Patcher's "MoveEntries."
Power Availability
With Special Power Utilities, special items and powers can now be marked as "unavailable" and will appear faded to the player on their special items and powers tab. Marking a power as "unavailable" does not do anything on its own—it would be up to you to determine what effects occur when a player's power is unavailable. It is intended for temporarily revoking the benefits granted by a power under circumstances you choose and then giving those benefits back later. It will not decrement any stats or remove any mail flags or anything like that. Players will still have the special items or powers unlocked (i.e. they will still meet the UnlockedCondition as described in the Data/Powers entry), but the effects of the special items or powers may just be temporarily suppressed. If a player uninstalls Special Power Utilities, their special items and powers will once more be made available to them.
It is important to note that setting a power from the base game (such as the Key to the Town) to be unavailable will do nothing on its own. Setting a power unavailable is simply setting a flag. Nothing will check that flag in the base game without you (or me) deeming it so, but for the base game powers, there are simply far too many places where each power would be checked for me to consider that a worthwhile time investment. Power (un)availability is intended for use with modded powers where you can precisely control these checks. Niche? Terribly. Useful to me? Surprisingly. Therefore, it's included, because why not.
Also, setting a power as available does not grant the player that power if they do not already have it. A power being available is not the same as a power being unlocked. If a player does not have a power but you set it to available, it simply means that it won't be unavailable when they do get it, but they will not get it before meeting the original unlock requirements.
I am not the best at writing documentation, I know, so I have also included an example Content Patcher mod in the optional files that will demonstrate how to use all of the above features (except for the trigger actions). However, if anything still remains unclear, please feel free to ask me and I will do my best to try and explain it better.
Usage for C# Mod Authors
There is no API currently available. However, it is planned to be included in a future update.
Configuration
SpecialPowerUtilities comes with three config options and each of them are explained below. It is recommended to use Generic Mod Config Menu for adjusting these values in game.
- EnableCategories: Rather self explanatory. If this is disabled, you will not see any mod categories on the left side of your Special Items & Powers tab, nor will your modded special items and powers be moved anywhere. All special items and powers, modded or otherwise, will be placed into the usual looking Special Items & Powers tab. It will appear almost no different than if the mod was not installed at all. The behind-the-scenes features available to mod authors will still function as normal.
- ParseModNames: If a mod follows the standard naming convention for their special items and powers (i.e. their special item and power IDs are prefixed with their mod ID, such as "Example.PowerMod_Power_One"), but does not otherwise support Special Power Utilities and the mod author has not designated a mod category, then Special Power Utilities will attempt to parse the mod name from those IDs in order to automatically assign modded special items and powers into their correct categories. Following the given example, if this option was enabled, you would see a category on the left side of your Special Items & Powers tab with the name "Example.PowerMod," a randomly assigned icon, and the "Power_One" power displayed within it. If this option is disabled, Special Power Utilities will not parse the mod name as described, and will instead add any uncategorized modded special item or power into a single "Miscellaneous" category.
- EnableMiscCategory: If disabled, Special Power Utilities will not add any uncategorized, modded special items or powers into a
"Miscellaneous" category. Instead, those special items and powers will be placed into the default "Stardew Valley" category that holds the
powers from the base game, which is where they would be if you did not have Special Power Utilities installed. It will still place modded
special items and powers into categories if those categories are specified by the mods themselves and "EnableCategories" is enabled.
- EnableMiscCategory: If enabled, the Special Items & Powers tab provided this mod will not be loaded at all. Unavailable powers will not be able to be differentiated from available powers, but the mod will otherwise function as intended. Turn this on if you are having issues with another mod that needs to edit the Special Items & Powers tab.
Mod Compatibility
Special Power Utilities should be compatible with any mod that adds a custom special item or power already, however it does completely replace the Special Items & Powers tab in your menu (even with EnableCategories disabled), so if another mod replaces the same menu, it will not be compatible. If you need to, you CAN toggle "UseVanillaMenu" on and go back to using the normal menu. Some features may not be visible, but they will still be functional.