HaRuuuBlog
DATE:2026/5/10

Vanilla FiveMで自作基盤を考える【HaruuuCore初期構成】

INDEX [CLICK TO OPEN] ↓

前回記事

【FiveMを立てる】IaCによるRPサーバー構築と接続確認

前回のFiveM関連ログでは、Ansibleを用いてFiveM RPサーバーを構築し、txAdmin、MariaDB、クライアント接続までを確認しました。

本記事では、既存フレームワークに依存し続けるのではなく、Vanilla FiveMを起点として自作基盤をどのように整理していくかを検討します。

1. Vanilla FiveMで自作フレームワークを始める理由

FiveM サーバー構築の初期検証では、既存フレームワークを利用する構成も確認しました。 ただ、最終的には QBCore などの既存フレームワークに乗り続けるのではなく、Vanilla FiveM を土台にして、自作フレームワークである HaruuuCore を段階的に作っていく方針に切り替えました。

目的は、既存フレームワークを否定することではありません。 FiveM の標準構成で何が起動し、何が不足し、character / money / player state / UI / job などをどこから自作する必要があるのかを、自分の環境で把握するためです。

本記事では、Vanilla FiveM 上で HaruuuCore を作り始めるために、最初に残した標準 resource、暫定 spawn、playerReady、character / core / money の責務分離を整理します。 この記事は完成済みフレームワークの紹介ではなく、実環境ベースの初期設計ログです。

2. FiveM標準resourceを残す初期方針

Vanilla 環境だからといって、FiveM 標準 resource をすべて外すわけではありません。 最初から spawn、session、map、chat まで完全に自作すると、接続直後の初期化や spawn 処理で切り分ける対象が増えすぎます。

そのため、初期状態では FiveM 標準 resource を残し、HaruuuCore 側では character、core state、money など、自作フレームワークとして必要になる領域から段階的に整理します。

ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager
ensure fivem
ensure hardcap
ensure rconlog

ensure oxmysql

ensure hc_minimal
ensure hc_character
ensure hc_core
ensure hc_money
ensure hc_progression
ensure hc_job_delivery
ensure hc_character_ui
ensure hc_test

mapmanager、spawnmanager、sessionmanager、fivem は、接続や標準 spawn の土台として維持します。 chat はコマンド結果や検証ログの表示に使い、hardcap と rconlog も標準の接続・ログ基盤として残します。

DB 連携には oxmysql を使い、その後ろに HaruuuCore の resource を起動します。 現時点ではすでに hc_progression や hc_job_delivery も存在していますが、この記事では初期基盤として重要な hc_minimal、hc_character、hc_core、hc_money を中心に扱います。

3. HaruuuCoreの最小resource構成

HaruuuCore は、1つの巨大な resource にすべてを詰め込むのではなく、役割ごとに resource を分ける方針にしています。 現在の resources/[hc] 配下には、character、core、money、progression、job、UI、test 用 resource が分かれています。

resources/[hc]/
├── hc_minimal
├── hc_character
├── hc_core
├── hc_money
├── hc_progression
├── hc_job_delivery
├── hc_character_ui
└── hc_test

この記事の範囲では、まず次の4つを HaruuuCore の初期基盤として扱います。

  • hc_minimal: 暫定 bootstrap、空港移動、playerReady 通知
  • hc_character: character DB / API、identifier と character_id の管理
  • hc_core: Players[source]、state、ready、characterId の管理
  • hc_money: character_id ベースの cash / bank 管理と表示同期

hc_character_ui、hc_progression、hc_job_delivery は、すでに後続の検証対象として存在しています。 ただし、これらは初期基盤の上に乗る機能として扱い、本記事では詳細には踏み込みません。

4. hc_minimalによる暫定spawnとplayerReady

初期段階で特に扱いが難しかったのは spawn です。 FiveM では、接続直後に ped をどこで生成するか、どのタイミングで script 側の準備完了とみなすかを慎重に扱う必要があります。

最初から server-driven な完全自作 spawn を作ろうとすると、black screen や Awaiting scripts から抜けない状態になりやすく、character や money の検証に進みにくくなります。 そのため、現時点では FiveM 標準の spawnmanager / basic-gamemode を残し、spawn 後に hc_minimal が空港座標へ移動させる方式を採用しています。

FiveM standard spawn
  ↓
hc_minimal client spawn.lua
  ↓
airport 座標へ移動
  ↓
hc_minimal:server:playerReady

現在の安定座標は、ロスサントス国際空港付近に固定しています。 この座標は、現時点の HaruuuCore baseline で接続確認と動作確認を行うための暫定位置です。

local AIRPORT_SPAWN = {
    x = -1037.72,
    y = -2738.04,
    z = 20.17,
    heading = 328.0
}

ここでの playerReady は、完成された gameplay ready ではありません。 まずは「標準 spawn 後に空港へ移動できた」「以降の resource が最低限の処理を開始できる」という意味の ready として扱っています。

5. character / core / money の責務分離

Vanilla FiveM では、既存フレームワークが持っていた player state、character、money などの概念を自分で整理する必要があります。 HaruuuCore では、最初に source、identifier、character_id を分けて考える方針にしました。

source:
  接続中だけの一時 player handle

identifier:
  player account を識別する値
  現在は license identifier を優先

character_id:
  DB上のcharacter永続ID
  money / progression / job / ownership / stats の基準

source は接続中だけの一時的な handle なので、reconnect によって変わります。 そのため、money や progression のような永続データの基準にはしません。 永続的な gameplay データは、最終的に character_id を基準に扱う方針です。

// 1. hc_character

hc_character は、character DB と character API を担当します。 license identifier をもとに character を管理し、slot、active / deleted、logical delete、select などの character 関連処理を扱います。

重要なのは、hc_character が player state 全体を抱え込まないことです。 character の永続データや slot payload は扱いますが、core state、money、job、NUI の状態までは担当しません。

// 2. hc_core

hc_core は、Players[source] を持つ backbone として扱います。 source、identifier、characterId、state、ready、joinedAt を集約し、character が選択されたタイミングで他 resource が参照できる player state を更新します。

joining
character_selecting
character_loaded
ready

character 未選択の状態で playerReady が来ることは、現時点では異常ではありません。 その場合は state=character_selecting、ready=false、characterId=nil として扱い、Select 後に ready=true へ移行します。

// 3. hc_money

hc_money は、character_id ベースの cash / bank を担当します。 client は表示用であり、正本は server / DB 側に置く方針です。

表示については、GTA の ESC メニュー側の cash / bank 表示に同期しつつ、通常 gameplay 中の top-right money HUD は隠す方向で検証しています。 money 操作を source 単位ではなく character_id 単位に寄せることで、将来的な job、property、ownership、progression と接続しやすくします。

6. 初期基盤として残した課題

この段階では、HaruuuCore のすべてを完成させることは目的にしていません。 まずは Vanilla FiveM の標準基盤を壊さずに、character / core / money の責務を切り出し、後続機能を載せられる状態を作ることを優先しています。

そのため、現時点であえて深追いしていないものがあります。

  • 完全自作 spawn resource の作成
  • server-driven spawn / clientReady / allowSpawn flow の再導入
  • character 選択後の本格 spawn 演出
  • NUI の詳細設計
  • money 表示の細かい UI 調整
  • progression / job / economy の詳細実装

特に spawn 周りは、今後 hc_spawn のような専用 resource に分離する可能性があります。 ただし、現時点では FiveM 標準 spawn を残すことで、接続、空港移動、character 選択、money 同期、job 検証に進める状態を優先しています。

7. 次に進めるHaruuuCoreの領域

Vanilla FiveM 上で自作フレームワークを作る場合、最初にすべてを作り込むよりも、標準 resource と自作 resource の境界を決めることが重要でした。

今回の初期整理により、HaruuuCore では次の方向へ進める土台ができました。

  • character_id を基準にした character 管理
  • Players[source] による player state 管理
  • cash / bank の character_id ベース管理
  • character selection UI
  • rank / XP / progression
  • delivery job などの gameplay resource
  • 生活・経済・犯罪リスクを含むソロ向け world design

次の段階では、character / core / money の責務分離をさらに詳しく整理し、source、identifier、character_id を分ける理由を記事としてまとめます。

INDEX [BACK TO SECTION] ↓