# Flying Jib

**Fully decentralized peer-to-peer Minecraft** — no master servers, ever.

Flying Jib is a **Bare/Pear** app that runs [Flying Squid](https://github.com/PrismarineJS/flying-squid) **inside Bare** (via `bare-node-runtime`), bound only to `127.0.0.1`. Friends join through encrypted Holepunch tunnels. Worlds stay private (capability invites) or enroll into a federated **mesh** of linked regions.

**End users do not install Node.js.** CI ships **single standalone executables** (`bare-build --standalone`) plus Pear P2P OTA.

> **Phase 0 complete:** architecture and documentation are in place (including [ADR-0013](./agent/ADRs/0013-bare-pear-only-runtime-and-distribution.md)). Application runtime arrives in Phase 1.

## Why “Flying Jib”?

A flying jib is a sail that works **with** the main sail — not above it as a master. Each peer runs its own server; the mesh is coordination among equals.

## Architecture (one paragraph)

Java Edition always connects to **localhost**. The Bare app owns Squid’s lifecycle and a **HyperDHT** tunnel for remote peers. Mesh membership uses **Autobase**; borders use **session migration**, not a global voxel database. Runtime: **Bare + pear-runtime** only. Stack: Hyperswarm, HyperDHT, Protomux, Corestore — see [living_docs/ARCHITECTURE_OVERVIEW.md](./living_docs/ARCHITECTURE_OVERVIEW.md).

## Documentation

| Tree | Audience |
|------|----------|
| [living_docs/](./living_docs/) | Current status, roadmap, progress, open questions |
| [developer_docs/](./developer_docs/) | Setup, deep architecture, modules, protocol, release |
| [user_docs/](./user_docs/) | End-user guides (features marked Planned until shipped) |
| [agent/](./agent/) | Rules for humans & AI agents, ADRs, security |

**Start here:** [living_docs/CURRENT_STATUS.md](./living_docs/CURRENT_STATUS.md) · [ADR-0013](./agent/ADRs/0013-bare-pear-only-runtime-and-distribution.md)

## Non-negotiables

1. No central/master game servers
2. Minecraft TCP only on `127.0.0.1`
3. **Bare/Pear only** — no system Node.js for the product; no Node child for Squid
4. CI: single standalone executables + Pear OTA
5. Documentation updated with every significant change
6. ADRs before architecture changes
7. Apache-2.0 — no AGPL hard dependencies

## Roadmap (summary)

| Phase | Focus | Status |
|-------|--------|--------|
| 0 | Research, ADRs, full docs/agent scaffold | **Done** |
| 1 | hello-pear-bare + Squid on Bare | Not started |
| 2 | Private worlds via HyperDHT tunnel | Not started |
| 3 | Presence + chat | Not started |
| 4 | Mesh registry + border migration | Not started |
| 5 | Security polish + bare-build CI/release | Not started |

## Development

```sh
npm install   # dev machine only; postinstall patches Bare engines + imports
BARE=./node_modules/bare-runtime/bin/bare

$BARE bin.mjs create demo
$BARE bin.mjs host demo --port 25565    # print fj1. invite; local Squid
$BARE bin.mjs join 'fj1.…' --port 25566 # guest tunnel

# Minecraft Java → 127.0.0.1:<port shown>
npm test
```

See [developer_docs/SETUP.md](./developer_docs/SETUP.md) and [living_docs/CURRENT_STATUS.md](./living_docs/CURRENT_STATUS.md).

## License

[Apache License 2.0](./LICENSE)