android: Change how apps access their APK's "assets" directory.

Now they can explicitly access it with "assets://" filenames, and optionally
turn off the fallback to checking assets if the native filesystem is missing
a file.

Author: icculus

include/SDL3/SDL_hints.h

@@ -65,6 +65,33 @@ extern "C" {
  */
 #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED"
 
+/**
+ * A variable to control if Android will fallback to accessing the app's APK.
+ *
+ * By default, on Android, several SDL APIs will attempt to work with files
+ * and directories on the real filesystem, but if those files cannot be found,
+ * SDL will attempt to locate them inside the "assets" folder in the app's APK
+ * archive. This can cause confusion when files show up in unexpected
+ * locations, or cause an unexpected override.
+ *
+ * As of SDL 3.4.6, the APK's assets can be accessed explicitly with the
+ * "assets://" URL scheme, making the existing behavior undesirable.
+ *
+ * This hint can change the behavior so that APK assets are only accessible
+ * by prepending "assets://" to a file path. As this is a change in behavior,
+ * the hint defaults to "1" to operate as usual.
+ *
+ * The variable can be set to the following values:
+ *
+ * - "0": SDL will _not_ fall back to the APK assets.
+ * - "1": SDL will fall back to the APK assets. (default)
+ *
+ * This hint can be set anytime.
+ *
+ * \since This hint is available since SDL 3.4.6.
+ */
+#define SDL_HINT_ANDROID_ALLOW_ASSET_DIR_FALLBACK "SDL_ANDROID_ALLOW_ASSET_DIR_FALLBACK"
+
 /**
  * A variable to control whether the SDL activity is allowed to be re-created.
  *

src/core/android/SDL_android.c

@@ -1880,9 +1880,16 @@ static APKNode *FindAPKChildNode(APKNode *parent, const char *child)
 
 static const APKNode *FindAPKNode(const char *constpath)
 {
+    //SDL_Log("FindAPKNode('%s') ...", constpath);
+    if (SDL_strncmp(constpath, "assets://", 9) == 0) {
+        constpath += 9;
+    }
+
     APKNode *parent = APKRootNode;
     if (!parent) {
         return NULL;
+    } else if (*constpath == '\0') {
+        return parent;
     }
 
     const size_t pathlen = SDL_strlen(constpath);
@@ -2341,12 +2348,20 @@ static void Internal_Android_Destroy_AssetManager(void)
 
 static const char *GetAssetPath(const char *path)
 {
-    if (path && path[0] == '.' && path[1] == '/') {
-        path += 2;
-        while (*path == '/') {
-            ++path;
-        }
+    if (!path) {
+        return NULL;
     }
+
+    if (path[0] == '.' && ((path[1] == '/') || (path[1] == '\0'))) {
+        path++;
+    } else if (SDL_strncmp(path, "assets://", 9) == 0) {
+        path += 9;
+    }
+
+    while (*path == '/') {
+        ++path;
+    }
+
     return path;
 }
 

src/filesystem/SDL_filesystem.c

@@ -371,20 +371,28 @@ char **SDL_InternalGlobDirectory(const char *path, const char *pattern, SDL_Glob
         return NULL;
     }
 
-    // if path ends with any slash, chop them off, so we don't confuse the pattern matcher later.
     char *pathcpy = NULL;
     size_t pathlen = SDL_strlen(path);
-    if ((pathlen > 1) && ((path[pathlen-1] == '/') || (path[pathlen-1] == '\\'))) {
-        pathcpy = SDL_strdup(path);
-        if (!pathcpy) {
-            return NULL;
-        }
-        char *ptr = &pathcpy[pathlen-1];
-        while ((ptr > pathcpy) && ((*ptr == '/') || (*ptr == '\\'))) {
-            *(ptr--) = '\0';
-            --pathlen;
+
+    // if path ends with any slash, chop them off, so we don't confuse the pattern matcher later.
+    #ifdef SDL_PLATFORM_ANDROID
+    if (SDL_strcmp(path, "assets://") == 0) {  // don't chop '//' off this if we're looking for the root of the asset tree.
+        pathlen--;  // we'll add a 1 again later.
+    } else
+    #endif
+    {
+        if ((pathlen > 1) && ((path[pathlen-1] == '/') || (path[pathlen-1] == '\\'))) {
+            pathcpy = SDL_strdup(path);
+            if (!pathcpy) {
+                return NULL;
+            }
+            char *ptr = &pathcpy[pathlen-1];
+            while ((ptr > pathcpy) && ((*ptr == '/') || (*ptr == '\\'))) {
+                *(ptr--) = '\0';
+                --pathlen;
+            }
+            path = pathcpy;
         }
-        path = pathcpy;
     }
 
     if (!pattern) {

src/filesystem/posix/SDL_sysfsops.c

@@ -47,6 +47,13 @@ bool SDL_SYS_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback
 #if defined(SDL_PLATFORM_ANDROID) || defined(SDL_PLATFORM_IOS)
     if (*path != '/') {
         #ifdef SDL_PLATFORM_ANDROID
+        if (SDL_strncmp(path, "assets://", 9) == 0) {
+            char *pathwithsep = NULL;
+            SDL_asprintf(&pathwithsep, "%s%s", path, (path[SDL_strlen(path) - 1] != '/') ? "/" : "");
+            const bool retval = pathwithsep ? Android_JNI_EnumerateAssetDirectory(pathwithsep, cb, userdata) : false;
+            SDL_free(pathwithsep);
+            return retval;
+        }
         SDL_asprintf(&apath, "%s/%s", SDL_GetAndroidInternalStoragePath(), path);
         #elif defined(SDL_PLATFORM_IOS)
         char *base = SDL_GetPrefPath("", "");
@@ -89,14 +96,15 @@ bool SDL_SYS_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback
 
     DIR *dir = opendir(pathwithsep);
     if (!dir) {
-#ifdef SDL_PLATFORM_ANDROID  // Maybe it's an asset...?
-        const bool retval = Android_JNI_EnumerateAssetDirectory(pathwithsep + extralen, cb, userdata);
-        SDL_free(pathwithsep);
-        return retval;
-#else
+#ifdef SDL_PLATFORM_ANDROID  // Maybe it's an asset... that didn't use an "assets://" URL?
+        if (SDL_GetHintBoolean(SDL_HINT_ANDROID_ALLOW_ASSET_DIR_FALLBACK, true)) {
+            const bool retval = Android_JNI_EnumerateAssetDirectory(pathwithsep + extralen, cb, userdata);
+            SDL_free(pathwithsep);
+            return retval;
+        }
+#endif
         SDL_free(pathwithsep);
         return SDL_SetError("Can't open directory: %s", strerror(errno));
-#endif
     }
 
     SDL_EnumerationResult result = SDL_ENUM_CONTINUE;
@@ -342,6 +350,8 @@ bool SDL_SYS_GetPathInfo(const char *path, SDL_PathInfo *info)
 #ifdef SDL_PLATFORM_ANDROID
     if (*path == '/') {
         rc = stat(path, &statbuf);
+    } else if (SDL_strncmp(path, "assets://", 9) == 0) {
+        return Android_JNI_GetAssetPathInfo(path, info);
     } else {
         char *apath = NULL;
         SDL_asprintf(&apath, "%s/%s", SDL_GetAndroidInternalStoragePath(), path);
@@ -351,7 +361,7 @@ bool SDL_SYS_GetPathInfo(const char *path, SDL_PathInfo *info)
         rc = stat(apath, &statbuf);
         SDL_free(apath);
     }
-    if (rc < 0) {
+    if ((rc < 0) && SDL_GetHintBoolean(SDL_HINT_ANDROID_ALLOW_ASSET_DIR_FALLBACK, true)) {
         return Android_JNI_GetAssetPathInfo(path, info);
     }
 #elif defined(SDL_PLATFORM_IOS)

src/io/SDL_iostream.c

@@ -1021,7 +1021,7 @@ SDL_IOStream *SDL_IOFromFile(const char *file, const char *mode)
         }
 
         return SDL_IOFromFP(fp, true);
-    } else {
+    } else if (SDL_strncmp(file, "assets://", 9) != 0) {
         // Try opening it from internal storage if it's a relative path
         char *path = NULL;
         SDL_asprintf(&path, "%s/%s", SDL_GetAndroidInternalStoragePath(), file);
@@ -1041,27 +1041,28 @@ SDL_IOStream *SDL_IOFromFile(const char *file, const char *mode)
 #endif // HAVE_STDIO_H
 
     // Try to open the file from the asset system
+    if ((SDL_strncmp(file, "assets://", 9) == 0) || SDL_GetHintBoolean(SDL_HINT_ANDROID_ALLOW_ASSET_DIR_FALLBACK, true)) {
+        void *iodata = NULL;
+        if (!Android_JNI_FileOpen(&iodata, file, mode)) {
+            return NULL;
+        }
 
-    void *iodata = NULL;
-    if (!Android_JNI_FileOpen(&iodata, file, mode)) {
-        return NULL;
-    }
-
-    SDL_IOStreamInterface iface;
-    SDL_INIT_INTERFACE(&iface);
-    iface.size = Android_JNI_FileSize;
-    iface.seek = Android_JNI_FileSeek;
-    iface.read = Android_JNI_FileRead;
-    iface.write = Android_JNI_FileWrite;
-    iface.close = Android_JNI_FileClose;
-
-    iostr = SDL_OpenIO(&iface, iodata);
-    if (!iostr) {
-        iface.close(iodata);
-    } else {
-        const SDL_PropertiesID props = SDL_GetIOProperties(iostr);
-        if (props) {
-            SDL_SetPointerProperty(props, SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER, iodata);
+        SDL_IOStreamInterface iface;
+        SDL_INIT_INTERFACE(&iface);
+        iface.size = Android_JNI_FileSize;
+        iface.seek = Android_JNI_FileSeek;
+        iface.read = Android_JNI_FileRead;
+        iface.write = Android_JNI_FileWrite;
+        iface.close = Android_JNI_FileClose;
+
+        iostr = SDL_OpenIO(&iface, iodata);
+        if (!iostr) {
+            iface.close(iodata);
+        } else {
+            const SDL_PropertiesID props = SDL_GetIOProperties(iostr);
+            if (props) {
+                SDL_SetPointerProperty(props, SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER, iodata);
+            }
         }
     }