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: obsidian, gold block, gilded blackstone, birch/oak planks) 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.

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 out the blocks that stick further outward than their immediate ring-neighbours - the "elbow" points of the shape, which is where a real Stargate's chevrons sit (an 11-wide octagonal ring like the reference design naturally produces 7 of them: the top apex, the four shoulder elbows, and the two side bumps). 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 switches from gate.iris-idle-material (default air - an idle gate is just an empty ring you can see straight through) to either the event horizon (gate.iris-open-material, default water) or, if the iris shield is closed, to gate.iris-shield-material (default iron block) instead, blocking travel even though the gate is actively connected. It auto-closes after dialing.open-seconds, switching back to the idle material either way.
• Walking into the event horizon teleports you to the connected gate, arriving just clear of its iris (never inside it - that would immediately teleport you right back) and still facing whatever direction you were already walking, so entering forward always means exiting forward.
• Right-click a button placed directly below the sign toggles the iris shield. Closing it never needs anything 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.
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.

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