Skip to content

Conversation

Spiderbuttons
Copy link

This change allows the image source of a tilesheet in a mod-loaded map to climb up a single directory in order to load the tilesheet relative to the game's root Content folder. Previously, no tilesheet climbing was allowed at all and all tilesheet image sources were always assumed to be relative to the Content/Maps directory by convention, limiting tilesheets to only using what could be found under Maps/. With this change, modded maps may use tilesheets whose image sources are any texture asset that can be found beneath the Content root directory (such as LooseSprites/Cursors), including modded assets, so long as their image sources are formatted appropriately.

In order to allow this, the tilesheet image source must start with one directory climbing segment (../) to climb out of the assumed Maps/ folder, with the remaining path being parsed as an asset name. For example, ../LooseSprites/Cursors will parse to the LooseSprites/Cursors asset, as will /../LooseSprites/Cursors. Any other placement of the directory climbing segment will lead to either the usual "tilesheet couldn't be found" error. No mods will be affected by this change as any instance of tilesheet climbing was previously barred.

When directory climbing in this way, SMAPI will not look for the tilesheet as an internal asset. It must be present in the content pipeline proper. This limitation was added to prevent the possibility of climbing out of a mod's folder entirely if their map was at the root of their mod directory. This limitation will affect no existing mods as it still requires the once-disallowed directory climbing for this limitation to present itself.

Attempting to use multiple directory climbing segments in a single path, no matter where they may be, will result in a new error for climbing multiple directories specifically. Additionally, the error when a tilesheet path is considered "rooted" has been separated into its own check with a new error message stating that the path must not be absolute. Both of these updated error messages will show the offending path or path segments in the log, though whether it's desirable to instead show constants like C:/ or ../../ no matter the path is up to personal taste.

The tilesheet image sources used for testing and their results were:

  • ../LooseSprites/Cursors -> OK
  • /../LooseSprites/Cursors -> OK
  • /LooseSprites/Cursors -> Couldn't be found error
  • ../../LooseSprites/Cursors -> Multiple climbing error
  • ../../../../LooseSprites/Cursors -> Multiple climbing error
  • LooseSprites/Cursors -> Couldn't be found error
  • ../Maps/../LooseSprites/Cursors -> Multiple climbing error
  • Mines/../LooseSprites/Cursors -> SMAPI: Couldn't be found error, Content Patcher: Caught early, relative path error

StardewModdingAPI-2025-06-22-19-18-10892

@Pathoschild Pathoschild force-pushed the develop branch 2 times, most recently from cfac33e to 6c0c089 Compare July 12, 2025 21:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant