john/cell
1
0
Fork 0
Code Issues 31 Pull Requests Packages Projects Releases 2 Wiki Activity

rework guide documentation

Browse Source
This commit is contained in:
John Alanbrook
2025-02-11 00:18:29 -06:00
parent 375a6ad3a4
commit c25c52faa0
7 changed files with 111 additions and 353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/resources.md
View File

@@ -1,51 +1,17 @@
# Resources & Data
This document provides a **high-level** explanation of how Prosperon handles resource loading, module discovery, and general file I/O. It is intended to give you insight into the **concepts and architecture** behind these systems, without detailing individual function calls.
Prosperon, being text based, encourages you to reference assets - images, sounds, etc - as strings.
---
## Module Loading and Discovery
## 1. Module Loading and Discovery
Prosperon uses a set of **search paths** to locate modules. Each path in this list is consulted in order, and the first matching module file is loaded.
**prosperon.PATH** is an array which is a list of directories in which it looks for resources. Developers can add or remove entries from this list, controlling where the engine will search. Assets are searched from `prosperon.PATH[0]` first.
Prosperon uses a set of **search paths** to locate modules. Each path in this list is consulted in order, and the first matching module file is loaded.
- **Paths Array:** The engine maintains a list of directories in which it looks for modules. Developers can add or remove entries from this list, controlling where the engine will search.
- **Extension Matching:** When asked to load a particular module by name, Prosperon tries recognized file extensions until it finds a suitable file. This means you do not have to specify the file’s extension; the engine infers it from a known set of possibilities.
- **Shadowing:** If your local module happens to have the same name as a built-in module, and is found first in the search path, it overrides the built-in. This can be used to replace or augment default behaviors.
**Extension Matching:** Assets should be referenced without a file extension. Based on the context of what asset is being searched for, a list of file extensions are iterated through to find the asset. When setting a sprite's texture, for example, first a 'png' may be searched for, then a 'gif', and so on. If a specific extension is requested, that specific extension - and only that one - will be searched for. it's very useful to not specify extensions at all, because that enables prosperon to optimize assets and replace them with backend specific ones, and the game will still work.
Prosperon **caches** each loaded module so it is only created once. Subsequent requests for the same module return the same instance.
Prosperon **caches** each loaded assets. When a sprite references a 'png', if another one does, it uses the same GPU texture.
---
## Mounts
Prosperon uses the idea of file mounting for all io operations. To start with, the write directory is set to the folder prosperon is ran from. That same folder is also mounted as a read directory, as well as the executable itself, which contains a zip file of the engine's core assets.
## 2. Resource System
Beyond modules, Prosperon categorizes other assets (images, sounds, fonts, etc.) by **common file extensions**.
- **Extension Lists:** Internally, there are sets of recognized extensions for each resource type (e.g., for images or sound files). These lists drive how Prosperon locates the actual file you intended to load.
- **Canonical Paths:** Whenever a resource is identified, its path is transformed into a “real” path on the host filesystem. This ensures the engine is working with unambiguous directory references, even if virtual or mounted paths are involved.
- **Consistency:** This approach keeps naming consistent across different platforms, so developers don’t need to worry about exact extension casing or platform-specific directory structures.
---
## 3. High-Level I/O Flow
Prosperon’s I/O subsystem provides a **unified interface** for reading and writing files, managing directories, and working with mounted filesystems or archives. While the specific operations vary (creating directories, checking file existence, enumerating directories, etc.), they are all handled through a single engine-provided interface. Key points include:
- **Mounting & Write Paths:** Prosperon can mount external directories or archives into its virtual filesystem, and can direct all “write” operations to a particular directory.
- **Metadata & Enumeration:** The engine tracks file metadata and can list contents of directories (including optional recursion into subdirectories).
- **Wildcard & Glob Patterns:** Certain patterns can be used to include or exclude files from an operation, helping developers filter out files easily.
By keeping resource lookups and filesystem interactions centralized, Prosperon’s I/O system fosters portability across different environments and platforms.
---
## 4. Integration in the Engine
From the moment Prosperon starts up, it initializes the module and resource systems. This guarantees that:
1. **Core Modules** (e.g., for rendering or audio) are found in known paths.
2. **Developer-Defined Modules** are discovered if they are placed in the search paths configured by the engine.
3. **Resource Operations** (like finding the correct variant of an image or script) are uniform, relying on known extension lists and standardized directory lookups.
Since everything is cached and resolved through the same system, developers can **easily control** how their projects load assets, override default modules, or customize file storage locations, without needing to replicate or reinvent these mechanisms.
---
## 5. Summary
Overall, Prosperon’s module system and resource loader work together to provide a **flexible, extensible** approach for organizing a project’s code and data. By adjusting the search paths and extension lists, developers can adapt the engine to a wide variety of use cases—while the I/O subsystem ensures that common file management patterns (mounting, enumerating, reading, and writing) all behave in a consistent manner across platforms and deployment scenarios.
Folders or archives like zip records can be mounted, allowing for an easy way to overwrite specific files with new ones. Because prosperon deals with file systems and strings for its operations, this makes modding easy. For example, a mod `mod.zip` may have a file `sprites/bug.png`. Once mounted, when your game loads `bug` as a sprite, that would be grabbed instead of your game's natives `bug`.