TheTree_mock/docs/FACILITY_DATA_DESIGN.md

施設詳細データ設計

• 文書ID: DATA-FACILITY-001
• 版: 0.2.0
• 状態: 実装基準
• 最終更新日: 2026-08-27

1. 目的と正本範囲

本書は、施設の静的定義、設置後の可変状態、日次・累計統計を分離し、施設追加やバランス変更でセーブデータを壊さないための正本である。ゲームルールはGAME_SPECIFICATION.md、実行順と障害時処理はSYSTEM_SPECIFICATION.mdを優先する。

施設の数値は次の3層へ分ける。

層	所有者	例	保存
Definition	コンテンツ	サイズ、建設費、提供サービス、必要職種	.tres。原則不変
Instance	セーブデータ	座標、レベル、耐久、配置職員、行列、現在Policy	Snapshotへ保存
Statistics	運営履歴	当日売上、処理客数、平均待ち時間、事故数	日次締めで集約して保存

Definitionへ「現在の汚れ」や「今日の売上」を置かず、Instanceへ表示名や基礎価格を複製しない。実行中サービスだけは開始時の価格、品質、所要時間、PolicyをSnapshotとして保持する。

2. Schema Version

version	用途	検証
1	既存施設の互換読込	従来必須値のみ
2	詳細施設定義	本書の詳細項目を厳密検証

definition_schema_version = 2を宣言した定義は、不足値を暗黙補完しない。古い定義はversion 1のまま読み込めるため、施設を1件ずつ検証して移行できる。versionを上げるだけの一括変換は禁止する。

3. FacilityDefinition version 2

3.1 識別・分類

フィールド	型	規則
id	StringName	小文字snake_case、永続的に変更しない
display_name	String	UI表示名
description	String	プレイヤー向け説明
category	StringName	lodging、guest_service、production等
service_types	Array[StringName]	施設が提供できるサービスID。1件以上
default_service_type	StringName	service_types内の既定サービス
service_profiles	Dictionary	全service typeに1対1で対応
tags	Array[StringName]	検索、隣接、ルール判定用の一意なID

3.2 配置・接続

フィールド	規則
zone / layer	地上・境界・地下とFRONT・BACKを別軸で指定
footprint	未回転状態の幅・高さ。各辺1以上
allowed_rotations	0/90/180/270の重複なし配列
guest_access_offsets	客がサービスへ入るFootprint内セル
staff_access_offsets	職員・物流が入るFootprint内セル
required_connection_tags	稼働に必須の通路・ネットワーク種別
preferred_adjacency_tags	効率や選好の加点候補
forbidden_adjacency_tags	配置拒否または重大減点となる隣接

Access offsetは未回転Footprintの左上を(0, 0)として記述し、配置時にoriginとrotationからWorld座標へ変換する。通過設備を除く施設は、客用または職員用Accessを最低1つ持つ。

3.3 建設・維持・成長

construction_costはGoldとMaterials、build_minutesは工期、weight_per_cellは構造負荷を表す。demolition_refund_percentは未予約資産に対する標準返却率で、事故・強制撤去補正は実行時に別途適用する。

max_levelは1～5、upgrade_costsはLv1→2から順に正確にmax_level - 1件を持つ。アップグレード後もDefinitionは変えず、Instanceのlevelとレベル別補正式で性能を求める。

維持費はmaintenance_gold、Manaはmaintenance_mana、停電時の配電順はpower_priorityで表す。

3.4 人員・営業

staff_min未満では新規サービスを開始せず、staff_maxを超える職員を稼働人員へ数えない。required_rolesは必要職種、primary_skillは品質計算の主技能である。

opening_scheduleは次の3キーだけを持つ。

キー	意味
morning	06:00の日次境界から始まる朝営業
day	昼営業
night	夜営業

日次締めは06:00に行い、同じ境界で前夜営業を閉じて朝営業へ切り替える。具体的な時刻帯はClockの正本に従い、Definitionへ時刻を重複保持しない。

3.5 Service Profile

各service_profiles[service_type]は次の5項目を必須とする。

項目	型・範囲	意味
duration_minutes	int、1以上	1回の基礎所要時間
base_quality	int、0～100	人員・環境補正前の品質
base_price	int、0以上	Policy補正前の基礎価格
capacity_units	int、1以上	同時処理人数または1バッチの生産単位
need_effects	Dictionary[StringName, int]	欲求ごとの変化量、各-100～100

need_effectsは負値を欲求不足の解消、正値を悪化として統一する。厨房のような中間生産は、客の欲求を直接変えないため0を指定し、実際の在庫産出はinventory_outputsで表す。

例:

service_types = [&"check_in", &"check_out"]
default_service_type = &"check_in"
service_profiles = {
    &"check_in": {
        &"duration_minutes": 8,
        &"base_quality": 60,
        &"base_price": 20,
        &"capacity_units": 1,
        &"need_effects": {&"sleep": 0},
    },
    &"check_out": {
        &"duration_minutes": 6,
        &"base_quality": 60,
        &"base_price": 0,
        &"capacity_units": 1,
        &"need_effects": {&"sleep": 0},
    },
}

旧base_service_minutes、base_quality、base_price、capacityはversion 1と現Runtimeの互換入口として当面残す。version 2の新規処理はservice profileを正本とし、移行期間中は既定profileと旧値の差分をテストで監視する。

3.6 在庫・環境・リスク

• inventory_inputs / inventory_outputs: 1サービスまたは1バッチの予約・産出量。
• cleanliness_decay_per_service / noise_per_service / heat_per_service: 完了時の発生値。
• beauty_effect / security_effect / concealment_effect: 設置中の環境寄与。
• incident_weights: 事故IDと非負の相対重み。確率そのものではない。

3.7 Policy

policy_schemaはPolicy IDごとに型と既定値を宣言する。

&"reservation_only": {&"type": &"bool", &"default": true}
&"price_mode": {&"type": &"enum", &"default": &"standard"}
&"quality_target": {&"type": &"int", &"default": 55}

現在の必須キーはtypeとdefaultで、typeはbool、enum、intのいずれかとする。選択肢、最小・最大、解禁Level、変更猶予は次のSchema拡張で追加し、未知キーを読込側で勝手に解釈しない。

3.8 客層・成人向け安全境界

allowed_guest_tagsとforbidden_guest_tagsは候補抽出の入口であり、予約・入室・サービス開始の3地点で再検証する。adult_content = trueの施設は必ずadult_onlyタグと、一般向け表示へ置換できるcontent_replacement_idを持つ。置換先は成人向け施設を参照してはならない。

3.9 解禁と統計

unlock_rankは1～7、research_requirementsは全件満足を原則とする。statistics_keysは施設固有の収集項目を宣言し、共通の売上・稼働率と分離する。定義に存在しない統計キーをセーブから消さず、旧版履歴として読取専用保持する。

4. FacilityInstance

Instanceは最低限、次を持つ。

• 識別: instance_id、definition_id、created_at
• 配置: origin、rotation、occupied_cells
• 成長: level、durability
• 稼働: state、state_reasons、opening_override
• 人員: assigned_staff_by_shift、active_staff_ids
• 接客: queue_entries、active_services
• 運営: policy_current、policy_pending
• 資源: local_inventory_id
• 集計: statistics_today、lifetime_statistics

Instanceは必ずdefinition_idから現行Definitionを引き、Definition変更で処理中サービスが変わらないよう、開始済みServiceInstanceだけは算出済みSnapshotを持つ。

5. 日次履歴

06:00の日次締めでstatistics_todayからFacilityDaySummaryを生成する。推奨キーは次の通り。

• business_date、facility_instance_id、definition_id、level
• open_minutes、active_minutes、downtime_by_reason
• services_started、services_completed、services_failed
• guest_processed、average_wait_minutes、average_quality
• gross_revenue、refunds、maintenance_cost、net_contribution
• inventory_consumed、inventory_produced、spoilage_quantity
• incidents_by_type、heat_generated

日次履歴は締め後に書換えず、修正は訂正レコードで行う。Definitionのバランス変更後も過去の売上や品質を再計算しない。

6. 検証と失敗方針

Definition Registryは起動時に全定義を検証し、致命的エラーの定義を検索・建築候補へ公開しない。エラーはcode、definition ID、resource path、field、messageを持ち、順序を決定的にする。

version 2では、ID形式、Access範囲、Upgrade件数、営業時間キー、Service Profile、Policy型、成人向け置換境界を必須検証する。欠損を0や空配列へ補完して稼働させない。

7. 現在の移行状況

施設	version	詳細化の狙い
受付	2	複数サービス、客・職員Access、価格Policy
厨房	2	BACK生産、入力・出力、バッチ単位
成人向け個室	2	夜営業、客層制限、成人向け置換、リスク
その他MVP 13施設	1	互換読込中
拡張16施設	1	通常パレット未解放、順次移行

次の移行順は、一般客室・食堂・酒場・浴場、倉庫・警備、通路・昇降機、地下拡張施設とする。売上施設を先に移行すると、客AI・価格・在庫の縦断検証を早い段階で固定できる。

明示階段（D-036、2026-09-09）

基礎16施設と任意拡張16施設の定義順は保持し、追加インフラ2種を data/facilities/infrastructure/ と FacilityCatalog.INFRASTRUCTURE_FACILITY_PATHS に分ける。通常Runtimeの登録数と建築パレットは基礎16＋階段2の18種。既存Registryの既定ディレクトリ単独走査は基礎16のまま。

ID	表示	サイズ	設置層	建設G／資材／分	通行容量	cost／維持魔力
guest_stairs	客用階段	1×1	FRONT	40／0／10	3	150／0
service_stairs	業務用階段	1×1	BACK	50／0／10	2	150／0

置くセルが上部踊り場で、同じx/layerのy-1へ接続する。下部足場が必要。業務用はstaff権限。旧保存の既設階段は施設定義へ置換せず、旧速度・権限を持つ別の接続所有記録として保存する。