연결 및 재연결

이 가이드에서는 실행 중인 OBS 인스턴스에 연결하는 방법, 연결 상태 머신, 자동 재연결, 그리고 바인딩할 수 있는 연결 관련 이벤트를 다룹니다.

OBS WebSocket 서버 활성화

플러그인이 연결되려면 OBS 내에서 WebSocket 서버를 먼저 활성화해야 합니다.

1. OBS Studio를 엽니다.
2. 도구 → WebSocket 서버 설정으로 이동합니다.
3. WebSocket 서버 활성화를 체크합니다.
4. 비밀번호를 설정합니다(권장).
5. 포트를 확인합니다(기본값: 4455).

연결

OBS Component(액터별) 또는 OBS Subsystem(전역)을 통해 연결할 수 있습니다. 두 방법 모두 호스트, 포트, 비밀번호를 입력받습니다.

OBS Component 사용 (대부분의 사용자에게 권장)

1. 임의의 액터에 OBS Controller 컴포넌트를 추가합니다.
2. 디테일 패널 상단의 Features 선택기에서 원하는 도메인을 활성화합니다(기본적으로 장면과 녹화 및 방송이 포함되며, 연결은 항상 활성화됩니다).
3. 연결 카드에서 연결 설정을 입력하고 Connect를 클릭합니다.
4. 내장 컨트롤을 사용하거나 Blueprint에서 이벤트에 바인딩합니다.

디테일 패널은 코드 작성 없이 OBS를 완전히 제어할 수 있으며, 선택한 기능만 표시되므로 최소 구성 시 복잡하지 않게 유지됩니다.

OBS Subsystem 사용 (Blueprint)

// Get the OBS Subsystem
Get Game Instance → Get Subsystem (InhyeongOBSSubsystem)

// Connect to OBS
Connect (Host: "localhost", Port: 4455, Password: "your_password")

// React to events
Bind to On Connected
Bind to On Disconnected

OBS Subsystem 사용 (C++)

// Get subsystem
UInhyeongOBSSubsystem* OBS = GetGameInstance()->GetSubsystem<UInhyeongOBSSubsystem>();

// Connect
OBS->Connect("localhost", 4455, "password");

// Bind to events (dynamic delegates for UFUNCTIONs)
OBS->OnConnected.AddDynamic(this, &AMyActor::HandleConnected);

// Or use native delegates with lambdas
OBS->GetClient()->OnConnectedNative.AddLambda([]() {
    UE_LOG(LogTemp, Log, TEXT("Connected to OBS"));
});

인증

OBS는 비밀번호가 설정된 경우 SHA256 챌린지/응답 핸드셰이크를 사용합니다. 이는 연결 과정에서 자동으로 처리되므로 비밀번호만 입력하면 됩니다. 비밀번호가 필요한데 제공되지 않은 경우, 연결이 지연되지 않고 즉시 실패합니다.

연결 상태 머신

연결은 다음 상태를 순서대로 거칩니다.

Disconnected → Connecting → Authenticating → Connected

Connected 상태가 되면, 클라이언트는 ID를 기반으로 요청을 대응시키고 수신된 OBS 이벤트를 적절한 핸들러로 전달합니다.

자동 재연결

자동 재연결은 기본적으로 활성화되어 있습니다. 연결이 끊어지면 클라이언트는 지수 백오프를 사용하여 재시도하므로 OBS에 과부하를 주지 않습니다. 백오프는 시도 횟수에 따라 증가하며, 설정된 최대 시도 횟수가 소진되면 재연결이 중지됩니다(무제한 설정 시 무한 재시도).

재연결이 진행 중인 동안 수동으로 Connect()를 호출해도 대기 중인 시도가 취소되지 않습니다. 새로운 연결 대상으로 덮어씌워집니다.

연결 및 재연결 이벤트

연결 생명주기 변화에 반응하려면 다음 이벤트에 바인딩합니다.

연결

재연결

모든 이벤트는 Blueprint에서 할당 가능한 동적 델리게이트와 네이티브 C++ 델리게이트 두 가지 형태로 제공됩니다(네이티브 변형은 Native 접미사가 붙습니다).

모든 OBS 도메인에 걸친 이벤트의 전체 목록은 이벤트 레퍼런스를 참조하세요.