Skip to content

[Phoenix] Adds Economy Tracking Modules - #189

Open
Frankie-hz wants to merge 2 commits into
phoenixffxi:betafrom
Frankie-hz:economytraack
Open

[Phoenix] Adds Economy Tracking Modules#189
Frankie-hz wants to merge 2 commits into
phoenixffxi:betafrom
Frankie-hz:economytraack

Conversation

@Frankie-hz

Copy link
Copy Markdown

I affirm:

  • I understand that if I do not agree to the following points by completing the checkboxes my PR will be ignored.
  • I understand I should leave resolving conversations to the LandSandBoat team so that reviewers won't miss what was said.
  • I have read and understood the Contributing Guide and the Code of Conduct.
  • I have tested my code and the things my code has changed since the last commit in the PR and will test after any later commits.

What does this pull request do?

I will be very honest in this PR, as usual. Core concept was ran through with AI over almost a combined 15 hours. Each function was hand audited and checked for clarity. Comments were kept short and concise as possible without going into paragraphs explaining things.

Each and every single gill audit was tested by hand, by myself.

Example sql:
image

Adds a gil economy ledger module for Phoenix. Every gil balance change on every character is written to a new audit_gil table with who moved it, why, with whom, and for what item. This gives us a full record of gil entering and leaving the economy, per character and per source, without editing any core file.

How it works

  • A CPP module (modules/phoenix/cpp/gil_audit.cpp) observes the ITEM_NUM packet the server already pushes for every gil quantity change, so no gil movement can be missed. Incoming packets (shop, guild, bazaar, trade, AH, delivery box) publish short-lived "reasons" that label the next movement; a Lua module (gil_audit_sources.lua) does the same for scripted gil (quest rewards, GM commands, mob drops, Mug, chocobo rental, starting gil) by wrapping the central helpers and calling through unchanged.
  • Movements no single packet can label are attributed through server state instead: gil consumed by an NPC trade during onEventFinish is matched to the character's open trade transaction, and delivery box movements to the open send or receive box.
  • Each row records: balance after, delta (NULL only when no earlier balance was seen), source as a readable name (VendorBuy, Script, GmCommand, ...), source_detail (the helper or packet), counterparty (the player, NPC, or mob on the other side), itemid where one applies, zone, and date.
  • Both legs of one exchange (a trade, a bazaar purchase) share a txn_id, unique across map processes and restarts, so bazaar tax is visible as the difference between legs.
  • Writes are synchronous so a movement inside a DB transaction (AH bid, delivery box claim) rolls back with it. A failed audit write logs an error and never affects gameplay.
  • Settings are seeded by the module itself: map.AUDIT_GIL and map.AUDIT_GIL_MOBS default to on with no settings file changes; an operator can force either off in settings/map.lua.
  • tools/gil_reconcile.py cross-checks the ledger against live char_inventory balances and reports per-source mint/burn totals.

Steps to test these changes

Full test plan with the exact expected row for every scenario (31 tests plus reconciliation checks): Gil Ledge Test Plan

@Frankie-hz
Frankie-hz force-pushed the economytraack branch 5 times, most recently from bb71e55 to 5f752ee Compare August 28, 2026 22:55
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.

1 participant