From 314f8613d3417b25c1ccced9ac1a0102a1958da9 Mon Sep 17 00:00:00 2001
From: _bryan <_bryan@noreply.gitea.ligthert.net>
Date: Tue, 17 Jan 2023 20:32:58 +0000
Subject: [PATCH] Add 'Filesystem'

---
 Filesystem.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 Filesystem.md

diff --git a/Filesystem.md b/Filesystem.md
new file mode 100644
index 0000000..6dfcccf
--- /dev/null
+++ b/Filesystem.md
@@ -0,0 +1,55 @@
+# Filesystem
+
+The filesystem is a wrapper of Panda3D's virtual filesystem. When loading the platform a default main asset folder is always loaded. The user must supply via the argument `-p` or `--package` a single or multiple packages which hold game data.
+
+Example: `python .\source\ --package C:\Users\Bryan\Documents\example-package ...`
+
+https://docs.panda3d.org/1.10/cpp/reference/panda3d.core.VirtualFileSystem
+
+## Folder structure
+
+The virtual file system follows the posix standard and uses forward slashes using `/` as root.
+
+```
+/
+  - main-assets
+    + models/
+    + animations/
+    + textures/
+    + materials/
+      gamepackage.json
+  - example-package
+    + models/
+    + animations/
+    + textures/
+    + materials/
+      gamepackage.json
+```
+
+* `models` - `.egg`, `.glTF`, or `.glb` files containing mesh information
+* `textures` - `.png`, or `.bmp` images
+* `materials` - definitions for non-albedo textures
+* `animations` - `.glTF` or `.glb` files containing armatures and animation sequences
+
+## Gamepackage.json
+
+Every package is required to have this file located at the base directory of the mod. The file contains the name, description, version, and other information about the package.
+
+```json
+{
+	"name": "main-assets",
+	"version": "0.1-alpha"
+}
+```
+
+## Loading package
+
+When starting the platform the argument `-p` or `--package` should be given a list of folders to be mounted. Each package is loaded into a respective `/<packagename>` folder.
+
+## Finding assets
+
+There are two ways to supply paths. Paths that start with `$/` mean use the first asset found and will check starting from the top of the list (last package supplied) to the bottom. This can be used to allow assets to be 'replaced' by other packages.
+
+If the path is instead `<packagename>/mymodel.glb`, than it will only look in that package for the given resource and not attempt to search other packages. In this way you can prevent other packages from replacing an asset.
+
+Assets that can't be found will return a default error asset.
\ No newline at end of file