0
# Resource Management
1

2
Automatic resource loading with path resolution, ZIP support, and caching.
3

4
## Quick Reference
5

6
```python
7
import pyglet
8

9
# Set resource paths
10
pyglet.resource.path = ['assets', 'assets/images', 'assets/sounds']
11
pyglet.resource.reindex()
12

13
# Load resources (automatically cached)
14
image = pyglet.resource.image('player.png')
15
sound = pyglet.resource.media('jump.wav', streaming=False)
16
texture = pyglet.resource.texture('wall.png')
17

18
# Custom loader
19
loader = pyglet.resource.Loader(['data', 'data/textures'])
20
sprite_img = loader.image('sprite.png')
21
```
22

23
## Default Loader
24

25
```python
26
# Module-level functions use default loader
27
def pyglet.resource.image(name, flip_x=False, flip_y=False, rotate=0) -> AbstractImage
28
def pyglet.resource.animation(name) -> Animation
29
def pyglet.resource.texture(name) -> Texture
30
def pyglet.resource.media(name, streaming=True) -> Source
31
def pyglet.resource.file(name, mode='rb') -> file
32
def pyglet.resource.location(name) -> Location
33
def pyglet.resource.add_font(name)
34

35
# Configure paths
36
pyglet.resource.path: list  # Search paths
37
pyglet.resource.reindex()  # Rebuild index after changing path
38
```
39

40
## Loader Class
41

42
```python
43
class pyglet.resource.Loader:
44
    """Custom resource loader"""
45
    __init__(path=None, script_home=None)
46

47
    # Load methods
48
    def image(name, flip_x=False, flip_y=False, rotate=0) -> AbstractImage
49
    def animation(name) -> Animation
50
    def texture(name) -> Texture
51
    def media(name, streaming=True) -> Source
52
    def file(name, mode='rb') -> file
53
    def add_font(name)
54

55
    # Shader loading
56
    def shader(name, shader_type=None) -> Shader
57

58
    # Location methods
59
    def location(name) -> Location
60
    def add_location(location: Location)
61

62
    # Properties
63
    _cached_images: dict  # Image cache
64
    _cached_textures: dict  # Texture cache
65
    _cached_animations: dict  # Animation cache
66
```
67

68
## Locations
69

70
```python
71
class pyglet.resource.Location:
72
    """Abstract resource location"""
73

74
class pyglet.resource.FileLocation:
75
    """Filesystem directory"""
76
    __init__(path)
77

78
class pyglet.resource.ZIPLocation:
79
    """ZIP archive"""
80
    __init__(zip_file, directory='')
81

82
class pyglet.resource.URLLocation:
83
    """Remote URL"""
84
    __init__(base_url)
85

86
# Add custom locations
87
loader = pyglet.resource.Loader()
88
loader.add_location(pyglet.resource.FileLocation('assets'))
89
loader.add_location(pyglet.resource.ZIPLocation('data.zip'))
90
```
91

92
## Examples
93

94
### Basic Resource Loading
95
```python
96
import pyglet
97

98
# Setup paths (relative to script location)
99
pyglet.resource.path = ['assets']
100
pyglet.resource.reindex()
101

102
# Load and use
103
player_img = pyglet.resource.image('player.png')
104
sprite = pyglet.sprite.Sprite(player_img, x=100, y=100)
105

106
jump_sound = pyglet.resource.media('jump.wav', streaming=False)
107
jump_sound.play()
108
```
109

110
### Organized Asset Structure
111
```python
112
# Directory structure:
113
# assets/
114
#   images/
115
#     player.png
116
#     enemies/
117
#       zombie.png
118
#   sounds/
119
#     jump.wav
120
#   fonts/
121
#     custom.ttf
122

123
pyglet.resource.path = [
124
    'assets/images',
125
    'assets/images/enemies',
126
    'assets/sounds',
127
    'assets/fonts'
128
]
129
pyglet.resource.reindex()
130

131
# Load from any registered path
132
player = pyglet.resource.image('player.png')
133
zombie = pyglet.resource.image('zombie.png')
134
jump = pyglet.resource.media('jump.wav', streaming=False)
135

136
# Add font
137
pyglet.resource.add_font('custom.ttf')
138
font = pyglet.font.load('Custom Font Name', 16)
139
```
140

141
### Multiple Loaders
142
```python
143
# Separate loaders for different asset types
144
ui_loader = pyglet.resource.Loader(['assets/ui'])
145
game_loader = pyglet.resource.Loader(['assets/game', 'assets/game/levels'])
146

147
# Load from specific loaders
148
button_img = ui_loader.image('button.png')
149
level_data = game_loader.file('level1.json')
150
```
151

152
### ZIP Archive Resources
153
```python
154
# Load from ZIP file
155
loader = pyglet.resource.Loader()
156
loader.add_location(pyglet.resource.ZIPLocation('assets.zip', 'images/'))
157

158
# Load as normal
159
sprite_img = loader.image('sprite.png')  # Loads from assets.zip/images/sprite.png
160
```
161

162
### Shader Loading
163
```python
164
loader = pyglet.resource.Loader(['shaders'])
165

166
# Auto-detect type from extension (.vert, .frag, etc.)
167
vert = loader.shader('basic.vert')
168

169
# Or specify type
170
frag = loader.shader('basic.frag', shader_type='fragment')
171

172
program = pyglet.graphics.shader.ShaderProgram(vert, frag)
173
```
174

175
### Resource Manager Class
176
```python
177
class ResourceManager:
178
    """Centralized resource management"""
179
    def __init__(self):
180
        pyglet.resource.path = ['assets/images', 'assets/sounds']
181
        pyglet.resource.reindex()
182

183
        # Preload common resources
184
        self.images = {
185
            'player': pyglet.resource.image('player.png'),
186
            'enemy': pyglet.resource.image('enemy.png'),
187
            'bullet': pyglet.resource.image('bullet.png'),
188
        }
189

190
        self.sounds = {
191
            'jump': pyglet.resource.media('jump.wav', streaming=False),
192
            'shoot': pyglet.resource.media('shoot.wav', streaming=False),
193
        }
194

195
        self.music = {
196
            'menu': pyglet.resource.media('menu_music.mp3', streaming=True),
197
            'game': pyglet.resource.media('game_music.mp3', streaming=True),
198
        }
199

200
    def get_image(self, name):
201
        return self.images.get(name)
202

203
    def get_sound(self, name):
204
        return self.sounds.get(name)
205

206
    def play_music(self, name):
207
        music = self.music.get(name)
208
        if music:
209
            music.play()
210

211
# Usage
212
resources = ResourceManager()
213
player_sprite = pyglet.sprite.Sprite(resources.get_image('player'))
214
resources.get_sound('jump').play()
215
```
216

217
### Loading Screen
218
```python
219
class LoadingScreen:
220
    def __init__(self, window):
221
        self.window = window
222
        self.label = pyglet.text.Label(
223
            'Loading...',
224
            x=window.width // 2,
225
            y=window.height // 2,
226
            anchor_x='center'
227
        )
228

229
    def load_resources(self):
230
        """Load all game resources"""
231
        resources_to_load = [
232
            ('player.png', 'image'),
233
            ('enemy.png', 'image'),
234
            ('background.png', 'image'),
235
            ('music.mp3', 'media'),
236
        ]
237

238
        loaded = {}
239
        total = len(resources_to_load)
240

241
        for i, (name, rtype) in enumerate(resources_to_load):
242
            # Update progress
243
            self.label.text = f'Loading... {i}/{total}'
244
            self.window.dispatch_event('on_draw')
245
            self.window.flip()
246

247
            # Load resource
248
            if rtype == 'image':
249
                loaded[name] = pyglet.resource.image(name)
250
            elif rtype == 'media':
251
                loaded[name] = pyglet.resource.media(name)
252

253
        return loaded
254
```
255

256
## Caching
257

258
Resources are automatically cached after first load:
259
```python
260
# First load: reads from disk
261
img1 = pyglet.resource.image('sprite.png')
262

263
# Second load: returns cached instance
264
img2 = pyglet.resource.image('sprite.png')
265

266
assert img1 is img2  # Same object
267
```
268

269
## Performance Tips
270

271
1. **Set paths early**: Configure `pyglet.resource.path` before loading
272
2. **Preload resources**: Load during initialization, not during gameplay
273
3. **Use appropriate streaming**: `streaming=False` for SFX, `True` for music
274
4. **Cache references**: Store loaded resources, don't reload
275
5. **ZIP archives**: Can improve load times for many small files
276

277
## Common Issues
278

279
1. **File not found**: Check `pyglet.resource.path` and call `reindex()`
280
2. **Wrong file loaded**: Multiple files with same name, first path wins
281
3. **Path separators**: Use forward slashes `/` even on Windows
282
4. **Relative paths**: Paths relative to script location by default
283
5. **Cache issues**: Create new Loader for fresh cache
284