Stargate/README.md

Stargate

A network-aware Stargate portal plugin for PaperMC, with sign-based dialing and cross-server travel over Velocity or BungeeCord.

Modules

Module	What it is
stargate-common	Shared models + JDBC storage (SQLite / MySQL) used only by the Paper plugin
stargate-paper	The actual gate plugin — install this on every backend server
stargate-velocity	Proxy companion for Velocity — install on the proxy only if using cross-server gates
stargate-bungee	Same, for BungeeCord/Waterfall

Build everything with ./gradlew build. Jars land in each module's build/libs/.

Building a gate

There's no fixed size or shape - build any single connected ring out of gate.frame-materials (default: just obsidian) with a fully sealed hollow interior. No gaps; the interior must be enclosed. "Connected" includes the usual diagonal stepping a round/octagonal ring needs at its corners (blocks touching only edge-to-edge or corner-to-corner still count), so a circular build doesn't need every block to share a full face with the next.

Add more materials to gate.frame-materials if your ring mixes blocks, but keep the list to materials used only for the ring - anything also used decoratively nearby (a backdrop wall, a matching accent elsewhere) risks getting swept into the frame if it touches the ring anywhere in the same plane, which is also where stray chevrons would show up.

Build it free-standing, one block thick, in a single flat plane (a vertical ring facing a direction, like all the examples above) - the plugin figures out which axis is the ring's "thickness" and only looks for the interior within that plane, so it doesn't try to flood-fill out through the open air in front of and behind the gate.

Chevrons aren't a separate material you place. When the gate is linked, the plugin flood-fills the ring, walks it in geometric order, and picks gate.chevron-count (default 7) blocks evenly spaced around the ring's actual perimeter. Those blocks swap to gate.chevron-lit-material (default glowstone) while dialing/open, and revert to whatever they looked like at rest when the gate closes - so a chevron can rest as plain obsidian and blend invisibly into the frame until it lights up.

1. Build the ring.
2. Optionally place a button directly below where you'll put the sign - this becomes the iris shield toggle (see below). Not required; a gate without one just has no shield control.
3. Place a sign anywhere - it doesn't need to touch the frame, so it can act like a DHD console standing apart from the gate - with:
   • Line 1: [Stargate]
   • Line 2: network name (blank = default network)
   • Line 3: gate name (blank = auto-generated)
   • Line 4: hidden to keep it out of the cycle list, fixed:GateName to lock this gate to always dial GateName (no right-click cycling), or blank
4. The sign will show "Punch the gate (30s)". Within gate.link-timeout-seconds, left-click (punch) any frame block, within gate.max-link-distance of the sign. The plugin scans out from that block and links the sign to it.

If punching a block doesn't work, the plugin tells you exactly why in chat - wrong material, unsealed interior, too far from the sign, etc.

Using a gate

• Right-click the sign: cycles the destination shown on line 3 among the other gates on the same network.
• Left-click the sign: dials the shown destination - chevrons light in sequence, then the interior becomes the event horizon (gate.iris-open-material, default water) and travel opens up. It auto-closes after dialing.open-seconds. That water is contained to exactly the iris blocks - the plugin actively cancels any attempt by Minecraft's own fluid physics to spread it further, so it can't leak out through a gap or an odd ring shape and flood the ground around the gate.
• Shift + left-click the sign: destroys the gate on the spot (same permission check as /sg destroy - owner or stargate.admin), breaking the sign as if you'd mined it. Quicker than looking at the sign and typing the command.
• Travel is one-way: only the gate you dialed from can send anything anywhere. Walking (or wandering, or drifting) into its event horizon teleports whatever entered to the destination, arriving just clear of its iris (never inside it) and still facing whatever direction it was already moving, so entering forward always means exiting forward. The destination's horizon is visible but not walkable - stepping into it does nothing, same as a real Stargate only running one direction at a time.
• Not just players - mobs, dropped items, minecarts, boats, arrows, anything that moves through the event horizon gets sent through too. Non-player entities can only travel to a same-server destination, though; there's no way to carry an arbitrary entity's state across the Velocity/Bungee plugin-messaging hop, so a cross-server gate just won't move anything but players.
• The iris shield is a separate, physical thing from the wormhole connection. Right-click a button placed directly below the sign to toggle it. Closed means closed - gate.iris-shield-material (default bedrock), solid, blocking everything - whether or not the gate is even connected right now, and travel is refused even if something manages to occupy that space anyway (flight, an elytra, a vehicle - not just relying on block collision). It blocks in both directions: a closed shield on the gate you're dialing from stops you from ever stepping in, and a closed shield on the destination refuses the trip too, matching a real iris stopping anything that hits it from either side. With the shield open, the interior just reflects the connection state: gate.iris-idle-material (default air) if idle, or the event horizon if actively dialed. Closing needs nothing extra; if the gate has a pin set (/sg pin <code>), opening a closed shield prompts you to type the code in chat within gate.pin-timeout-seconds before it'll open.

Multi-world

Gates are addressed by network name, not world — a gate on any loaded world can dial any other gate on the same network regardless of world, exactly like same-server cross-world travel in the original Stargate mod.

Cross-server (Velocity / Bungee)

1. Set storage.type: mysql in every backend server's config.yml and point them at the same database — this is how servers see each other's gates. Add any connection parameters your host requires (TLS, timezone, etc.) under storage.mysql.properties - each key becomes ?key=value on the JDBC URL. It defaults to useSSL: false / autoReconnect: true; list a key here to override that default (e.g. useSSL: true plus sslMode: REQUIRED).
2. Give each backend a unique server-id in config.yml that matches its name in the proxy config (velocity.toml / config.yml servers list).
3. Set cross-server.enabled: true on every backend.
4. Drop stargate-velocity (or stargate-bungee) into the proxy's plugin folder.

When a player dials a gate hosted on another backend, the Paper plugin asks the proxy (over the stargate:teleport plugin channel) to connect the player to that server; once they land, the proxy forwards a delivery message so the destination server's Stargate instance teleports them to the gate's exit point.

Each backend only loads gates from the shared database at startup (and on /sg reload), then polls for what other servers have added, changed, or removed every cross-server.refresh-seconds (default 30) while cross-server.enabled: true. So a gate built on one server shows up as a destination on another within that window automatically - no restart or manual reload needed, though /sg reload still works if you want it immediately.

Permissions

• stargate.use (default: true) — dial/cycle gates
• stargate.create (default: op) — build new gates
• stargate.destroy (default: op) — break your own gates
• stargate.admin (default: op) — reload, break/manage any gate

Commands

• /sg list [network]
• /sg networks
• /sg destroy (look at a gate's sign)
• /sg pin <code|clear> (look at a gate's sign) — requires that code in chat before a closed iris shield will open on that gate
• /sg reload