|
1 |
| -# DISCONTINUED: please, refer to <a href="https://github.com/overdev/raylibpyctbg">raylibpyctbgh</a> for a possibly better alternative</h1> |
| 1 | + |
2 | 2 |
|
3 | 3 | <img align="left" src="https://github.com/overdev/raylib-py/blob/master/logo/raylib-py_256x256.png" width=256>
|
4 | 4 |
|
|
8 | 8 | [](https://pepy.tech/project/raylib-py)
|
9 | 9 | A python binding for the great _C_ library **[raylib](https://github.com/raysan5/raylib)**.
|
10 | 10 |
|
11 |
| -## Getting Started |
12 |
| -<!-- |
13 |
| -These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system. |
14 |
| ---> |
15 |
| -### Prerequisites |
16 |
| - |
17 |
| -_raylib-py_ uses type [annotations](https://www.python.org/dev/peps/pep-3107/#id30) in its source, so a Python version that supports it is required. |
18 |
| - |
19 |
| -Some Python versions may not have [enum](https://pypi.org/project/enum/) and/or [typings](https://pypi.org/project/typing/) modules as part of the standard library, wich are required. These are installed automatically by pip. |
20 |
| - |
21 |
| -### Installing |
22 |
| - |
23 |
| -The easiest way to install _raylib-py_ is by the pip install command: |
24 |
| - |
25 |
| -Depending on you system and python version(s) installed, the command might be: |
26 |
| - |
27 |
| -``` |
28 |
| -pip install raylib-py |
29 |
| -``` |
30 |
| - |
31 |
| -or |
32 |
| - |
33 |
| -``` |
34 |
| -python -m pip install raylib-py |
35 |
| -``` |
36 |
| - |
37 |
| -or (with Python3.7 launcher with multiple versions installed) |
38 |
| - |
39 |
| -``` |
40 |
| -py-3.x-32 -m pip install raylib-py |
41 |
| -``` |
42 |
| - |
43 |
| -> Note that the minimum Python version tested is 3.4. Please, let me know if you're able to run it in Python33. |
44 |
| -
|
45 |
| -_raylib-py_ comes with 32bit binaries for Windows, Mac and Linux, but you're not required to use these. If you have a custom _raylib_ _**dll**_, _**dylib**_ or _**so**_ binary, make sure to set a PATH indicating the directory it is located: |
46 |
| - |
47 |
| -```python |
48 |
| -import os |
49 |
| - |
50 |
| -# set the path before raylib is imported. |
51 |
| -os.environ["RAYLIB_BIN_PATH"] = "path/to/the/binary" |
52 |
| - |
53 |
| -import raylibpy |
54 |
| - |
55 |
| -# let the fun begin. |
56 |
| -``` |
57 |
| - |
58 |
| -You can set `"__file__"` as value to `"RAYLIB_BIN_PATH"` and _raylib-py_ will search for the binary in the package dir: |
59 |
| - |
60 |
| -```python |
61 |
| -# bynary file is wherever the package is located. |
62 |
| -os.environ["RAYLIB_BIN_PATH"] = "__file__" |
63 |
| -``` |
64 |
| - |
65 |
| -`"__main__"` can also be set to look for the binary in the project's directory where the starting script is located: |
66 |
| - |
67 |
| -```python |
68 |
| -# binary file is in the same dir as this py file. |
69 |
| -os.environ["RAYLIB_BIN_PATH"] = "__main__" |
70 |
| - |
71 |
| -# ... |
72 |
| - |
73 |
| -if __name__ == "__main__": |
74 |
| - # run the game |
75 |
| - # ... |
76 |
| -``` |
77 |
| - |
78 |
| -> Make sure the bin file name for the respective platform is `libraylib_shared.dll`, `libraylib.2.0.0.dylib` or `libraylib.so.2.0.0`. |
79 |
| -
|
80 |
| -## Tests |
81 |
| - |
82 |
| -_raylib-py_ does not have test code, but you can run the examples in the [examples directory](https://github.com/overdev/raylib-py/tree/master/examples). |
83 |
| - |
84 |
| -<!-- |
85 |
| -### Break down into end to end tests |
86 |
| -
|
87 |
| -Explain what these tests test and why |
88 |
| -
|
89 |
| -``` |
90 |
| -Give an example |
91 |
| -``` |
92 |
| -
|
93 |
| -### And coding style tests |
94 |
| -
|
95 |
| -Explain what these tests test and why |
96 |
| -
|
97 |
| -``` |
98 |
| -Give an example |
99 |
| -``` |
100 |
| -
|
101 |
| -## Deployment |
102 |
| -
|
103 |
| -Add additional notes about how to deploy this on a live system |
104 |
| -
|
105 |
| ---> |
106 |
| - |
107 |
| -## _raylib_ vs _raylib-py_ |
108 |
| - |
109 |
| -Below are the differences in usage between _raylib_ and _raylib-py_. Note, though that these differences are being worked to make _raylib-py_ as pythonic as possible, so changes may occur without notification. |
110 |
| - |
111 |
| -### Constant values |
112 |
| - |
113 |
| -All C `#define`s got translated to Python 'constants'. Enums got translated to |
114 |
| -Python [enums](https://docs.python.org/3/library/enum.html). |
115 |
| - |
116 |
| -### Structures |
117 |
| - |
118 |
| -In general, all structures inherit from `ctypes.Structure` class. At the moment, constructors |
119 |
| -(except for vectors) require the exact argument types, so `int`s can't be passed |
120 |
| -where `float`s are expected (although the argument can be omitted). |
121 |
| - |
122 |
| -All structures have `__str__()` implemented, so they have a very basic textual representation: |
123 |
| -```python |
124 |
| -# Define the camera to look into our 3d world |
125 |
| ->>> camera = Camera() |
126 |
| ->>> camera.position = Vector3(5., 4., 5.) |
127 |
| ->>> camera.target = Vector3(0., 2., 0.) |
128 |
| ->>> camera.up = Vector3(0., 1., 0.) |
129 |
| ->>> camera.fovy = 45.0 |
130 |
| ->>> camera.type = CAMERA_PERSPECTIVE |
131 |
| ->>> camera |
132 |
| -"(CAMERA3D: position: (5.0, 4.0, 5.0), target: (0.0, 2.0, 0.0), up: (0.0, 1.0, 0.0), fovy: 45.0°, type: PERSPECTIVE)" |
133 |
| -``` |
134 |
| -Not all information is exposed, though. Mesh objects, for example, exposes only the |
135 |
| -vertex and triangle count attributes. |
136 |
| - |
137 |
| - |
138 |
| -#### Vectors |
139 |
| - |
140 |
| -Vector2, Vector3 and Vector4 support basic aritmetic operations: addiction, subtraction, |
141 |
| -multiplication (incluiding scalar multiplication), division and modulo. Augmented |
142 |
| -assignment is also supported; the right hand side operand can be any sequence of same |
143 |
| -number of components: |
144 |
| - |
145 |
| -```python |
146 |
| -vec_a = Vector3(3., 5., 7.) |
147 |
| -vec_b = Vector3(4., 2., 0.) |
148 |
| -vec_a * vec_b # outputs (12.0, 10.0, 0.0) |
149 |
| -vec_a + (8, 100, -1) # outputs (11.0, 105.0, 6.0) |
150 |
| -vec_a %= 2 # augmented assignment (modulo) |
151 |
| -vec_a # outputs (1.0, 1.0, 0.0) |
152 |
| -``` |
153 |
| - |
154 |
| -Vectors also support GLSL vector swizzling. Also, `x`, `y`, `z` and `w` coordinates maps to |
155 |
| -normalized color values (`r`, `g`, `b` and `a`; only for `Vector3` and `Vector4`) and |
156 |
| -texture coordinates (`u` and `v`): |
157 |
| - |
158 |
| -```python |
159 |
| -# Reading (__getattr__) |
160 |
| -vec3 = Vector3(123.0, 467.0, 789.0) |
161 |
| -vec2 = vec3.uv # x and y respectively as u and v |
162 |
| -vec3 = vec3.bgr # x, y and z respectively as r, g and b ( rgb is not available in Vector 2) |
163 |
| -vec4 = vec2.rrrg # for attribute reading, is ok to repeat components |
164 |
| - |
165 |
| -# Writing (__setattr__) |
166 |
| -vec3 = Vector3(123.0, 467.0, 789.0) |
167 |
| -vec4.yxwz = 10, 0, -1, vec3.z # sequences of ints and/or floats are accepted as value |
168 |
| -vec2.vu = vec3.xy # x and y respectively as u and v |
169 |
| -vec3.bgr = 12, vec4.x # x, y and z respectively as r, g and b ( rgb is not available in Vector 2) |
170 |
| - |
171 |
| -# the following raises an exception: |
172 |
| -vec3.rrr = vec4.yxw # for attribute writing, is _not_ ok to repeat components |
173 |
| -vec2.br = vec4.uv # r, g and b is not available in Vector2 |
174 |
| -vec4.brxy = (0., 0., vec2.x, vec3.z) # can't mix component name groups (rgba, xywz and uv) |
175 |
| -``` |
176 |
| - |
177 |
| -Constructors and swizzled attributes now accept any combination of numbers, |
178 |
| -vectors and sequences, as long as the total number of arguments are preserved: |
179 |
| -```python |
180 |
| -# all these results in the same Vector4 |
181 |
| -a = Vector4(3, 4, 5, 6) |
182 |
| -b = Vector4(a.xy, 5, 6) |
183 |
| -c = Vector4(b.x, b.yz, 6) |
184 |
| -d = Vector4(3, c.y, c.zw) |
185 |
| -e = Vector4(d.xy, (5, 6)) |
186 |
| -f = Vector4(e.xyz, 6) |
187 |
| -g = Vector4(3, f.yzw) |
188 |
| -h = Vector4(g) |
189 |
| -``` |
190 |
| - |
191 |
| -Setting attributes also works: |
192 |
| - |
193 |
| -```python |
194 |
| -a = Vector4(Vector2(10, 0), 100, 20) |
195 |
| -b = Vector4.zero() |
196 |
| -b.rgba = 0.0, vec4.rg, 1.0 |
197 |
| -a.xyzw = (10, b.uv), 1.0 |
198 |
| -``` |
199 |
| - |
200 |
| -This became available by dropping a previous feature wich allowed for a very basic |
201 |
| -swizzling emulation. A feature more similar to GLSL vectors is implemented on |
202 |
| -top of Python container emulation magic functions: |
203 |
| - |
204 |
| -```python |
205 |
| -vec = Vector4(0., 1., 2., 3.) |
206 |
| - |
207 |
| -# __len__() |
208 |
| -print(len(vec)) # outputs 4 |
209 |
| - |
210 |
| -# __iter__() |
211 |
| -for comp in vec: |
212 |
| - print(comp) # iterates on Vector4 components |
213 |
| - |
214 |
| -# __getitem__() |
215 |
| -x = vec[0] # key as int |
216 |
| -y = vec['y'] # key as str |
217 |
| -zw = vec[2:] # key as slice; returns a List[float] |
218 |
| - |
219 |
| -# __setitem__() |
220 |
| -vec[0] = 10 |
221 |
| -vec['y'] = 20 |
222 |
| -# vec[2:] = zw # <--- not supported; will raise TypeError |
223 |
| -``` |
224 |
| - |
225 |
| -## Additional (feature) draw function: `draw_texture_npatch` |
226 |
| - |
227 |
| -The custom DLL installed by _raylib-py_ includes an not yet official drawing function and |
228 |
| -corresponding `NPatchInfo` helper structure: |
229 |
| - |
230 |
| -```python |
231 |
| -# draws an 3-patch (vertical, or horizontal) or 9-patch textured that stretches and |
232 |
| -# shrinks nicely. |
233 |
| -# Seq means any sequence type |
234 |
| -def draw_texture_npatch(texture: Texture2D, npatch_info: NPatchInfo, |
235 |
| - dest_rec: Union[Rectangle, Seq], origin: Union[Vector2, Seq], |
236 |
| - rotation: float, tint: Union[Color, Seq]) -> None: |
237 |
| -``` |
238 |
| - |
239 |
| -At the moment (after _raylib_ v2.0.0), only the x86 custom DLL contains this function |
240 |
| -and, to enabled it, an specific `os.environ` key must be set: |
241 |
| - |
242 |
| -```python |
243 |
| -# set this before importing raylibpy (the value does not matter as long is a str type) |
244 |
| -os.environ['ENABLE_V2_0_0_FEATURE_DRAWTEXTURENPATCH'] = '1' |
245 |
| -``` |
246 |
| - |
247 |
| -## Building _raylib_ from source |
248 |
| - |
249 |
| -_raylib_ wiki pages contains information on how to build it on [Windows](https://github.com/raysan5/raylib/wiki/Working-on-Windows), [Mac](https://github.com/raysan5/raylib/wiki/Working-on-macOS), [Linux](https://github.com/raysan5/raylib/wiki/Working-on-GNU-Linux) and other platforms. |
250 |
| - |
251 |
| -## Contributing |
252 |
| - |
253 |
| -Please, let me know if you find any strange or unexpected behavior while using _raylib-py_. If you want to [request features](https://github.com/raysan5/raylib/pulls) or [report bugs](https://github.com/raysan5/raylib/issues) related to the library (in contrast to this binding), please refer to the [author's project repo](https://github.com/raysan5/raylib). |
254 |
| - |
255 |
| -## Authors |
256 |
| - |
257 |
| -* **Ramon Santamaria** - *raylib's author* - [raysan5](https://github.com/raysan5) |
258 |
| -* **Jorge A. Gomes** - *python binding code* - [overdev](https://github.com/overdev) |
259 |
| - |
260 |
| -See also the list of [contributors](https://github.com/raysan5/raylib/graphs/contributors) who participated in this project. |
261 |
| - |
262 |
| -## License |
263 |
| - |
264 |
| -_raylib-py_ (and _raylib_) is licensed under an unmodified zlib/libpng license, which is an OSI-certified, BSD-like license that allows static linking with closed source software. |
265 | 11 |
|
266 |
| -<!-- |
267 |
| -## Acknowledgments |
| 12 | +# WARNING: This project is in a semi discontinued state. |
268 | 13 |
|
269 |
| -* Hat tip to anyone whose code was used |
270 |
| -* Inspiration |
271 |
| -* etc |
272 |
| ---> |
| 14 | +Plase, read this [issue](https://github.com/overdev/raylib-py/issues/45) for more information. |
273 | 15 |
|
| 16 | +I intend to use this repository only to make new package distribution releases. |
| 17 | +No specific changes in the source will be made. |
0 commit comments