// Protocol Buffer Definition: FreeExile Safe Teleportation & Town Portal Engine
// Schema-First Specification for Teleport Channeling (3.5s Cast, Damage/Move Interrupt),
// 2-Way Town Portal Engine, PoE2 6-Portal Charges, and Boss/Secret Quarantine Locks.

syntax = "proto3";

package freeexile.portal;

option go_package = "freeexile/portal";
option java_package = "com.freeexile.proto.portal";
option csharp_namespace = "FreeExile.Proto.Portal";

// Target Categories for Safe Teleportation
enum TeleportTargetType {
  TARGET_UNSPECIFIED = 0;
  TARGET_PARTY_MEMBER = 1;  // Dịch chuyển đến đồng đội trong party
  TARGET_FRIEND = 2;        // Dịch chuyển đến bạn bè
  TARGET_GUILDMATE = 3;     // Dịch chuyển đến hội viên bang hội
  TARGET_TOWN_PORTAL = 4;   // Dịch chuyển qua cổng Town Portal
}

// Teleport Channel Lifecycle State
enum TeleportChannelState {
  CHANNEL_IDLE = 0;
  CHANNEL_CASTING = 1;      // Đang niệm chú (3.5s)
  CHANNEL_COMPLETED = 2;    // Niệm chú hoàn tất, dịch chuyển thành công
  CHANNEL_INTERRUPTED = 3;  // Bị ngắt quãng (di chuyển hoặc nhận sát thương)
  CHANNEL_FAILED = 4;       // Thất bại do kiểm tra điều kiện đích đến
}

// Interruption & Cancellation Reasons
enum TeleportCancelReason {
  REASON_NONE = 0;
  REASON_MOVEMENT = 1;                // Nhân vật di chuyển (analog mag > 0.05)
  REASON_DAMAGE_TAKEN = 2;           // Nhân vật nhận sát thương từ CombatEngine
  REASON_TARGET_OFFLINE = 3;         // Mục tiêu đã ngắt kết nối
  REASON_TARGET_DIFFERENT_REALM = 4; // Vi phạm cách ly thực cảnh (Realm Firewall)
  REASON_DESTINATION_FULL = 5;       // Instance đích đã đủ 6 người
  REASON_DESTINATION_QUARANTINED = 6;// Khu vực đích đang bị khóa cách ly
  REASON_MANUAL_CANCEL = 7;          // Người chơi chủ động bấm hủy
}

// Anti-Exploit Quarantine Error Codes
enum QuarantineErrorCode {
  QUARANTINE_OK = 0;
  QUARANTINE_BOSS_COMBAT_ACTIVE = 1;     // Đang trong giao tranh Boss, cấm mở portal / trốn chạy
  QUARANTINE_SECRET_CHAMBER_ACTIVE = 2;  // Buồng mật thất đếm ngược đang kích hoạt
  QUARANTINE_MAX_PORTALS_EXHAUSTED = 3;  // Đã hết 6 lượt cổng của bản đồ (0/6)
  QUARANTINE_ZONE_DISALLOWS_PORTAL = 4;  // Vùng cấm mở cổng dịch chuyển
  QUARANTINE_REALM_MISMATCH = 5;         // Khác Thực Cảnh (Standard vs Seasonal)
}

// Real-Time Teleport Channeling Progress
message TeleportChannelProgress {
  string player_id = 1;
  TeleportTargetType target_type = 2;
  string target_id = 3;
  TeleportChannelState channel_state = 4;
  float cast_time_seconds = 5;           // Mặc định 3.5s
  float elapsed_seconds = 6;
  TeleportCancelReason cancel_reason = 7;
  int64 channel_start_timestamp_ms = 8;
}

// 2-Way Town Portal State Link
message TownPortalLink {
  string portal_id = 1;
  string owner_id = 2;
  string wilderness_zone_id = 3;
  string wilderness_instance_id = 4;
  float wilderness_x = 5;
  float wilderness_y = 6;
  string sanctuary_zone_id = 7;          // zone_player_hideout hoặc zone_boundless_sanctuary
  string sanctuary_instance_id = 8;
  float sanctuary_x = 9;
  float sanctuary_y = 10;
  int32 remaining_charges = 11;          // Tối đa 6 lượt cho map instances
  bool is_open = 12;
  int64 created_at_ms = 13;
}

// Request / Response Messages

message StartTeleportChannelRequest {
  string player_id = 1;
  TeleportTargetType target_type = 2;
  string target_id = 3;
}

message StartTeleportChannelResponse {
  bool success = 1;
  float cast_time_seconds = 2;           // 3.5s
  QuarantineErrorCode error_code = 3;
  string error_message = 4;
}

message InterruptTeleportChannelNotice {
  string player_id = 1;
  TeleportCancelReason reason = 2;
  string details = 3;
}

message OpenTownPortalRequest {
  string player_id = 1;
  string current_zone_id = 2;
  string current_instance_id = 3;
  float pos_x = 4;
  float pos_y = 5;
}

message OpenTownPortalResponse {
  bool success = 1;
  TownPortalLink portal_link = 2;
  QuarantineErrorCode error_code = 3;
  string error_message = 4;
}

message EnterTownPortalRequest {
  string player_id = 1;
  string portal_id = 2;
  bool to_sanctuary = 3;                 // true: dã ngoại -> hideout, false: hideout -> dã ngoại
}

message EnterTownPortalResponse {
  bool success = 1;
  string destination_zone_id = 2;
  string destination_instance_id = 3;
  float spawn_x = 4;
  float spawn_y = 5;
  int32 remaining_charges = 6;
  QuarantineErrorCode error_code = 7;
  string error_message = 8;
}

message CheckQuarantineRequest {
  string zone_id = 1;
  string instance_id = 2;
  string player_id = 3;
}

message CheckQuarantineResponse {
  bool is_quarantined = 1;
  QuarantineErrorCode error_code = 2;
  string reason = 3;
}

// Real-Time Notification: Player Death Portal Penalty
message PlayerDeathPortalPenaltyNotice {
  string player_id = 1;
  string portal_id = 2;
  bool portal_closed = 3;
  int32 remaining_charges = 4;
}