docs: python bindings guide

Author: matthewjberger

docs/PYTHON_BINDINGS.md

@@ -0,0 +1,97 @@
+# Python Bindings
+
+Python drives the engine through the command stream. You build a command as plain
+data, submit it, and read the reply. The bindings live at
+`crates/nightshade-api/bindings/python` and wrap that stream in a small ergonomic
+layer, so the spinning cube is the whole pitch:
+
+```python
+import nightshade as ns
+
+app = ns.open()
+cube = app.spawn_cube([0.0, 0.5, 0.0])
+app.set_color(cube, [0.2, 0.6, 1.0, 1.0])
+while app.frame():
+    app.rotate(cube, [0.0, 1.0, 0.0], app.delta_time())
+```
+
+## Building
+
+Needs a Rust toolchain and `maturin`. From the binding directory:
+
+```
+just develop      # build the extension into the active environment
+just test         # headless tests (the GPU render test is gated off)
+just build        # produce an abi3 wheel in ./dist
+```
+
+The wheel is `abi3`, so one build serves CPython 3.8 and up. A window needs a
+display and a GPU. For headless work, `ns.render_to_image` draws one offscreen
+frame after a setup batch.
+
+## The model
+
+The extension is a thin forwarder. It opens a window, advances a frame, and
+submits commands through the same `submit_commands` the rest of the api uses. No
+`World`, no engine internals cross the boundary, only commands in and replies
+out. Commands and replies travel as json, so the bridge has no per-object
+conversion layer.
+
+`App` is the open window. Its ergonomic methods build a command and submit it:
+`spawn_cube`, `spawn_sphere`, `spawn_floor`, `set_color`, `set_metallic_roughness`,
+`set_emissive`, `set_position`, `rotate`, `set_scale`, `set_parent`, `despawn`,
+`point_light`, `set_sun`, `set_background`, `orbit_camera`, `fly_camera`,
+`look_at`, `play_animation`, `delta_time`, `elapsed_seconds`, `key_down`,
+`key_pressed`, `mouse_clicked`, `wasd`, `clicked_entity`, `entity_under_cursor`,
+`cursor_on_ground`, and more.
+
+Spawns return an `Entity` handle. Pass it straight back into any command that
+takes one.
+
+```python
+ball = app.spawn_sphere([0.0, 4.0, 0.0])
+app.set_metallic_roughness(ball, 0.9, 0.2)
+hit = app.clicked_entity()
+if hit is not None:
+    app.set_color(hit, [1.0, 0.3, 0.2, 1.0])
+```
+
+## The full surface
+
+The ergonomic methods cover the common calls. For anything else, `submit` and
+`submit_batch` take the whole command surface as dicts in the
+`{"Variant": {fields}}` form. A batch can reference an entity an earlier command
+produced, so it builds and wires a scene in one call.
+
+```python
+app.submit({"SetExposure": {"exposure": 1.2}})
+app.submit_batch([
+    {"SpawnCube": {"position": [-1.5, 0.5, 0.0]}},
+    {"SpawnSphere": {"position": [1.5, 0.5, 0.0]}},
+])
+```
+
+`ns.command_schema()` returns the json schema for the command surface, and
+`ns.command_reply_schema()` the reply schema, both as dicts. They are the source
+a binding language generates its encoder and decoder from.
+
+## Input
+
+Key names are plain strings: letters, digits, `"space"`, `"enter"`, `"escape"`,
+`"tab"`, the arrows `"left"`/`"right"`/`"up"`/`"down"`, and `"shift"`/`"ctrl"`/
+`"alt"`. The `ns.keys` namespace holds the common ones. Mouse buttons are
+`0` left, `1` middle, `2` right.
+
+```python
+while app.frame():
+    if app.key_down("space"):
+        ...
+    move = app.wasd()
+```
+
+## Not bound yet
+
+The participant event stream (`push_command` and `drain_events`) is not exposed.
+Its `Event` and `Command` types need a serde wire form that matches their
+packed-integer entity schema before the binding can carry them. The command
+stream above is the whole surface for now.