CivPortal

A Fabric client mod that brings a civilization server's web portal into the game: your duties, the nation's announcements, its build projects and its storage, on a screen you can open mid-walk instead of alt-tabbing to a website.

It talks to any site that implements the mod API — nothing about one nation is baked in. Point it at a portal, pair once, and it works.

Placeholder — a screenshot of the dashboard open on the Tasks tab.

---

Contents

• Features
• Installing
• First run
• Using it
• Commands
• Settings
• The inventory ledger
• For portal operators
• Building from source
• Privacy and security
• Licence

---

Features

The dashboard

One screen, opened with a keybind, with a tab per thing the nation does.

Tab	What it shows
Herald	Announcements, newest first, with unread marking
Tasks	Your duties, your team's, and the realm's — create, complete and withdraw them in game
Builds	Build projects, their progress, and their schematics
Settings	Everything below

Tabs you do not want can be switched off, and ones your office does not grant you never appear.

Placeholder — the Herald tab showing a couple of announcements.

Tasks

Four kinds, raised in game or on the portal, addressed to one member, a branch, or the whole nation:

Kind	Closes when
Duty	Somebody ticks it off
Gathering	The materials reach the treasury — see the inventory ledger
Build work	Somebody ticks it off; the schematic comes with it
Travel to	You get there

Work set for more than one person can be individual — it leaves your Ledger the moment you have done your part — or group, which keeps it on everyone's, counting up, until the last of them is done. Who a group task waits for is fixed when it is raised, so joining the branch afterwards does not add you to it.

A Travel to task carries a destination and how near counts as arrived, and closes itself when you walk into that radius. Group and travel together give you a regroup order: everybody's Ledger shows 3/5 done until the last person reaches the muster point.

The tab has two views. Set for me is your own list; Set by me is the work you have handed out, with the tick and cross beside each row — because whoever set a task may always close or withdraw it. It appears only if your office can set tasks at all. Nothing on that list counts as yours: it raises no notifications, drops no waypoints, arms no arrival, and a gathering job there shows what you asked for without measuring it against your own pockets.

Placeholder — the Tasks tab with a group travel task counting up.

Nameplates

Rank, nation, Discord handle or diplomatic stance above players' heads, cycled with a keybind. Colours follow the meaning of the line, the stance, or one colour of your choosing. Size is yours to set too. Your own tag is off by default, since vanilla never draws it anyway.

If tags are hard to read, two things are worth knowing before you touch the size. Long rank titles are automatically shrunk to fit a fixed width — turn off Shrink long tags and they stop being. And the dark backdrop behind every nametag is a vanilla setting, Text Background Opacity under Options → Video Settings; at zero there is no backdrop and no mod can put one back. That is usually why one player finds the tags fine and another cannot read them at all.

Placeholder — a few players with rank and stance nameplates.

Relations

Local friend/enemy overrides that take precedence over whatever the portal says, for the times you know something the roster does not yet.

Notifications

Quiet toasts rather than chat spam. New announcements and new tasks arrive as they happen; a task being completed raises a green toast with a chime, and one being cancelled a red one. Batches collapse into a single summary instead of a wall.

Placeholder — the green completion toast.

Waypoints — needs Xaero's Minimap

Task locations, atlas markers and build sites appear on the minimap and world map the moment the portal updates, colour-coded by kind. They live in Xaero's third-party store, so your own waypoints are never touched and the nation's pins can be toggled separately in Xaero's settings.

Build rendering — needs Litematica

Both directions.

Down: a build task hands its schematic straight to Litematica, placed at the origin, rotation and mirror the portal recorded — so everyone building it sees the same ghost in the same place.

Up: a build manager who has positioned a placement by eye can publish it, file and numbers together, and every later download puts it back exactly there. No coordinates read aloud, no "is it one block north?".

Without Litematica the buttons grey out and say why.

Inventory ledger — needs Chest Tracker

Quartermasters can publish what the nation's storage holds, so build planning knows what is already in the treasury and gathering tasks close themselves when the materials arrive. See The inventory ledger — nothing is published unless you add it deliberately.

It works without any of those

Litematica, Xaero and Chest Tracker are each optional. CivPortal runs standalone; the features that need a companion mod say <Mod> not installed in their settings section instead of disappearing, so you can see what you are missing.

---

Installing

Required

Minecraft	1.21.11
Loader	Fabric
Fabric API	any current build

Drop civportal-<version>.jar into .minecraft/mods alongside Fabric API.

Optional companions — install only the ones whose features you want:

Mod	Unlocks	Note
Xaero's Minimap	Waypoints	Xaero's World Map draws them too, if you have it
Litematica	Build rendering	Needs malilib, as usual
Chest Tracker	Inventory ledger	On 1.21.11 use the unofficial port linked here, plus YACL. Everything else it needs is bundled inside it.

---

First run

1. Launch the game and open the dashboard with /civportal dashboard. Both keybinds ship unbound so they cannot collide with your existing ones — set them under Settings → Keybinds whenever you like.
2. Go to Settings → Portal, enter your nation's site address, press Apply. Plain http:// is refused except for localhost.
3. Run /civportal link in chat. You will get a short code.
4. Open your portal's linking page in a browser, signed in, and enter the code. Where that page lives is up to the site — ask whoever runs yours if you do not know.
5. The mod stores a token and connects. That token is yours alone and is revocable from the site.

Placeholder — the link code in chat next to the portal's pairing page.

Changing the portal address later unlinks you automatically — a token issued by one site means nothing to another.

---

Using it

• The dashboard keybind opens and closes it; /civportal dashboard does the same.
• The cycle nameplates keybind steps through the modes you have enabled.
• Both are unbound until you set them in Settings → Keybinds.
• Tasks can be ticked off or withdrawn from the Tasks tab, if your office allows it.
• New tasks — duties, gathering work, build jobs or somewhere to travel to — can be created in game, including at your current coordinates.
• The Builds tab lists projects and, with Litematica installed, renders the one you pick.

---

Commands

Everything is under /civportal.

Command	Effect
/civportal or status	Connection state, rank, permissions, roster size
/civportal link	Pair this client with the portal
/civportal unlink	Forget the token
/civportal portal <url>	Point at a different portal
/civportal refresh	Fetch everything now
/civportal dashboard	Open the dashboard
/civportal waypoint <label>	Share your position to the nation's atlas
/civportal relation …	Local friend/enemy overrides
/civportal inventory	Whether a sync would work, and how much it would send
/civportal inventory sync	Send it now

---

Settings

Grouped so you can find things, with the mod-dependent parts last.

PORTAL          address, which servers to poll on
TABS            which tabs to show
NAMEPLATES      modes, colouring, size, shrinking, your own tag
NOTIFICATIONS   which events raise a toast
REFRESH RATES   how often to sync
WAYPOINTS  · XAERO'S MINIMAP
BUILDS     · LITEMATICA
INVENTORY  · CHEST TRACKER
KEYBINDS

Placeholder — the Settings tab, ideally scrolled to the integration sections.

Refresh rates. Three sliders: dashboard and tasks (10 s – 2 min), map atlas (30 s – 10 min) and, with Chest Tracker, the inventory sync (10 s – 2 min). You rarely need the fast end: if the portal supports change signalling, the mod notices updates within a few seconds regardless and these become a fallback.

Settings live in .minecraft/config/civportal/. Your token is stored separately with owner-only file permissions and is never written to the log.

---

The inventory ledger

Chest Tracker keeps the index: every container it has seen, where it is, and what was in it. The mod uploads that index to the nation's ledger, and adds nothing of its own to it.

1. Open the chest once so Chest Tracker knows what is inside.
2. That is all. It syncs when the contents change, and within seconds of you closing the chest.

/civportal inventory reports whether both prerequisites are met and how many containers Chest Tracker currently remembers here — which is exactly how many the next sync sends. If it says no memory bank is loaded, that is not the same as an empty base, and nothing is uploaded until one is: the portal reads an empty upload as "these containers hold nothing" and clears your stock accordingly.

Only players holding the portal's inventory-management grant sync at all. That grant is an office the nation hands out, and it is the whole of the decision — there is no second, per-chest opt-in. Earlier versions kept one, but a hand-maintained list beside Chest Tracker's own could disagree with it silently, and a ledger that is quietly incomplete is worse than one that is obviously wrong.

Placeholder — the nation's inventory page showing synced stock.

---

For portal operators

The mod is generic; the site does the deciding. Every permission is re-derived server-side on every request, so nothing the client claims is trusted.

Implement the contract in MINECRAFT-MOD-API.md — pairing, /me, roster, dashboard, tasks, atlas, builds, gathering and the inventory ledger. A site can also publish /.well-known/civportal.json to give the mod its nation name, colour, icon and the server addresses its members play on, before the first request lands.

Your pairing page — where a player types the code from /civportal link — may live at any address you like; the mod never assumes one and never prints one. Tell your members where it is.

There is a complete mock portal in tools/MockPortalServer.java if you want to see the shapes without building a backend.

---

Building from source

./gradlew build

The jar lands in build/libs/. Java 21 and an internet connection for the first run.

Running the dev client:

./gradlew runClient

Litematica comes in automatically. Xaero and Chest Tracker do not — drop them into run/mods/ by hand, because a mod jar on the dev classpath does not get its bundled libraries unpacked. build.gradle lists the exact files.

Tests — all headless, no game client needed:

java tools/MockPortalServer.java 8099 &
java -cp "build/classes/java/client;$GSON;$SLF4J;tools" tools/PortalClientSmokeTest.java 8099
java -cp "build/classes/java/client;$GSON;$SLF4J;tools" tools/XaeroWaypointsTest.java
java -cp "build/classes/java/client;$GSON;$SLF4J;$FABRIC;tools" tools/InventorySnapshotTest.java
java -cp "build/classes/java/client;$GSON;$SLF4J;tools" tools/TaskOutcomesTest.java

They cover the network and parsing stack, the waypoint file merge, the inventory snapshot's null-versus-empty contract and the task-outcome notifications.

---

Privacy and security

• Your token is per player, stored hashed on the portal, kept locally with owner-only file permissions, never logged in full, and revocable from the site.
• No shared secret is baked into the jar. There is nothing in a build worth extracting.
• HTTPS is required, except for localhost while developing.
• Your location is never transmitted. Nothing in the mod sends where you are.
• Your own waypoints are never read or modified.
• Storage is opt-in, per container, as described above.
• Chat and logs never carry the token, the portal's responses, or other members' private fields.
• The mod cannot run code. No process launching, no class loading, no archive extraction, no clickable chat, and it never hands a file to the operating system. The only file it downloads is a schematic, under a name stripped to [A-Za-z0-9._-], into Litematica's own folder, where it stays inert until you ask Litematica to load it.

SECURITY.md is the full review: what was checked, what a hostile portal could and could not do, and the handful of robustness issues still worth fixing.

---

Licence

Written by KarolexDev — github.com/KarolexDev/CivPortal.

See LICENSE.txt. Litematica (LGPL-3.0) and Chest Tracker (LGPL-3.0) are called through their public APIs and none of their code is bundled. Xaero's mods are all-rights-reserved and are integrated entirely by reflection, with nothing compiled against or redistributed.