所持金をcharacter_idに紐づける理由
HaruuuCore では、接続中の player を表す source、アカウント側の識別子である identifier、ゲーム内キャラクターの実体である character_id を分けて扱います。
money もこの方針に合わせて、player account ではなく selected character に紐づく値として扱います。
1つの identifier が複数の character slot を持てる場合、所持金を identifier に直接紐づけると、別キャラクター間で cash / bank が混ざります。
そのため、HaruuuCore では hc_money を character_id ベースの money resource として整理します。
この作業では、cash / bank を DB に保存し、選択中 character の money を client へ同期し、GTA 標準の ESC メニュー表示まで反映できる状態を確認しました。
hc_moneyが担当する範囲
hc_money は、money の値と同期を担当する resource です。
character selection そのものは担当しません。
どの character を操作中にするかは hc_character と hc_core の責務であり、hc_money は選択済み character を基準に cash / bank を扱います。
hc_money:
character_id based money
cash
bank
DB-backed money values
GTA STAT / ESC money display sync
normal top-right HUD suppression
cash change notification preservation逆に、hc_money は character を選択しません。
slot browsing 中に money target を変えず、select が完了して selected character が決まってから money の同期対象を確定します。
hc_money が担当しないこと:
character selection
character slot payload
NUI
rank / XP
job
inventory
shop
banking UI
smartphone UIcashとbankを分ける
現時点の money account は、cash と bank の2種類です。
cash は手元の現金、bank は銀行残高として扱います。
money accounts:
cash
bank将来的には banking UI、ATM、salary、tax、property payment などを追加できます。 ただし、現時点では UI や経済設計を広げる前に、character_id 単位で cash / bank を保存し、同期できる状態を優先します。
まずは「誰の money なのか」を明確にする段階です。
そのため、cash / bank の source of truth は selected character の character_id に紐づく DB 上の値として扱います。
character未選択時は同期しない
hc_money は selected character を前提に動きます。
character がまだ選択されていない状態では、money の対象になる character_id が決まっていません。
character未選択:
selected character_id = nil
money target = nil
money sync = skipこの状態で money sync が skip されるのは異常ではありません。 character selection UI で slot を眺めているだけの状態では、まだ money target を切り替えません。
money の同期対象が変わるのは、character を明示的に select したときです。
select が成功し、hc_core 側の player state に selected character_id が入ってから、hc_money がその character の cash / bank を同期します。
slot browsing:
money targetは変わらない
create character:
money targetは変わらない
select character:
money targetがselected character_idへ変わるDBの値をmoney stateとして扱う
現時点では、cash / bank は character table 側の値として保存しています。
将来的に account table を分ける可能性はありますが、まずは hc_characters に紐づく money value として扱います。
hc_characters
├── id
├── identifier
├── slot
├── first_name
├── last_name
├── cash
├── bank
└── ...hc_money は、selected character の cash / bank を DB から読み込み、server 側の money state として扱います。
money を変更した場合は DB に保存し、client へ同期します。
money update:
selected character_idを確認する
cash / bankを更新する
DBへ保存する
clientへ同期する
GTA STATへ反映するこの段階では、money の永続化と同期を成立させることが目的です。 UI としての銀行画面や取引履歴はまだ扱いません。
money操作をexportsにまとめる
money の変更は、resource 内外から同じ手順で扱えるように exports にまとめます。
job reward、shop payment、test command などが money を直接書き換えるのではなく、hc_money の API を経由する形にします。
exports:
getMoney(source, account)
setMoney(source, account, amount)
addMoney(source, account, amount)
removeMoney(source, account, amount)
hasMoney(source, account, amount)
syncMoney(source)account には cash または bank を渡します。
amount は負の値にならないように扱い、上限は GTA / STAT 側との相性も考えて安全な範囲に収めます。
外部 resource は、money の保存場所や同期方法を意識しません。
たとえば配達ジョブが報酬を渡す場合も、addMoney(source, “cash”, amount) のように呼び出すだけにします。
GTA STATへ同期する
FiveM では、GTA 側の既存表示を使うために STAT へ値を同期できます。 HaruuuCore では、独自の常時 money HUD を作るのではなく、GTA 標準の money 表示と連携する方針にしました。
cash:
MP0_WALLET_BALANCE
bank:
BANK_BALANCEserver で money を更新したあと、client に cash / bank を送り、client 側で STAT を更新します。 これにより、ESC メニュー側の money 表示に反映されます。
server:
cash / bankを更新
DBへ保存
clientへsync
client:
StatSetInt(MP0_WALLET_BALANCE, cash)
StatSetInt(BANK_BALANCE, bank)独自 UI で money を常時表示するより、既存の GTA UI に寄せたほうが、画面の情報量を増やさずに済みます。 まずは ESC メニューで確認できる状態を正とします。
ESCメニュー表示を使う
最終的な表示方針は、通常 gameplay 中に money を常時見せるのではなく、ESC メニュー側で確認できるようにすることです。 cash / bank の値は STAT に同期し、ESC メニュー右上の既存表示に寄せます。
通常プレイ中:
money HUDは常時表示しない
ESCメニュー:
cash / bankをGTA標準表示に同期する
money増減時:
GTA標準の +$ / -$ 通知は残すこれにより、money を確認したいときは ESC メニューを開き、通常プレイ中は画面をすっきり保てます。 HaruuuCore の初期方針では、スマホ UI や銀行 UI をまだ作っていないため、既存の GTA 表示を活用します。
通常HUDのmoney表示は隠す
GTA の money 表示をそのまま出すと、通常 gameplay 中の右上に cash / bank の表示が残りやすくなります。 HaruuuCore では、通常プレイ中の money HUD は隠す方針にしています。
normal gameplay:
hide HUD component 3
hide HUD component 4
pause menu:
ESCメニュー側の表示は使うここで重要なのは、STAT 同期と通常HUD表示を分けて扱うことです。 STAT は ESC メニュー表示のために同期します。 しかし、通常画面の右上に money を常時出し続ける必要はありません。
そのため、client 側では通常プレイ中に money HUD component を抑制し、pause menu 側では同期済みの値を確認できる状態にします。
+$と-$の通知は残す
通常HUDの money 表示は隠しますが、money が増減した瞬間の GTA 標準通知は残します。 報酬や支払いの反応が何もないと、操作結果が分かりにくいためです。
残す:
+$ 通知
-$ 通知
隠す:
通常画面右上の常時money表示たとえば配達報酬で cash が増えた場合、画面右上に一時的な +$ 通知が出ます。
これは gameplay feedback として有効なので、常時表示とは別扱いにします。
今回のアイキャッチでも、money 増加時の +$ 通知が見える状態を使います。
これは、hc_money が単に DB を更新するだけではなく、GTA 側の money feedback とも接続していることを示す画面です。
テストコマンドで確認する
money の挙動は、まず debug command で確認します。 本番 gameplay の job や shop より先に、cash / bank の更新、DB 保存、client 同期、ESC 表示を単体で確認するためです。
/money/money では、現在選択中 character の cash / bank を確認します。
character が未選択の場合は、money target がないため同期対象がありません。
/cash 5000
/bank 10000
/money/cash と /bank は、cash / bank を直接設定する確認用 command です。
設定後に /money を実行し、server 側の値が変わっていることを確認します。
/addcash 5000
/removecash 1000
/addbank 2000
/removebank 500加算と減算の command では、money の増減処理と通知を確認します。
cash の増減では、GTA 標準の +$ / -$ 通知が表示されるかも見ます。
/hascash 1000
/hasbank 1000
/money_resync/hascash と /hasbank では、指定額を持っているかを確認します。
/money_resync では、DB 側の値と client 側の STAT 表示を同期し直します。
hc_testから統合確認する
hc_test 側にも、money の統合確認用 command を用意しています。
これは、hc_money の exports を他 resource から呼び出す確認として使います。
/paytest 100
/rewardtest 500
/bankpaytest 100
/moneychecktest/paytest は cash が足りるかを確認してから支払い処理を行います。
/rewardtest は cash 報酬を追加します。
/bankpaytest は bank から支払います。
/moneychecktest は cash / bank の状態を確認します。
この段階で見たいのは、money API が単体 command だけでなく、別 resource から呼ばれても同じように動くことです。 job reward や shop payment は、将来的にこの形へ接続します。
確認した流れ
久しぶりに money の挙動を確認する場合は、character を選択してから money command を実行します。 character 未選択のままでは、money target が決まっていないためです。
/charuiまず character selection UI を開き、操作対象の character を選択します。
command で確認する場合は、/selectchar 1 のように slot を指定して選択します。
/selectchar 1
/money
/addcash 5000
/money
/money_resynccash を加算したあと、/money で server 側の値を確認し、ESC メニューで表示も確認します。
画面右上の常時 money HUD が出ていなくても、それは意図した状態です。
/tpcoords -1037.72 -2738.04 20.17 328.0場所をそろえて検証したい場合は、空港付近へ teleport して確認します。 UI や通知を撮影するときも、背景を固定しておくと記事用スクリーンショットを整理しやすくなります。
所持金同期で到達した状態
この作業で、HaruuuCore は selected character に紐づく cash / bank を扱えるようになりました。 money は identifier 直下ではなく、character_id 単位の gameplay data として同期します。
確認済み:
selected character_idをmoney targetにできる
cash / bankを分けて扱える
DB-backed money valueとして保存できる
getMoney / setMoney / addMoney / removeMoney / hasMoneyを使える
money更新後にclientへ同期できる
GTA STATへcash / bankを反映できる
ESCメニューでmoneyを確認できる
通常画面右上のmoney HUDを隠せる
+$ / -$ の通知を残せる
hc_testからmoney exportsを呼び出せるまだ扱っていないものもあります。 銀行 UI、ATM、shop、inventory、salary、tax、property payment、smartphone banking、取引履歴などは未実装です。
ただし、character_id 単位で money を保存し、GTA 標準の ESC 表示と増減通知へ接続できたことで、job reward や支払い処理を追加するための土台は作れました。
