soshi 0.0.1__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
soshi/SDL3.dll ADDED
Binary file
soshi/__init__.py ADDED
@@ -0,0 +1,49 @@
1
+ """Soshi: a small, fast 2D engine with a pygame-shaped API."""
2
+
3
+ from . import entity, input, render, window
4
+ from ._native import SoshiError
5
+ from .audio import Sound, audio
6
+ from .entity import Entity, world
7
+ from .input import event, mouse_pos
8
+ from .render import display, draw
9
+ from .texture import Texture
10
+ from .version import __version__
11
+ from .window import Clock, init, quit
12
+
13
+ K_ESCAPE = 27
14
+ K_RETURN = 13
15
+ K_SPACE = 32
16
+ K_LEFT = 1073741904
17
+ K_RIGHT = 1073741903
18
+ K_UP = 1073741906
19
+ K_DOWN = 1073741905
20
+
21
+ __all__ = [
22
+ "Clock",
23
+ "Entity",
24
+ "K_DOWN",
25
+ "K_ESCAPE",
26
+ "K_LEFT",
27
+ "K_RETURN",
28
+ "K_RIGHT",
29
+ "K_SPACE",
30
+ "K_UP",
31
+ "Sound",
32
+ "SoshiError",
33
+ "Texture",
34
+ "audio",
35
+ "display",
36
+ "draw",
37
+ "event",
38
+ "init",
39
+ "mouse_pos",
40
+ "quit",
41
+ "world",
42
+ "__version__",
43
+ ]
44
+
45
+
46
+ def __getattr__(name):
47
+ if name == "running":
48
+ return window.is_running()
49
+ raise AttributeError(f"module 'soshi' has no attribute {name!r}")
soshi/_native.py ADDED
@@ -0,0 +1,159 @@
1
+ """The only module that touches the native library.
2
+
3
+ Every exported function gets an explicit signature here so calls stay cheap and
4
+ type-conversion surprises stay out of the game loop.
5
+ """
6
+
7
+ import ctypes
8
+ import os
9
+ import sys
10
+
11
+ _LIBRARY_NAMES = {
12
+ "win32": "soshi.dll",
13
+ "darwin": "libsoshi.dylib",
14
+ }
15
+
16
+ _FLOAT = ctypes.c_float
17
+ _FLOAT_POINTER = ctypes.POINTER(ctypes.c_float)
18
+
19
+ _PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__))
20
+ _dll_directory = None
21
+
22
+
23
+ class SoshiError(RuntimeError):
24
+ """Raised when the native engine reports a failure."""
25
+
26
+
27
+ def _library_path():
28
+ name = _LIBRARY_NAMES.get(sys.platform, "libsoshi.so")
29
+ return os.path.join(_PACKAGE_DIR, name)
30
+
31
+
32
+ def _load():
33
+ global _dll_directory
34
+
35
+ path = _library_path()
36
+ if not os.path.exists(path):
37
+ raise ImportError(
38
+ f"soshi native library is missing at {path}; "
39
+ "build it with scripts/build.cmd or install a prebuilt wheel"
40
+ )
41
+ if sys.platform == "win32" and hasattr(os, "add_dll_directory"):
42
+ _dll_directory = os.add_dll_directory(_PACKAGE_DIR)
43
+ return ctypes.CDLL(path)
44
+
45
+
46
+ lib = _load()
47
+
48
+ lib.soshi_init.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_char_p]
49
+ lib.soshi_init.restype = ctypes.c_int
50
+ lib.soshi_quit.argtypes = []
51
+ lib.soshi_quit.restype = None
52
+ lib.soshi_is_running.argtypes = []
53
+ lib.soshi_is_running.restype = ctypes.c_int
54
+ lib.soshi_pump_events.argtypes = []
55
+ lib.soshi_pump_events.restype = None
56
+
57
+ lib.soshi_clear.argtypes = [ctypes.c_uint8, ctypes.c_uint8, ctypes.c_uint8, ctypes.c_uint8]
58
+ lib.soshi_clear.restype = None
59
+ lib.soshi_present.argtypes = []
60
+ lib.soshi_present.restype = None
61
+ lib.soshi_draw_rects.argtypes = [_FLOAT_POINTER, ctypes.c_int]
62
+ lib.soshi_draw_rects.restype = None
63
+ lib.soshi_draw_circles.argtypes = [_FLOAT_POINTER, ctypes.c_int]
64
+ lib.soshi_draw_circles.restype = None
65
+ lib.soshi_draw_world.argtypes = []
66
+ lib.soshi_draw_world.restype = None
67
+ lib.soshi_set_vsync.argtypes = [ctypes.c_int]
68
+ lib.soshi_set_vsync.restype = None
69
+ lib.soshi_display_size.argtypes = [_FLOAT_POINTER]
70
+ lib.soshi_display_size.restype = ctypes.c_int
71
+
72
+ lib.soshi_key_pressed.argtypes = [ctypes.c_int]
73
+ lib.soshi_key_pressed.restype = ctypes.c_int
74
+ lib.soshi_key_released.argtypes = [ctypes.c_int]
75
+ lib.soshi_key_released.restype = ctypes.c_int
76
+ lib.soshi_mouse_position.argtypes = [_FLOAT_POINTER]
77
+ lib.soshi_mouse_position.restype = ctypes.c_int
78
+ lib.soshi_clock_tick.argtypes = [_FLOAT]
79
+ lib.soshi_clock_tick.restype = _FLOAT
80
+
81
+ lib.soshi_world_set_bounds.argtypes = [_FLOAT, _FLOAT, _FLOAT, _FLOAT]
82
+ lib.soshi_world_set_bounds.restype = None
83
+ lib.soshi_world_set_gravity.argtypes = [_FLOAT]
84
+ lib.soshi_world_set_gravity.restype = None
85
+ lib.soshi_world_set_restitution.argtypes = [_FLOAT]
86
+ lib.soshi_world_set_restitution.restype = None
87
+ lib.soshi_world_step.argtypes = [_FLOAT]
88
+ lib.soshi_world_step.restype = None
89
+ lib.soshi_world_count.argtypes = []
90
+ lib.soshi_world_count.restype = ctypes.c_int
91
+ lib.soshi_world_capacity.argtypes = []
92
+ lib.soshi_world_capacity.restype = ctypes.c_int
93
+
94
+ lib.soshi_entity_create.argtypes = [_FLOAT] * 9
95
+ lib.soshi_entity_create.restype = ctypes.c_uint64
96
+ lib.soshi_entity_destroy.argtypes = [ctypes.c_uint64]
97
+ lib.soshi_entity_destroy.restype = ctypes.c_int
98
+ lib.soshi_entity_position.argtypes = [ctypes.c_uint64, _FLOAT_POINTER]
99
+ lib.soshi_entity_position.restype = ctypes.c_int
100
+ lib.soshi_entity_set_position.argtypes = [ctypes.c_uint64, _FLOAT, _FLOAT]
101
+ lib.soshi_entity_set_position.restype = ctypes.c_int
102
+ lib.soshi_entity_set_velocity.argtypes = [ctypes.c_uint64, _FLOAT, _FLOAT]
103
+ lib.soshi_entity_set_velocity.restype = ctypes.c_int
104
+ lib.soshi_entity_set_color.argtypes = [ctypes.c_uint64, _FLOAT, _FLOAT, _FLOAT, _FLOAT]
105
+ lib.soshi_entity_set_color.restype = ctypes.c_int
106
+
107
+ lib.soshi_entity_set_rotation.argtypes = [ctypes.c_uint64, _FLOAT]
108
+ lib.soshi_entity_set_rotation.restype = ctypes.c_int
109
+ lib.soshi_entity_set_parent.argtypes = [ctypes.c_uint64, ctypes.c_uint64]
110
+ lib.soshi_entity_set_parent.restype = ctypes.c_int
111
+ lib.soshi_entity_set_sprite.argtypes = [ctypes.c_uint64, ctypes.c_uint64, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, _FLOAT, ctypes.c_int]
112
+ lib.soshi_entity_set_sprite.restype = ctypes.c_int
113
+ lib.soshi_entity_set_draw_size.argtypes = [ctypes.c_uint64, _FLOAT, _FLOAT]
114
+ lib.soshi_entity_set_draw_size.restype = ctypes.c_int
115
+ lib.soshi_entity_set_frame.argtypes = [ctypes.c_uint64, ctypes.c_int]
116
+ lib.soshi_entity_set_frame.restype = ctypes.c_int
117
+ lib.soshi_entity_play_animation.argtypes = [ctypes.c_uint64]
118
+ lib.soshi_entity_play_animation.restype = ctypes.c_int
119
+ lib.soshi_entity_stop_animation.argtypes = [ctypes.c_uint64]
120
+ lib.soshi_entity_stop_animation.restype = ctypes.c_int
121
+
122
+ lib.soshi_texture_load.argtypes = [ctypes.c_char_p]
123
+ lib.soshi_texture_load.restype = ctypes.c_uint64
124
+ lib.soshi_texture_destroy.argtypes = [ctypes.c_uint64]
125
+ lib.soshi_texture_destroy.restype = None
126
+ lib.soshi_texture_size.argtypes = [ctypes.c_uint64, _FLOAT_POINTER]
127
+ lib.soshi_texture_size.restype = ctypes.c_int
128
+
129
+ lib.soshi_sound_load.argtypes = [ctypes.c_char_p]
130
+ lib.soshi_sound_load.restype = ctypes.c_uint64
131
+ lib.soshi_sound_destroy.argtypes = [ctypes.c_uint64]
132
+ lib.soshi_sound_destroy.restype = None
133
+ lib.soshi_sound_play.argtypes = [ctypes.c_uint64]
134
+ lib.soshi_sound_play.restype = ctypes.c_int
135
+ lib.soshi_audio_set_volume.argtypes = [_FLOAT]
136
+ lib.soshi_audio_set_volume.restype = None
137
+ lib.soshi_audio_available.argtypes = []
138
+ lib.soshi_audio_available.restype = ctypes.c_int
139
+
140
+ lib.soshi_last_error.argtypes = []
141
+ lib.soshi_last_error.restype = ctypes.c_char_p
142
+
143
+
144
+ def last_error():
145
+ message = lib.soshi_last_error()
146
+ return message.decode("utf-8", "replace") if message else "unknown engine error"
147
+
148
+
149
+ def check(result):
150
+ """Turn the C convention (0 = ok) into an exception."""
151
+ if result != 0:
152
+ raise SoshiError(last_error())
153
+ return result
154
+
155
+
156
+ def to_rgba(color):
157
+ """Accept (r, g, b) or (r, g, b, a) with 0-255 components."""
158
+ alpha = color[3] if len(color) > 3 else 255
159
+ return float(color[0]), float(color[1]), float(color[2]), float(alpha)
soshi/audio.py ADDED
@@ -0,0 +1,40 @@
1
+ """WAV playback through one shared output stream."""
2
+
3
+ from ._native import SoshiError, check, last_error, lib
4
+
5
+
6
+ class Sound:
7
+ """A decoded WAV ready to play. Playback queues on the shared stream."""
8
+
9
+ __slots__ = ("handle",)
10
+
11
+ def __init__(self, path):
12
+ self.handle = lib.soshi_sound_load(str(path).encode("utf-8"))
13
+ if self.handle == 0:
14
+ raise SoshiError(f"cannot load sound {path}: {last_error()}")
15
+
16
+ def play(self):
17
+ check(lib.soshi_sound_play(self.handle))
18
+
19
+ def destroy(self):
20
+ lib.soshi_sound_destroy(self.handle)
21
+ self.handle = 0
22
+
23
+ def __enter__(self):
24
+ return self
25
+
26
+ def __exit__(self, *_exception):
27
+ self.destroy()
28
+
29
+
30
+ class _Audio:
31
+ __slots__ = ()
32
+
33
+ def available(self):
34
+ return bool(lib.soshi_audio_available())
35
+
36
+ def set_volume(self, volume):
37
+ lib.soshi_audio_set_volume(float(volume))
38
+
39
+
40
+ audio = _Audio()
soshi/entity.py ADDED
@@ -0,0 +1,141 @@
1
+ import ctypes
2
+
3
+ from ._native import SoshiError, check, lib, to_rgba
4
+
5
+ _position_scratch = (ctypes.c_float * 2)()
6
+
7
+
8
+ class Entity:
9
+ """A body living in the native world; drawable as a circle or a sprite."""
10
+
11
+ __slots__ = ("handle", "radius", "color", "texture")
12
+
13
+ def __init__(
14
+ self,
15
+ *,
16
+ pos=(0.0, 0.0),
17
+ vel=(0.0, 0.0),
18
+ radius=10.0,
19
+ color=(255, 255, 255),
20
+ texture=None,
21
+ frame_size=None,
22
+ frames=1,
23
+ columns=None,
24
+ fps=0.0,
25
+ loop=True,
26
+ rotation=0.0,
27
+ parent=None,
28
+ ):
29
+ red, green, blue, alpha = to_rgba(color)
30
+ self.handle = lib.soshi_entity_create(
31
+ float(pos[0]),
32
+ float(pos[1]),
33
+ float(vel[0]),
34
+ float(vel[1]),
35
+ float(radius),
36
+ red,
37
+ green,
38
+ blue,
39
+ alpha,
40
+ )
41
+ if self.handle == 0:
42
+ raise SoshiError(f"world is full ({world.capacity()} entities)")
43
+
44
+ self.radius = float(radius)
45
+ self.color = tuple(color)
46
+ self.texture = texture
47
+
48
+ if texture is not None:
49
+ frame_width = int(frame_size[0]) if frame_size else int(texture.width)
50
+ frame_height = int(frame_size[1]) if frame_size else int(texture.height)
51
+ column_count = int(columns) if columns else max(1, int(texture.width) // frame_width)
52
+ check(
53
+ lib.soshi_entity_set_sprite(
54
+ self.handle,
55
+ texture.handle,
56
+ frame_width,
57
+ frame_height,
58
+ int(frames),
59
+ column_count,
60
+ float(fps),
61
+ 1 if loop else 0,
62
+ )
63
+ )
64
+ if frame_size is None:
65
+ check(lib.soshi_entity_set_draw_size(self.handle, texture.width, texture.height))
66
+
67
+ if rotation:
68
+ self.set_rotation(rotation)
69
+ if parent is not None:
70
+ self.set_parent(parent)
71
+
72
+ @property
73
+ def pos(self):
74
+ check(lib.soshi_entity_position(self.handle, _position_scratch))
75
+ return (_position_scratch[0], _position_scratch[1])
76
+
77
+ @pos.setter
78
+ def pos(self, value):
79
+ check(lib.soshi_entity_set_position(self.handle, float(value[0]), float(value[1])))
80
+
81
+ def set_velocity(self, velocity):
82
+ check(lib.soshi_entity_set_velocity(self.handle, float(velocity[0]), float(velocity[1])))
83
+
84
+ def set_rotation(self, radians):
85
+ check(lib.soshi_entity_set_rotation(self.handle, float(radians)))
86
+
87
+ def set_size(self, width, height):
88
+ check(lib.soshi_entity_set_draw_size(self.handle, float(width), float(height)))
89
+
90
+ def set_parent(self, parent):
91
+ """Attach to another entity; this entity's position becomes an offset from it."""
92
+ parent_handle = 0 if parent is None else parent.handle
93
+ check(lib.soshi_entity_set_parent(self.handle, parent_handle))
94
+
95
+ def play(self):
96
+ check(lib.soshi_entity_play_animation(self.handle))
97
+
98
+ def stop(self):
99
+ check(lib.soshi_entity_stop_animation(self.handle))
100
+
101
+ def set_frame(self, index):
102
+ check(lib.soshi_entity_set_frame(self.handle, int(index)))
103
+
104
+ def update(self, dt, screen_rect=None):
105
+ """Single-body convenience: sets the bounds, then steps the whole world.
106
+
107
+ Scenes with many entities should call ``soshi.world.step(dt)`` once per frame
108
+ instead of calling this per entity.
109
+ """
110
+ if screen_rect is not None:
111
+ world.set_bounds(screen_rect)
112
+ world.step(dt)
113
+
114
+ def destroy(self):
115
+ check(lib.soshi_entity_destroy(self.handle))
116
+ self.handle = 0
117
+
118
+
119
+ class _World:
120
+ __slots__ = ()
121
+
122
+ def step(self, dt):
123
+ lib.soshi_world_step(float(dt))
124
+
125
+ def set_bounds(self, rect):
126
+ lib.soshi_world_set_bounds(float(rect[0]), float(rect[1]), float(rect[2]), float(rect[3]))
127
+
128
+ def set_gravity(self, value):
129
+ lib.soshi_world_set_gravity(float(value))
130
+
131
+ def set_restitution(self, value):
132
+ lib.soshi_world_set_restitution(float(value))
133
+
134
+ def count(self):
135
+ return int(lib.soshi_world_count())
136
+
137
+ def capacity(self):
138
+ return int(lib.soshi_world_capacity())
139
+
140
+
141
+ world = _World()
soshi/input.py ADDED
@@ -0,0 +1,27 @@
1
+ import ctypes
2
+
3
+ from ._native import check, lib
4
+
5
+ _mouse_scratch = (ctypes.c_float * 2)()
6
+
7
+
8
+ class _Event:
9
+ __slots__ = ()
10
+
11
+ def pump(self):
12
+ """Drain the OS event queue into the engine's input state."""
13
+ lib.soshi_pump_events()
14
+
15
+ def key_pressed(self, keycode):
16
+ return bool(lib.soshi_key_pressed(int(keycode)))
17
+
18
+ def key_released(self, keycode):
19
+ return bool(lib.soshi_key_released(int(keycode)))
20
+
21
+
22
+ event = _Event()
23
+
24
+
25
+ def mouse_pos():
26
+ check(lib.soshi_mouse_position(_mouse_scratch))
27
+ return (_mouse_scratch[0], _mouse_scratch[1])
soshi/render.py ADDED
@@ -0,0 +1,110 @@
1
+ import ctypes
2
+
3
+ from ._native import check, lib, to_rgba
4
+
5
+ RECT_STRIDE = 8
6
+ CIRCLE_STRIDE = 7
7
+
8
+ _BATCH_CAPACITY = 4096
9
+ _SIZE_SCRATCH = (ctypes.c_float * 2)()
10
+
11
+ _rect_buffer = (ctypes.c_float * (RECT_STRIDE * _BATCH_CAPACITY))()
12
+ _circle_buffer = (ctypes.c_float * (CIRCLE_STRIDE * _BATCH_CAPACITY))()
13
+
14
+
15
+ class Surface:
16
+ """The window drawing target; it also carries the current window size."""
17
+
18
+ __slots__ = ("width", "height")
19
+
20
+ def __init__(self, width=0, height=0):
21
+ self.width = width
22
+ self.height = height
23
+
24
+ @property
25
+ def rect(self):
26
+ return (0.0, 0.0, self.width, self.height)
27
+
28
+ def clear(self, color=(0, 0, 0)):
29
+ red, green, blue, alpha = to_rgba(color)
30
+ lib.soshi_clear(int(red), int(green), int(blue), int(alpha))
31
+
32
+
33
+ _surface = Surface()
34
+
35
+
36
+ class _Display:
37
+ __slots__ = ()
38
+
39
+ def get_surface(self):
40
+ check(lib.soshi_display_size(_SIZE_SCRATCH))
41
+ _surface.width = _SIZE_SCRATCH[0]
42
+ _surface.height = _SIZE_SCRATCH[1]
43
+ return _surface
44
+
45
+ def flip(self):
46
+ lib.soshi_present()
47
+
48
+ def set_vsync(self, enabled=True):
49
+ lib.soshi_set_vsync(1 if enabled else 0)
50
+
51
+
52
+ class _Draw:
53
+ __slots__ = ()
54
+
55
+ def rect(self, surface, rect, color):
56
+ self.rects(surface, [(rect[0], rect[1], rect[2], rect[3], color)])
57
+
58
+ def rects(self, surface, items):
59
+ base = 0
60
+ buffered = 0
61
+ for x, y, width, height, color in items:
62
+ red, green, blue, alpha = to_rgba(color)
63
+ _rect_buffer[base + 0] = x
64
+ _rect_buffer[base + 1] = y
65
+ _rect_buffer[base + 2] = width
66
+ _rect_buffer[base + 3] = height
67
+ _rect_buffer[base + 4] = red
68
+ _rect_buffer[base + 5] = green
69
+ _rect_buffer[base + 6] = blue
70
+ _rect_buffer[base + 7] = alpha
71
+ base += RECT_STRIDE
72
+ buffered += 1
73
+ if buffered == _BATCH_CAPACITY:
74
+ lib.soshi_draw_rects(_rect_buffer, buffered)
75
+ base = 0
76
+ buffered = 0
77
+ if buffered:
78
+ lib.soshi_draw_rects(_rect_buffer, buffered)
79
+
80
+ def circle(self, surface, center, radius, color):
81
+ self.circles(surface, [(center[0], center[1], radius, color)])
82
+
83
+ def circles(self, surface, items):
84
+ base = 0
85
+ buffered = 0
86
+ for x, y, radius, color in items:
87
+ red, green, blue, alpha = to_rgba(color)
88
+ _circle_buffer[base + 0] = x
89
+ _circle_buffer[base + 1] = y
90
+ _circle_buffer[base + 2] = radius
91
+ _circle_buffer[base + 3] = red
92
+ _circle_buffer[base + 4] = green
93
+ _circle_buffer[base + 5] = blue
94
+ _circle_buffer[base + 6] = alpha
95
+ base += CIRCLE_STRIDE
96
+ buffered += 1
97
+ if buffered == _BATCH_CAPACITY:
98
+ lib.soshi_draw_circles(_circle_buffer, buffered)
99
+ base = 0
100
+ buffered = 0
101
+ if buffered:
102
+ lib.soshi_draw_circles(_circle_buffer, buffered)
103
+
104
+ def world(self):
105
+ """Draw every entity in one native call."""
106
+ lib.soshi_draw_world()
107
+
108
+
109
+ display = _Display()
110
+ draw = _Draw()
soshi/soshi.dll ADDED
Binary file
soshi/texture.py ADDED
@@ -0,0 +1,31 @@
1
+ """Images and sprite sheets."""
2
+
3
+ import ctypes
4
+
5
+ from ._native import SoshiError, check, last_error, lib
6
+
7
+ _SIZE_SCRATCH = (ctypes.c_float * 2)()
8
+
9
+
10
+ class Texture:
11
+ """A decoded image on the renderer. Load once, reuse for every sprite."""
12
+
13
+ __slots__ = ("handle", "width", "height")
14
+
15
+ def __init__(self, path):
16
+ self.handle = lib.soshi_texture_load(str(path).encode("utf-8"))
17
+ if self.handle == 0:
18
+ raise SoshiError(f"cannot load texture {path}: {last_error()}")
19
+ check(lib.soshi_texture_size(self.handle, _SIZE_SCRATCH))
20
+ self.width = _SIZE_SCRATCH[0]
21
+ self.height = _SIZE_SCRATCH[1]
22
+
23
+ def destroy(self):
24
+ lib.soshi_texture_destroy(self.handle)
25
+ self.handle = 0
26
+
27
+ def __enter__(self):
28
+ return self
29
+
30
+ def __exit__(self, *_exception):
31
+ self.destroy()
soshi/version.py ADDED
@@ -0,0 +1 @@
1
+ __version__ = "0.0.1"
soshi/window.py ADDED
@@ -0,0 +1,27 @@
1
+ from ._native import check, lib
2
+
3
+
4
+ def init(width=800, height=600, title="Soshi"):
5
+ """Open the window and reset the engine world."""
6
+ check(lib.soshi_init(int(width), int(height), str(title).encode("utf-8")))
7
+
8
+
9
+ def quit():
10
+ """Close the window and release SDL."""
11
+ lib.soshi_quit()
12
+
13
+
14
+ def is_running():
15
+ return bool(lib.soshi_is_running())
16
+
17
+
18
+ class Clock:
19
+ """Frame limiter. ``tick()`` sleeps as needed and returns the delta in seconds."""
20
+
21
+ __slots__ = ("fps",)
22
+
23
+ def __init__(self, fps=60):
24
+ self.fps = float(fps)
25
+
26
+ def tick(self):
27
+ return float(lib.soshi_clock_tick(self.fps))
@@ -0,0 +1,249 @@
1
+ Metadata-Version: 2.4
2
+ Name: soshi
3
+ Version: 0.0.1
4
+ Summary: A small, fast 2D game engine for Python with a pygame-shaped API
5
+ Author: HadeShiki
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/HadeShiki/soshi
8
+ Project-URL: Issues, https://github.com/HadeShiki/soshi/issues
9
+ Keywords: game engine,2d,sdl3,pygame,zig
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Programming Language :: C++
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Other
17
+ Classifier: Topic :: Games/Entertainment
18
+ Classifier: Topic :: Multimedia :: Graphics
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # Soshi
25
+
26
+ A small, fast 2D engine for Python with a pygame-shaped API. Game scripts call a native
27
+ shared library through `ctypes`, so nothing is compiled on the player's machine: no C++
28
+ toolchain, no Python headers, and no build per Python version.
29
+
30
+ ```
31
+ Python script -> soshi.dll (C++20 + SDL3) -> soshi_core.lib (Zig 0.17.1)
32
+ ```
33
+
34
+ * C++ owns SDL3: window, renderer, textures, audio, events, clock, draw batches.
35
+ * Zig owns the engine core: math, entity table, physics, animation, scene graph.
36
+ * Only `extern "C"` functions taking plain C types cross the boundary.
37
+
38
+ ## Using it
39
+
40
+ ```
41
+ pip install soshi
42
+ ```
43
+
44
+ ```python
45
+ import soshi
46
+
47
+ soshi.init(width=800, height=600, title="Soshi Demo")
48
+ screen = soshi.display.get_surface()
49
+
50
+ ball = soshi.Entity(pos=(120, 120), vel=(260, 190), radius=24, color=(255, 90, 90))
51
+ clock = soshi.Clock(60)
52
+
53
+ while soshi.running:
54
+ dt = clock.tick()
55
+ soshi.event.pump()
56
+ if soshi.event.key_pressed(soshi.K_ESCAPE):
57
+ break
58
+
59
+ ball.update(dt, screen_rect=screen.rect)
60
+ screen.clear((18, 18, 28))
61
+ soshi.draw.world()
62
+ soshi.display.flip()
63
+
64
+ soshi.quit()
65
+ ```
66
+
67
+ ### Sprites and animation
68
+
69
+ ```python
70
+ sheet = soshi.Texture("assets/sheet.png") # PNG or BMP, loaded once
71
+
72
+ ship = soshi.Entity(pos=(320, 240), texture=sheet, frame_size=(32, 32), frames=1)
73
+ ship.set_size(64, 64) # draw size, physics radius unchanged
74
+
75
+ thruster = soshi.Entity(
76
+ pos=(320, 240 - 46),
77
+ texture=sheet,
78
+ frame_size=(32, 32),
79
+ frames=4, # four frames in the sheet
80
+ fps=10, # animated from spawn
81
+ )
82
+ thruster.set_parent(ship) # follows the ship, including rotation
83
+ ```
84
+
85
+ Entities are drawn as circles while they have no texture and as sprites once they do;
86
+ `draw.world()` batches both (one geometry call for circles, one per texture).
87
+
88
+ ### Audio
89
+
90
+ ```python
91
+ blip = soshi.Sound("assets/blip.wav") # WAV, converted to the device format at load
92
+ soshi.audio.set_volume(0.7)
93
+ blip.play()
94
+ ```
95
+
96
+ ### Manual drawing
97
+
98
+ ```python
99
+ soshi.draw.rect(screen, (10, 10, 200, 40), (60, 64, 92))
100
+ soshi.draw.circle(screen, (400, 300), 30, (255, 80, 80))
101
+ soshi.draw.circles(screen, [(x, y, radius, (120, 200, 255)) for x, y in positions])
102
+ ```
103
+
104
+ ## Frame cost
105
+
106
+ A frame crosses into native code a fixed number of times: `clock.tick()`,
107
+ `event.pump()`, one `world.step()`, one draw call, one `flip()`. Entity and primitive
108
+ counts never add crossings, and nothing allocates per frame.
109
+
110
+ Measured on this machine (Release build, 5000 entities, 800x600, 300 frames, windowed,
111
+ two runs):
112
+
113
+ | stage | ms/frame |
114
+ |---|---|
115
+ | world step (integrate, wall bounce, grid collisions, scene resolve, animation) | 1.7 |
116
+ | draw + present (5000 circles, one geometry call) | 6.2 - 6.5 |
117
+ | CPU total | 7.9 - 8.2 (about 122 - 126 fps) |
118
+
119
+ Headless (`SDL_VIDEODRIVER=dummy`) uses SDL's software rasterizer, so its draw cost is
120
+ not representative of a real window.
121
+
122
+ ## Roadmap
123
+
124
+ | phase | scope | state |
125
+ |---|---|---|
126
+ | 0 | DLL load, window | done |
127
+ | 1 | clear, present, batched rects | done |
128
+ | 2 | events, keys, clock | done |
129
+ | 3 | entities, physics, bouncing ball | done |
130
+ | 4 | circles, textures, sprites | done |
131
+ | 5 | animation, scene graph, audio | done |
132
+ | 6 | wheel, docs, examples | wheel, sdist + PyPI packaging done; multi-platform CI is not |
133
+
134
+ ## Building from source (Windows, verified)
135
+
136
+ Requirements: Visual Studio with the C++ toolset, CMake + Ninja, Zig 0.17.1, and a vcpkg
137
+ checkout at `vcpkg/` with `sdl3:x64-windows` installed.
138
+
139
+ ```
140
+ scripts\build.cmd
141
+ ```
142
+
143
+ Outputs `build/soshi.dll` and copies it with `SDL3.dll` into `python/soshi/`.
144
+ Zig is looked up on `PATH`, then in the WinGet package folder; override with
145
+ `-DZIG_EXECUTABLE=<path to zig.exe>`. Set `VCVARS` to pin a specific `vcvars64.bat`.
146
+
147
+ The Zig core can also be built alone:
148
+
149
+ ```
150
+ zig build-lib src/zig/soshi_core.zig -target native -O ReleaseFast -mcpu=baseline -fstrip -femit-bin=build/soshi_core.lib
151
+ ```
152
+
153
+ Building a wheel (the binaries must already exist in `python/soshi/`):
154
+
155
+ ```
156
+ py -3.12 -m pip wheel . -w dist --no-deps
157
+ ```
158
+
159
+ ## Publishing to PyPI
160
+
161
+ The version lives in one place, `python/soshi/version.py`; the wheel, the sdist and
162
+ `soshi.__version__` all read from it. To cut a release:
163
+
164
+ ```
165
+ py -3.12 -m pip install twine
166
+ scripts\release.cmd
167
+ ```
168
+
169
+ The script builds `dist/soshi-<version>-py3-none-win_amd64.whl` plus the sdist and runs
170
+ `twine check` on both. Upload to TestPyPI with a token first:
171
+
172
+ ```
173
+ py -3.12 -m twine upload --repository testpypi dist/*
174
+ py -3.12 -m pip install --index-url https://test.pypi.org/simple soshi
175
+ ```
176
+
177
+ When that installs and runs, upload for real:
178
+
179
+ ```
180
+ py -3.12 -m twine upload dist/*
181
+ ```
182
+
183
+ Username is `__token__` and the password is the API token, either typed or taken from
184
+ `~/.pypirc`. Notes:
185
+
186
+ * `release.cmd` stops if `python/soshi/soshi.dll` or `SDL3.dll` is missing, and checks
187
+ both artifacts again after the build, because a wheel without the DLLs cannot be
188
+ replaced once it is on PyPI.
189
+ * The name comes from `project.name` in `pyproject.toml` and must be free on PyPI.
190
+ * Every upload needs a new version; PyPI rejects a re-upload of the same file.
191
+ * The wheel is tagged for the platform it was built on (Windows x64 here). The sdist
192
+ carries the same binaries, so it installs without a toolchain on Windows, but a wheel
193
+ per target platform is what other systems need.
194
+ * Do not run `python -m build` from the repository root: the local `build/` output folder
195
+ shadows the `build` package. `scripts\release.cmd` avoids the problem.
196
+
197
+ ## Examples
198
+
199
+ The demo assets are generated, not checked in as binaries of unknown origin:
200
+
201
+ ```
202
+ python scripts/make_assets.py # examples/assets/sheet.png + blip.wav
203
+ ```
204
+
205
+ ```
206
+ set PYTHONPATH=python
207
+ python examples\bouncing_ball.py
208
+ python examples\sprites.py
209
+ python examples\audio.py
210
+ python examples\bench_world.py --entities 5000 --frames 300
211
+ ```
212
+
213
+ Headless smoke tests:
214
+
215
+ ```
216
+ set SDL_VIDEODRIVER=dummy
217
+ set SDL_AUDIODRIVER=dummy
218
+ python examples\bouncing_ball.py --frames 120
219
+ python examples\sprites.py --frames 120
220
+ python examples\audio.py --frames 60
221
+ ```
222
+
223
+ ## Limits
224
+
225
+ * One world per process with 8192 entity slots, all allocated up front.
226
+ * One renderer, 256 texture slots, 64 sound slots, and up to 32 distinct textures drawn per frame.
227
+ * Children inherit position and rotation from their parent; depth is capped at 8 levels.
228
+ * Physics covers gravity, wall bounces, and circle/circle impulses with a grid broad phase.
229
+ Sprites use the same circular body.
230
+ * Sound playback queues on a single output stream: overlapping sounds are not mixed.
231
+ * Verified on Windows only. The C++ layer contains no OS-specific logic beyond a CRT shim
232
+ for `sincosf`, so other platforms need only a rebuild, but they are untested here.
233
+ * Release binaries are stripped: no debug info, no PDB, no Python bytecode.
234
+
235
+ ## Layout
236
+
237
+ ```
238
+ src/zig/ engine core: math, ecs, animation, scene, physics, world, C-ABI exports
239
+ src/cpp/ SDL3 context, texture bank, audio bank, public C API
240
+ python/soshi/ ctypes bridge, the pygame-shaped API and version.py
241
+ examples/ bouncing ball, sprites, audio, benchmark, generated assets
242
+ scripts/ build entry point, asset generator, release script
243
+ pyproject.toml package metadata, build config and PyPI classifiers
244
+ setup.py wheel tag override (the wheel carries native libraries)
245
+ MANIFEST.in what ships in the sdist: sources, scripts, examples
246
+ ```
247
+
248
+ `python/soshi/*.dll` (and any `.so`/`.dylib`) are build outputs: they are not committed,
249
+ they are produced by `scripts\build.cmd` and shipped inside the wheels.
@@ -0,0 +1,16 @@
1
+ soshi/SDL3.dll,sha256=Y62YfKyKESJtVemSzRy3oJU49oPyQLF4eof6fik-LF4,2498048
2
+ soshi/__init__.py,sha256=i1borgRipmsvyeb5PwqNKEvm0oIMzM9XTiHAd5scHBk,969
3
+ soshi/_native.py,sha256=MFOQy4I0tv7c3S8hQRtTfLiQVPCW_RtQp6Y9cos14Dg,6019
4
+ soshi/audio.py,sha256=W3VkJdqJsAFKle1-X8alnaKUOCiTHPT2Myn1FNJSPKE,919
5
+ soshi/entity.py,sha256=HRRPi-ObirsJcNuuofenUYmTCTGz-0lDv4I6j4yqFPU,4272
6
+ soshi/input.py,sha256=iFTV8lG7N7rLeB09Oz2fOJ8QemXi08UkW0gInxkriFc,576
7
+ soshi/render.py,sha256=yUD7xZ4v-vzOlqYRi90sMTYqGjFuYqjpOL_bDsRSJw0,3169
8
+ soshi/soshi.dll,sha256=NtQmh8FpwFoxXHawShUnVmq708RWzOv4kswA_TbD6Qk,978432
9
+ soshi/texture.py,sha256=1oJhRmceetMixM5Op1z5hY9VX7H3Yx_H2WVrqzmB8HY,839
10
+ soshi/version.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
11
+ soshi/window.py,sha256=rg3g5fJ_9ZVDFLl_Y88F_Q6Gu4VbjpVF3I_YebaXSOY,619
12
+ soshi-0.0.1.dist-info/licenses/LICENSE,sha256=Zz-yCxVCpYiALZ1OQRaieKTTA_TElGYl0hgRR2E9iT4,1066
13
+ soshi-0.0.1.dist-info/METADATA,sha256=tmB-NUBcdbNwVkkIN3S_Hr5ioGhN53kiiF9wIg5CUgE,8673
14
+ soshi-0.0.1.dist-info/WHEEL,sha256=79BCzrXBJOa2YV6ugKrK59dqWifMGjAkgVd_6AQrqbU,98
15
+ soshi-0.0.1.dist-info/top_level.txt,sha256=Hum1Waf_E7nzs9qae8dqfCSB-kQCWBioUFrWDXSMYp8,6
16
+ soshi-0.0.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: false
4
+ Tag: py3-none-win_amd64
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HadeShiki
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ soshi