Resource Subsystem

[AstraLuma]

Add system to load and cache resources, including zip safe.

[AstraLuma]

I currently see resource management as a foundational library used by explicit systems like graphics and sound. Under the current ppb flavor, I'm not sure there's a lot of need for developers to interact with the resource subsystem. (Except maybe declarative resource usage hints.)

[pathunstrom]

Realizing today I never actually commented. I think the most important bit of any resource system is

(Except maybe declarative resource usage hints.)

Being able to have scene prep a preload list and letting the subsystems load those things early one would be awesome so we get the right behavior for minimal effort.

[AstraLuma]

Ok, so my most current design involves redoing how resource usage is done.

Resources are started to be loaded as soon as their usage is first declared, in the background.

Resources are used like: Image('path/to/sprite.png'), Sound('sounds/beep.ogg'), etc and then used where strings are currently used. The construction of these implicitly signal ("hint") to the resource system to add them to the load queue.

The resource system can also produce signals about loading, so we can produce template load screens.

[AstraLuma]

I'm also thinking that instead of the current resource path system, we extend sys.path into a "Python Virtual File System". Resources will be searched for against sys.path in the same manner as modules.

[pathunstrom]

I definitely want to see what the virtual file system one looks like in use. So we should definitely make a stab at that.

[AstraLuma]

It's pretty much what pyglet does if you prefix the resource with @.

[AstraLuma]

Ok, here's what I'm thinking:

• Move to "Python VFS" and nix resource paths: As discussed above, remove __resource_path__ and switch to a game-wide virtual path system, using Python's module system/sys.path as a basis. This was prototyped in [nomerge] Nix __resource_path__ #289.
• Add an background-loading component: Detect first reference and begin loading immediately in a background thread. We would still block on first use.

The second of the two is by far the more dramatic change (from an end-user's perspective). So, here's what's happening:

• All resource references become object instantiations: Image, Sound, etc
• There's a common parent class Resource that deals with all the interfacing with the resource system
• Different systems should define their own Resource subclasses with their own specialized parsing/loading (eg, decoding an image and loading it onto a Surface, loading sound codecs, etc)
• Proxy resources may exist, if they implement specific interfaces. The animation feature should be re-written to do this.

So, in summary, we'll start seeing this:

class MySprite(BaseSprite):
    image = Image('mygame/sprites/MySprite.png')
    
    def on_click(self, event, signal):
        signal(PlaySound(sound=Sound('mygame/sounds/clicked.ogg'), at=self))

In addition to the above, the Resource subsystem:

• Is a real subsystem under the engine
• Fires events around resource loading, for both loading queue and specific resources loading
• Should provide the underpinnings needed for loading screens

[pathunstrom]

Question regarding the Python VFS system: how would that affect a local resource folder that doesn't live in the same module space as the game the end user is writing?

[AstraLuma]

The requirements for this are:

• It needs to be a real package and not a namespace one (it needs to have an __init__.py)--this is a limitation of importlib.resources
• It needs to be on sys.path; how to achieve this depends on how the game is packaged and launched (a zipapp, a launch script from a project, a installed package, -m from the source directory, etc) but I believe no extra steps need to be taken if the standard patterns are followed

So, if you have a project folder with the mygame and assets packages (directories with an __init__.py), you should either use an entry script in the root or at mygame/__main__.py. Then you may say either python rungame.py or python -m mygame. (Again, these are the standard patterns.)

(In this example, I believe only assets/__init__.py is required; mygame/__init__.py I believe is not.)

If these prove insufficient, we can add something like ppb.asset_dir() that does the necessary manipulations (Add to sys.path, set a __file__ on sys.modules, etc) to enable it to work. However, this should be implemented carefully to remain compatible with packaging and distribution.

[AstraLuma]

Oh, and I think I'm going to use the Resource objects for caching, so the caches are cleaned up when nobody's using them anymore.

[AstraLuma]

Ok, here's the list

• Write the asset system and convert core stuff to use it (Revamp Assets #306)
• Refactor ppb.systems into thematic submodules (Move things, break loops #316)
• Update the animation feature to be an asset proxy (Apply Assets to Animation #308)
• Add an AssetLoaded event (Add AssetLoaded event #315)
• Add a loading screen feature (Add Loading Screen #336)
• Solution for multiple references to the same asset (internize assets #323)
• Update ppb-mutant (Rebuild for Assets ppb-mutant#5)

[AstraLuma]

Closing this, as it's complete!