Skip to content

Sync: opt-in live fleet state (fleets) - #325

Open
ProgenyAlpha wants to merge 8 commits into
STFC-Mod:devfrom
ProgenyAlpha:fleet-sync
Open

ProgenyAlpha wants to merge 8 commits into
STFC-Mod:devfrom
ProgenyAlpha:fleet-sync

Conversation

@ProgenyAlpha

@ProgenyAlpha ProgenyAlpha commented Oct 13, 2026 •

Copy link
Copy Markdown

Summary

Adds an opt-in sync type fleets that sends fleet records: what each of your fleets is doing (state, cargo, mining node and timer, repair and travel timers, hull and shield). Off by default; only sent to targets that enable it.

Why: the existing sync types cover what you own, not what your fleets are doing, so a receiver can't show "mining, full in 40 min" or "warping, arriving 2:10" without screenshots.

fleet records on a local receiver

What changes

  • fleets under [sync] and per target (one SyncOptions row, config.cc untouched). English example only.
  • Client records (src: client), from the existing fleet_watch observer: one per state change, plus a snapshot of all slots at login.
    {"type":"fleet","src":"client","fid":2810669496199887731,"slot":1,"hull_id":1029262994,"level":33,
     "state_name":"Mining","prev_state_name":"Impulsing","is_mining":true,"cargo":382,"cargo_max":7623,
     "node_resource":1779416627,"node_amount":18000,"occupied_since":1792725830,"mining_due":1792729728,"t":1792725834}
    Depending on what the ship is doing they also carry repair_due, travel_due (warp/impulse arrival) and hull_damage (docked only).
  • Server records (src: server): the MyDeployedFleets entity group already reaches HandleEntityGroup. With fleets on it's parsed into system, hull and shield, cargo cap, warp range, strength and pursued_by (a count). Only fleets whose record changed are sent; no ids of other players.
  • Repair jobs include the fleet id when fleets is on.
  • MyDeployedFleetsResponse is in its own stfc.sync.proto because the game doesn't declare it and regenerating the Digit protos would drop it.
  • No new hook, no new server call.

Notes

Verified

Windows, mod built from dev + this change, against a local sync target: warp and impulse with arrival times, mining through to full hold and empty node, fights, a destroyed ship, repair with the job's fleet id, and login snapshots. macOS not tested.

Checks

Local MSVC release build clean; macOS not built locally. No CHANGELOG or version changes.

@ProgenyAlpha
ProgenyAlpha marked this pull request as ready for review October 13, 2026 05:36
@ProgenyAlpha

Copy link
Copy Markdown
Author

Tested in-game on Windows (build from this branch, fleets = true under [sync]): after login the receiver got a 3-fleet first-sync snapshot within ~15 s, then single fleet records on each transition (WarpCharging → Warping → Docked observed), with state_name, hull_id and slot as described. No fast polling, no visible impact on the game.

@ProgenyAlpha
ProgenyAlpha changed the base branch from main to dev October 13, 2026 07:17
@ProgenyAlpha

Copy link
Copy Markdown
Author

Rebased onto dev (the PR target per AGENTS.md) and dropped the non-English example-config edits per the current guideline. Second commit fixes a real bug found in play: HullSpec::Id is read as a 32-bit long, so hull ids past 2^31 (Kumari, Jellyfish) came out negative in the records; the value is now widened as unsigned. Release build on dev: build ok, git diff --check clean.

Comment thread mods/src/patches/parts/sync.cc Outdated
Comment on lines +2764 to +2766
{"state", static_cast<int>(state)},
{"state_name", state_name(state)},
{"prev_state", static_cast<int>(previous)},

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be consistent, shouldn't we include prev_state_name too?

@netniV

netniV commented Oct 22, 2026

Copy link
Copy Markdown
Collaborator

@ProgenyAlpha -- Please see my previous comments and you also need to rebase now as there are conflicts.

@ProgenyAlpha

Copy link
Copy Markdown
Author

I've been working on this significantly since original PR. Will update once I have it dialed in.

BetaOp9 and others added 8 commits October 22, 2026 23:04
Subscribe to fleet_watch from the sync patches when any target enables
`fleets`, and queue one record per FleetState transition:

  {"type":"fleet","fid":<fleet id>,"slot":<0-9>,"hull_id":<hull or 0>,
   "level":<ship level>,"state":<FleetState>,"state_name":"Mining",
   "prev_state":<FleetState>,"t":<unix seconds>}

A full snapshot of all occupied slots is queued as a first sync
(X-PRIME-SYNC: 2) whenever fleet_watch establishes a baseline (login,
fleet topology change) and whenever another category's first sync is
queued. Callbacks run on the game thread and only build JSON and queue
it; HTTP stays on the existing sync worker.

fleet_watch gains an optional Subscription::on_baseline callback.
Default off; documented in every example config.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
HullSpec::Id is read as a 32-bit long and hull ids exceed 2^31 (Kumari is
3005922948), so widening the signed value put negative ids in the records
and name lookups failed for those hulls.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
Client records now carry the home/mining/repairing flags, cargo, and while
mining the node, amount mined and the game's own due time (mining_due).
Repairing fleets carry repair_due. Missing values are left out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
MyDeployedFleets is parsed into src=server fleet records: system, node,
hull/shield, cargo cap, warp range, strength and pursued_by. No other
players' ids. Only fleets that changed are sent.

MyDeployedFleetsResponse lives in its own stfc.sync.proto because the game
doesn't declare it, and regenerating the Digit protos would drop it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
Repair jobs carry the fleet id. They're only sent with fleets on, so
jobs-only receivers see nothing new.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
Client records carry hull_damage while the fleet is docked or destroyed;
the client doesn't keep it current in space, where the server's hull
points are the live value.

The client fills in some values (mining and travel timers, damage) from
server data that arrives after the state change. When the server sends
new data for a fleet, or drops it from the deployed list, or a repair job
arrives for it, that fleet is re-read a second later and resent if those
values changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
While a fleet charges, warps or moves on impulse, client records carry
travel_due, the arrival time from the fleet's timer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNMkDr9v6waKrZ538gutCK
ProgenyAlpha pushed a commit to ProgenyAlpha/mod that referenced this pull request Oct 23, 2026
ProgenyAlpha pushed a commit to ProgenyAlpha/mod that referenced this pull request Oct 23, 2026
@ProgenyAlpha ProgenyAlpha changed the title Sync: opt-in live fleet state ("fleet" records, config key "fleets") Sync: opt-in live fleet state (fleets) Oct 23, 2026
@ProgenyAlpha
ProgenyAlpha requested a review from netniV October 23, 2026 08:02
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.

3 participants