plozone 0.1.2

3D spatial zone engine: geofencing, octree hole-scanning, realtime sync (WebSocket + QUIC + io_uring), voxel pathfinding, and AV sensor fusion.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# Contributing to Plozone

Thanks for your interest in contributing. This document covers the basics.

## Setup

```sh
git clone https://github.com/fentz26/plozone.git
cd plozone
cargo test --features full
```

Requires Rust 1.85+ (edition 2024).

## Workflow

1. **Fork** the repo and create a feature branch from `main`.
2. **Write code**. Follow existing style — no comments unless requested.
3. **Add tests** for new functionality. Every public function should have at
   least one test.
4. **Run all checks** before pushing (see below).
5. **Open a pull request** with a clear description of what and why.

## Checks

All of these must pass before merge:

```sh
cargo fmt --check
cargo test --features full
cargo clippy --features full -- -D warnings
cargo audit
cargo test --features quic
cargo clippy --features quic -- -D warnings
```

On Linux, additionally:

```sh
cargo test --features io_uring
cargo clippy --features io_uring -- -D warnings
```

## Feature flags

Plozone uses Cargo features heavily. New modules should be feature-gated and
added to the `full` feature in `Cargo.toml`. The core (`coord`, `zone`,
`octree`, `store`, `scan`) is always available with zero dependencies.

| Rule | Detail |
|---|---|
| Core is zero-dep | `coord`, `zone`, `octree`, `store`, `scan` compile with no optional deps |
| Feature-gated modules | New modules go behind `#[cfg(feature = "...")]` |
| Additive only | Never break existing public API. Add new methods/variants instead. |
| `full` includes all | Add new features to the `full` aggregate |

## Code style

- **Edition 2024** — non-negotiable.
- **No comments** unless the logic is genuinely non-obvious or requested.
- **Rustdoc on all public items** — every `pub fn`, `pub struct`, `pub enum`
  needs a `///` doc comment.
- **`serde` for wire types** — anything sent over the network derives
  `Serialize`/`Deserialize`.
- **Tests next to code** — `#[cfg(test)] mod tests` in the same file.

## Architecture notes

The full design document is [PLOZONE.md](PLOZONE.md) (3,700+ lines). Read the
relevant section before working on a subsystem. Key design decisions:

- **Two-layer zone model**: `enum Zone` (wire-safe built-in shapes) + `trait
  ZoneShape` (custom/dynamic shapes). Both stored as `Box<dyn ZoneShape>` in
  the R-tree.
- **ENU internally**: all geometry operates in ENU (East-North-Up) coordinates.
  WGS84 conversion happens at the `ZoneStore` boundary.
- **Postcard wire format**: compact, no_std-compatible. LZ4 for large messages,
  zstd for snapshots.
- **Hysteresis debounce**: zone enter/exit events require consecutive ticks to
  fire, preventing jitter.

## Reporting bugs

Open a [GitHub Issue](https://github.com/fentz26/plozone/issues) with:

- Rust version (`rustc --version`)
- Feature flags enabled
- Minimal reproduction case
- Expected vs actual behavior

## License

By contributing, you agree your contributions are licensed under the MIT
license.