chickenbstrips/TheTree_mock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
423fd6dd2e75da926e38b35ac8c435e462b168d9
TheTree_mock/docs/FACILITY_DATA_DESIGN.md
T

10 KiB
Raw Blame History

施設詳細データ設計

  • 文書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・価格・在庫の縦断検証を早い段階で固定できる。

Reference in New Issue View Git Blame Copy Permalink