# Voxel Earth

> Real places, in Minecraft.

[![Join us on Discord]( https://img.shields.io/discord/3083...goColor=ffffff&color=7389D8&labelColor=6A7EC2")]( https://discord.gg/8MK8J9EQGe)

Voxel Earth is a full pipeline for turning photogrammetry and 3D Tiles into block-based worlds.
It streams Google Photorealistic 3D Tiles (and other sources) into Minecraft as voxelized chunks, so you can walk through real cities, mountains, and landmarks — block by block.

- Stream real-world 3D Tiles into Minecraft
- CPU voxelization, no GPU required on the server
- ⚡ Designed to work hand-in-hand with FastAsyncWorldEdit (FAWE)
- Web client for browser-side experiments and previews
- Separate CLIs for each pipeline stage (download → decode → voxelize)

---

## Links & Community

- **Website:** https://voxelearth.org
- **Play server:** `play.voxelearth.org`
- **Web client demo:** https://beta.voxelearth.org (browser viewer)
- **Discord:** https://discord.gg/8MK8J9EQGe
- **Monorepo (reference):** https://github.com/ryanhlewis/VoxelEarth

---

## What is Voxel Earth and why should I use it?

Voxel Earth is a Minecraft + web ecosystem for exploring real-world geometry as voxels:

- **3D Tiles to blocks**
Fetches photogrammetry tiles (e.g. Google Photorealistic 3D Tiles), normalizes them, and converts them into Minecraft block palettes.

- **On-demand streaming**
Tiles are pulled and voxelized as players move around, so you can “walk into” a real city and watch it appear around you.

- **Flexible pipeline**
Each major step (download, Draco decode, voxelization) exists as a separate CLI tool and as embedded code in the plugin. You can test each stage locally before wiring everything together.

- **Server-friendly**
The Minecraft plugin is built as a single shaded JAR, with CPU voxelization and async integration with FAWE for high-throughput placement.

---

## Downloads

> **Note:** Links below are placeholders / targets; some may not exist yet.

- **Minecraft plugin (core Voxel Earth JAR)**
- GitHub Releases: https://github.com/ryanhlewis/VoxelEarth/releases
- Modrinth: https://modrinth.com/plugin/voxelearth
- SpigotMC: https://www.spigotmc.org/resources/voxelearth.00000/ (coming soon)

- **Web client**
- GitHub: https://github.com/voxelearth/web-client

---

## Minecraft Plugin

### Requirements

- **Server:** Paper or Spigot **1.20+** with **FastAsyncWorldEdit (FAWE) installed**
- **Java:** **Java 21+**

---

## Commands

VoxelEarth’s plugin adds commands for geocoding, tile loading, and per-player preferences:

```yml
/visit <location>
Teleport to a geocoded location (city, landmark, etc.) and stream tiles around it.

/visitradius <tiles>
Configure how many tiles /visit loads around the target area.

/moveradius <tiles>
Set how many tiles are loaded as the player moves.

/movethreshold <blocks>
Movement distance (in blocks) required before triggering new loads.

/moveload <on|off|toggle|status>
Enable/disable movement-based loading for yourself.

/visitother <player> <location>
Teleport another player to a geocoded location and stream tiles.

/visitradiusother <player> <tiles>
/moveradiusother <player> <tiles>
/movethresholdother <player> <blocks>
Admin variants that adjust settings and notify other players.

/voxelapikey <google-api-key>
Store a Google API key for geocoding and tile access (per server).
```

Permissions are namespaced under `voxelearth.*` and default to `true` or `op` as appropriate (see `plugin.yml` for full details).

---

## Web Client

If you just want to experiment with tiles and voxelization **in your browser**, use the web client:

* **Repo:** [ https://github.com/voxelearth/web-client](https://github.com/voxelearth/web-client)
* **Live demo:** [ https://beta.voxelearth.org](https://beta.voxelearth.org)

The web client:

* Fetches Google Photorealistic 3D Tiles in the browser
* Normalizes/rotates them into a viewable frame
* Can hand off data to the Voxel Earth voxelization pipeline
* Is ideal for exploring regions, testing zoom/SSE parameters, and visually inspecting tilesets before you spin up a Minecraft server

---

## License

Voxel Earth and its companion CLIs are released under the **MIT License**, unless otherwise noted in sub-projects.
See the `LICENSE` file in this repository for full terms.

“Minecraft” is a trademark of Mojang AB.
Voxel Earth is not affiliated with or endorsed by Mojang AB, Microsoft, or Google.