Metadata-Version: 2.4
Name: flysim
Version: 0.5.0
Summary: Minimal 3D drone simulator with keyboard/mouse/HID (WFLY ET16S) control, lighting, shadow, and live-tunable physics.
Author-email: cycleuser <cycleuser@cycleuser.org>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/CodeOfMe/FlySim
Project-URL: Repository, https://github.com/CodeOfMe/FlySim
Project-URL: Issues, https://github.com/CodeOfMe/FlySim/issues
Keywords: drone,simulator,3d,opengl,pygame,hid,et16s,rc
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Simulation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame>=2.4
Requires-Dist: PyOpenGL>=3.1.7
Requires-Dist: numpy>=1.24
Requires-Dist: trimesh>=4.0
Requires-Dist: pygltflib>=1.0
Dynamic: license-file

# FlySim

A minimal but complete 3D drone simulator with real-time OpenGL rendering,
lighting, shadow, and three input methods: **keyboard**, **mouse**, and the
**WFLY ET16S** RC transmitter over USB HID.

## Features

- Real-time 3D rendering (pygame + PyOpenGL): perspective camera, depth test,
  per-vertex lighting (ambient + diffuse), smooth shading
- Tiled checkerboard ground with cardinal direction markers (N/E arrows)
- Point light source (yellow sphere) with ambient + diffuse components
- Soft blob shadow projected under the drone
- Drone model: body, 4 arms, 4 motors, independently spinning propellers
  (speed scales with throttle + differential for pitch/roll/yaw)
- Payload box hanging by a rope below the drone (swings with acceleration)
- Front markers: two red squares on the nose; rear marker: green triangle
- Third-person orbit camera (mouse drag = orbit, wheel = zoom)
- Flight telemetry HUD: position (N/E/Alt from takeoff), heading, pitch/roll,
  speed, acceleration, velocity vector
- Live RC transmitter visualization panel (twin-stick, Mode 2)
- Fully configurable HID axis mapping (axis index + sign per channel)
- Live-tunable physics: max tilt, pitch/roll/throttle force, yaw rate, damping
- Persistent config: `axismap.txt` and `tuning.txt` auto-loaded/saved

## Install

```bash
pip install dronesim
```

Or from source:

```bash
git clone https://github.com/CodeOfMe/FlySim.git
cd FlySim
pip install -e .
```

## Run

```bash
dronesim          # installed entry point
# or
python -m dronesim
```

## Requirements

- Python >= 3.10
- pygame >= 2.4, PyOpenGL >= 3.1.7, numpy >= 1.24

## Controls

### Keyboard

| Action | Keys |
|--------|------|
| Forward / back (pitch) | W / S or Up / Down |
| Strafe left / right (roll) | A / D or Left / Right |
| Yaw left / right | Q / E |
| Throttle up / down | Shift / Ctrl |
| Orbit camera | Mouse drag |
| Zoom | Mouse wheel |
| Pause | P |
| Reset drone | R |
| Toggle help | H |
| Toggle axis editor | F1 |
| Quit | ESC |

### WFLY ET16S (HID, Mode 2 / USA transmitter)

| Action | Stick |
|--------|-------|
| Throttle (up/down) | Left stick Y |
| Yaw (turn) | Left stick X |
| Pitch (forward/back) | Right stick Y |
| Roll (left/right) | Right stick X |

The HID input is auto-detected. If any ET16S stick moves beyond its deadzone,
it takes priority over the keyboard.

### Live HID axis configuration

Press **F1** to open the axis editor. Then:

| Key | Action |
|-----|--------|
| 1 / 2 / 3 / 4 | Select channel: throttle / yaw / pitch / roll |
| [ / ] | Decrement / increment axis index |
| ; / ' | Flip sign for current channel |
| F2 | Save axis map to `axismap.txt` |

### Live physics tuning

| Key | Action |
|-----|--------|
| F3 | Select `max_tilt_deg` |
| F4 | Select `pitch_force` |
| F5 | Select `roll_force` |
| F6 | Select `throttle_force` |
| F7 | Select `yaw_rate` |
| F8 | Select `damping` |
| + / - | Increase / decrease selected parameter |
| F9 | Save tuning to `tuning.txt` |
| F10 | Load tuning from `tuning.txt` |

## Scene

- Ground: 40 x 40 m checkerboard with N (red) and E (blue) arrows, origin cross
- Light: point light at (20, 30, 15) with ambient + diffuse
- Shadow: soft radial blob projected on ground under the drone
- Drone: body + 4 arms + 4 motors + spinning props + payload on rope
- Camera: third-person orbit, follows the drone

## Coordinate system

- Origin = takeoff point on the ground
- North = -Z, South = +Z, East = +X, West = -X, Up = +Y
- yaw = 0 faces North; yaw increases clockwise (top view)

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
