0
# Core System Management
1

2
Essential system functions for initializing pygame, managing modules, and handling errors. These functions form the foundation that must be called before using other pygame functionality.
3

4
## Capabilities
5

6
### Module Initialization
7

8
Core functions that initialize and shut down pygame modules. The `init()` function must be called before using any other pygame functionality.
9

10
```python { .api }
11
def init() -> tuple[int, int]:
12
    """
13
    Initialize all pygame modules.
14
    
15
    Returns:
16
        tuple[int, int]: (successful_modules, failed_modules)
17
    """
18

19
def quit() -> None:
20
    """
21
    Uninitialize all pygame modules.
22
    Call before exiting your program.
23
    """
24

25
def get_init() -> bool:
26
    """
27
    Check if pygame is initialized.
28
    
29
    Returns:
30
        bool: True if pygame has been initialized
31
    """
32
```
33

34
### Module Registration
35

36
Register cleanup functions to be called when pygame quits.
37

38
```python { .api }
39
def register_quit(callable: callable) -> None:
40
    """
41
    Register a function to be called when pygame quits.
42
    
43
    Parameters:
44
        callable: Function to call during pygame.quit()
45
    """
46
```
47

48
### Error Handling
49

50
Functions for getting and setting error messages from pygame operations.
51

52
```python { .api }
53
def get_error() -> str:
54
    """
55
    Get the current error message from pygame/SDL.
56
    
57
    Returns:
58
        str: Current error message, empty string if no error
59
    """
60

61
def set_error(msg: str) -> None:
62
    """
63
    Set the current error message.
64
    
65
    Parameters:
66
        msg: Error message to set
67
    """
68
```
69

70
### SDL Information
71

72
Functions to get information about the underlying SDL library.
73

74
```python { .api }
75
def get_sdl_version() -> tuple[int, int, int]:
76
    """
77
    Get the version of SDL that pygame is using.
78
    
79
    Returns:
80
        tuple[int, int, int]: (major, minor, patch) version numbers  
81
    """
82

83
def get_sdl_byteorder() -> int:
84
    """
85
    Get the byte order of the SDL library.
86
    
87
    Returns:
88
        int: Byte order constant (LIL_ENDIAN or BIG_ENDIAN)
89
    """
90
```
91

92
### Version Information
93

94
```python { .api }
95
__version__: str  # pygame-ce version string
96
```
97

98
### Exception Classes
99

100
```python { .api }
101
class error(RuntimeError):
102
    """
103
    Main pygame exception class.
104
    Raised by pygame functions when they encounter errors.
105
    """
106
```
107

108
## Usage Examples
109

110
### Basic Initialization Pattern
111

112
```python
113
import pygame
114
import sys
115

116
try:
117
    # Initialize pygame - returns (success_count, fail_count)
118
    success, failed = pygame.init()
119
    print(f"Successfully initialized {success} modules")
120
    if failed > 0:
121
        print(f"Failed to initialize {failed} modules")
122
    
123
    # Check if initialization was successful
124
    if not pygame.get_init():
125
        raise pygame.error("pygame failed to initialize")
126
    
127
    # Your game code here
128
    # ...
129
    
130
except pygame.error as e:
131
    print(f"pygame error: {e}")
132
    print(f"SDL error: {pygame.get_error()}")
133
    
134
finally:
135
    # Always quit pygame before exiting
136
    pygame.quit()
137
    sys.exit()
138
```
139

140
### Error Handling
141

142
```python
143
import pygame
144

145
pygame.init()
146

147
try:
148
    # Some pygame operation that might fail
149
    surface = pygame.display.set_mode((800, 600))
150
    
151
except pygame.error:
152
    # Get the specific error message
153
    error_msg = pygame.get_error()
154
    print(f"Display initialization failed: {error_msg}")
155
    
156
    # Clear the error for next operation
157
    pygame.set_error("")
158
```
159

160
### Custom Cleanup Function
161

162
```python
163
import pygame
164

165
def cleanup_resources():
166
    """Custom cleanup function"""
167
    print("Cleaning up custom resources...")
168
    # Clean up your resources here
169

170
pygame.init()
171

172
# Register cleanup function to be called during quit
173
pygame.register_quit(cleanup_resources)
174

175
# Your game code here
176
# ...
177

178
# cleanup_resources() will be automatically called
179
pygame.quit()
180
```
181

182
## Constants
183

184
```python { .api }
185
# Byte order constants
186
LIL_ENDIAN: int  # Little endian byte order
187
BIG_ENDIAN: int  # Big endian byte order
188
```