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.
- soshi-0.0.1/CMakeLists.txt +61 -0
- soshi-0.0.1/LICENSE +21 -0
- soshi-0.0.1/MANIFEST.in +17 -0
- soshi-0.0.1/PKG-INFO +249 -0
- soshi-0.0.1/README.md +226 -0
- soshi-0.0.1/examples/assets/blip.wav +0 -0
- soshi-0.0.1/examples/assets/sheet.png +0 -0
- soshi-0.0.1/examples/audio.py +52 -0
- soshi-0.0.1/examples/bench_world.py +61 -0
- soshi-0.0.1/examples/bouncing_ball.py +44 -0
- soshi-0.0.1/examples/sprites.py +68 -0
- soshi-0.0.1/pyproject.toml +40 -0
- soshi-0.0.1/python/soshi/SDL3.dll +0 -0
- soshi-0.0.1/python/soshi/__init__.py +49 -0
- soshi-0.0.1/python/soshi/_native.py +159 -0
- soshi-0.0.1/python/soshi/audio.py +40 -0
- soshi-0.0.1/python/soshi/entity.py +141 -0
- soshi-0.0.1/python/soshi/input.py +27 -0
- soshi-0.0.1/python/soshi/render.py +110 -0
- soshi-0.0.1/python/soshi/soshi.dll +0 -0
- soshi-0.0.1/python/soshi/texture.py +31 -0
- soshi-0.0.1/python/soshi/version.py +1 -0
- soshi-0.0.1/python/soshi/window.py +27 -0
- soshi-0.0.1/python/soshi.egg-info/SOURCES.txt +45 -0
- soshi-0.0.1/scripts/build.cmd +27 -0
- soshi-0.0.1/scripts/check_release.py +66 -0
- soshi-0.0.1/scripts/make_assets.py +81 -0
- soshi-0.0.1/scripts/release.cmd +41 -0
- soshi-0.0.1/setup.cfg +4 -0
- soshi-0.0.1/setup.py +29 -0
- soshi-0.0.1/src/cpp/audio_bank.cpp +105 -0
- soshi-0.0.1/src/cpp/audio_bank.h +40 -0
- soshi-0.0.1/src/cpp/capi.cpp +273 -0
- soshi-0.0.1/src/cpp/capi.h +62 -0
- soshi-0.0.1/src/cpp/capi_core.h +34 -0
- soshi-0.0.1/src/cpp/crt_shim.cpp +12 -0
- soshi-0.0.1/src/cpp/handles.h +23 -0
- soshi-0.0.1/src/cpp/sdl_context.cpp +392 -0
- soshi-0.0.1/src/cpp/sdl_context.h +82 -0
- soshi-0.0.1/src/cpp/texture_bank.cpp +69 -0
- soshi-0.0.1/src/cpp/texture_bank.h +35 -0
- soshi-0.0.1/src/zig/animation.zig +63 -0
- soshi-0.0.1/src/zig/ecs.zig +110 -0
- soshi-0.0.1/src/zig/math.zig +39 -0
- soshi-0.0.1/src/zig/physics.zig +177 -0
- soshi-0.0.1/src/zig/scene.zig +51 -0
- soshi-0.0.1/src/zig/soshi_core.zig +171 -0
- 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.
|
soshi-0.0.1/MANIFEST.in
ADDED
|
@@ -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()
|