스텔스 감각 아키텍처: 동적 레이캐스트 시야 콘, 그림자 볼륨 샘플링 및 음향 감쇠 제어

--!strict
-- StealthSensoryController.luau
-- 로블록스 스튜디오용 프로덕션 잠입 감각 제어 엔진

local Workspace = game:GetService("Workspace")
local Players = game:GetService("Players")

export type AlertState = "Unaware" | "Suspicious" | "Alerted" | "Combat"

export type GuardSensoryConfig = {
    FieldOfViewDeg: number,
    SightRangeMax: number,
    HearingRangeMax: number,
    ShadowDetectionFactor: number, -- 그림자 은폐 시 시각 감지 배율 (예: 0.35)
    AlertBuildRate: number,        -- 초당 경계치 상승량
    AlertDecayRate: number,        -- 초당 경계치 자연 감소량
}

local StealthController = {}
StealthController.__index = StealthController

function StealthController.new(guardModel: Model, config: GuardSensoryConfig)
    local self = setmetatable({}, StealthController)
    self.Guard = guardModel
    self.Config = config
    self.Head = guardModel:WaitForChild("Head") :: BasePart
    self.Awareness = 0 -- 0 ~ 100 경계도 수치
    self.State = "Unaware" :: AlertState

    -- 충돌 필터링이 적용된 재사용 레이캐스트 파라미터
    self.RayParams = RaycastParams.new()
    self.RayParams.FilterType = RaycastFilterType.Exclude
    self.RayParams.FilterDescendantsInstances = {guardModel}
    self.RayParams.IgnoreWater = true

    return self
end

function StealthController:IsTargetInSightCone(targetPos: Vector3): (boolean, number)
    local eyePos = self.Head.Position
    local lookDir = self.Head.CFrame.LookVector
    local toTarget = targetPos - eyePos
    local distance = toTarget.Magnitude

    if distance > self.Config.SightRangeMax then
        return false, 0
    end

    local dirNormalized = toTarget.Unit
    local dotProduct = lookDir:Dot(dirNormalized)
    local minDot = math.cos(math.rad(self.Config.FieldOfViewDeg * 0.5))

    if dotProduct >= minDot then
        return true, distance
    end
    return false, distance
end

function StealthController:IsTargetInShadow(targetPart: BasePart): boolean
    -- 태양 방향 벡터 (게임 환경 설정에 맞게 동적 바인딩 가능)
    local sunDir = Vector3.new(0.3, 0.9, 0.2).Unit
    local rayOrigin = targetPart.Position + Vector3.new(0, 1, 0)
    local rayDir = sunDir * 100

    local result = Workspace:Raycast(rayOrigin, rayDir, self.RayParams)
    -- 상공에 구조물이 있어 태양광이 차단되면 그림자 볼륨 내부에 위치함
    return result ~= nil
end

function StealthController:EvaluateSensory(playerCharacter: Model, dt: number)
    local targetTorso = playerCharacter:FindFirstChild("HumanoidRootPart") :: BasePart?
    local targetHead = playerCharacter:FindFirstChild("Head") :: BasePart?
    if not targetTorso or not targetHead then return end

    local inCone, dist = self:IsTargetInSightCone(targetHead.Position)
    local canSee = false

    if inCone then
        -- 시야 차폐 검증 레이캐스트
        local eyePos = self.Head.Position
        local toHead = targetHead.Position - eyePos
        local hitResult = Workspace:Raycast(eyePos, toHead, self.RayParams)

        if hitResult and hitResult.Instance:IsDescendantOf(playerCharacter) then
            canSee = true
        end
    end

    if canSee then
        local inShadow = self:IsTargetInShadow(targetTorso)
        local lightFactor = inShadow and self.Config.ShadowDetectionFactor or 1.0
        local distanceFactor = 1.0 - math.clamp(dist / self.Config.SightRangeMax, 0, 1)

        -- 근거리이거나 밝은 조명 아래 있을수록 경계 게이지가 빠르게 상승
        local buildIncrement = self.Config.AlertBuildRate * distanceFactor * lightFactor * dt
        self.Awareness = math.clamp(self.Awareness + buildIncrement, 0, 100)
    else
        -- 시야에서 사라졌을 때 경계치 자연 감소
        self.Awareness = math.clamp(self.Awareness - (self.Config.AlertDecayRate * dt), 0, 100)
    end

    -- 상태 머신 전이 판정
    if self.Awareness >= 100 then
        self.State = "Combat"
    elseif self.Awareness >= 70 then
        self.State = "Alerted"
    elseif self.Awareness >= 25 then
        self.State = "Suspicious"
    else
        self.State = "Unaware"
    end
end

return StealthController