Skip to content

Make supply hubs easier to start and link any hubs by rail - #100

Merged
Drefvelin merged 1 commit into
mainfrom
hub-onboarding
Oct 2, 2026
Merged

Drefvelin merged 1 commit into
mainfrom
hub-onboarding

Conversation

@Drefvelin

Copy link
Copy Markdown
Contributor

Why

A guild's first supply hub does nothing on its own, and the game never said so. Players could build a hub, pay upkeep, see "Active", and get no trade. Hubs also only linked to hubs of the same kind, the default limit of 2 was hidden in config, and upkeep grew with every hub.

What changes

Telling the player what a hub does

  • /guild hub build away from the capital province, while the guild has no hub in its capital, shows a one-time tutorial with a [Got It] button and does not build. After Got It the build goes through, with a one-line note that the guild still has no capital hub. Once the guild has a capital hub there is no placement advice.
  • Every successful build says what the hub linked to, or that a hub does nothing alone, or that it is not linked to the guild's other hubs.
  • /guild hub list and the hub menu show "Not linked to another hub" on an active hub with no link.

Rail joins any two hubs

  • Train track links any two hubs in different provinces, whatever their installations (port to station, airport to station, and so on), at the normal rail rates.
  • Ports still link by sea and airports by air. A pair that qualifies for both gets the link with the higher trade share.
  • A link now records its two installations, so hub tax, the map export and the "Sends to" lines no longer guess the hub from the link's mode.
  • A track lookup that finds nothing is remembered for 30 seconds.

Limit and upkeep come from the branches

  • Hub limit is the whole part of hub_limit; Supply Lines is now hub_limit 2 0.5, so the 2 shows in the branch. The limit does not shrink while a guild is inactive.
  • New hub_upkeep modifier: upkeep per hub per day. Supply Lines is hub_upkeep 15 1, Storehouses hub_upkeep 0 0.5. Every hub costs the same.
  • supply-hubs.base-limit, base-upkeep and upkeep-growth are removed from config (old files still load).

Branches

  • Freight Yards becomes Counting Houses (counting_houses): trade_upkeep 0 -0.01.
  • hub_production 0 0.08 moves to Supply Lines; hub_trade is 0 0.05, as on the live server.
  • Guild data saved with freight_yards loads as counting_houses with its level.

Deploying

plugins/SimpleFactions/Guilds/branches.yml on a server is not updated by the jar. It needs the new Supply Lines, Storehouses and Counting Houses lines, or guilds get a hub limit of 0 and free hubs.

Testing

mvn verify: 2513 tests pass. Tested on the dev server with a bot: tutorial, Got It, build messages, list output, upkeep.

🤖 Generated with Claude Code

A guild's first hub does nothing alone, and nothing told players that.
Building away from the capital before the guild has a capital hub now
shows a one-time tutorial with a [Got It] button, and every build says
what the new hub linked to.

Train track now links any two hubs, whatever their installations: a
port or airport on a line links to a station. Ports still link by sea
and airports by air; a pair that has both gets the stronger link.

The hub limit and upkeep move into the branches so players can see
them: Supply Lines gives 2 hubs at level 0 and 15d per hub, and each
level of Supply Lines or Storehouses adds a little upkeep per hub.
Every hub costs the same; the cost no longer grows per hub.

Freight Yards becomes Counting Houses (lower trade upkeep). Hub
production moves to Supply Lines. Guilds saved with freight_yards keep
their levels.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 2, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: fcb0debf-581a-41e3-acfa-0c9c4b11628b

📥 Commits

Reviewing files that changed from the base of the PR and between 0556d00 and edb5217.

📒 Files selected for processing (23)
  • src/main/java/net/tfminecraft/simplefactions/Cache.java
  • src/main/java/net/tfminecraft/simplefactions/database/Database.java
  • src/main/java/net/tfminecraft/simplefactions/database/GuildData.java
  • src/main/java/net/tfminecraft/simplefactions/enums/GuildModifier.java
  • src/main/java/net/tfminecraft/simplefactions/guild/Guild.java
  • src/main/java/net/tfminecraft/simplefactions/guild/hub/HubNetwork.java
  • src/main/java/net/tfminecraft/simplefactions/guild/hub/HubTaxService.java
  • src/main/java/net/tfminecraft/simplefactions/guild/hub/HubTransport.java
  • src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubCommands.java
  • src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubService.java
  • src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubTutorial.java
  • src/main/java/net/tfminecraft/simplefactions/loaders/BranchLoader.java
  • src/main/java/net/tfminecraft/simplefactions/managers/inventory/GuildCreator.java
  • src/main/java/net/tfminecraft/simplefactions/managers/inventory/SupplyHubView.java
  • src/main/java/net/tfminecraft/simplefactions/map/export/Markers.java
  • src/main/resources/Guilds/branches.yml
  • src/main/resources/config.yml
  • src/test/java/net/tfminecraft/simplefactions/guild/hub/HubNetworkTest.java
  • src/test/java/net/tfminecraft/simplefactions/guild/hub/HubTaxServiceTest.java
  • src/test/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubServiceTest.java
  • src/test/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubTutorialTest.java
  • src/test/java/net/tfminecraft/simplefactions/loaders/SupplyHubBranchesTest.java
  • src/test/java/net/tfminecraft/simplefactions/objects/handler/TaxHandlerHubTaxTest.java
💤 Files with no reviewable changes (2)
  • src/test/java/net/tfminecraft/simplefactions/objects/handler/TaxHandlerHubTaxTest.java
  • src/main/java/net/tfminecraft/simplefactions/Cache.java

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.


📝 Summary

Summary by CodeRabbit

  • New Features
    • Added an in-game supply hub tutorial with placement guidance and an option to dismiss it.
    • Supply hub connections now support links between different hub types, including sea and air routes, and show the connected installations.
    • Guild branches now offer updated hub capacity, trade, production and upkeep modifiers, plus a trade-upkeep reduction.
    • Guild finances now show supply hub upkeep per hub.
  • Improvements
    • Supply hub upkeep is now a flat amount per hub, determined by guild modifiers; unaffordable hubs are removed newest first.
    • Updated hub listings to show per-hub upkeep and identify hubs without connections.

Walkthrough

Supply hub limits and flat upkeep now use guild modifiers. Transport links identify their source and destination installations by faction and installation IDs. Guild commands can display a supply hub tutorial and save a player’s dismissal state.

Changes

Supply hub systems

Layer / File(s) Summary
Modifier-based limits and upkeep
src/main/java/net/tfminecraft/simplefactions/Cache.java, src/main/java/net/tfminecraft/simplefactions/enums/GuildModifier.java, src/main/java/net/tfminecraft/simplefactions/guild/Guild.java, src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubService.java, src/main/java/net/tfminecraft/simplefactions/loaders/BranchLoader.java, src/main/java/net/tfminecraft/simplefactions/managers/inventory/GuildCreator.java, src/main/java/net/tfminecraft/simplefactions/managers/inventory/SupplyHubView.java, src/main/resources/Guilds/branches.yml, src/main/resources/config.yml, src/test/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubServiceTest.java, src/test/java/net/tfminecraft/simplefactions/loaders/SupplyHubBranchesTest.java, src/test/java/net/tfminecraft/simplefactions/objects/handler/TaxHandlerHubTaxTest.java
Hub limits use the HUB_LIMIT modifier. Each hub has flat upkeep from HUB_UPKEEP. Branch definitions, branch-name fallback, configuration, expense labels, inventory text, and related tests reflect these changes.
Identity-based transport links
src/main/java/net/tfminecraft/simplefactions/guild/hub/HubTransport.java, src/main/java/net/tfminecraft/simplefactions/guild/hub/HubNetwork.java, src/main/java/net/tfminecraft/simplefactions/guild/hub/HubTaxService.java, src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubCommands.java, src/main/java/net/tfminecraft/simplefactions/managers/inventory/SupplyHubView.java, src/main/java/net/tfminecraft/simplefactions/map/export/Markers.java, src/test/java/net/tfminecraft/simplefactions/guild/hub/HubNetworkTest.java, src/test/java/net/tfminecraft/simplefactions/guild/hub/HubTaxServiceTest.java
Links carry endpoint faction and installation IDs. The network considers eligible transport modes and selects the valid link with the higher trade factor. Tax and connection displays match links to hubs by endpoint identity.
Tutorial and saved dismissals
src/main/java/net/tfminecraft/simplefactions/database/Database.java, src/main/java/net/tfminecraft/simplefactions/database/GuildData.java, src/main/java/net/tfminecraft/simplefactions/guild/Guild.java, src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubCommands.java, src/main/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubTutorial.java, src/test/java/net/tfminecraft/simplefactions/guild/hub/SupplyHubTutorialTest.java
Hub-building commands evaluate tutorial eligibility and display placement guidance. Players can dismiss the tutorial, and the guild saves dismissal IDs in GuildData.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Player
  participant SupplyHubCommands
  participant Guild
  participant Database
  Player->>SupplyHubCommands: Run /guild hub gotit
  SupplyHubCommands->>Guild: Record tutorial dismissal
  SupplyHubCommands->>Database: Save faction
  Database->>Guild: Persist dismissal IDs in GuildData
  SupplyHubCommands->>Player: Prompt another build attempt
Loading

Suggested reviewers: ryanbarlow97

Merge Risk: ⚪ Minimal · up to edb52

The change moves supply hub limits and upkeep to branch modifiers, links hubs by rail across installation types, and adds a dismissible placement tutorial. No concrete merge-blocking defect was identified. Server operators must update their branches.yml files for Supply Lines, Storehouses and Counting Houses, because the jar does not update them.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to edb52

Upgrading without updating existing branch settings can reduce hub limits and eliminate upkeep charges. The new transport behavior retains ownership and permit checks, but configuration compatibility and some ownership-change recovery paths remain uncertain.

Retained concerns

  • Medium · architecture · inferred: Existing branch files are retained during startup, but head stops adding the configured base limit and stops reading configured upkeep. With the previous bundled branch settings, a guild loses the two-slot baseline and resolves hub upkeep to zero. This can silently change capacity enforcement and remove the economic cost control across upgraded guilds. Updating bundled resources and aliasing the renamed branch do not establish migration of existing modifier values; deployed configuration contents remain unknown.
Security review details

Security Blast Radius

  • inferred — The demonstrated boundary is between guild economic activity and faction-owned installations, including permitted foreign hosts. Configuration compatibility can affect every guild using a retained branch file; the inspected paths concern game capacity, trade, production, and host taxation rather than establishing broader infrastructure exposure.

Trust Boundaries and Controls

  • observed — Player-directed construction requires current guild leadership and permitted economic rules, then validates duplicate prevention, guild limit, installation slots, positive trade, and owner-or-host-permit authority before mutation. Tutorial dismissal changes only guidance state and cannot bypass these checks.

Resilience and Maintainability Implications

  • observed — Cached links are returned without per-read ownership revalidation, and installation removal or transfer hooks do not themselves rebuild that cache. Immediate-parent source contains the same behavior, so this is not established as a newly introduced vulnerability. The stricter endpoint contract makes refresh ordering important; complete transfer and recovery ordering remains unproven.

Hardening Proposals

  • proposed — Provide a versioned migration or explicit compatibility validation for retained branch settings before enabling modifier-only hub economics. Preserve administrator customization, identify missing baseline modifiers, and document a reversible upgrade procedure.
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.


Comment @coderabbitai help to get the list of available commands.

@Drefvelin
Drefvelin merged commit cb3462d into main Oct 2, 2026
2 checks passed
@Drefvelin
Drefvelin deleted the hub-onboarding branch October 2, 2026 09:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants