0
# Specialized Features
1

2
Advanced features including particle systems, A* pathfinding, performance monitoring, tilemap support, and experimental rendering effects for enhanced game functionality.
3

4
## Capabilities
5

6
### Particle System
7

8
```python { .api }
9
class Emitter:
10
    """
11
    Particle emitter for creating visual effects.
12
    """
13
    def __init__(self, center_xy: tuple[float, float], 
14
                 emit_controller: arcade.EmitController,
15
                 particle_factory: callable):
16
        """Create particle emitter."""
17
    
18
    center_xy: tuple[float, float]
19
    
20
    def update(self) -> None:
21
        """Update particles and emission."""
22
    
23
    def draw(self) -> None:
24
        """Draw all particles."""
25

26
class Particle:
27
    """Base particle class."""
28
    def __init__(self):
29
        """Create particle."""
30
    
31
    position: tuple[float, float]
32
    velocity: tuple[float, float]
33
    lifetime: float
34
    
35
    def update(self) -> bool:
36
        """Update particle. Returns True if still alive."""
37

38
class EmitController:
39
    """Controls when and how particles are emitted."""
40
    def can_emit(self) -> bool:
41
        """Check if emission should occur."""
42

43
def make_burst_emitter(center_xy: tuple[float, float], particle_factory: callable, 
44
                      particle_count: int) -> arcade.Emitter:
45
    """Create burst emitter."""
46

47
def make_interval_emitter(center_xy: tuple[float, float], particle_factory: callable,
48
                         interval: float, particle_count: int) -> arcade.Emitter:
49
    """Create interval-based emitter."""
50
```
51

52
### Pathfinding
53

54
```python { .api }
55
class AStarBarrierList:
56
    """
57
    Barrier list for A* pathfinding algorithm.
58
    """
59
    def __init__(self, moving_sprite: arcade.Sprite, blocking_sprites: arcade.SpriteList, 
60
                 grid_size: int, left: int, right: int, bottom: int, top: int):
61
        """Create A* barrier list."""
62

63
def astar_calculate_path(start_point: tuple[int, int], end_point: tuple[int, int], 
64
                        barriers: arcade.AStarBarrierList, 
65
                        diagonal_movement: bool = True) -> list[tuple[int, int]]:
66
    """
67
    Calculate path using A* algorithm.
68
    
69
    Args:
70
        start_point: Starting grid position
71
        end_point: Target grid position
72
        barriers: Barrier list with obstacles
73
        diagonal_movement: Allow diagonal movement
74
    
75
    Returns:
76
        List of grid positions forming the path
77
    """
78

79
def has_line_of_sight(point1: tuple[float, float], point2: tuple[float, float], 
80
                     barriers: arcade.AStarBarrierList) -> bool:
81
    """
82
    Check line of sight between two points.
83
    
84
    Args:
85
        point1: First point
86
        point2: Second point
87
        barriers: Obstacles to check against
88
    
89
    Returns:
90
        True if clear line of sight exists
91
    """
92
```
93

94
### Performance Monitoring
95

96
```python { .api }
97
class PerfGraph:
98
    """
99
    Visual performance graph for monitoring frame rates and timing.
100
    """
101
    def __init__(self, width: int, height: int, graph_data: str, 
102
                 sample_count: int = 60):
103
        """Create performance graph."""
104
    
105
    def update(self, value: float) -> None:
106
        """Add new performance sample."""
107
    
108
    def draw(self) -> None:
109
        """Draw performance graph."""
110

111
def enable_timings() -> None:
112
    """Enable performance timing collection."""
113

114
def disable_timings() -> None:
115
    """Disable performance timing collection."""
116

117
def get_fps() -> float:
118
    """Get current frames per second."""
119

120
def print_timings() -> None:
121
    """Print collected timing information."""
122

123
def get_timings() -> dict:
124
    """Get timing data programmatically."""
125

126
def clear_timings() -> None:
127
    """Clear collected timing data."""
128
```
129

130
### Tilemap Support
131

132
```python { .api }
133
class TileMap:
134
    """
135
    Manages tile-based maps for 2D games.
136
    """
137
    def __init__(self):
138
        """Create tilemap."""
139
    
140
    # Map properties
141
    width: int
142
    height: int
143
    tile_width: int
144
    tile_height: int
145
    
146
    # Sprite lists for different layers
147
    sprite_lists: dict[str, arcade.SpriteList]
148
    
149
    def get_cartesian(self, x: int, y: int) -> tuple[float, float]:
150
        """Convert tile coordinates to world coordinates."""
151
    
152
    def get_tilemap_layer(self, layer_name: str) -> arcade.SpriteList:
153
        """Get sprite list for specific layer."""
154

155
def load_tilemap(map_path: str, scaling: float = 1.0, 
156
                layer_options: dict = None) -> arcade.TileMap:
157
    """
158
    Load tilemap from TMX file.
159
    
160
    Args:
161
        map_path: Path to TMX tilemap file
162
        scaling: Scale factor for tiles
163
        layer_options: Options for specific layers
164
    
165
    Returns:
166
        Loaded TileMap object
167
    """
168
```
169

170
### Scene Management
171

172
```python { .api }
173
class Scene:
174
    """
175
    Container for managing multiple sprite lists as named layers.
176
    """
177
    def __init__(self, sprite_lists: dict[str, arcade.SpriteList] = None):
178
        """Create scene with optional initial sprite lists."""
179
    
180
    def add_sprite_list(self, name: str, sprite_list: arcade.SpriteList = None) -> None:
181
        """Add sprite list layer to scene."""
182
    
183
    def get_sprite_list(self, name: str) -> arcade.SpriteList:
184
        """Get sprite list by layer name."""
185
    
186
    def remove_sprite_list(self, name: str) -> None:
187
        """Remove sprite list layer."""
188
    
189
    def update(self, names: list[str] = None) -> None:
190
        """Update specified layers or all layers."""
191
    
192
    def draw(self, names: list[str] = None, **kwargs) -> None:
193
        """Draw specified layers or all layers."""
194

195
class SceneKeyError(Exception):
196
    """Exception for scene layer access errors."""
197
    pass
198
```
199

200
### Experimental Features
201

202
```python { .api }
203
# Shader effects
204
class Shadertoy:
205
    """
206
    Shadertoy-compatible shader system for visual effects.
207
    """
208
    def __init__(self, size: tuple[int, int], main_source: str):
209
        """Create Shadertoy shader."""
210
    
211
    def render(self, time: float = 0, mouse_position: tuple[float, float] = (0, 0)) -> None:
212
        """Render shader effect."""
213

214
class CRTFilter:
215
    """CRT monitor visual effect filter."""
216
    def __init__(self, width: int, height: int):
217
        """Create CRT filter."""
218
    
219
    def use(self) -> None:
220
        """Apply CRT effect to subsequent rendering."""
221
    
222
    def render(self) -> None:
223
        """Render CRT effect."""
224

225
class BloomFilter:
226
    """Bloom lighting effect filter."""
227
    def __init__(self, width: int, height: int, threshold: float = 0.7):
228
        """Create bloom filter."""
229
    
230
    threshold: float
231
    
232
    def use(self) -> None:
233
        """Apply bloom effect."""
234
    
235
    def render(self) -> None:
236
        """Render bloom effect."""
237
```
238

239
### Hit Box System
240

241
```python { .api }
242
class HitBox:
243
    """Base hit box class for collision detection."""
244
    def __init__(self, points: list[tuple[float, float]]):
245
        """Create hit box from points."""
246
    
247
    points: list[tuple[float, float]]
248
    
249
    def create_rotated(self, angle: float) -> 'HitBox':
250
        """Create rotated version of hit box."""
251

252
class RotatableHitBox(HitBox):
253
    """Hit box that supports rotation."""
254
    def __init__(self, points: list[tuple[float, float]]):
255
        """Create rotatable hit box."""
256
    
257
    def rotate(self, angle: float) -> None:
258
        """Rotate hit box by angle."""
259

260
# Hit box algorithms
261
class SimpleHitBoxAlgorithm:
262
    """Simple rectangular hit box algorithm."""
263
    def calculate(self, texture: arcade.Texture) -> list[tuple[float, float]]:
264
        """Calculate simple hit box points."""
265

266
class PymunkHitBoxAlgorithm:
267
    """Detailed hit box using Pymunk for complex shapes."""
268
    def calculate(self, texture: arcade.Texture, detail: float = 4.5) -> list[tuple[float, float]]:
269
        """Calculate detailed hit box points."""
270

271
# Algorithm instances
272
algo_simple: SimpleHitBoxAlgorithm
273
algo_detailed: PymunkHitBoxAlgorithm
274
algo_default: SimpleHitBoxAlgorithm  # Default algorithm
275
```
276

277
## Usage Examples
278

279
### Particle Effects
280

281
```python
282
import arcade
283

284
class ParticleDemo(arcade.Window):
285
    def __init__(self):
286
        super().__init__(800, 600, "Particle Effects")
287
        self.emitter_list = []
288
    
289
    def setup(self):
290
        # Create explosion effect
291
        def make_particle():
292
            particle = arcade.FadeParticle(
293
                filename_or_texture=":resources:images/space_shooter/meteorGrey_med1.png",
294
                change_xy=(arcade.rand_vec_magnitude(0, 2, 5)),
295
                scale=0.1,
296
                lifetime=2.0
297
            )
298
            return particle
299
        
300
        # Burst emitter for explosion
301
        explosion = arcade.make_burst_emitter(
302
            center_xy=(400, 300),
303
            particle_factory=make_particle,
304
            particle_count=50
305
        )
306
        self.emitter_list.append(explosion)
307
    
308
    def on_draw(self):
309
        self.clear()
310
        for emitter in self.emitter_list:
311
            emitter.draw()
312
    
313
    def on_update(self, delta_time):
314
        for emitter in self.emitter_list:
315
            emitter.update()
316

317
def main():
318
    game = ParticleDemo()
319
    game.setup()
320
    arcade.run()
321

322
if __name__ == "__main__":
323
    main()
324
```