Improved notes on bundle resources

docs/en/manuals/file-access.md

@@ -80,9 +80,34 @@ When saving and loading application specific files such as high scores, user set
 ### How to access files bundled with the application
 You can bundle files with your application in two ways:
 
-1. **CUSTOM RESOURCES** - As part of the game archive using the [*Custom Resources* field](https://defold.com/manuals/project-settings/#custom-resources) in *game.project*. You can read these files using [`sys.load_resource()`](https://defold.com/ref/sys/#sys.load_resource). Note that these aren't actual files on the file system. Files included this way becomes part of the binary game archive and the only way to access them is through `sys.load_resource()`.
+1. **CUSTOM RESOURCES**
+:[Custom Resources](../shared/custom-resources.md)
 
-2. **BUNDLE RESOURES** - As additional files and folders located as a part of your application bundle using the [*Bundle Resources* field](https://defold.com/manuals/project-settings/#bundle-resources) in *game.project*. You can use [`sys.get_application_path()`](https://defold.com/ref/stable/sys/#sys.get_application_path:) to get the path to where the application is stored. Use this application base path to create the final absolute path to the files you need access to. Once you have the absolute path of these files you can use the `io.*` and `os.*` functions to access the files (see above).
+```lua
+-- Load level data into a string
+local data, error = sys.load_resource("/assets/level_data.json")
+-- Decode json string to a Lua table
+if data then
+  local data_table = json.decode(data)
+  pprint(data_table)
+else
+  print(error)
+end
+```
+
+2. **BUNDLE RESOURES**
+:[Bundle Resources](../shared/bundle-resources.md)
+
+```lua
+local path = sys.get_application_path()
+local f = io.open(path .. "/mycommonfile.txt", "rb")
+local txt, err = f:read("*a")
+if not txt then
+	print(err)
+	return
+end
+print(txt)
+```
 
 ::: sidenote
 For security reasons browsers (and by extension any JavaScript running in a browser) is prevented from accessing system files. File operations in HTML5 builds in Defold still work, but only on a "virtual file system" using the IndexedDB API in the browser. What this means is that there is no way to access bundle resources using `io.*` or `os.*` functions. You can however access bundle resources using `http.request()`.
@@ -94,9 +119,9 @@ For security reasons browsers (and by extension any JavaScript running in a brow
 | Characteristic              | Custom Resources                          | Bundle Resources                               |
 |-----------------------------|-------------------------------------------|------------------------------------------------|
 | Loading speed               | Faster - files loaded from binary archive | Slower - files loaded from filesystem          |
-| Load partial files          | No - only entire files                    | Yes - read arbitrary bytes from file           |
+| Load partial files          | No - only entire files                    | Yes - read arbitrary bytes from file           |
 | Modify files after bundling | No - files stored inside a binary archive | Yes - files stored on the local file system    |
-| HTML5 support               | Yes                                       | Yes - but access through http and not file I/O |
+| HTML5 support               | Yes                                       | Yes - but access through http and not file I/O |
 
 
 ### System file access

docs/en/manuals/project-settings.md

@@ -38,18 +38,15 @@ A list of URLs to the project *Library URL*s. Refer to the [Libraries manual](/m
 
 #### Custom Resources
 `custom_resources`
-A comma separated list of resources that will be included in the project. If directories are specified, all files and directories in that directory are recursively included. The resources can be loaded using [`sys.load_resource()`](/ref/sys/#sys.load_resource). Loading custom resources is covered in more detail in the [File Access manual](/manuals/file-access/#how-to-access-files-bundled-with-the-application).
+:[Custom Resources](../shared/custom-resources.md)
+
+Loading custom resources is covered in more detail in the [File Access manual](/manuals/file-access/#how-to-access-files-bundled-with-the-application).
 
 #### Bundle Resources
 `bundle_resources`
-A comma separated list of directories containing resource files and folders that should be copied as-is into the resulting package when bundling. The directories must be specified with an absolute path from the project root, for example `/res`. The resource directory must contain subfolders named by `platform`, or `architecture-platform`.
-
-Supported platforms are `ios`, `android`, `osx`, `win32`, `linux`, `web`, `switch`
-
-A subfolder named `common` is also allowed, containing resource files common for all platforms.
+:[Bundle Resources](../shared/bundle-resources.md)
 
-Access to files within the the bundle resources is platform specific. The Lua module `io` is one way to do it. Care must be taken to have the correct file paths for the platform.
-(e.g. prefix using "file:///android_asset/" on Android). Loading files is covered in more detail in the [File Access manual](/manuals/file-access/#how-to-access-files-bundled-with-the-application).
+Loading bundle resources is covered in more detail in the [File Access manual](/manuals/file-access/#how-to-access-files-bundled-with-the-application).
 
 #### Bundle Exclude Resources
 `bundle_exclude_resources`

docs/en/shared/bundle-resources.md

@@ -0,0 +1,20 @@
+Bundle resources are additional files and folders located as a part of your application bundle using the [*Bundle Resources* field](/manuals/project-settings/#bundle-resources) in *game.project*.
+
+The *Bundle Resources* field should contain a comma separated list of directories containing resource files and folders that should be copied as-is into the resulting package when bundling. The directories must be specified with an absolute path from the project root, for example `/res`. The resource directory must contain subfolders named by `platform`, or `architecture-platform`.
+
+Supported platforms are `ios`, `android`, `osx`, `win32`, `linux`, `web`, `switch` A subfolder named `common` is also allowed, containing resource files common for all platforms. Example:
+
+```
+res
+├── win32
+│   └── mywin32file.txt
+├── common
+│   └── mycommonfile.txt
+└── android
+    ├── myandroidfile.txt
+    └── res
+        └── xml
+            └── filepaths.xml
+```
+
+You can use [`sys.get_application_path()`](/ref/stable/sys/#sys.get_application_path:) to get the path to where the application is stored. Use this application base path to create the final absolute path to the files you need access to. Once you have the absolute path of these files you can use the `io.*` and `os.*` functions to access the files.

docs/en/shared/custom-resources.md

@@ -0,0 +1,3 @@
+Custom resources are bundled in the main game archive using the [*Custom Resources* field](https://defold.com/manuals/project-settings/#custom-resources) in *game.project*.
+
+The *Custom Resources* field should contain a comma separated list of resources that will be included in the main game archive. If directories are specified, all files and directories in that directory are recursively included. You can read the files using [`sys.load_resource()`](/ref/sys/#sys.load_resource).