Skip to content

Commit acf9684

Browse files
authored
Merge pull request #13 from peans99/community-data
Name the cargo: opt-in community dataset
2 parents 8251e8c + 219b8ec commit acf9684

24 files changed

Lines changed: 2664 additions & 136 deletions

.github/workflows/release.yml

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,9 @@ jobs:
121121
Your Star Citizen install is found automatically.
122122
123123
Quantum Wake then sits in the notification area. Right-click it to open the
124-
dashboard, show or hide the in-game overlay, or quit; the overlay setting is
125-
remembered. ``Ctrl+Alt+O`` toggles overlay click-through.
124+
dashboard or quit. The in-game overlay is off by default - switch it on from
125+
the dashboard's Settings page or the tray menu, and the choice is remembered.
126+
``Ctrl+Alt+O`` toggles overlay click-through.
126127
127128
Windows will warn that the publisher is unknown - the executable is not code
128129
signed, which costs money a free fan tool does not have. Choose **More info**,
@@ -134,7 +135,9 @@ jobs:
134135
### What it does not do
135136
136137
Reads ``Game.log`` only. Nothing is written to the game directory, no memory is
137-
touched, nothing is injected, and no network request leaves your machine.
138+
touched, and nothing is injected. The app connects to the internet only when
139+
you ask it to - the optional community dataset, from the Settings page - and
140+
never on its own.
138141
139142
Star Citizen must run in Borderless Windowed for the overlay to be visible.
140143
"@

README.md

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,23 +9,26 @@
99
![Windows 10/11](https://img.shields.io/badge/Windows-10%20%2F%2011-0078D6)
1010
![Licence Apache 2.0](https://img.shields.io/badge/licence-Apache--2.0-blue)
1111
![154 tests](https://img.shields.io/badge/tests-154%20passing-4fd48a)
12-
![No network](https://img.shields.io/badge/network-none-46617a)
12+
![Network](https://img.shields.io/badge/network-opt--in%20only-46617a)
1313

1414
Star Citizen writes everything you do to `Game.log` and then rotates it away.
1515
Quantum Wake reads it — the live file and every backup — and gives you back the
1616
flight it recorded: where you have been, what you flew, what you hauled and what
1717
it cost you. A second-screen dashboard, a transparent in-game overlay, and a map
1818
of the whole 'verse with your own trail across it.
1919

20-
It is read-only, entirely offline, and never touches the game.
20+
It is read-only and never touches the game. It connects to the internet only
21+
when you ask it to - the optional community dataset, fetched from the Settings
22+
page - and never on its own.
2123

2224
**[Download `QuantumWake.exe`](https://github.com/peans99/QuantumWake/releases/latest)
2325
and double-click it.** That is the whole installation — one file, no runtime to
2426
install, nothing to unpack or configure. It finds your Star Citizen install
2527
itself, across every fixed drive.
2628

2729
It then sits in the notification area. Right-click to open the dashboard, show
28-
or hide the overlay, or quit; the overlay choice is remembered. `Ctrl+Alt+O`
30+
or hide the overlay, or quit. The in-game overlay is off until you turn it on -
31+
from the Settings page or the tray - and the choice is remembered. `Ctrl+Alt+O`
2932
toggles overlay click-through, and the dashboard is on
3033
<http://127.0.0.1:31337>.
3134

@@ -87,10 +90,11 @@ things here are not in the others:
8790
- **The whole map, not just your trail.** Others plot where you went. This draws
8891
every place it can resolve — 292 of them, against the 72 this install has
8992
actually visited — so the map shows how much 'verse is left, not just a trail.
90-
- **Offline all the way down.** Every other tool that shows real item names
91-
fetches them from UEX, the wiki or scunpacked. This reads `Data.p4k` directly
92-
with its own ZIP64 + ZStd reader, so "no outbound network calls" survives
93-
contact with the naming problem.
93+
- **Offline by default, all the way down.** Every other tool that shows real
94+
item names fetches them from UEX, the wiki or scunpacked. This reads
95+
`Data.p4k` directly with its own ZIP64 + ZStd reader. The single exception is
96+
commodity names, which exist nowhere in the local install - naming them is an
97+
opt-in, one-file community download that never happens without a click.
9498
- **It says what the logs cannot support.** Inferred locations carry a
9599
confidence level, estimates are labelled and capped, and an event CIG removed
96100
produces an explanation rather than a bare zero.
@@ -117,7 +121,9 @@ running Easy Anti-Cheat:
117121

118122
- Reads log files only; nothing is ever written to the game directory
119123
- No memory access, no DLL injection, no DirectX or WinAPI hooking
120-
- No outbound network calls in standalone mode — no CDN, no telemetry
124+
- No CDN, no telemetry, no phoning home. The app connects to the internet only
125+
at your request, from the Settings page - the optional community dataset - and
126+
never on its own
121127
- The overlay is an ordinary top-most window using documented Win32 styles
122128

123129
The trade-off of doing it safely: an always-on-top window is **not** composited
@@ -226,7 +232,7 @@ silently dropped).
226232
- [docs/architecture.md](docs/architecture.md) — decisions and why
227233
- [docs/phase-1-core.md](docs/phase-1-core.md) — parser build log
228234
- [docs/commodity-names.md](docs/commodity-names.md) — why a cargo sale cannot be named
229-
- [docs/commodity-catalogue.md](docs/commodity-catalogue.md)parked: how to learn what sells where
235+
- [docs/commodity-catalogue.md](docs/commodity-catalogue.md)what the game data can and cannot tell us about trade
230236
- [docs/credits.md](docs/credits.md) — every external resource used, and what came from where
231237
- [docs/naming.md](docs/naming.md) — why the project is called Quantum Wake
232238
- [docs/releasing.md](docs/releasing.md) — how a release is cut, and what enforces the version bump

docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Compiled 2026-08-20 against a real install: **SC 4.9.188.23497**, handle `nekron
1717
| [log-simulator.md](log-simulator.md) | The fake-log generator: how to use it and why it reproduces the format's quirks. |
1818
| [untapped-signals.md](untapped-signals.md) | Log signals we have not used yet, ranked, with formats and counts. |
1919
| [commodity-names.md](commodity-names.md) | Why a cargo sale cannot be named, and where the mapping actually lives. |
20-
| [commodity-catalogue.md](commodity-catalogue.md) | Parked: routes to a table of what each kiosk trades, and what each costs. |
20+
| [commodity-catalogue.md](commodity-catalogue.md) | What the DataCore does and does not hold about commodities and shops. |
2121
| [credits.md](credits.md) | Every external resource this app uses, and what was taken from each. |
2222
| [naming.md](naming.md) | Why the project is called Quantum Wake, and what the name had to survive. |
2323
| [landscape.md](landscape.md) | Who else builds on Game.log, what overlaps, and what is still ours. |

docs/commodity-catalogue.md

Lines changed: 125 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,125 @@
1-
# Parked: what commodities can be sold where
2-
3-
Raised 2026-08-21 by nekron, parked to come back to. This is the state of the
4-
question and the routes out of it, written down while the detail is fresh.
5-
6-
The related finding — that a cargo sale in *our own logs* cannot be named — is in
7-
[commodity-names.md](commodity-names.md) and is not repeated here. This page is
8-
about the other half: a **reference table of which kiosk trades which commodity**,
9-
which needs no logs at all, only the game's own static data.
10-
11-
## The three layers between us and it
12-
13-
| Layer | What it is | Where we stand |
14-
|---|---|---|
15-
| **Archive encryption** | `Data.p4k` is a ZIP64 container; CryEngine/Lumberyard encrypts some entries | Partly a non-issue. The localisation table is *not* encrypted and `P4kArchive` already reads it, which is where 9,527 item and 1,343 place names come from. Encrypted entries are reported, never guessed at. |
16-
| **CryXMLB** | XML compiled to a binary format; opens as junk in a text editor | Not hit yet. The files read so far are plain. Community tools (`unforge`, `CryXMLConverter`) convert it, and the format is documented. |
17-
| **DataForge** | `Data\Game2.dcb`, the record database — ships, items, shops, prices | **Readable.** 330 MB, unencrypted, extractable today with `P4kArchive`. It holds the commodity catalogue: `libs/foundry/records/entities/commodities/minerals/dolivine.xml`, `.../natural/sunsetberry.xml`, `.../scrap/scrap.xml`. |
18-
19-
The community's account of these layers is accurate, but on this install the
20-
DataCore is *not* the wall. It is open. What we have not done is **parse** it —
21-
every search so far has been a raw byte scan, which finds strings and misses
22-
structure. A DataForge reader resolves records, enums, string tables and
23-
pointers, and only then can a shop record be asked what it stocks.
24-
25-
## The routes, and what each costs
26-
27-
**1. Write a DataForge reader.** Parse `Game2.dcb` from the user's own install,
28-
the way `P4kArchive` already parses the container. Offline, no redistribution, no
29-
new dependency, and it either answers the question or proves the answer is not
30-
in there. The format is community-documented and `ScDataDumper` is a working
31-
reference implementation to check behaviour against.
32-
33-
*Recommended.* It is the only route that keeps every promise the README makes.
34-
35-
**2. Ship pre-extracted JSON** from `StarCitizenWiki/scunpacked-data`.
36-
Fastest by far, and it directly contradicts our own `NOTICE`: *no game data is
37-
contained in this repository, and none may be added to it*. It also redistributes
38-
data derived from CIG's build. Rejected unless that policy changes deliberately.
39-
40-
**3. Fetch UEX or scunpacked at runtime.** Would give live prices too, which is
41-
genuinely useful for trading and is what most neighbours do. It breaks "no
42-
outbound network calls", which is the thing that distinguishes this app in
43-
[landscape.md](landscape.md). Only ever as an opt-in that is off by default and
44-
says plainly what it contacts.
45-
46-
**4. Decrypt `Data\ShopInventories\*.json`.** These are the shop stock tables and
47-
are the most likely home of the `resourceGUID` mapping. They are deliberately
48-
encrypted. Reading what CIG left open is one thing; circumventing a protection
49-
measure they chose to apply is another, and it would break on any key change
50-
besides. **Not planned.**
51-
52-
## What to try first, if this is picked up
53-
54-
1. Extract `Data\Game2.dcb` with the existing `P4kArchive` — already proven.
55-
2. Parse the DataForge header: structure definitions, property tables, enums,
56-
string tables, then records.
57-
3. Look for shop or kiosk records that reference commodity records, and for any
58-
id form matching the four `resourceGUID` values in the logs.
59-
4. If the mapping is there, the Cargo view gains real names and a
60-
"where to sell this" reference, entirely offline.
61-
5. If it is not, say so here, and the decision becomes route 3 or nothing.
62-
63-
Whatever comes of it, the rule from [architecture.md](architecture.md) holds: if
64-
a name cannot be established, show what is provably known and stay quiet about
65-
the rest rather than guessing from unit price.
1+
# What commodities can be sold where
2+
3+
Raised 2026-08-21 by nekron. Route 1 — write a DataForge reader — was tried the
4+
same day. This page is now the result rather than the plan.
5+
6+
**The short answer: half of it is possible offline, and the interesting half is
7+
not.** The commodity catalogue is in the DataCore and can be read today. Which
8+
kiosk trades which commodity is not in there at all, and neither is the join that
9+
would name a sale in our own logs.
10+
11+
The related finding — that a cargo sale cannot be named from the log alone — is
12+
in [commodity-names.md](commodity-names.md).
13+
14+
## What was done
15+
16+
`Data\Game2.dcb` was pulled out of `Data.p4k` with the existing `P4kArchive`,
17+
no external tool involved, and examined in four passes. It is **330,491,142
18+
bytes**, unencrypted, and its header reads cleanly: version 8, then the
19+
definition counts — **6,685 structs, 23,722 properties, 772 enums, 116,512
20+
records**.
21+
22+
So the community's account of the three protection layers is accurate in
23+
general, and beside the point here: on this install the DataCore is open.
24+
25+
## 1. The commodity catalogue is there
26+
27+
**135 commodity records**, named and categorised:
28+
29+
| Category | | Category | | Category | |
30+
|---|---:|---|---:|---|---:|
31+
| minerals | 21 | manmade | 12 | agriculturalsupplies | 4 |
32+
| metals | 17 | gas | 7 | halogens | 4 |
33+
| vice | 17 | processedgoods | 5 | food | 3 |
34+
| natural | 16 | alloys | 4 | counterfeit | 3 |
35+
| consumergoods | 12 | medicalsupplies | 3 | scrap | 2 |
36+
| mixedmining | 2 | non_metals | 2 | waste | 1 |
37+
38+
Real names, not ids: `aphorite`, `bexalite`, `dolivine`, `agricium`,
39+
`quantumfuel`, `rmc`, `sunsetberry`, `altruciatoxin`. This is a usable reference
40+
table and it costs nothing but a parser.
41+
42+
Shops are represented too, but only as **brands**: 58 kiosk manufacturer records
43+
and 58 brand styles — CenterMass, Casaba, Astro Armada, Cordry's. The app
44+
already resolves those from the localisation table.
45+
46+
## 2. The kiosks are not
47+
48+
The log names shops as `SCShop_OmegaPro_NewBabbage` and
49+
`SCShop_Admin_lt_base_g`. The DataCore contains **zero strings beginning
50+
`SCShop`**. The only location-flavoured shop records are seven UI map section
51+
definitions (`shop_admin`, `shop_centermass`, `shop_wallys` and four more),
52+
which are map furniture, not stock lists.
53+
54+
There is no shop→commodity table in this file. Nothing to parse harder for.
55+
56+
## 3. The join is not there either
57+
58+
Every `resourceGUID` this install has ever logged was extracted — **13 distinct
59+
ids across 146 log files** — and each was searched through the whole DataCore in
60+
three forms: ASCII text, little-endian bytes, big-endian bytes.
61+
62+
**None of the 13 appears, in any form.** That settles the question the earlier
63+
note left open: the ids in the sale log belong to a different numbering from
64+
anything the DataCore holds. (The earlier note said four ids; the true figure
65+
across every backup is thirteen.)
66+
67+
## 4. There is no second copy
68+
69+
The DataCore is compiled from source records, so the archive was checked for
70+
those too — `Data\Libs\Foundry\Records\...` in both slash styles and both cases,
71+
five root spellings. **All misses.** The compiled database is the only copy in
72+
the archive.
73+
74+
## Where that leaves it
75+
76+
| Want | Possible offline? |
77+
|---|---|
78+
| A catalogue of every commodity, by category | **Yes.** 135 records, names and all, from the user's own install |
79+
| Which brand a kiosk belongs to | **Yes**, and already done |
80+
| What a given kiosk buys or sells | **No** — not in the DataCore. Community data has it; see below |
81+
| Naming a commodity in our own sale log | **Not offline** — solved via the opt-in community dataset; see below |
82+
83+
The last two most likely live in `Data\ShopInventories\*.json`, which ships
84+
encrypted. Reading what CIG leaves open is one thing; circumventing a protection
85+
measure they deliberately applied is another, and it would break on any key
86+
change besides. Still not planned.
87+
88+
## The break: the community already resolved the join
89+
90+
Checked the same day, at nekron's prompting: **StarCitizenWiki/scunpacked-data**
91+
carries `resources/commodities.json` — 243 KB, regenerated after each game
92+
patch — and it resolves **every resourceGUID this install has ever logged**.
93+
All of them, tested, not sampled: the sales were DynaFlex, Waste, Tin, Stims,
94+
Medical Supplies, Iron, Copper, Aluminum, Nitrogen, Hydrogen, Hephaestanite and
95+
a Year of the Rat Envelope.
96+
97+
Seven further byte-order permutations were tried against the DataCore first
98+
(CryEngine's CigGuid has its own layout) — all misses, so the id genuinely is
99+
not recoverable from the local install. The community file is the only source.
100+
101+
**Shipped as an opt-in.** The repository carries no licence and the data is
102+
CIG-derived, so it is not vendored into this repository or the binary — that
103+
decision is not ours to make. Instead the Cargo page offers a button that
104+
fetches the one file into local app data, with the source named and the promise
105+
stated: it is the only network request the application can make, and it never
106+
happens without the click. `CommunityData` in the Data project holds the
107+
mechanics; the README's network claims carry the exception.
108+
109+
## Still open: what sells where, on the map
110+
111+
The same repository has `resources/commodity_trade_locations.json` (27.9 MB):
112+
per commodity, the facilities that buy and sell it, with class names like
113+
`DC_Stan_Hurston_S1_Farnesway_CargoShop` that our resolver's grammar can meet.
114+
That is the map-enrichment half of nekron's ask — "sell Waste here" markers —
115+
and it is a second, larger piece of work: download opt-in alongside the first
116+
file, parse, and join facility class names onto atlas nodes. Parked until the
117+
naming slice has settled.
118+
119+
## If the offline catalogue is still wanted
120+
121+
Parsing 135 records out of the DataCore needs the DataForge structure walked
122+
properly. The header is understood (above), which is the part that usually
123+
stops people. But with the community file resolving ids for anyone who opts in,
124+
the offline catalogue would only serve those who decline — worth doing someday
125+
for completeness, not first.

docs/commodity-names.md

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# Can we name what was sold?
22

3-
Short answer: no, and not for want of looking. The blocker is real and specific.
3+
Short answer: **not from the local install** — the blocker below is real and was
4+
verified three ways, then four more. But the community publishes the missing
5+
table, and the app now names cargo through it as an opt-in: see
6+
[commodity-catalogue.md](commodity-catalogue.md). The rest of this page is the
7+
evidence for why the offline route fails, kept because it took real work to
8+
establish and the next patch will tempt someone to re-litigate it.
49

510
## What the log gives
611

@@ -16,9 +21,11 @@ A cargo sale is fully described except for the one field that matters:
1621
```
1722

1823
Money, volume, box layout, mode and kiosk — all exact. The commodity appears
19-
only as `resourceGUID`, and that id is never repeated anywhere in any of the
20-
144 backup logs alongside a name. Four distinct ids show up across the whole
21-
history.
24+
only as `resourceGUID`, and that id is never repeated anywhere in the logs
25+
alongside a name. **Thirteen** distinct ids show up across the full history of
26+
146 log files — an earlier figure of four here came from a sample rather than
27+
from every backup, and is corrected in
28+
[commodity-catalogue.md](commodity-catalogue.md).
2229

2330
Buys carry one extra field, `shopPricePerCentiSCU`, which gives an exact unit
2431
price but still no name.
@@ -32,7 +39,7 @@ place to look, and it does hold the commodity catalogue —
3239
`.../natural/sunsetberry.xml`, `.../scrap/scrap.xml` — plus 24,442 guid-shaped
3340
strings.
3441

35-
All four log ids were searched through the entire file three ways:
42+
All thirteen log ids were searched through the entire file three ways:
3643

3744
| Form | Result |
3845
|---|---|

docs/credits.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,12 @@ below are theirs, re-implemented.
2626
| [AutoTrackR2](https://github.com/BubbaGumpShrump/AutoTrackR2) | BubbaGumpShrump | Studied for its live-tail loop and overlay approach. |
2727
| [SC-Kill-Monitor](https://github.com/greluc/SC-Kill-Monitor) | greluc | Studied as the cautionary case: one regex, no fallback, total failure when the format moved. |
2828
| [citizenmon](https://github.com/danieldeschain/citizenmon) | danieldeschain | Studied for its tailing strategy. |
29+
| [scunpacked-data](https://github.com/StarCitizenWiki/scunpacked-data) | StarCitizenWiki | **The optional commodity names.** A cargo sale logs the commodity as an id nothing in the local install can resolve; this repository publishes the id-to-name table, regenerated after each patch, and it resolved every id this project had ever logged. Fetched only when the user opts in — never vendored, never fetched silently. |
30+
| [ScDataDumper](https://github.com/octfx/ScDataDumper) | octfx | The loader that generates scunpacked-data from the game files. Not run or shipped here, but the names the opt-in feature shows exist because of it. |
31+
| [UEX](https://uexcorp.space) | UEX Corp and its datarunners | **The optional live prices**, crowd-sourced by players and fetched only at the user's request - and the destination of the optional price reports, where a user with UEX credentials can contribute the sale prices their own logs recorded. |
2932

30-
The comparison of all seven, and what each one does on a current install, is in
31-
[docs/README.md](README.md).
33+
The comparison of the seven log tools, and what each one does on a current
34+
install, is in [docs/README.md](README.md).
3235

3336
## Game data and file formats
3437

0 commit comments

Comments
 (0)