soshi 0.0.1__tar.gz

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.
Files changed (48) hide show
  1. soshi-0.0.1/CMakeLists.txt +61 -0
  2. soshi-0.0.1/LICENSE +21 -0
  3. soshi-0.0.1/MANIFEST.in +17 -0
  4. soshi-0.0.1/PKG-INFO +249 -0
  5. soshi-0.0.1/README.md +226 -0
  6. soshi-0.0.1/examples/assets/blip.wav +0 -0
  7. soshi-0.0.1/examples/assets/sheet.png +0 -0
  8. soshi-0.0.1/examples/audio.py +52 -0
  9. soshi-0.0.1/examples/bench_world.py +61 -0
  10. soshi-0.0.1/examples/bouncing_ball.py +44 -0
  11. soshi-0.0.1/examples/sprites.py +68 -0
  12. soshi-0.0.1/pyproject.toml +40 -0
  13. soshi-0.0.1/python/soshi/SDL3.dll +0 -0
  14. soshi-0.0.1/python/soshi/__init__.py +49 -0
  15. soshi-0.0.1/python/soshi/_native.py +159 -0
  16. soshi-0.0.1/python/soshi/audio.py +40 -0
  17. soshi-0.0.1/python/soshi/entity.py +141 -0
  18. soshi-0.0.1/python/soshi/input.py +27 -0
  19. soshi-0.0.1/python/soshi/render.py +110 -0
  20. soshi-0.0.1/python/soshi/soshi.dll +0 -0
  21. soshi-0.0.1/python/soshi/texture.py +31 -0
  22. soshi-0.0.1/python/soshi/version.py +1 -0
  23. soshi-0.0.1/python/soshi/window.py +27 -0
  24. soshi-0.0.1/python/soshi.egg-info/SOURCES.txt +45 -0
  25. soshi-0.0.1/scripts/build.cmd +27 -0
  26. soshi-0.0.1/scripts/check_release.py +66 -0
  27. soshi-0.0.1/scripts/make_assets.py +81 -0
  28. soshi-0.0.1/scripts/release.cmd +41 -0
  29. soshi-0.0.1/setup.cfg +4 -0
  30. soshi-0.0.1/setup.py +29 -0
  31. soshi-0.0.1/src/cpp/audio_bank.cpp +105 -0
  32. soshi-0.0.1/src/cpp/audio_bank.h +40 -0
  33. soshi-0.0.1/src/cpp/capi.cpp +273 -0
  34. soshi-0.0.1/src/cpp/capi.h +62 -0
  35. soshi-0.0.1/src/cpp/capi_core.h +34 -0
  36. soshi-0.0.1/src/cpp/crt_shim.cpp +12 -0
  37. soshi-0.0.1/src/cpp/handles.h +23 -0
  38. soshi-0.0.1/src/cpp/sdl_context.cpp +392 -0
  39. soshi-0.0.1/src/cpp/sdl_context.h +82 -0
  40. soshi-0.0.1/src/cpp/texture_bank.cpp +69 -0
  41. soshi-0.0.1/src/cpp/texture_bank.h +35 -0
  42. soshi-0.0.1/src/zig/animation.zig +63 -0
  43. soshi-0.0.1/src/zig/ecs.zig +110 -0
  44. soshi-0.0.1/src/zig/math.zig +39 -0
  45. soshi-0.0.1/src/zig/physics.zig +177 -0
  46. soshi-0.0.1/src/zig/scene.zig +51 -0
  47. soshi-0.0.1/src/zig/soshi_core.zig +171 -0
  48. soshi-0.0.1/src/zig/world.zig +57 -0
@@ -0,0 +1,61 @@
1
+ cmake_minimum_required(VERSION 3.24)
2
+
3
+ if(NOT DEFINED CMAKE_TOOLCHAIN_FILE AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake")
4
+ set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
5
+ CACHE FILEPATH "vcpkg toolchain file")
6
+ set(VCPKG_TARGET_TRIPLET x64-windows CACHE STRING "vcpkg triplet")
7
+ endif()
8
+
9
+ project(soshi LANGUAGES CXX)
10
+
11
+ set(CMAKE_CXX_STANDARD 20)
12
+ set(CMAKE_CXX_STANDARD_REQUIRED ON)
13
+ set(CMAKE_CXX_EXTENSIONS OFF)
14
+
15
+ find_package(SDL3 CONFIG REQUIRED)
16
+
17
+ find_program(ZIG_EXECUTABLE NAMES zig)
18
+ if(NOT ZIG_EXECUTABLE)
19
+ file(GLOB ZIG_INSTALLS "$ENV{LOCALAPPDATA}/Microsoft/WinGet/Packages/zig.zig_*/zig-*/zig.exe")
20
+ if(ZIG_INSTALLS)
21
+ list(SORT ZIG_INSTALLS)
22
+ list(GET ZIG_INSTALLS -1 ZIG_EXECUTABLE)
23
+ endif()
24
+ endif()
25
+ if(NOT ZIG_EXECUTABLE)
26
+ message(FATAL_ERROR "zig not found: install Zig or configure with -DZIG_EXECUTABLE=<path to zig.exe>")
27
+ endif()
28
+
29
+ file(GLOB ZIG_SOURCES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/zig/*.zig")
30
+ set(SOSHI_CORE_LIBRARY "${CMAKE_CURRENT_BINARY_DIR}/soshi_core.lib")
31
+
32
+ add_custom_command(
33
+ OUTPUT "${SOSHI_CORE_LIBRARY}"
34
+ COMMAND "${ZIG_EXECUTABLE}" build-lib "${CMAKE_CURRENT_SOURCE_DIR}/src/zig/soshi_core.zig"
35
+ -target native -O ReleaseFast -mcpu=baseline -fstrip -femit-bin=${SOSHI_CORE_LIBRARY}
36
+ DEPENDS ${ZIG_SOURCES}
37
+ COMMENT "Compiling soshi_core.lib with Zig"
38
+ VERBATIM)
39
+
40
+ add_custom_target(soshi_core DEPENDS "${SOSHI_CORE_LIBRARY}")
41
+
42
+ add_library(soshi SHARED
43
+ src/cpp/audio_bank.cpp
44
+ src/cpp/capi.cpp
45
+ src/cpp/crt_shim.cpp
46
+ src/cpp/sdl_context.cpp
47
+ src/cpp/texture_bank.cpp)
48
+
49
+ add_dependencies(soshi soshi_core)
50
+ target_link_libraries(soshi PRIVATE SDL3::SDL3 "${SOSHI_CORE_LIBRARY}")
51
+
52
+ set_target_properties(soshi PROPERTIES
53
+ PREFIX ""
54
+ OUTPUT_NAME "soshi")
55
+
56
+ set(SOSHI_PYTHON_DIR "${CMAKE_CURRENT_SOURCE_DIR}/python/soshi")
57
+ add_custom_command(TARGET soshi POST_BUILD
58
+ COMMAND ${CMAKE_COMMAND} -E make_directory "${SOSHI_PYTHON_DIR}"
59
+ COMMAND ${CMAKE_COMMAND} -E copy_if_different "$<TARGET_FILE:soshi>" "${SOSHI_PYTHON_DIR}"
60
+ COMMAND ${CMAKE_COMMAND} -E copy_if_different $<TARGET_RUNTIME_DLLS:soshi> "${SOSHI_PYTHON_DIR}"
61
+ COMMAND_EXPAND_LISTS)
soshi-0.0.1/LICENSE ADDED
@@ -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,17 @@
1
+ include CMakeLists.txt
2
+ include LICENSE
3
+ include README.md
4
+
5
+ recursive-include src *.cpp *.h *.zig
6
+ recursive-include scripts *.cmd *.py
7
+ recursive-include examples *.py
8
+ recursive-include examples/assets *.png *.wav
9
+
10
+ prune build
11
+ prune dist
12
+ prune python/soshi.egg-info
13
+ prune vcpkg
14
+ prune .zig-cache
15
+
16
+ global-exclude *.py[cod]
17
+ global-exclude .DS_Store
soshi-0.0.1/PKG-INFO ADDED
@@ -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.
soshi-0.0.1/README.md ADDED
@@ -0,0 +1,226 @@
1
+ # Soshi
2
+
3
+ A small, fast 2D engine for Python with a pygame-shaped API. Game scripts call a native
4
+ shared library through `ctypes`, so nothing is compiled on the player's machine: no C++
5
+ toolchain, no Python headers, and no build per Python version.
6
+
7
+ ```
8
+ Python script -> soshi.dll (C++20 + SDL3) -> soshi_core.lib (Zig 0.17.1)
9
+ ```
10
+
11
+ * C++ owns SDL3: window, renderer, textures, audio, events, clock, draw batches.
12
+ * Zig owns the engine core: math, entity table, physics, animation, scene graph.
13
+ * Only `extern "C"` functions taking plain C types cross the boundary.
14
+
15
+ ## Using it
16
+
17
+ ```
18
+ pip install soshi
19
+ ```
20
+
21
+ ```python
22
+ import soshi
23
+
24
+ soshi.init(width=800, height=600, title="Soshi Demo")
25
+ screen = soshi.display.get_surface()
26
+
27
+ ball = soshi.Entity(pos=(120, 120), vel=(260, 190), radius=24, color=(255, 90, 90))
28
+ clock = soshi.Clock(60)
29
+
30
+ while soshi.running:
31
+ dt = clock.tick()
32
+ soshi.event.pump()
33
+ if soshi.event.key_pressed(soshi.K_ESCAPE):
34
+ break
35
+
36
+ ball.update(dt, screen_rect=screen.rect)
37
+ screen.clear((18, 18, 28))
38
+ soshi.draw.world()
39
+ soshi.display.flip()
40
+
41
+ soshi.quit()
42
+ ```
43
+
44
+ ### Sprites and animation
45
+
46
+ ```python
47
+ sheet = soshi.Texture("assets/sheet.png") # PNG or BMP, loaded once
48
+
49
+ ship = soshi.Entity(pos=(320, 240), texture=sheet, frame_size=(32, 32), frames=1)
50
+ ship.set_size(64, 64) # draw size, physics radius unchanged
51
+
52
+ thruster = soshi.Entity(
53
+ pos=(320, 240 - 46),
54
+ texture=sheet,
55
+ frame_size=(32, 32),
56
+ frames=4, # four frames in the sheet
57
+ fps=10, # animated from spawn
58
+ )
59
+ thruster.set_parent(ship) # follows the ship, including rotation
60
+ ```
61
+
62
+ Entities are drawn as circles while they have no texture and as sprites once they do;
63
+ `draw.world()` batches both (one geometry call for circles, one per texture).
64
+
65
+ ### Audio
66
+
67
+ ```python
68
+ blip = soshi.Sound("assets/blip.wav") # WAV, converted to the device format at load
69
+ soshi.audio.set_volume(0.7)
70
+ blip.play()
71
+ ```
72
+
73
+ ### Manual drawing
74
+
75
+ ```python
76
+ soshi.draw.rect(screen, (10, 10, 200, 40), (60, 64, 92))
77
+ soshi.draw.circle(screen, (400, 300), 30, (255, 80, 80))
78
+ soshi.draw.circles(screen, [(x, y, radius, (120, 200, 255)) for x, y in positions])
79
+ ```
80
+
81
+ ## Frame cost
82
+
83
+ A frame crosses into native code a fixed number of times: `clock.tick()`,
84
+ `event.pump()`, one `world.step()`, one draw call, one `flip()`. Entity and primitive
85
+ counts never add crossings, and nothing allocates per frame.
86
+
87
+ Measured on this machine (Release build, 5000 entities, 800x600, 300 frames, windowed,
88
+ two runs):
89
+
90
+ | stage | ms/frame |
91
+ |---|---|
92
+ | world step (integrate, wall bounce, grid collisions, scene resolve, animation) | 1.7 |
93
+ | draw + present (5000 circles, one geometry call) | 6.2 - 6.5 |
94
+ | CPU total | 7.9 - 8.2 (about 122 - 126 fps) |
95
+
96
+ Headless (`SDL_VIDEODRIVER=dummy`) uses SDL's software rasterizer, so its draw cost is
97
+ not representative of a real window.
98
+
99
+ ## Roadmap
100
+
101
+ | phase | scope | state |
102
+ |---|---|---|
103
+ | 0 | DLL load, window | done |
104
+ | 1 | clear, present, batched rects | done |
105
+ | 2 | events, keys, clock | done |
106
+ | 3 | entities, physics, bouncing ball | done |
107
+ | 4 | circles, textures, sprites | done |
108
+ | 5 | animation, scene graph, audio | done |
109
+ | 6 | wheel, docs, examples | wheel, sdist + PyPI packaging done; multi-platform CI is not |
110
+
111
+ ## Building from source (Windows, verified)
112
+
113
+ Requirements: Visual Studio with the C++ toolset, CMake + Ninja, Zig 0.17.1, and a vcpkg
114
+ checkout at `vcpkg/` with `sdl3:x64-windows` installed.
115
+
116
+ ```
117
+ scripts\build.cmd
118
+ ```
119
+
120
+ Outputs `build/soshi.dll` and copies it with `SDL3.dll` into `python/soshi/`.
121
+ Zig is looked up on `PATH`, then in the WinGet package folder; override with
122
+ `-DZIG_EXECUTABLE=<path to zig.exe>`. Set `VCVARS` to pin a specific `vcvars64.bat`.
123
+
124
+ The Zig core can also be built alone:
125
+
126
+ ```
127
+ zig build-lib src/zig/soshi_core.zig -target native -O ReleaseFast -mcpu=baseline -fstrip -femit-bin=build/soshi_core.lib
128
+ ```
129
+
130
+ Building a wheel (the binaries must already exist in `python/soshi/`):
131
+
132
+ ```
133
+ py -3.12 -m pip wheel . -w dist --no-deps
134
+ ```
135
+
136
+ ## Publishing to PyPI
137
+
138
+ The version lives in one place, `python/soshi/version.py`; the wheel, the sdist and
139
+ `soshi.__version__` all read from it. To cut a release:
140
+
141
+ ```
142
+ py -3.12 -m pip install twine
143
+ scripts\release.cmd
144
+ ```
145
+
146
+ The script builds `dist/soshi-<version>-py3-none-win_amd64.whl` plus the sdist and runs
147
+ `twine check` on both. Upload to TestPyPI with a token first:
148
+
149
+ ```
150
+ py -3.12 -m twine upload --repository testpypi dist/*
151
+ py -3.12 -m pip install --index-url https://test.pypi.org/simple soshi
152
+ ```
153
+
154
+ When that installs and runs, upload for real:
155
+
156
+ ```
157
+ py -3.12 -m twine upload dist/*
158
+ ```
159
+
160
+ Username is `__token__` and the password is the API token, either typed or taken from
161
+ `~/.pypirc`. Notes:
162
+
163
+ * `release.cmd` stops if `python/soshi/soshi.dll` or `SDL3.dll` is missing, and checks
164
+ both artifacts again after the build, because a wheel without the DLLs cannot be
165
+ replaced once it is on PyPI.
166
+ * The name comes from `project.name` in `pyproject.toml` and must be free on PyPI.
167
+ * Every upload needs a new version; PyPI rejects a re-upload of the same file.
168
+ * The wheel is tagged for the platform it was built on (Windows x64 here). The sdist
169
+ carries the same binaries, so it installs without a toolchain on Windows, but a wheel
170
+ per target platform is what other systems need.
171
+ * Do not run `python -m build` from the repository root: the local `build/` output folder
172
+ shadows the `build` package. `scripts\release.cmd` avoids the problem.
173
+
174
+ ## Examples
175
+
176
+ The demo assets are generated, not checked in as binaries of unknown origin:
177
+
178
+ ```
179
+ python scripts/make_assets.py # examples/assets/sheet.png + blip.wav
180
+ ```
181
+
182
+ ```
183
+ set PYTHONPATH=python
184
+ python examples\bouncing_ball.py
185
+ python examples\sprites.py
186
+ python examples\audio.py
187
+ python examples\bench_world.py --entities 5000 --frames 300
188
+ ```
189
+
190
+ Headless smoke tests:
191
+
192
+ ```
193
+ set SDL_VIDEODRIVER=dummy
194
+ set SDL_AUDIODRIVER=dummy
195
+ python examples\bouncing_ball.py --frames 120
196
+ python examples\sprites.py --frames 120
197
+ python examples\audio.py --frames 60
198
+ ```
199
+
200
+ ## Limits
201
+
202
+ * One world per process with 8192 entity slots, all allocated up front.
203
+ * One renderer, 256 texture slots, 64 sound slots, and up to 32 distinct textures drawn per frame.
204
+ * Children inherit position and rotation from their parent; depth is capped at 8 levels.
205
+ * Physics covers gravity, wall bounces, and circle/circle impulses with a grid broad phase.
206
+ Sprites use the same circular body.
207
+ * Sound playback queues on a single output stream: overlapping sounds are not mixed.
208
+ * Verified on Windows only. The C++ layer contains no OS-specific logic beyond a CRT shim
209
+ for `sincosf`, so other platforms need only a rebuild, but they are untested here.
210
+ * Release binaries are stripped: no debug info, no PDB, no Python bytecode.
211
+
212
+ ## Layout
213
+
214
+ ```
215
+ src/zig/ engine core: math, ecs, animation, scene, physics, world, C-ABI exports
216
+ src/cpp/ SDL3 context, texture bank, audio bank, public C API
217
+ python/soshi/ ctypes bridge, the pygame-shaped API and version.py
218
+ examples/ bouncing ball, sprites, audio, benchmark, generated assets
219
+ scripts/ build entry point, asset generator, release script
220
+ pyproject.toml package metadata, build config and PyPI classifiers
221
+ setup.py wheel tag override (the wheel carries native libraries)
222
+ MANIFEST.in what ships in the sdist: sources, scripts, examples
223
+ ```
224
+
225
+ `python/soshi/*.dll` (and any `.so`/`.dylib`) are build outputs: they are not committed,
226
+ they are produced by `scripts\build.cmd` and shipped inside the wheels.
Binary file
Binary file
@@ -0,0 +1,52 @@
1
+ """Audio: a queued WAV blip on a timer and on SPACE."""
2
+
3
+ import argparse
4
+ import pathlib
5
+
6
+ import soshi
7
+
8
+ ASSETS = pathlib.Path(__file__).with_name("assets")
9
+
10
+
11
+ def main():
12
+ parser = argparse.ArgumentParser(description="Soshi audio demo")
13
+ parser.add_argument("--frames", type=int, default=0, help="stop after N frames (smoke tests)")
14
+ arguments = parser.parse_args()
15
+
16
+ soshi.init(width=480, height=320, title="Soshi audio")
17
+ screen = soshi.display.get_surface()
18
+
19
+ blip = soshi.Sound(ASSETS / "blip.wav")
20
+ soshi.audio.set_volume(0.7)
21
+
22
+ clock = soshi.Clock(60)
23
+ since_play = 0.0
24
+ plays = 0
25
+ frames = 0
26
+
27
+ while soshi.running:
28
+ dt = clock.tick()
29
+ soshi.event.pump()
30
+ if soshi.event.key_pressed(soshi.K_ESCAPE):
31
+ break
32
+
33
+ since_play += dt
34
+ if since_play >= 0.5 or soshi.event.key_released(soshi.K_SPACE):
35
+ since_play = 0.0
36
+ blip.play()
37
+ plays += 1
38
+
39
+ screen.clear((16, 14, 22))
40
+ soshi.draw.circle(screen, (screen.width / 2, screen.height / 2), 40 + plays % 24, (240, 180, 90))
41
+ soshi.display.flip()
42
+
43
+ frames += 1
44
+ if arguments.frames and frames >= arguments.frames:
45
+ break
46
+
47
+ print(f"ran {frames} frames, played {plays} blips, audio available: {soshi.audio.available()}")
48
+ soshi.quit()
49
+
50
+
51
+ if __name__ == "__main__":
52
+ main()
@@ -0,0 +1,61 @@
1
+ """Measure step and draw cost for a crowded world."""
2
+
3
+ import argparse
4
+ import random
5
+ import time
6
+
7
+ import soshi
8
+
9
+
10
+ def main():
11
+ parser = argparse.ArgumentParser(description="Soshi world benchmark")
12
+ parser.add_argument("--entities", type=int, default=5000)
13
+ parser.add_argument("--frames", type=int, default=300)
14
+ parser.add_argument("--gravity", type=float, default=0.0)
15
+ arguments = parser.parse_args()
16
+
17
+ soshi.init(width=800, height=600, title="Soshi bench")
18
+ soshi.display.set_vsync(False)
19
+ screen = soshi.display.get_surface()
20
+
21
+ soshi.world.set_bounds((0.0, 0.0, screen.width, screen.height))
22
+ soshi.world.set_gravity(arguments.gravity)
23
+
24
+ random.seed(7)
25
+ for _ in range(arguments.entities):
26
+ soshi.Entity(
27
+ pos=(random.uniform(20.0, screen.width - 20.0), random.uniform(20.0, screen.height - 20.0)),
28
+ vel=(random.uniform(-90.0, 90.0), random.uniform(-90.0, 90.0)),
29
+ radius=random.uniform(3.0, 9.0),
30
+ color=(120, 200, 255),
31
+ )
32
+
33
+ dt = 1.0 / 60.0
34
+ step_seconds = 0.0
35
+ draw_seconds = 0.0
36
+
37
+ for _ in range(arguments.frames):
38
+ started = time.perf_counter()
39
+ soshi.world.step(dt)
40
+ stepped = time.perf_counter()
41
+
42
+ screen.clear((10, 10, 16))
43
+ soshi.draw.world()
44
+ soshi.display.flip()
45
+ draw_seconds += time.perf_counter() - stepped
46
+ step_seconds += stepped - started
47
+
48
+ frames = arguments.frames
49
+ total = step_seconds + draw_seconds
50
+ print(f"entities : {soshi.world.count()}")
51
+ print(f"frames : {frames}")
52
+ print(f"step : {step_seconds / frames * 1000:.3f} ms/frame")
53
+ print(f"draw+present : {draw_seconds / frames * 1000:.3f} ms/frame")
54
+ print(f"cpu frame : {total / frames * 1000:.3f} ms")
55
+ print(f"cpu fps : {frames / total:.0f}")
56
+
57
+ soshi.quit()
58
+
59
+
60
+ if __name__ == "__main__":
61
+ main()