올린 글을 장부로 다시 관리한다#

전편에서는 올린 뒤에는 추적하지 않는 쪽으로 범위를 줄였다. 이번에는 판매 중인 글을 계속 끌어올리고 싶다는 요구가 생겨서 장부를 다시 뒀다. 스크립트가 모델 없이 돌아야 해서 판매 중인 글 목록을 스크립트가 직접 알아야 했기 때문이다.

• listings.json: 글마다 플랫폼, URL, 제목, 가격, 상태, 끌어올리기 이력과 가격 변경 이력을 적는다.
• listing-sync 스킬: 두 플랫폼의 내 상품 페이지를 읽기 전용으로 열어 장부와 비교하고, 새 글 추가·종료 처리·가격 변경 반영을 한다.
• price-adjust 스킬: 가격을 바꾸고 플랫폼 목록에서 다시 읽어 확인한 뒤에만 장부에 기록한다. 이번 22만원은 채팅 흥정으로 정해져서 이 스킬을 쓰지 않았다.

listings.json은 data/ 아래에 있어서 설정 백업 저장소에는 올라가지 않는다. 글 URL과 가격 같은 거래 정보를 올리지 않으려는 선택이다.

끌어올리기 규칙부터 확인했다#

횟수 제한과 비용은 플랫폼마다 다르다. 구현 전에 직접 확인했다.

• 중고나라: 글 상세 페이지의 위로 올리기 버튼을 누르면 확인창이 뜬다. 상품당 하루 2회, 최대 20번이라고 적혀 있다. 총 한도가 20번이라 아무 때나 누르면 금방 소진돼서 하루 1회로 잡았다. 하루 1번이면 글 하나로 20일 정도 쓴다.
• 번개장터: 공식 고객센터 FAQ 기준으로 무료 UP체험권이 매일 5개 충전되고, 같은 상품에는 하루 한 번만 쓸 수 있다. 영상 광고를 보는 UP과 유료 UP은 자동화하지 않는다.

끌어올리기가 실제로 됐는지는 알림 문구가 아니라 상대 시간 표시로 확인한다. 올리기 전 “17분 전”이던 글이 올린 뒤 “4초 전”으로 바뀐 것을 읽어야 성공으로 기록한다.

모델 없이 크론으로 돌린다#

끌어올리기는 가격이나 문구를 바꾸지 않고 같은 글을 다시 노출하는 일이다. 매번 판단할 것이 없어서 에이전트를 부르지 않는 no_agent 크론으로 만들었다.

1
schedule: */10 20-22 * * *  (Asia/Seoul)
2
no_agent: true
3
script:   listing_bump.py → listing-bump/scripts/bump_listings.py
4
deliver:  #flea-market

• 글과 플랫폼마다 날짜별 목표 시각이 있다. 날짜, 플랫폼, 글 ID를 해시해서 오후 8시대 안에서 정한다. 한꺼번에 몰아 누르지 않으려는 방식이다.
• 목표 시각이 지났고 오늘 아직 누르지 않은 글만 대상이 된다. 오후 11시까지 못 누르면 그날은 포기하고 놓침으로 알린다.
• 그날 첫 대상 실행에서 listing-sync를 한 번 돌려 판매됐거나 삭제된 글을 먼저 ended로 바꾼다. 팔린 글을 누르지 않기 위해서다.
• 글은 하나씩, 4–8초 간격으로 누른다. 실패하면 하루 최대 3번 다시 시도한다.
• 간격, 하루 횟수, 중고나라 총 한도는 data/bump_config.json으로 코드 수정 없이 바꾼다. 글마다 bump.enabled로 끌 수도 있다.
• Slack에는 결과가 있을 때만 올린다. 아무것도 하지 않은 실행은 출력이 비어서 메시지가 없다.

누적 3/20은 중고나라가 센 이 글의 끌어올리기 횟수다.

팔린 뒤에는 남은 글이 위험하다#

판매는 11월 8일 오후에 끝났다. 번개장터에서 22만원에 팔렸다고 Slack에 적었더니 Merchant가 이렇게 답했다.

번개장터 글은 장부에서 sold로 바뀌고 판매가 22만원이 기록됐고, 끌어올리기도 꺼졌다.

남은 문제는 같은 물건을 올려 둔 중고나라 글이었다. 아직 판매중이라 이중 판매 위험이 있었고, 그날 저녁 끌어올리기 크론이 이 글을 올릴 예정이었다. 그래서 이 글의 끌어올리기를 먼저 끄고, 글을 내리거나 판매완료로 바꾸는 일은 승인 대상이라 내게 물었다.

중고나라 글은 내가 판매완료로 바꾸고 다시 확인을 시켰다. 판매중 목록에서 글이 빠진 것이 확인돼 장부에 ended로 기록됐고, 그날 저녁 크론은 두 글 모두 아무것도 누르지 않았다.

마치며#

사진 한 장과 한 줄로 시작한 판매글이 끌어올리기를 거쳐 실제 판매까지 이어졌다. 자동화를 만들고 그 결과로 물건이 실제로 팔리는 것까지 보니 신기했고, AI 자동화가 일하는 방식을 바꾸고 있다는 것을 처음으로 몸으로 느꼈다.

모바일 메뉴 드로어#

• 모바일 드로어를 열면 배경이 회색으로 어두워지던 문제와 오버레이 계층 문제를 고쳤다.
• 드로어와 오버레이를 fixed 대신 absolute 기준으로 옮기고, 열 때의 문서 위치와 높이를 CSS 변수(--mobile-menu-document-top, --mobile-menu-paint-height)로 잡는다. Safari의 하단 툴바 애니메이션으로 그리기 영역이 바뀌는 것을 막으려는 변경이다.
• 검은 scrim 대신 드로어와 같은 유리 질감 배경을 사용하고, 닫힐 때는 슬라이드가 끝난 뒤(0.3초) 숨겨 화면 가장자리에 그림자가 남지 않게 했다.
• BrowserChrome.astro를 추가해 브라우저 UI 색(theme-color)을 현재 라이트·다크 테마 배경에 맞춘다. viewport-fit=cover도 함께 설정된다.

날짜 처리#

릴리스 이후 변경(#700)이다. 날짜 포맷과 아카이브 그룹핑이 siteConfig.timezone을 따르도록 바뀌었다.

• formatDateToYYYYMMDD가 toISOString() 대신 설정된 타임존으로 날짜를 만든다.
• 2026-11-06처럼 시간 없이 적은 날짜(UTC 자정으로 해석되는 값)는 입력한 날짜를 그대로 유지한다.
• allPostMeta.json에 publishedDate가 추가되고, 추천 글 위젯이 이 값을 사용한다.

이 블로그의 published 중 시간이 들어간 값은 +09:00 기준 오전 9시, 오후 2시, 오후 5시대라서 siteConfig.timezone(Asia/Shanghai)으로 바꿔도 날짜가 달라지지 않는다.

음악 플레이어#

릴리스 이후 변경(#697)이다.

• 키보드 미디어 키와 시스템 재생 컨트롤을 플레이어 상태와 동기화한다.
• 진행 슬라이더를 드래그할 수 있다.
• 접근성 포커스 링이 잘리던 문제를 고쳤다.

갤러리와 MDX#

• 릴리스 이후 변경(#699): 모바일 앨범 상세에서 뒤로가기 버튼이 제목에 가려져 눌리지 않던 문제를 고쳤다.
• 릴리스 이후 변경(#672): remark-image-grid가 MDX 컴포넌트(<TimelineItem>, <StepItem>) 안의 [grid] 블록을 처리한다. [grid] 앞뒤 줄에 본문이 붙어 있어도 문단을 분리해 마커를 인식한다. 이 블로그에는 .mdx 글이 없어 영향받는 글은 없다.

빌드와 도구#

• 빌드 스크립트의 astro build가 astro build --force로 바뀌었다(#679).
• Biome을 2.5.12에서 2.6.3으로 올렸고 biome.json에서 Markdown 콘텐츠 파일을 제외했다(#680).
• biome.yml 워크플로의 biomejs/setup-biome에서 version 고정을 제거했다. 이 저장소가 고정해 두었던 2.5.7도 함께 사라지므로 package.json의 Biome 버전을 따른다.

의존성#

패치 업데이트 23개(#696) 중 주요 항목이다.

• katex: 0.19.0 → 0.19.1
• marked: 18.1.0 → 18.1.1
• sanitize-html: 2.18.0 → 2.18.1
• sharp: 0.35.4 → 0.35.5
• svelte: 5.57.0 → 5.57.2
• @astrojs/check: 0.9.10 → 0.9.12
• @astrojs/markdown-remark: 7.3.1 → 7.3.4

검증#

• pnpm check: 266개 파일, 오류·경고·힌트 0개.
• pnpm type-check, pnpm build: 통과. 정적 페이지 124개를 생성하고 Pagefind에 95개 페이지를 인덱싱했다.
• biome ci ./src: 323개 파일 검사, 수정 사항 없음.

업스트림 변경 비교

감시를 빼고 올리는 일만 남겼다#

처음에는 중고나라에 테스트 글을 올려 보는 것에서 시작했다. 사진을 첨부하지 않으면 판매하기가 거부되고(사진/동영상을 1개 이상 첨부해 주세요), 사진을 올리면 설명 칸에 사이트가 추천 문구를 끼워 넣는다는 것을 이때 알았다. 테스트 글은 [테스트] 제목으로 올리고 바로 지웠다.

그다음에는 게임잡 즐겨찾기처럼 올린 글을 장부로 관리하고, 크론이 상태를 확인해 알려 주고, 시세를 보고 가격 조정을 제안하고, 원하는 물품을 찾아 주는 쪽까지 구상했다. 장부를 git으로 추적할지, 로그인이 풀리면 어떻게 할지를 논의하면서 data/market/listings.json 하나만 추적하는 정책까지 정했다.

그러다 범위를 줄였다. 장부와 캐시, 가격 조정 이력이 필요한 이유는 모두 감시와 시세 기능이었다. 이 기능을 빼면 저장할 데이터가 없다. 남긴 것은 판매글 작성, 가격 제안, 등록이고, 올린 뒤에는 추적하지 않는다. 장부용으로 추가했던 .gitignore 규칙은 되돌렸고, 프로필의 스킬·config.yaml·memories는 기본 프로필과 같은 비공개 저장소로 백업한다.

구매 쪽 기능은 나중에 별도로 붙일 예정이라 프로필 설명과 SOUL.md는 판매 전용이나 중고나라 전용으로 쓰지 않았다. 지금 지원하는 기능만 “현재 지원”으로 따로 적는다. 사진은 내가 직접 주기 때문에 Merchant가 맡을 일은 내용 작성, 가격 제안, 실제 등록 과정이다.

사진과 한 줄로 시작해 모자란 것만 묻는다#

스킬이 호출되면 아래 템플릿을 코드 블록으로 먼저 올리고, 채워 온 답에서 비어 있거나 모호한 필수 항목만 한 번에 되묻는다.

1
[중고 판매 정보]
2

3
• 상품 (브랜드/모델):
4
• 올릴 곳 (중고나라 / 번개장터 / 둘 다):
5
• 상태 (중고 / 새상품):
6
• 구매 시기 · 사용 기간:
7
• 하자/흠집 (없으면 "없음"):
8
• 구성품 (전체 / 일부 / 없음 + 내용):
9
• 희망가 (비우면 시세 보고 제안):
10
• 최저가 (있으면):
11
• 거래 방법 (직거래 지역 / 택배 배송비 포함·별도 금액):
12
• 기타 전달사항:
13

14
사진은 이 스레드에 첨부해 주세요.

PS4 Pro는 템플릿 없이 사진 4장과 “출시할 때 바로 산 건데 중고나라에 팔려고 한다”는 한 줄로 시작했다. Merchant는 사진에서 읽은 것(본체, 컨트롤러 2개, 후면 포트, 스틱 고무 커버)을 먼저 적고, 모자란 항목 다섯 가지를 번호를 매겨 물었다. 모델과 용량, 하자, 구성품, 거래 방법, 가격이다. 나는 번호대로 한 번에 답했다.

시세를 조사하고 근거 링크와 함께 가격을 제안한다#

가격은 직접 정하지 않고 조사해서 제안하게 했고, 근거가 되는 링크를 함께 보여 달라고 했다. 조사는 공개 페이지를 curl로 읽는다. 중고나라는 검색 결과 HTML에, 당근은 페이지에 들어 있는 JSON에 목록이 있어서 읽을 수 있었다. 번개장터는 공개 API가 막혀 있었고 네이버 플리마켓은 로그인 없이 볼 수 없었다. 그래서 초안에도 중고나라와 당근만 근거로 삼았다고 적혔다.

한정판, VR, 게임이 다수 포함된 글, 부품용, 중복 게시를 걸러 1TB 일반 블랙 21건이 남았다. 중앙값은 23만원, 중간 50% 구간은 20만–25만원, 전체 범위는 18만–30만원이었다. 모두 판매 희망가라서 실제로 팔리는 가격은 이보다 낮을 수 있다는 단서도 같이 왔다.

첫 제안은 희망가 24만원, 빠른 판매가 21만원이었다. 이후 사용 횟수나 펌웨어처럼 정보가 바뀔 때마다 가격을 다시 제안했고, 승인하기 전에는 바꾸지 않았다. 중고나라에는 빠른 판매가 22만원으로 등록한 뒤 26만원으로 고쳤고, 초기화 문구를 본문에 넣으면서 24만원으로 내렸다. 번개장터에도 같은 24만원으로 올렸다.

사진은 원본을 두고 복사본을 가공한다#

사진은 내가 올리고 Merchant가 모든 사진을 확대해 읽는다. 구동 확인용으로 찍은 시스템 정보 화면에는 MAC 주소와 계정명이 보였다. 그대로 올리지 않고 복사본에 검은 박스를 덮었다. 펌웨어 8.50은 읽히게 남겼고, 본문에도 개인정보를 가렸다고 적었다.

컨트롤러 사진에는 오른쪽 그립에 잔기스가 있었다. 본문에는 흠집이 없다고 적어 둔 상태였는데, Merchant가 사진과 어긋난다고 먼저 짚어서 [상태]에 잔기스를 한 줄 넣었다. 나는 거기에 사진에도 붉은 원으로 표시해 달라고 요청했다. 원도 복사본에 그렸고 원본 파일은 건드리지 않았다.

본문의 사실은 출처를 구분한다#

본문은 가능한 한 자세한 스펙과 구성품을 빠짐없이 적게 했다. 대신 적는 사실의 출처를 세 곳으로 제한했다. 내가 쓴 내용, 내가 준 사진, 모델이 특정되는 범위의 제조사 공식 자료다. 세 곳에 없는 정보는 쓰지 않고, 중요한데 확인이 안 되면 한 번에 되묻거나 뺀다. Slack 초안에서는 스펙 묶음마다 사용자 제공 / 사진 확인 / 공식 스펙 기준을 표시하고, 게시 문구에는 넣지 않는다.

PS4 Pro에서는 이렇게 나뉘었다. 모델명 CUH-7017B는 처음에는 “같아”라고 적었다가, 직접 확인한 값이 맞다고 답했다. 펌웨어와 잔기스는 사진에서, 1TB 단일 구성은 소니 공식 자료에서, 4K 업스케일링과 HDR은 공식 스펙에서 가져왔다. 한국 출시 모델의 세부 번호는 찾지 못해서 처음에는 CUH-7000 시리즈까지만 적었고, 내가 확인한 번호를 받은 뒤 CUH-7017B로 바꿨다.

이 규칙은 Merchant가 스스로 어긴 일에서 나왔다. 번개장터 폼을 채운 뒤 보고하면서 가격 제안 받기가 기본으로 체크돼 있고 예상 정산액이 225,600원이라고 썼는데, 그 시점에는 둘 다 폼에서 읽은 적이 없었다. 정산액은 이후 폼에서 읽은 값과 같았지만 말한 시점에는 근거가 없었다. Merchant가 다음 메시지에서 먼저 정정했다. 체크 여부는 확인하지 못했고, 정산액은 본 적 없는 숫자라는 내용이다. 이 일 이후 스킬 규칙에 도구 출력으로 확인하지 않은 숫자나 체크 상태는 말하지 않는다는 항목이 들어갔다.

승인한 뒤에만 등록하고 공개 페이지로 대조한다#

폼을 다 채운 뒤에도 판매하기는 누르지 않고 입력된 내용과 확인할 점을 스레드에 올리게 했다. 아래 보고에는 사이트가 본문 맨 위에 슬림 디스크 버전이라는 문구를 자동으로 넣었다가 지우고 승인본으로 되돌렸다는 내용이 있다. 승인 없이는 등록하지 않는다는 규칙은 판매글뿐 아니라 가격 변경과 메시지 전송까지 적용한다.

중고나라 폼에서 걸렸던 부분은 스킬의 references/form-recipe.md에 적어 두었다.

• 제목은 64자까지만 들어가고 넘치면 조용히 잘린다. 펌웨어를 제목에 넣을 때 제트블랙을 빼서 63자로 맞췄다. 색상은 본문에 있다.
• 사진을 추가할 때마다 사이트가 설명 맨 위에 추천 문구를 넣는다. 마지막 사진 변경 뒤에 설명을 지우고 다시 입력하고, textarea.value가 승인본과 같은지 확인한다.
• 카테고리는 기본값을 믿지 않는다. 한 번은 게임 > 기타 게임으로 등록돼서 등록 직후 수정 폼에서 게임 > 플레이스테이션으로 바꿨다. 지금은 제목을 입력하면 나오는 추천 칩을 눌러 고르고, 등록 뒤 칩을 다시 확인한다.
• 가격은 fill로 넣어도 반영되지 않는다. 필드가 옆 패널을 열기 때문에 입력창을 클릭해 키를 입력하고 입력 완료를 눌러야 한다.

등록 뒤에는 공개 페이지를 curl로 읽어 제목, 가격, 본문의 핵심 줄, 카테고리를 승인본과 대조한 뒤 URL을 보고한다. 수정 폼에서 저장하면 탭이 새 탭으로 넘어가 화면으로는 결과를 볼 수 없는 경우가 있어서, 수정 후에도 공개 페이지로 확인한다.

번개장터를 붙이면서 스킬을 나눴다#

번개장터는 내가 ego-browser에 로그인해 둔 계정으로 같은 흐름을 돌렸다. 폼은 중고나라와 달랐다.

• 처음 열면 브라우저 알림 권한 팝업이 뜬다. 에이전트는 이 팝업을 처리하지 않고 작업 공간을 넘기며, 내가 누른 뒤 같은 작업 공간에서 이어 간다.
• 직거래 기본값은 불가다. 가능으로 바꾼 뒤 희망 장소를 넣는다.
• 화면 아래 고정 바가 입력창을 가려서 요소를 가운데로 스크롤한 뒤 좌표로 클릭한다.
• 상품 페이지는 브라우저에서 렌더링되어 curl로는 내용이 읽히지 않는다. 그래서 등록 직후 브라우저에 뜬 페이지에서 제목, 가격, 본문 앞부분까지만 확인했다.

첫 등록이라 이번에는 폼을 채운 뒤 등록 직전에서 멈추고 요약을 받았다. 가격 제안 받기는 유지하고 가격은 24만원 그대로 올리라고 답했다.

번개장터를 한 스킬에 계속 이어 붙이면 joongna-posting이 두 플랫폼의 절차와 공통 규칙을 함께 들게 된다. 본문, 가격, 사진 쪽은 두 곳이 같고 폼만 다르다는 점을 근거로 구조를 나눴다. 공통 부분은 메타 스킬 secondhand-sell-desk에 올리고, 플랫폼별 폼 절차는 각 스킬에 둔다.

채널이 새 메타 스킬로 시작하게 하려면 config.yaml의 채널 바인딩을 바꿔야 한다. 이 파일은 에이전트가 쓰지 못하게 막혀 있어서 Merchant는 우회하지 않고 바꿀 줄을 알려 줬고, 내가 직접 고친 뒤 게이트웨이를 재시작했다. joongna-posting에 “연결 변경됨”이라고 적어 놓았던 것도 사실이 아니라서 Merchant가 되돌렸다. 설정 파일에 반영된 것은 확인했다.

1
slack:
2
  channel_skill_bindings:
3
    - id: <#flea-market 채널 ID>
4
      skills:
5
        - secondhand-sell-desk

이제 #flea-market에 새 스레드를 열면 secondhand-sell-desk가 템플릿부터 시작하고, 올릴 곳에 따라 joongna-posting이나 bunjang-posting의 폼 절차를 부른다. 다른 플랫폼을 붙일 때는 폼 절차 스킬 하나만 더하면 된다. 구매 쪽 기능도 이 판매 스킬에 섞지 않고 별도 스킬로 붙일 생각이다.

Relevancy가 정하는 것#

면접관의 첫 질문은 Relevancy가 무엇이냐였다. 레벨에는 액터가 많지만 한 플레이어에게 영향을 주는 것은 일부다. 서버는 연결(connection)마다 그 클라이언트에 의미 있는 액터 집합을 정하고 그 집합의 액터만 복제한다. 이 집합에 드는 액터가 그 연결에 Relevant하다. 판정 단위는 액터가 아니라 액터와 연결의 쌍이라서, 같은 액터가 A 클라이언트에는 연관 있고 B 클라이언트에는 연관 없을 수 있다.

서버에서 Relevancy는 Actor channel을 열고 닫는 기준이다.

• 채널이 없는 액터는 연관 없으면 보내지 않는다. 연관 있으면 채널을 열고 처음 복제한다.
• 채널이 있는 액터는 연관성을 잃어도 바로 닫지 않고 유예 뒤에 닫는다(아래 연관성을 잃고 되찾을 때).
• Multicast RPC도 연관 있는 연결에만 보낸다.

Relevancy가 RPC에 관여하는 것은 이 세 번째 항목 정도다. 꼬리 질문인 “언제 Relevant해야 하나”의 답은 아래의 판정 순서와, 그 순서를 바꾸는 플래그에 있다.

IsNetRelevantFor의 판정 순서#

AActor의 기본 구현이다. 위에서부터 검사해 처음 걸린 조건으로 끝난다.

1
bool AActor::IsNetRelevantFor(const AActor* RealViewer, const AActor* ViewTarget, const FVector& SrcLocation) const
2
{
3
  if (bAlwaysRelevant || IsOwnedBy(ViewTarget) || IsOwnedBy(RealViewer) || this == ViewTarget || ViewTarget == GetInstigator())
4
  {
5
    return true;
6
  }
7
  else if (bNetUseOwnerRelevancy && Owner)
8
  {
9
    return Owner->IsNetRelevantFor(RealViewer, ViewTarget, SrcLocation);
10
  }
11
  else if (bOnlyRelevantToOwner)
12
  {
13
    return false;
14
  }
15
  else if (RootComponent && RootComponent->GetAttachParent() && RootComponent->GetAttachParent()->GetOwner() && (Cast<USkeletalMeshComponent>(RootComponent->GetAttachParent()) || (RootComponent->GetAttachParent()->GetOwner() == Owner)))
16
  {
17
    return RootComponent->GetAttachParent()->GetOwner()->IsNetRelevantFor(RealViewer, ViewTarget, SrcLocation);
18
  }
19
  else if(IsHidden() && (!RootComponent || !RootComponent->IsCollisionEnabled()))
20
  {
21
    return false;
22
  }
23

24
  if (!RootComponent)
25
  {
26
    UE_LOGF(LogNet, Warning, "Actor %ls / %ls has no root component in AActor::IsNetRelevantFor. (Make bAlwaysRelevant=true?)", *GetClass()->GetName(), *GetName() );
27
    return false;
28
  }
29

30
  return !GetDefault<AGameNetworkManager>()->bUseDistanceBasedRelevancy ||
31
      IsWithinNetRelevancyDistance(SrcLocation);
32
}

세 인자는 연결마다 정해진다.

단계별로 보면 다음과 같다. 번호는 위 그림과 같다.

1. 이 연결의 것인지 먼저 본다. bAlwaysRelevant이거나, Owner 체인에 그 연결의 PlayerController나 Pawn이 있거나, 그 Pawn이 Instigator면 숨김이나 거리와 관계없이 연관 있다.
2. bNetUseOwnerRelevancy면 Owner의 판정을 그대로 쓴다.
3. bOnlyRelevantToOwner면 연관 없다. 소유자는 이미 1번에서 통과했으므로, 여기까지 온 것은 소유자가 아닌 연결뿐이다.
4. 다른 액터에 붙어 있으면 부모 액터의 판정을 따른다. Epic 문서는 스켈레탈 메시에 붙은 경우만 설명하지만, 부모 액터의 Owner가 내 Owner와 같을 때도 부모를 따른다.
5. 숨기기만 해서는 빠지지 않고, 루트 충돌까지 꺼져 있어야 연관 없음이 된다. 반대로 렌더링이 필요 없다고 충돌 없는 액터를 서버에서 SetHidden(true)로 스폰하면 아무에게도 복제되지 않는다. Replication Graph를 측정할 때 테스트 액터 5,000개가 이 조건에 걸려 기본 드라이버로는 하나도 복제되지 않았다.
6. 루트 컴포넌트가 없으면 경고 로그를 남기고 연관 없음이 된다. 루트 없이 데이터만 나르는 액터는 1–3번에서 결론이 나도록 플래그를 정해 둔다.
7. 마지막이 거리다. 기준점은 Pawn이 아니라 카메라 시점이라서, 3인칭 카메라가 폰 뒤로 빠져 있으면 기준점도 그만큼 뒤에 있다. NetCullDistanceSquared는 이름대로 제곱값이고 기본값 225000000은 150 m다.

Owner가 판정을 바꾸는 방식#

Owner는 판정 순서에서 세 번 쓰인다.

1. 소유 체인. IsOwnedBy는 Owner를 끝까지 따라 올라간다. 무기의 Owner가 Pawn이고 Pawn의 Owner가 PlayerController면(빙의하면 Pawn의 Owner는 PlayerController가 된다) 무기는 거리와 관계없이 그 플레이어에게 항상 연관 있다.
2. bOnlyRelevantToOwner. 소유자 외에는 연관 없다. Owner가 없으면 아무에게도 가지 않는다.
3. bNetUseOwnerRelevancy. 판정을 Owner에게 넘긴다. 폰이 들고 있는 무기나 장비는 폰이 보이는 클라이언트에게 같이 보여야 하므로 이 플래그를 켜고 Owner를 폰으로 둔다.

1번 조건에는 Instigator도 있다. 내 Pawn이 Instigator인 투사체는 거리와 관계없이 나에게 연관 있다.

판정은 서버에서 돌기 때문에 Owner도 서버에서 정한다.

1
// 예시: 폰이 들고 다니는 무기
2
AMyWeapon::AMyWeapon()
3
{
4
  bReplicates = true;
5
  bNetUseOwnerRelevancy = true; // 폰이 연관 있는 연결에만 연관 있다
6
}
7

8
// 서버에서 스폰할 때 Owner와 Instigator를 지정한다
9
FActorSpawnParameters Params;
10
Params.Owner = OwnerPawn;
11
Params.Instigator = OwnerPawn;
12
GetWorld()->SpawnActor<AMyWeapon>(WeaponClass, SpawnTransform, Params);

정리하면 꼬리 질문의 답은 다음 표다.

연관성을 잃고 되찾을 때#

여기부터는 면접에서 이어서 받을 만한 질문을 정리했다. 먼저 “연관성을 잃었다가 되찾으면 클라이언트에서는 무슨 일이 생기나요?”다.

• 연관성을 잃어도 바로 끊지 않는다. 마지막으로 Relevant했던 때부터 RelevantTimeout(기본 5초)이 지날 때까지는 계속 복제한다. 경계를 오가는 액터가 생겼다 사라지기를 반복하지 않게 하는 장치로 보인다.
• 유예가 끝나면 동적으로 스폰한 액터는 채널이 닫혀 클라이언트에서 파괴되고 EndPlay가 불린다. 맵에 배치한 액터는 채널이 남아 사라지지 않고 복제만 멈춘다.
• 다시 Relevant해지면 동적 액터는 새로 스폰되어 BeginPlay가 다시 불리고, 기본값과 다른 프로퍼티의 OnRep이 온다. 맵에 배치한 액터는 복제가 재개되어 바뀐 값의 OnRep이 온다. 처음부터 범위 밖에서 스폰된 액터도 Relevant해질 때까지는 클라이언트에 나타나지 않는다.

RPC는 프로퍼티와 다르게 다룬다. 연관 없는 연결에도 채널이 열려 있으면 Reliable Multicast는 간다. Unreliable Multicast는 연관 없는 연결에는 가지 않는다. 그래서 유예 중인 액터나 채널이 남아 있는 맵 배치 액터는 범위 밖에서도 Reliable Multicast를 받는다. 채널이 닫힌 동적 액터는 아무것도 받지 못하고, 다시 Relevant해져도 그사이 RPC는 재전송되지 않는다.

액터를 짤 때는 두 가지를 전제로 둔다.

• 동적 액터의 클라이언트 BeginPlay와 EndPlay는 여러 번 불릴 수 있다. BeginPlay에서 다른 객체에 등록했다면 EndPlay에서 해제해, 다시 불려도 문제없게 한다.
• 늦게 보게 된 클라이언트도 알아야 하는 상태는 RPC가 아니라 복제 프로퍼티에 두고, 현재 프로퍼티 값만으로 상태를 다시 맞출 수 있게 한다. RPC는 그 순간의 연출 같은 이벤트에 쓴다.

바꿀 때 주의할 점#

“연관성을 직접 바꿀 때 주의할 점은요?”라는 질문에는 세 가지를 답할 수 있다.

Relevancy, Dormancy, Priority#

Relevancy를 설명하면 Dormancy, Priority와는 무엇이 다르냐는 질문도 나오기 쉽다. 셋 다 “덜 보내기” 위한 장치지만 묻는 질문이 다르다.

Priority는 연관 있는 액터 사이의 순서다. Actor Priority 문서에 따르면 연결이 포화됐을 때 무엇을 먼저 보낼지 정하는 상대 비율이다. Dormancy는 Relevancy와 다르다. 휴면 액터는 클라이언트에 남은 채 정해 둔 시점까지 업데이트만 멈춘다. 자세한 내용은 휴면 액터 깨우기에 정리했다.

다시 답한다면#

같은 질문을 다시 받는다면 위 내용을 줄여 이렇게 답하고 싶다. 질문별로 나눠 답했다.

참고 자료#

• Actor Relevancy in Unreal Engine
• Actor Priority in Unreal Engine
• Net Relevancy Explained; Actor Relevancy Explained - UE C++ Tutorial, enigma tutorials

즐겨찾기를 어디에 두고 어떻게 보여 줄지#

저장 위치는 세 가지를 비교했다.

• config.json의 watch 안에 favorites 목록을 두는 방식
• 별도 파일 favorites.json에 두는 방식
• Notion이나 Obsidian에 동기화하는 방식

첫 번째는 관리할 파일이 늘지 않지만 검색 조건과 내 기록이 한 파일에 섞인다. 세 번째는 나중에 붙여도 되는 기능이라 원본으로 삼을 이유가 없었다. 별도 파일로 정했다. 즐겨찾기한 공고는 공고 번호(GI_No)만이 아니라 회사, 제목, 경력, 지역, 마감일, 추가한 시각과 메모까지 스냅샷으로 저장한다. 게임잡에서 공고가 내려가도 어떤 공고였는지 남기려는 목적이다.

1
{
2
  "favorites": {
3
    "286506": {
4
      "id": "286506",
5
      "company": "㈜매드엔진",
6
      "title": "[매드엔진] [AI 기술 센터] Senior Unreal Engineer",
7
      "url": "https://www.gamejob.co.kr/Recruit/GI_Read/View?GI_No=286506",
8
      "career": "경력5년↑",
9
      "location": "경기 > 성남시",
10
      "employ": "정규직",
11
      "deadline_raw": "~11/29",
12
      "added_at": "2026-11-03T14:56:31+09:00",
13
      "note": "",
14
      "last_live": "2026-11-03"
15
    }
16
  }
17
}

last_live는 마지막으로 게임잡 목록에서 확인된 날짜다. 공고가 목록에 있는 동안은 실행할 때마다 스냅샷을 새 값으로 갱신한다.

표시 규칙은 다음과 같다.

• 즐겨찾기 구간 ⭐ 즐겨찾기 (N)을 언리얼 구간 위에 둔다. 즐겨찾기한 공고는 언리얼·C++ 구간에서 빠지고, 그 구간의 건수도 그만큼 줄어든다. 같은 공고가 두 번 나오지 않게 하려는 것이다.
• 즐겨찾기한 공고는 필터를 통과하지 못해도 표시한다. 필터는 후보를 고르는 기준이고, 즐겨찾기는 내가 이미 고른 결과이기 때문이다.
• 즐겨찾기한 공고에는 신규 표시(🆕)를 붙이지 않는다. 필터 밖의 공고를 즐겨찾기했을 때 가짜 신규가 생기지 않게 하려는 것이다.
• 목록에서 사라진 공고는 자동으로 지우지 않는다. 스냅샷으로 표시하면서 🔚 게시 종료를 붙이고 구간 맨 아래로 내린다.
• 메모가 있으면 공고 줄 끝에 · 📝 1차 지원 예정처럼 메모 내용을 붙인다.

8건을 한 번에 넣고 재전송한 목록이다. 같은 회사의 공고는 다른 구간처럼 회사명 아래에 묶인다.

즐겨찾기가 하나도 없을 때도 구간은 남기고, 등록 방법을 인용 블록 한 줄로 안내한다. 공고 목록과 섞이지 않게 글머리 기호 대신 인용 블록을 썼다.

지금은 예시에 특정 회사 대신 "[회사명] [공고 키워드] 즐겨찾기해줘"라는 자리표시자를 쓴다.

대충 말해도 찾는 일은 에이전트가 맡는다#

“크래프톤 팰월드 모바일 전투 쪽 즐겨찾기해줘” 같은 요청을 공고 번호로 바꾸는 일은 스크립트에 넣지 않았다. 이 매칭은 에이전트가 하고, 스크립트는 정확한 공고 번호나 링크만 받는다.

1
S=~/.hermes/scripts/gamejob_watch.sh
2
$S --fav-add 286506 279893 ...           # 공고 번호나 링크, 여러 건 가능
3
$S --fav-remove 286506                   # 해제
4
$S --fav-list                            # 목록
5
$S --fav-note 286506 "1차 지원 예정"      # 메모, 빈 문자열이면 삭제
6
$S --resend                              # 신규 표시 상태를 바꾸지 않고 다시 출력

에이전트는 상세 페이지 캐시(seen.json)와 현재 목록에서 회사명과 제목을 맞춰 본다. 후보가 하나로 좁혀지면 바로 등록하고, 여러 개면 짧은 선택지로 되묻는다. 찾지 못하면 링크를 달라고 한다. 이렇게 나누면 사람 말을 해석하는 부분에만 모델이 쓰이고, 매일 오전 9시의 크론은 이전처럼 LLM 호출 없이 스크립트만 실행한다.

처음 등록할 때는 채널에 올라온 목록에서 8줄을 그대로 복사해 보냈다. 회사명이 빠진 하위 줄도 섞여 있었지만 줄마다 공고 링크가 들어 있어서 번호를 바로 얻었다. 매칭 판단이 필요한 것은 회사명이나 제목 일부만 보낼 때다.

신규 표시를 건드리지 않는 재전송#

즐겨찾기를 넣은 뒤 바로 채널에 다시 보내는 부분에서 걸리는 점이 있었다. 기존 일일 크론을 수동 실행(cronjob run)하면 실제 실행이라서 본 공고 기록(seen.json)과 직전 실행 목록이 갱신된다. 즐겨찾기할 때마다 이렇게 보내면 다음 날 아침의 신규 표시와 “사라진 공고” 집계가 어긋난다.

그래서 스크립트에 --resend 옵션을 추가했다. 미리보기(--dry-run)처럼 신규 판정 기준인 본 공고 기록과 직전 실행 목록을 바꾸지 않고, 제목 옆에 🔁 재전송을 붙인다. 속도를 위해 이미지 본문 OCR은 건너뛰어서 한 번에 20초 정도 걸린다. 이 옵션을 실행하는 재전송 크론을 따로 등록하고 일시정지해 두었다. 크론 작업에는 일정이 필요해서 일일 크론과 같은 매일 오전 9시로 등록했다.

1
{
2
  "id": "4d47295f5480",
3
  "name": "gamejob-watch-resend",
4
  "script": "gamejob_watch_resend.sh",
5
  "no_agent": true,
6
  "schedule": { "kind": "cron", "expr": "0 9 * * *" },
7
  "enabled": false,
8
  "state": "paused",
9
  "deliver": "slack:C0CE49Y6VKK"
10
}

gamejob_watch_resend.sh는 일일 크론의 래퍼와 같은 스크립트를 --resend로 실행한다. 스크립트 출력을 채널에 보내는 일은 크론 전송을 거쳐야 해서, 재전송도 크론으로 만들었다.

일시정지한 크론은 수동 실행도 거부된다. 그래서 재전송할 때는 크론을 재개하고, 실행하고, 바로 다시 일시정지한다. 실행은 백그라운드에서 이어지므로 일시정지해도 전송은 끝난다. 재개한 채로 두면 다음 날 오전 9시에 정식 목록과 재전송 목록이 함께 올라가기 때문에, 이 순서를 스킬 문서에 적어 두었다.

검증은 실제 데이터를 복사한 폴더에서 먼저 했다. 즐겨찾기 3건(일부러 만든 게시 종료 공고 1건 포함)을 넣었을 때 언리얼 구간이 40건에서 38건으로 줄었고, 게시 종료 공고에는 마감일 대신 🔚 게시 종료가 붙었다. 재전송 전후로 본 공고 기록과 직전 실행 목록은 그대로였다. 정식 실행에서는 게시 종료된 즐겨찾기 공고가 직전 실행 목록(last_ids)에 들어가지 않는 것도 확인했다. 들어가면 다음 실행마다 “사라진 공고”로 잡힌다.

점검에서 나온 필터 오탐#

즐겨찾기를 붙인 뒤 스크립트와 설정을 한 번 점검했다. 정규식은 대소문자를 구분하지 않고 공고 제목과 본문에 적용되는데, 단어 일부에 걸리거나 범위가 너무 넓은 항목이 나왔다. 경력 조건과 설정 검증도 하나씩 손봤다.

유니티 판정 정규식의 unity는 community나 opportunity 안에서도 걸렸다. 영어 공고에 흔한 단어라서, 언리얼 공고가 유니티 언급이 더 많다고 판정돼 빠질 수 있었다. 이번 목록에서 이 때문에 빠진 공고는 없었지만 단어 단위로만 맞추게 바꿨다.

1
before: 유니티|unity|cocos|…
2
after:  유니티|\bunity(?![a-z])|cocos|…

직무 포함 정규식의 엔진은 엔진 프로그래머를 받으려고 넣은 단어인데, 제목에 언리얼엔진이 들어간 아트 공고까지 통과시켰다. 드래곤플라이의 [스페셜포스 리마스터] 언리얼엔진 3D 그래픽 모집이 그런 경우였다. 제목에 아트가 없어서 제외 정규식에도 걸리지 않았다. 앞에 언리얼이 붙은 엔진은 맞추지 않도록 부정형 lookbehind를 넣었다. 블랙스톰의 언리얼5 RPG 게임 프로젝트 신규 개발자 채용 (이펙트)는 개발자로 통과하고 있어서, 제외 정규식에 이펙트를 추가했다.

1
before: …|서버|엔진|네트워크|…
2
after:  …|서버|(?<!언리얼)(?<!언리얼 )엔진|네트워크|…

반대 방향의 오탐도 있었다. 제외 정규식의 보안이 네오플의 최적화/보안 클라이언트 프로그래머를 직무 단계에서 빼고 있었다. 보안 직군만 빠지도록 범위를 좁혔다. 이 공고는 본문에 Unity가 적혀 있어서 고친 뒤에도 엔진 단계에서 빠졌고, 최종 목록은 바뀌지 않았다.

1
before: …|인프라|보안|강사|…
2
after:  …|인프라|보안 ?(?:엔지니어|관제|담당자|운영)|정보보안|강사|…

경력 조건에도 하나가 있었다. 하이퍼센트의 [PC 게임] 언리얼 개발자 신입 채용은 게임잡 경력 필드가 경력무관이라 통과하고 있었다. career_min_years가 설정되어 신입을 제외하는 경우에는 제목에 신입만 있고 경력이 없는 공고는 빼도록 했다. 서버(신입/경력)처럼 둘 다 적힌 공고는 남는다.

정규식 변경은 캐시된 상세 페이지에 다시 적용하면 되기 때문에, 바꾸기 전과 후의 결과를 공고 번호로 비교했다. 최종 47건에서 아트·이펙트 공고 2건이 빠져 45건, 신입 공고 1건이 더 빠져 44건이 됐다.

마지막으로 조건 변경 명령(--set)의 검증 범위를 넓혔다. 이전에는 일부 정규식만 저장 전에 검사해서, 엔진 판정 정규식에 오타가 있으면 그대로 저장되고 다음 날 크론이 오류로 끝날 수 있었다. 지금은 이름이 _regex로 끝나는 항목을 모두 저장 전에 컴파일해 본다.

에이전트가 아니라 스크립트로 돌린다#

처음 정한 조건은 단순했다. 하루 한 번 오전 9시에 실행하고, 신규 공고만이 아니라 현재 진행 중인 전체 목록을 보여 준다. 새로 올라온 공고에는 신규 표시를 붙인다. 이전 공고를 계속 보여 주지 않으면 놓칠 수 있다는 이유였다. 알림은 DM이 아니라 별도 채널에 받기로 했다.

실행 방식으로는 두 가지를 비교했다. 에이전트가 매번 수집하고 비교하고 포맷하는 방식과, 이 단계를 스크립트로 고정하고 크론이 스크립트만 실행하는 방식이다. 이 작업은 요청, 파싱, 목록 비교, 포맷팅이 대부분이라 높은 추론이 필요하지 않다. 스크립트는 결과가 매일 같은 규칙으로 나오고 비용이 거의 없다. 대신 사이트 구조가 바뀌거나 차단되면 스크립트가 실패하고, 실패하면 알림이 간다. 스크립트 방식으로 정했다.

크론은 no_agent 모드로 등록했다. 이 모드에서는 스케줄러가 스크립트를 실행하고 stdout을 그대로 채널에 보낸다. 수동으로 실행한 결과에도 API calls: 0과 Mode: no_agent (script)가 찍혔다.

처음에는 언리얼 전용 스킬 gamejob-unreal-watch로 시작했다. 이후 검색 조건을 직접 정하고 바꿀 수 있게 스킬 이름을 gamejob-watch로 바꾸고, 조건을 config.json의 watch 단위로 분리했다. 지역, 직무, 경력, 엔진 규칙이 모두 이 파일에 있고, 변경은 스크립트 옵션으로 한다.

키워드 검색으로는 놓친다#

처음 확인할 건 게임잡 검색이었다. 스크립트에서 GET /Recruit/joblist?searchstring=...을 보내면 서버가 키워드를 무시하고 모든 공고를 돌려줬다. 엉터리 검색어를 넣어도 마찬가지였다. 브라우저에서 같은 주소로 검색이 되는 것은 페이지가 목록을 따로 불러오기 때문으로 보인다. 스크립트에서 키워드가 실제로 적용되는 쪽은 POST /Recruit/_GI_Job_List/였다.

그런데 키워드가 적용돼도 문제가 남았다. 일부 공고에는 언리얼이라는 단어가 없어서 검색에 걸리지 않았다. 키워드에 C++, GAS만 적힌 공고가 그런 경우다. 그래서 키워드 검색을 버리고 서울·경기 공고를 전부 수집한 뒤, 직무와 본문을 읽어 판정하는 구조로 바꿨다. 한 번 실행에 수집하는 공고는 1,000건이 넘는다(최근 실행에서 1,322건).

오분류를 추적하며 규칙을 고친 과정#

판정 규칙은 Slack에 실제로 보낸 결과를 내가 보고 짚는 대로 고쳤다. 큰 수정은 세 가지였다.

첫째는 엔진이 적히지 않은 후보를 기기 종류로 좁히려던 시도다. 새 필터로 처음 보낸 전송은 전체 78건 가운데 엔진 미명시 후보가 45건이었고, 개발 PM과 유니티 프로젝트가 섞여 있었다. 금지 목록을 늘리지 않고 들어오는 조건을 좁히기로 했다. 직무 포함 목록에서 PM 관련 단어를 빼고, 엔진 미명시 후보는 게임잡에 PC·콘솔 대상으로 등록된 공고만 받았다. 모바일 프로젝트는 대개 유니티라는 가정이었다. 후보는 23건, 전체는 55건이 됐다.

그런데 유니티 공고인 니케 공고가 여전히 후보에 있었다. 본문에 엔진 이름이 없었고 등록된 디바이스는 모바일게임, 멀티플랫폼게임이었다. 후보 조건이 PC·콘솔·멀티플랫폼 중 하나만 있어도 통과였는데, 이 공고처럼 멀티플랫폼게임이 모바일 위주 게임에도 붙기 때문에 걸러지지 않았다. 디바이스가 전부 PC나 콘솔일 때만 통과시키자 후보가 17건에서 9건으로 줄었다. 하지만 모바일과 멀티플랫폼 공고도 받아야 하는데, 기기 종류로 유니티를 가려내는 방식은 근거가 약하다고 보고 접었다.

둘째는 본문을 읽는 위치가 틀렸다는 점이다. 니케 공고를 다시 확인하다가 본문을 읽지 못하고 있었다는 것을 알았다. 실제 담당업무와 자격요건은 View 페이지가 아니라 iframe 두 개(GI_Read_Comt_Ifrm, GI_Read_GI_Comment_Ifrm)에 있는데, 이 iframe을 댓글 영역으로 오해해서 읽지 않았다. 그때까지의 엔진 판정은 제목, 키워드, 모집분야, 디바이스만 보고 한 것이었다. 본문을 읽기 시작하자 “Unity 엔진 … 능숙하신 분” 같은 문장이 잡혔고, 본문에 유니티가 있던 후보는 빠졌다. 반대로 본문에 언리얼이 적혀 있던 공고는 언리얼 구간으로 올라왔다.

본문을 읽으니 유니티 필수에 언리얼 우대인 공고, Unreal Engine 또는 Unity로 적힌 공고가 언리얼 구간에 들어와 있다는 것도 보였다. 그래서 언리얼 언급이 유니티 언급보다 많을 때만 언리얼 공고로 인정하기로 했다. 이 규칙이 생기면서 니케 공고를 번호로 제외하던 수동 설정을 걷어 냈다.

셋째는 본문이 이미지 한 장인 공고다. 언리얼 공고인데 빠져 있던 공고(GI_No=285987)는 Tong_....png 한 장이 본문이었다. 이미지 안에는 Unreal Engine, GAS, Unreal Editor가 적혀 있었지만 텍스트로는 한 글자도 읽을 수 없었다.

위 이미지는 공고 이미지에서 이 표만 잘라 낸 것이다.

직무 필터를 통과한 136건 가운데 26건(약 19%)이 이미지 본문이었다. 공고마다 include_ids로 고정하는 방법도 있었지만 이미지 공고가 계속 올라오기 때문에 자동화하는 쪽을 택했다. macOS의 Swift로 Apple Vision의 한국어 OCR을 스크립트에 붙였다. OCR은 로컬에서 실행되므로 모델 호출이 없다. 이미지는 한 번 읽어 캐시에 저장하고, 실행마다 처리하는 장수에 상한을 둬서 크론이 길어지지 않게 했다. 이미지 주소에 한글이 들어 있는 공고에서 OCR이 실패하는 오류도 이때 고쳤다.

엔진 판정 기준을 정리하기#

한동안은 엔진 미명시 후보를 PC·콘솔 후보와 모바일·멀티플랫폼 후보 두 구간으로 나눠 보여 줬다. 후보를 둘로 나눌 필요는 없다고 판단해서 하나로 합쳤고, 기기 구분 설정(candidate_platform_regex)은 비워 뒀다. 이어서 구간 이름도 “언리얼 명시”는 “언리얼”, “엔진 미명시”는 “C++“로 바꿨다. 이름만 바꾼 게 아니라 규칙으로 만들었다. 엔진 언급이 없는 공고 중 C++가 언급된 공고만 후보가 된다. 모바일 유니티 프로젝트는 대개 C#이라 이 조건에서 걸러지는 효과도 있다. 후보 7건은 모두 이 조건을 만족해서 목록은 그대로였다.

최종 기준은 두 구간이다. 언리얼 구간은 본문이나 이미지에 Unreal, UE4/5나 간접 단서가 있고, 그 언급이 다른 엔진보다 많은 공고다. C++ 구간은 엔진 언급이 전혀 없고 C++가 언급되며 직무가 클라이언트·엔진 계열인 공고다. 다른 엔진 언급이 더 많거나 후보 조건에 맞지 않는 공고는 어느 구간에도 들어가지 않는다.

간접 단서도 함께 정했다. 처음 필터 안내에는 Unreal·UE4/5·GAS·블루프린트만 적혀 있었는데, 목록을 넓혔다. 이제 GAS, 블루프린트, UMG, Dedicated Server, Niagara, Nanite, UCLASS와 UPROPERTY 같은 매크로, Gameplay Ability System, World Partition, Enhanced Input, Control Rig, MetaSound를 쓴다. Slate, Sequencer, Chaos, Lumen, Mass, PCG, Epic Games, Lyra는 너무 일반적이라 넣지 않았다. Dedicated Server는 유니티 프로젝트에서도 쓰는 말이지만, 언리얼보다 유니티 언급이 많은 공고는 언리얼 구간에 넣지 않는 규칙이 이를 걸러 준다. 이 단서들을 추가했을 때 기존 캐시에서 판정이 바뀐 공고는 없었다.

필수와 우대를 나눠서 우대에만 언리얼이 있는 공고를 따로 표시하는 방안도 검토했다. 이미지 본문의 OCR 텍스트는 순서를 믿을 수 없어서 파싱 비용에 비해 얻는 게 적다고 보고 하지 않기로 했다. 해당하는 공고는 당시 언리얼 구간 40건 중 1건 정도였다.

Slack에서 읽기 편하게 고치기#

첫 전송 결과에서 바로 고칠 것이 나왔다. 가장 먼저 필터 내용을 항상 최상단에 두기로 했다. 제목도 게임잡 언리얼 개발 공고에서 게임잡 공고로 바꿨다. 조건이 바뀔 때마다 제목이 어긋나므로 제목에는 조건을 넣지 않고 필터 블록에 적는다. 한 줄로 길게 이어지던 필터는 항목별 목록으로 나눴다.

들여쓰기는 여러 번 고쳤다. 같은 회사의 공고가 여러 개면 회사명 아래에 하위 항목으로 묶어 보여 주는데, 처음에는 한 회사에서 회사명 줄의 글머리 기호가 사라졌다. 여러 공고가 있는 회사의 이름 앞에 •를 붙이고 아래 항목을 들여써서 고쳤다.

다음 문제는 메시지가 길어서 나뉘는 지점에서 하위 항목의 들여쓰기가 사라지는 것이었다.

소스를 확인해 보니 Slack 어댑터가 긴 메시지를 나눈 뒤 다음 조각을 lstrip()한다. 새 조각의 첫 줄 앞 공백이 지워지는 이유다. 처음에는 일반 공백 대신 공백으로 취급되지 않는 점자 빈 칸(U+2800)으로 들여써서 막았다. 하지만 회사명 줄과 하위 공고가 서로 다른 조각으로 갈라지는 문제는 그대로였다. 그래서 나뉠 것 같으면 다음 블록에서 시작하게 바꿨다. 회사 묶음은 쪼개지 않고, 블록이 2,400자 가까이 되면 다음 묶음부터 새 블록에서 시작한다. 이렇게 하면 블록이 하위 항목으로 시작하는 일이 없다. 이때 점자 빈 칸은 걷어 내고 일반 공백 들여쓰기로 되돌렸다.

그런데 블록 중간에 있는 묶음에서도 공백 들여쓰기가 사라지는 경우가 나왔다. 블록 경계만의 문제가 아니었다. 그래서 공백 들여쓰기를 포기하고 하위 항목의 줄 머리를 점자 빈 칸 두 개와 ↳로 바꿨다. 공백이 사라져도 ↳만으로 하위 항목임을 알 수 있다. 블록을 나누는 방식은 그대로 두었다.

같은 확인 과정에서 Hermes의 Slack 어댑터가 *텍스트*를 기울임으로 바꾼다는 것도 알게 됐다. 굵게 하려던 회사명이 기울임으로 나오고 있어서 굵은 글씨는 **텍스트**로 쓴다.

마지막으로 메시지 맨 아래에 실행 정보를 붙였다. 소요 시간, 수집에서 최종까지의 건수, 직전 실행 대비 신규와 사라진 공고 수, OCR 처리 현황을 보여 준다. 소요 시간은 스크립트 실행 시간만 잰다.

최종 구성#

스킬 gamejob-watch는 스크립트, OCR 도우미, 설명 문서로 이루어진다. 조건과 상태는 스킬 밖에 둬서 스킬을 수정해도 남는다.

1
~/.hermes/skills/productivity/gamejob-watch/
2
├── SKILL.md              # 조건 변경 절차, 필터 원칙, 함정 기록
3
└── scripts/
4
    ├── gamejob_watch.py  # 수집·판정·포맷 (표준 라이브러리만 사용)
5
    └── ocr.swift         # Apple Vision OCR (필요할 때 컴파일)
6

7
~/.hermes/scripts/gamejob_watch.sh        # 크론이 실행하는 래퍼
8
~/.hermes/data/gamejob-watch/config.json  # 조건
9
~/.hermes/data/gamejob-watch/seen.json    # 본 공고 기록, 상세 페이지 캐시

크론은 래퍼 스크립트 하나를 실행한다.

1
#!/bin/bash
2
exec /usr/bin/python3 -I "$HOME/.hermes/skills/productivity/gamejob-watch/scripts/gamejob_watch.py" "$@"

config.json은 watch 이름 아래에 조건을 둔다. 정규식이 길어서 일부는 …로 줄였다.

1
{
2
  "watches": {
3
    "unreal-dev": {
4
      "title": "게임잡 공고",
5
      "local_codes": ["I000", "B000"],
6
      "location_regex": "서울|경기",
7
      "role_include_regex": "프로그래|개발자|엔지니어|클라이언트|서버|엔진|…",
8
      "role_exclude_regex": "아트|\\bTA\\b|테크니컬|…|QA|기획|…",
9
      "candidate_role_regex": "클라이언트|클라\\b|게임플레이|엔진|…",
10
      "engine_regex": "언리얼|unreal|\\bUE[45]\\b|\\bGAS\\b|블루프린트|…",
11
      "other_engine_regex": "유니티|unity|cocos|코코스|godot|자체 ?엔진|in-?house engine",
12
      "candidate_require_regex": "C\\+\\+",
13
      "career_min_years": 1,
14
      "career_max_years": 7,
15
      "career_any_ok": true,
16
      "imminent_days": 3,
17
      "baseline_first_run": true
18
    }
19
  }
20
}

경력 조건은 요구 경력이 1년에서 7년인 공고와 경력무관만 받고 신입은 제외하는 설정이다. 경력이 7–8년 수준이라 요구 경력의 하한이 7년 이하인 공고만 보기로 했다. 필터는 제외 목록을 늘리는 대신 포함 조건으로 정하는 것이 원칙이다. 직무는 제목이 포함 정규식에 맞아야 하고, role_exclude_regex는 남은 것을 정리하는 용도로만 쓴다. PM 직군은 포함 정규식에 PM 관련 단어를 넣지 않아서 빠지고, 유니티 프로젝트는 본문의 엔진 언급을 비교해서 걸러진다.

조건은 스크립트 옵션으로 바꾼다. 변경한 뒤에는 --dry-run으로 결과를 확인한다. 이 옵션은 본 공고 기록을 갱신하지 않는다.

1
S=~/.hermes/scripts/gamejob_watch.sh
2
$S --show                                  # watch 목록과 설정
3
$S --set unreal-dev career_max_years 7     # 값은 JSON 또는 문자열
4
$S --dry-run --watch unreal-dev            # 미리보기

크론 작업은 no_agent로 등록되어 있다. 아래는 저장된 작업 정의에서 실행에 쓰이는 항목이다.

1
{
2
  "id": "b46eb024f9ff",
3
  "name": "gamejob-watch-daily",
4
  "script": "gamejob_watch.sh",
5
  "no_agent": true,
6
  "schedule": { "kind": "cron", "expr": "0 9 * * *" },
7
  "deliver": "slack:C0CE49Y6VKK"
8
}

스크립트가 0이 아닌 코드로 끝나면 오류 알림이 간다. 채널 메시지 맨 위의 Cronjob Response와 job_id는 크론 전송이 붙이는 머리글이다.

cronjob run으로 수동 실행하면 실제 전송이고 본 공고 기록도 바뀐다. 필터를 크게 바꾼 뒤에는 신규 표시가 한꺼번에 붙을 수 있으므로, 채널에 보내지 않고 기준만 갱신할 때는 래퍼를 직접 실행한다.

다음에 하려는 일#

지금 이 파이프라인은 조건에 맞는 후보를 모아서 보여 주는 데까지만 한다. 그 뒤는 두 가지로 이어 갈 계획이다.

• 후보 추천도: 모은 후보를 세컨드 브레인(이력, 경력, 포트폴리오 같은 내 자료를 정리해 둔 곳)의 기준 자료와 비교해서 공고마다 추천도를 붙인다.
• 지원서 사전 준비: 내가 직접 고른 일부 후보에 한해서 에이전트가 다룰 수 있는 브라우저인 ego-browser로 지원 양식을 확보하고, 세컨드 브레인 자료를 바탕으로 그 양식에 맞춰 지원서를 미리 준비한다.

GitHub Actions#

GitHub Actions 러너에서 Node.js 20 기반 액션이 deprecated되면서 워크플로마다 경고가 나오던 것을 각 액션의 Node.js 24 릴리스로 올렸다. 이 변경은 직접 업스트림에 보낸 CuteLeaf/Firefly#676이다.

• SHA로 고정된 액션은 SHA와 버전 주석을 함께 갱신하고, 태그로 참조하던 액션은 태그를 유지했다.
• upload-pages-artifact는 v4부터 숨김 파일을 기본으로 제외한다. deploy.yml에 include-hidden-files: true를 추가해 dist/.nojekyll이 계속 업로드되도록 했다.
• dependabot.yml에 주 단위로 액션 업데이트를 묶어 올리는 github-actions 항목을 추가했다. 기존 npm 항목은 그대로다.

이 블로그도 GitHub Pages 배포에 같은 deploy.yml을 사용한다.

의존성#

• katex: 0.18.7 → 0.19.0. 폰트에 문자 메트릭이 없는 경우를 strict 옵션으로 보고하도록 바뀌었고(symbolNotInFont), strict 콜백이 undefined나 null을 반환하면 무시하지 않고 경고한다.
• marked: 18.0.12 → 18.1.0
• sanitize-html: 2.17.7 → 2.18.0, @types/sanitize-html: 2.16.1 → 2.16.2
• takumi-js: 2.13.7 → 2.14.0
• wrangler: 4.127.1 → 4.147.0
• subset-font: 2.7.0 → 2.9.0

검증#

• pnpm check: 265개 파일, 오류·경고·힌트 0개.
• pnpm type-check, pnpm build: 통과. 정적 페이지 119개를 생성하고 Pagefind에 91개 페이지를 인덱싱했다.
• 수식이 들어간 블로그 가이드가 KaTeX 0.19.0에서 katex-error 없이 렌더링되는 것을 확인했다.

업스트림 변경 비교

세 함수 비교#

각 함수가 하는 일#

언제 무엇을 부르나#

ForceNetUpdate의 flush는 조건부 덤이므로, 휴면 액터를 깨우는 일은 FlushNetDormancy에 맡긴다. 둘을 함께 쓰면 flush가 두 번 일어나지만, 두 번째 flush는 replicator를 다시 만들지 않아 비용이 거의 없다.

자주 하는 실수#

1
void AActor::ForceNetUpdate()
2
{
3
  UNetDriver* NetDriver = GetNetDriver();
4

5
  if (GetLocalRole() == ROLE_Authority)
6
  {
7
    if (NetDriver && NetDriver->GetNetMode() < ENetMode::NM_Client)
8
    {
9
      NetDriver->ForceNetUpdate(this);
10

11
      if (NetDormancy > DORM_Awake)
12
      {
13
        FlushNetDormancy();
14
      }
15
    }
16
  }
17

18
  // (생략) 게임 NetDriver가 아닌 NetDriver에는 ForceNetUpdate만 전달한다.
19
}

1
void AChestActor::AddItem(const FChestItem& NewItem)
2
{
3
  FChestItem& Item = Items.Items.Add_GetRef(NewItem);
4
  Items.MarkItemDirty(Item);
5

6
  // 휴면 중이었다면 위 항목은 전달되지 않는다.
7
  ForceNetUpdate();
8
}

1
void AChestActor::AddItem(const FChestItem& NewItem)
2
{
3
  FlushNetDormancy();
4

5
  FChestItem& Item = Items.Items.Add_GetRef(NewItem);
6
  Items.MarkItemDirty(Item);
7
}

실수를 막는 방법#

1
void ADoorActor::SetOpen(bool bNewOpen)
2
{
3
  check(HasAuthority());
4

5
  if (bOpen == bNewOpen)
6
  {
7
    return;
8
  }
9

10
  FlushNetDormancy();
11
  bOpen = bNewOpen;
12

13
  // 바로 보내야 하는 변경일 때만
14
  ForceNetUpdate();
15
}

참고 자료#

• Epic Games: Actor Network Dormancy
• Unreal Engine - Push Model Networking

한눈에 보기#

파일은 12개뿐이고 실행 로직이 있는 코드는 SessionStart 훅 스크립트 하나다.

• 작성자는 Epic Games 개발자들이다.
• 원래 이름은 unreal-mcp였다. 개발 중에 “as per legal request”라는 사유로 지금 이름으로 바뀌었다.
• 스킬을 크게 고친 커밋 여러 개에 Co-Authored-By: Claude 트레일러가 붙어 있다. 스킬을 Claude와 함께 다듬어 왔다.
• Anthropic 공식 마켓플레이스 claude-plugins-official에 등록돼 있다. 마켓플레이스에서는 Unreal Engine MCP라는 이름으로 보인다.

실제 기능은 엔진에 있다. 레포는 Claude가 그 기능을 쓰는 방법을 적은 문서 묶음에 가깝다.

• 연결 주소는 기본값 http://127.0.0.1:8000/mcp다.
• 플러그인은 .mcp.json을 포함하지 않는다. 에디터 콘솔에서 ModelContextProtocol.GenerateClientConfig ClaudeCode로 만든다.
• ModelContextProtocol만 켜면 서버는 뜨지만 도구가 하나도 없다. 도구는 AllToolsets가 켜는 툴셋 플러그인들이 제공한다.

unreal-mcp: 에디터를 조작하는 스킬#

1
Concrete triggers:
2
  spawn/move/duplicate/transform actors,
3
  create or edit a Blueprint/Widget/Material/...,
4
  read or write properties on actors
5
  (e.g. `bIsLocked` on `BP_DoorActor`), ...
6
Treat as Unreal context even without
7
the word "Unreal":
8
  asset prefixes `BP_`, `WBP_`, `M_`, `SK_`, ...;
9
  UE C++ types/macros; `.uproject`;
10
  Content Browser; Outliner; PlayerStart; ...
11
Skip for:
12
  pure conceptual/docs questions,
13
  Unity, Godot, or unrelated uses of
14
  "blueprint"/"sequencer"/"widget".

create-toolset: Claude가 쓸 도구를 Claude가 만들게 하는 스킬#

에디터에 새 도구를 추가하는 방법을 다룬다. 레포에서 가장 큰 스킬이다.

1
// Over-documented: every line restates the signature or narrates usage.
2
/**
3
 * Runs a cheat. @param CheatName The cheat name (case-insensitive), pass it to run the cheat.
4
 * @param Args Optional arguments; fill in the slots from the Args hint (e.g. "<float F>" -> "2.0",
5
 *             "<float A> <float B>" -> "1 2"). Empty string for no arguments.
6
 */
7
// Trimmed: only the non-inferable facts remain.
8
/**
9
 * Runs a cheat on the local player, as if typed into the console.
10
 * @param CheatName The cheat command name.
11
 * @param Args Arguments as a single space-separated string. Empty for none.
12
 */

unreal-skill: 스킬을 만드는 스킬#

스킬이 두 층이다#

이 스킬은 엔진 쪽 Agent Skill을 작성하는 방법을 다룬다. Claude Code 스킬과는 이름만 같고 다른 물건이다.

	Claude Code 스킬	Agent Skill
정체	SKILL.md 파일	UAgentSkill 파생 UClass
위치	.claude/skills/ 등	플러그인 코드, Content 에셋
전달	하네스가 파일을 읽음	에디터가 MCP로 반환
호출	자동	ListSkills 직접 호출
클라이언트	Claude Code	MCP 클라이언트 전부

Agent Skill은 플러그인의 C++/Python 클래스로 정의하거나 프로젝트 Content에 블루프린트 클래스 에셋으로 만든다. 어느 쪽이든 에디터가 로드한 클래스를 MCP 도구가 텍스트로 돌려준다.

• ListSkills는 UAgentSkill의 파생 클래스를 모두 찾아 경로와 Description을 돌려준다. 프로젝트 설정의 허용/차단 정규식(AgentSkillAllowedNames, AgentSkillBlockedNames)으로 노출할 스킬을 거른다.
• 자동 호출이 없기 때문에 unreal-mcp 스킬이 “낯선 작업을 시작할 때마다 ListSkills를 확인하라”고 지시한다. Claude Code에서는 하네스가 하는 일을 여기서는 지시문이 대신한다.

1
UCLASS()
2
class UPCGGraphGenerationSkill : public UAgentSkill
3
{
4
  GENERATED_BODY()
5

6
protected:
7
  virtual FString GeneratePrompt_Implementation(const FString& InitialInstructions) const override
8
  {
9
    FString CustomInstructions = InitialInstructions;
10
    CustomInstructions.ReplaceInline(TEXT("{Subgraphs}"),
11
      *FString::Join(UPCGToolset::ListAvailableSubgraphs(), TEXT(", ")));
12
    CustomInstructions.ReplaceInline(TEXT("{Nodes}"),
13
      *FString::Join(UPCGToolset::ListNativeNodes(true), TEXT(", ")));
14
    // {Examples}, {Instant Graphs}도 같은 방식으로 채운다.
15
    return CustomInstructions;
16
  }
17
};

SessionStart 훅#

• 세션이 시작될 때(startup, resume, clear) 현재 디렉터리에서 위로 올라가며 UE 프로젝트 루트를 찾는다. Source/나 Content/ 안에서 세션을 열어도 찾는다.
• 루트 판정은 *.uproject 또는 GenerateProjectFiles.*(엔진 소스 트리)로 한다. Engine 폴더는 일부러 기준에서 뺐다.

1
is_project_root() {
2
  # Reliable top-level markers only. A bare `Engine` directory is NOT a marker:
3
  # the Unreal source tree contains an `Engine` module at
4
  # `Engine/Source/Runtime/Engine`, so walking up from a Runtime module would
5
  # otherwise short-circuit at `Source/Runtime` and mis-identify it as the root.
6
  local directory="$1"
7
  [ -f "$directory/GenerateProjectFiles.bat" ] && return 0
8
  [ -f "$directory/GenerateProjectFiles.sh" ] && return 0
9
  [ -f "$directory/GenerateProjectFiles.command" ] && return 0
10
  for candidate in "$directory"/*.uproject; do
11
    [ -e "$candidate" ] && return 0
12
  done
13
  return 1
14
}

• 찾으면 다음 내용을 컨텍스트에 넣는다. UE 프로젝트(또는 엔진 소스 트리)라는 사실, C++/UObject·Slate·UHT 관례를 따르라는 안내, 에디터 조작에는 unreal-mcp 스킬을 쓰라는 안내, .mcp.json이 없으면 생성 명령.
• UE 프로젝트가 아니면 아무것도 출력하지 않는다.
• 스킬의 자동 호출은 description에 기대므로 확률적이다. 훅은 이 폴더가 UE 프로젝트이고 쓸 스킬이 있다는 사실을 세션 처음에 확정적으로 알린다.
• bash 스크립트라서 Windows에서는 Git Bash나 WSL이 필요하다. 없으면 훅만 빠지고 MCP 도구는 동작한다. README에도 “There is no separate PowerShell companion script today”라고 적혀 있다.

보안: 경고는 글로, 강제는 어디서#

README의 Security 절은 네 가지를 경고한다.

1. “Localhost is not a trust boundary.” Origin 검증은 브라우저 탭을 막을 뿐이고 같은 사용자로 도는 프로세스는 모두 서버에 붙을 수 있다. 공식 문서도 인증 계층이 없다고 밝힌다.
2. ProgrammaticToolset.execute_tool_script는 에디터 프로세스 안에서 임의의 Python을 실행한다.
3. --dangerously-skip-permissions와 함께 쓰지 않는다. 쓴다면 범위를 좁히고 버려도 되는 프로젝트에서 쓴다.
4. 긴 세션 전에는 저장하고 커밋해 둔다. 도구 호출 한 번이 버전 관리 대상 에셋을 옮기거나 지울 수 있다.

스킬과 도구 설명도 같은 내용을 모델에게 말한다. 엔진의 CreateSkill/UpdateSkill 설명에는 “This should ONLY be called after getting explicit direction or permission from the user.”라고 적혀 있다. 사람이 읽는 README의 경고를 모델 쪽에서는 스킬과 도구 설명이 맡는다.

그렇다면 플러그인이 훅으로 강제할 수 있었을까. 네 가지를 하나씩 보면 대부분 Claude Code 훅의 범위 밖이다.

• localhost 문제의 위협 주체는 Claude Code가 아닌 다른 프로세스다. 서버 인증, 즉 엔진의 문제다.
• execute_tool_script는 PreToolUse 훅이 call_tool의 toolset_name과 tool_name을 보고 확인을 요구하거나 거부할 수 있다.
• 에디터의 미저장 에셋은 셸 훅이 볼 수 없다. 커밋 안 된 변경을 알려 주는 정도만 가능하다.

결국 훅으로 다룰 수 있는 경고는 execute_tool_script 하나다. 도구 검색 모드에서는 모든 호출이 call_tool 하나로 들어오므로, 도구 이름 기반 권한 규칙으로는 읽기 도구와 Python 실행을 나눠 허용할 수 없다. 훅이라면 나눌 수 있다. 다만 훅에 ProgrammaticToolset.execute_tool_script라는 이름을 넣으면 레포가 지키려는 Durable 원칙과 부딪힌다. 이 레포의 위험은 대부분 엔진 서버와 사용자의 운영 습관 쪽에 있어서 플러그인이 할 수 있는 일은 원래 좁다.

MCP만으로는 안 되나#

MCP 서버도 연결 직후(initialize 응답)에 instructions 문자열로 사용법을 보낼 수 있고 Claude Code는 이를 시스템 프롬프트에 넣는다. Unreal MCP의 응답 구조체에도 Instructions 필드가 있지만(ModelContextProtocolSession.h) 5.8.3 소스에서 값을 채우는 코드는 찾지 못했다. 지금은 스킬이 이 자리를 대신하고 있다.

instructions를 채운다고 해도 스킬이 맡는 일은 남는다.

• 도구 검색 모드에서 모델이 보는 것은 범용 메타 도구 3개뿐이다. 스킬은 BP_DoorActor 같은 표현만으로도 불린다.
• MCP는 연결되지 않으면 아무 정보도 보내지 못한다. 스킬은 setup.md, operations.md로 서버를 켜는 법과 복구법을 안내한다.
• 툴셋을 C++/Python으로 작성하는 일은 MCP 호출 밖의 코드 작업이라 create-toolset이 맡는다.

MCP는 연결된 뒤에만 말할 수 있고 스킬은 연결되기 전에도 말할 수 있다. 대신 스킬은 Claude Code에서만 동작하고 앞의 동시 호출 항목처럼 문서나 서버와 따로 바뀔 수 있다.

Claude Code용만 있다#

• 엔진의 Unreal MCP 서버는 특정 클라이언트에 묶여 있지 않다. ModelContextProtocol.GenerateClientConfig는 Claude Code, Cursor, VS Code, Gemini CLI, Codex CLI 다섯 가지 설정 파일을 만든다.
• 그런데 Epic이 함께 내놓은 스킬과 훅은 Claude Code 플러그인 하나뿐이다. EpicGames GitHub 조직에 공개된 AI 클라이언트용 플러그인은 이 레포뿐이고, 공식 문서도 이 플러그인만 언급한다.
• 설정 파일도 대우가 조금 다르다. Claude Code용 .mcp.json은 다시 생성하면 기존 내용에 병합되지만, Codex용 .codex/config.toml은 이미 있으면 덮어쓰지 않아서 손으로 고쳐야 한다.
• Codex 같은 다른 클라이언트도 MCP 도구와 엔진 쪽 Agent Skill은 그대로 쓸 수 있다. 빠지는 것은 이 레포의 스킬이 주는 트리거, 안전 수칙, 설치·복구 안내와 툴셋 작성 가이드다.

참고 자료#

• EpicGames/unreal-engine-skills-for-claude-code-plugin
• create-toolset 반환값 규칙에 관한 이슈 #11
• Epic Games: Unreal MCP in Unreal Editor
• Claude 마켓플레이스: Unreal Engine MCP
• 언리얼 엔진 5.8 MCP로 본 게임 개발과 에이전틱 코딩의 거리

사이드 채팅을 여러 개 열고 세션으로 분리할 수 있다#

지난 글을 쓸 때는 사이드 채팅을 하나만 열 수 있었다. 이제는 Ctrl+;나 /btw로 연 사이드 채팅이 오른쪽 패널에 탭으로 쌓인다. 탭마다 따로 대화하고 각 탭 모두 메인 세션의 맥락을 읽는다.

기록이 쌓이는 방식도 달라졌다. 예전에는 사이드 채팅이 하나뿐이라 닫았다가 다시 열어도 이전 사이드 채팅 기록이 계속 이어서 쌓였다. 지금은 열 때마다 새 사이드 채팅이 만들어지는 것 같다. 질문마다 깨끗한 사이드 채팅에서 시작할 수 있어서 앞선 질문의 대화가 다음 질문에 섞이지 않는다.

탭 메뉴에는 최상위 레벨로 분리와 사이드 채팅 닫기가 있다.

최상위 레벨로 분리를 누르면 사이드바에 btw:로 시작하는 일반 세션이 생기고 패널에는 나머지 탭만 남는다. 분리한 세션에서도 그대로 대화를 이어갈 수 있다.

써보니 사이드 채팅을 세션 포크처럼 쓰는 기능에 가깝다. 실제로 Claude에게 세션 정보를 조회하게 해보면 분리한 세션은 원래 세션을 부모로 기록하고 있고 분리된 상태(detached)로 표시된다. 지난 글에서 Codex의 사이드 채팅을 포크처럼 쓸 수 있어서 더 편했다고 적었는데, 이제는 Claude Code에서도 비슷하게 쓸 수 있다.

공식 문서는 아직 사이드 채팅을 앱을 닫으면 다시 돌아갈 수 없는 대화로 설명한다. 남겨 둘 대화라면 분리해서 세션으로 만들어 두면 된다.

세션이 띄운 세션은 부모 아래에 묶인다#

Claude가 작업 도중 다른 세션을 시작하면 새 세션은 사이드바에서 원래 세션 아래에 묶여 표시된다. 하위 세션이 턴을 마치면 결과 요약이 부모 세션으로 돌아온다. 9월 중순에도 사이드바를 부모/자식 트리로 보여 달라는 요청이 올라왔을 만큼 이전에는 세션 사이의 관계가 사이드바에 드러나지 않았다.

이 글을 준비하면서도 Codex 쪽 동작을 조사하는 일을 하위 세션으로 맡겼다. Claude가 조사 세션을 카드로 제안했고 카드를 눌러 시작하자 이 세션 아래에 붙었다. 조사가 끝나자 결과가 원래 세션으로 전달됐다.

Codex에서는 조율하는 작업이 별도 작업(백그라운드 스레드)을 만들어 일을 나누는 식으로 써왔다. 비교하려고 Codex에서도 작업 하나에 별도 작업 두 개를 만들게 해봤다.

만들어진 작업은 사이드바에 원래 작업과 같은 레벨로 나열된다. 원래 작업의 오른쪽 패널에 생성된 작업으로 표시되기는 하지만 사이드바는 트리 구조가 아니다. 생성된 작업 쪽에 들어가 있으면 어느 작업이 만들었는지 알기 어려울 것 같다. 실제로 작업이 늘어나면 어느 대화에서 시작된 작업인지 헷갈렸다. Claude Code에서는 시작한 세션 아래에 묶여 있어서 이 관계가 바로 보인다.

Codex도 서브에이전트는 각자의 스레드를 열어 진행 상황을 볼 수 있고 부모 아래 묶어 보여주는 쪽이 의도된 동작으로 보인다. 다만 8월 이후 일부 데스크톱 빌드에서 서브에이전트 스레드가 최상위 목록에 따로 뜬다는 이슈가 올라와 있다. 내가 불편했던 쪽은 서브에이전트가 아니라 별도 작업이었다.

작업 과정이 기본으로 보인다#

이제 Claude가 여러 단계의 일을 하면 마지막 메시지 아래에 작업 목록이 붙는다. 진행 중인 단계와 남은 단계가 표시되고 계획이 바뀌면 목록도 함께 바뀐다.

예전에는 진행 상황을 보려고 ledger나 체크포인트 문서 같은 외부 파일을 따로 만들고 세션이 그 파일을 확인하면서 단계가 끝날 때마다 보고하게 했다. 이제는 그런 파일 없이도 지금 어느 단계인지 화면에서 바로 보인다.

턴이 끝나면 요약 카드도 뜬다. 무엇이 바뀌었고 어디까지 됐는지를 두세 문장으로 정리하고 사용자가 정해야 할 일이 있으면 질문과 선택 버튼을 함께 보여준다. 업데이트 소개 기사에 따르면 사이드바에서도 작업 중인 세션과 입력을 기다리는 세션이 구분된다.

새 세션 화면과 환경 저장#

새 세션 화면도 바뀌었다. 새로 생성을 누르면 화면 가운데에 최근에 쓴 폴더 목록과 환경 선택 메뉴가 뜬다. 환경 선택에서는 로컬, 클라우드, Remote Control, WSL을 고를 수 있고 새 환경으로 구성을 추가할 수 있다. 로컬 환경에는 Alt+1, Alt+2 같은 단축키가 붙는다. CLI에서 시작한 세션을 가져오는 버튼도 같은 화면에 있다.

업데이트 소개 기사에 따르면 저장한 환경에는 여러 폴더와 SSH 호스트나 클라우드 대상, 폴더별 worktree 사용 여부가 들어간다.

지난 글에서 여러 폴더를 묶는 과정이 어색하다고 적었는데, 환경 저장이 그 부분을 겨냥한 기능으로 보인다. 아직 직접 써보지는 않아서 Codex의 프로젝트처럼 쓸 수 있는지는 확인하지 못했다.

정리#

한 달이 지나면 Codex로 돌아갈 생각이었다. 그런데 지난 글에서 아쉬운 점으로 적은 사이드 채팅이 2주도 안 돼서 바뀌었고, 세션이 띄운 세션을 묶어 보여주는 방식은 Codex보다 낫다고 느꼈다. 돌아갈지는 조금 더 써보고 정하려 한다.

참고 자료#

• ClaudeDevs: Claude Code 데스크톱 앱 업데이트 발표
• AlphaSignal: Anthropic’s Claude Code Now Runs Nested Sessions and Saves Dev Environments
• Claude Code Docs: Desktop application
• Codex Docs: Subagents
• anthropics/claude-code#95195: Desktop sidebar: show sessions as a parent/child tree
• openai/codex#38780

기본 드라이버가 하는 일과 리플리케이션 그래프가 바꾸는 것#

UNetDriver::ServerReplicateActors는 매 네트워크 틱마다 세 단계를 거친다(Engine/Private/NetDriver.cpp).

1. Consider: FNetworkObjectList의 활성 액터를 순회해 NetUpdateFrequency로 계산한 갱신 시각이 지난 액터를 모은다. dormant 액터는 별도 목록에 있어 이 순회에서 빠진다.
2. Prioritize: 연결마다 consider list의 액터 하나하나에 AActor::IsNetRelevantFor와 GetNetPriority를 호출해 정렬한다.
3. Replicate: 정렬된 순서로 채널을 열어 UActorChannel::ReplicateActor를 호출한다.

두 번째 단계에 비용이 집중된다. IsNetRelevantFor와 GetNetPriority는 가상 함수라 엔진은 답이 언제 바뀌는지 알 수 없다. 그래서 매 프레임 모든 액터 × 모든 연결에 대해 다시 부른다. relevancy 검사를 통과한 액터만 세 번째 단계에 들어가므로 넓은 맵에 액터가 흩어진 게임일수록 두 번째 단계의 비용이 실제 송신 작업보다 커진다. 액터가 모두 한곳에 몰려 모든 연결에 관련 있으면 두 번째 단계는 어차피 다 통과하고 세 번째 단계가 지배한다.

리플리케이션 그래프는 UReplicationDriver를 구현한 UReplicationGraph다. 서버의 UNetDriver에 리플리케이션 드라이버가 설정돼 있으면 ServerReplicateActors는 stat·CSV 범위를 열고 메트릭을 리셋한 뒤 바로 ReplicationDriver->ServerReplicateActors로 넘긴다. consider list 구성과 우선순위 계산은 돌지 않는다. 플러그인 안에서 IsNetRelevantFor를 부르는 곳은 디버그 액터의 오버라이드뿐이다. 프로퍼티 비교와 직렬화는 그대로 UActorChannel::ReplicateActor가 한다.

리플리케이션 그래프는 프레임을 세 단계로 처리한다.

1. Gather: 연결마다 전역 노드와 그 연결의 노드에 GatherActorListsForConnection을 호출해 후보 리스트를 모은다. 노드는 대부분 프레임을 넘어 유지되는 리스트를 돌려주므로 어떤 액터를 고려할지를 다시 계산하지 않는다. 기본 드라이버의 consider list 구성에 해당하는 단계다.
2. Prioritize: 모은 리스트의 액터마다 dormancy, 리플리케이션 주기, 거리 컬링을 적용하고 우선순위 점수를 매겨 정렬한다.
3. Replicate: 정렬된 순서로 ReplicateSingleActor를 호출하고 연결이 포화되면 멈춘다.

공간 분할 노드인 Grid(UReplicationGraphNode_GridSpatialization2D)는 거리 검사를 대체하지 않는다. Grid는 맵을 정사각형 Cell로 나누고 viewer가 서 있는 Cell의 액터 리스트를 돌려줄 뿐이다. Cell에는 Net Cull Distance(액터의 NetCullDistanceSquared, 이하 Cull Distance) 범위가 Cell과 겹치는 모든 액터가 들어 있으므로 반경 밖 액터도 섞여 있다. 실제 거리 검사는 2단계에서 연결별 CullDistanceSquared로 따로 한다. 2018년 Epic 라이브스트림의 표현으로는 Grid가 broad phase, 거리 검사가 narrow phase다.

노드도 매 틱 조건을 검사하지 않는다. 노드의 역할은 조건을 한 번 평가해 리스트에 넣어 두고 바뀔 때만 옮기는 것이다. 매 틱 돌아가는 액터별 검사는 2단계에 모여 있다.

리플리케이션 그래프는 서버 CPU를 줄인다. 어떤 액터를 어느 연결에 보낼지가 같다면 보내는 바이트도 같다. 다만 리플리케이션 그래프 쪽에는 기본 드라이버에 없는 송신 측 도구가 둘 있다. dynamic 액터를 NumBuckets개 버킷에 나눠 두고 ReplicationFrameNum % NumBuckets번 버킷만 돌려주는 frequency bucket 노드와, 이동 상태를 한 번 직렬화해 모든 연결에 재사용하는 Fast Shared Path다.

Fast Shared Path는 액터 쪽에 FastSharedReplicationFunc로 등록할 unreliable multicast 함수를 써야 하고 그 프레임에는 일반 프로퍼티 리플리케이션이 생략되는 경로다. 그래서 측정에서는 켜지 않았다(Epic의 Fast Shared Path 가이드에 설정 절차가 있다). 테스트 액터에는 이동 상태가 없다. 효과도 Player Pawn 수 × 연결 수에서 나오므로 클라이언트 16개로는 보여 줄 폭이 작다.

측정: 액터 5,000개, 클라이언트 16개까지#

드라이버와 분포#

아래는 프레임당 ServerReplicateActors ms의 5회 평균과 표준편차다.

분포	기본 드라이버	Basic 그래프	OpenWorld 그래프
Cluster	8.09 ± 0.09	3.44 ± 0.03	4.48 ± 0.04
NearPlayers	6.47 ± 0.47	2.25 ± 0.02	2.84 ± 0.02
Uniform	2.54 ± 0.20	0.40 ± 0.01	0.35 ± 0.02

기본 드라이버의 NearPlayers와 Uniform은 런마다 서버 프레임 시간이 41–47 ms로 흔들려 편차가 ±8%이고 나머지 조건은 ±5% 안이다. 같은 기본 드라이버 Uniform 조건을 다른 측정 세트에서 다시 돌리면 2.05–2.23 ms가 나온다. 표의 2.54는 가장 높은 세트의 값이다. 아래 단계별 분해는 위의 Insights 타이머로 했다. 트레이스가 있는 첫 번째 런 하나의 값이라 표의 평균과 조금 다르다.

Uniform에서 리플리케이션 그래프는 기본 드라이버의 7분의 1이다. 단계별로 나누면 다음과 같다.

단계	기본 드라이버 (ms)	OpenWorld 그래프 (ms)
Consider / Gather	consider list 구성 1.7	PrepareForReplication 0.12, gather 0.01
Prioritize	두 연결 0.9	0.04 (검토 항목 71개)
Replicate	0.2 (프레임당 67회)	0.13
합계	2.8	0.3

기본 드라이버는 5,265개 중 연결당 30개 남짓만 보내는데 비용의 90% 이상이 보낼지 말지를 정하는 데 든다. OpenWorld 그래프는 Grid가 viewer Cell의 리스트만 돌려주므로 나머지 5,100개는 검토 대상이 아니다.

모든 액터가 모든 연결에 관련 있는 Cluster에서도 OpenWorld 그래프가 기본 드라이버의 55%, Basic이 43%다. 다만 이 차이는 판별 비용이 아닌 보내는 횟수에서 온다.

드라이버	연결당 ReplicateActor 호출	구성
기본 드라이버	1,561	깨어 있는 액터 전부를 매 프레임
Basic 그래프	524	깨어 있는 1,580개 전부가 버킷 3개에 나뉘어 세 프레임에 한 번
OpenWorld 그래프	735	AI·탈것 1,000개가 버킷에서 333회, 깨어 있는 소품 315개가 static 리스트에서 매 프레임, dependent 무기가 탈것에 묻어 83회

보내는 횟수를 맞춘 대조군 둘의 결과다.

기본 드라이버의 NetUpdateFrequency를 10으로 낮추면 호출이 연결당 501회로 줄고 3.06 ms가 된다. 서버가 초당 21–23 프레임이라 10 Hz는 세 프레임에 한 번꼴이다.

반대로 OpenWorld의 버킷을 1개로 줄이면 호출 수가 1,555회로 100 Hz 기본 드라이버의 1,561회와 거의 같아진다. 이때 리플리케이션 그래프는 9.89 ms로 기본 드라이버보다 22% 느리다.

네 조건의 호출당 비용은 2.6–3.2 µs로 같은 자릿수다. 밀집 조건의 비용은 보내는 횟수가 정하고 그 횟수는 어느 드라이버든 설정으로 바꿀 수 있다.

아래 두 그림은 Cluster 조건에서 측정 구간 60초의 Callees 트리를 펼친 것이다.

① UActorChannel::ReplicateActor 안의 시간은 7.51 s와 7.22 s, 프레임당 5.80 ms와 5.55 ms로 같고 호출당 약 1.8 µs다. 후보를 고르는 단계도 비슷하다. 첫 번째 그림의 기본 드라이버는 ② 두 연결의 우선순위 1.04 s와 ③ consider list 894.94 ms(프레임당 0.69 ms)를 합쳐 프레임당 1.49 ms다. 두 번째 그림의 리플리케이션 그래프는 prepare와 gather 0.16 ms에 ③ 우선순위 계산 1.68 s를 합쳐 1.45 ms다.

NET_ReplicateActors_ReplicateSingleActor가 채널 밖에서 하는 일에서 차이가 난다. 두 번째 그림의 ② DependentActors 1.72 s와 CallPreReplication 1.1 s가 그 일부다. DependentActors는 inclusive라 그 안에서 재귀 호출되는 무기 액터의 채널 시간이 대부분이고 순회 자체(Excl 열)는 0.24 s다.

리플리케이션 그래프의 채널 밖 작업	ms
ReplicateSingleActor 자체. dependent 목록 수집, 연결 정보의 프레임 번호 갱신, 채널 조회	1.31
액터마다 PreReplication 호출(CallPreReplication)	0.85
dependent actor 순회와 그 채널 닫힘 프레임 갱신(DependentActors 자체)	0.19
연결별 리스트 순회와 채널 정리(ReplicateActorsForConnection 잔여, LookForNonRelevantChannels, 후처리)	0.30
합계	2.65

기본 드라이버에서 ReplicateActor 밖에 남는 리플리케이션 루프 시간은 0.93 ms다. PreReplication은 consider list를 만들면서 부르므로 앞의 consider list 0.69 ms 안에 들어 있다. 리플리케이션한 액터 하나당 채널 밖 비용은 기본 0.30 µs, 리플리케이션 그래프 0.85 µs다. 영속 리스트가 줄이는 것은 검토할 액터 수뿐이고 보내는 액터마다 붙는 부가 비용은 기본 드라이버보다 크다. 보낼 액터가 많을수록 그 차이가 쌓인다.

NearPlayers는 둘의 중간이어야 하는데 기본 드라이버는 6.47 ms로 Cluster에 가깝다. 보내는 양은 연결당 770회로 Cluster의 절반이다. 그런데 consider list 구성이 1.38 ms로 Cluster의 두 배이고 우선순위 계산이 1.97 ms다.

테스트 프로젝트는 소품의 90%와 루트 전부를 DORM_DormantAll로 둔다. 그런데 FNetworkObjectList는 액터가 모든 연결에서 dormant가 됐을 때만 active 목록에서 뺀다(Engine/Private/NetworkObjectList.cpp, MarkDormant의 DormantConnections.Num() == NumConnections). Cluster에서는 두 클라이언트가 모든 액터를 받으므로 3,685개가 빠져 active가 1,580개다. 흩어진 분포에서는 각 소품을 한 클라이언트만 받으므로 영영 active에 남아 매 프레임 5,265개 전부가 consider list를 거친다. Uniform의 1.7 ms도 같은 원인이다.

CSV의 NumberOfFullyDormantActors는 Cluster에서 3,685, NearPlayers에서 0, Uniform에서 60 남짓(두 플레이어가 3 m 거리라 같은 소품 일부를 본다)이다. 일부 연결에서만 dormant인 액터는 그 연결의 우선순위 계산만 건너뛰고 consider list 구성 비용은 그대로 낸다. 목록에서는 모든 연결이 그 액터를 한 번씩 본 뒤에야 빠진다. 넓은 맵에서는 그런 일이 잘 일어나지 않는다. 리플리케이션 그래프는 dormant 액터를 연결별 bDormantOnConnection으로 걸러서 이 문제가 없다.

수치가 나오는 구조: 세 층, Grid, 프레임당 검사#

1
GridSpatialization2D
2
└── GridCell (Cell마다)
3
    ├── static 리스트 (자기 ReplicationActorList)
4
    ├── DynamicNode: ActorListFrequencyBuckets 또는 DynamicSpatialFrequency
5
    └── DormancyNode
6
        └── ConnectionDormancyNode (연결마다, 마스터 리스트의 사본)

설정값이 실제로 바꾸는 것#

Cell 크기, 버킷 수, NetUpdateFrequency, 우선순위 스케일, 채널 타임아웃이 각각 무엇을 바꾸는지 소스에서 확인하고 OpenWorld 그래프로 하나씩 바꿔 가며 쟀다. 조건은 Uniform 분포, 액터 5,000개, 클라이언트 2개이고 기준값은 Cell 100 m, 버킷 3개, NetUpdateFrequency 100, DistancePriorityScale 1, StarvationPriorityScale 1, ActorChannelFrameTimeout 4다. 각 3회 평균이고 단위는 프레임당 ServerReplicateActors ms, 호출은 연결당 ReplicateActor 횟수, 채널은 두 연결에 열린 채널 수의 합(Replication/NumOpenChannels, 프레임 평균), 검토는 Prioritize_InnerLoop가 프레임에 본 항목 수다.

시간을 크게 바꾸는 설정은 없다. 이 밀도에서 설정값은 보내는 횟수와 열린 채널 수를 바꾼다. 그 효과는 Cull Distance 안의 액터가 많을수록 커져 Cluster에서 두드러진다.

CellSize는 액터 하나가 등록되는 Cell 수(Cull Distance 150 m에 25 m Cell이면 13×13), dynamic 액터의 Cell 갱신 빈도, viewer Cell에 섞이는 Cull Distance 밖 액터 수를 정한다. 측정에서는 25 m와 400 m 모두 0.05 ms 안이고 400 m에서 검토 항목만 두 배다. Cull Distance와 같은 자릿수로 두고 NET_PrepareReplication과 검토 항목 수를 보며 조정한다.

버킷 수는 frequency bucket 노드가 Cell의 dynamic 액터를 나누는 개수이고 dynamic 액터 주기의 하한이다. ReplicationPeriodFrame과 겹치면 주기를 버킷 수의 배수로 올림한 값이 실제 간격이다(버킷 3에 주기 4면 6프레임). 1개면 호출 33회이고 Cluster에서는 4.48 ms와 9.89 ms를 가른다. Cull Distance 안에 dynamic 액터가 많을 때 가장 먼저 만진다. 단 30 Hz에 3개면 dynamic 액터가 10 Hz가 되니 이동 보간이 감당하는지 클라이언트에서 확인한다.

NetUpdateFrequency는 초기화 때 CDO 값으로 RoundToInt(NetServerMaxTickRate / NetUpdateFrequency)를 ReplicationPeriodFrame에 쓰고 그 뒤로는 프레임 수로만 센다. 런타임 SetNetUpdateFrequency는 반영되지 않고(Net.RepGraph.SetPeriodFrame은 클래스·액터와 명령을 보낸 연결의 값을 고친다) MinNetUpdateFrequency의 적응형 주기도 없다. 100·10·2에서 호출은 21·14·8회, 시간은 0.35·0.32·0.28 ms로 호출보다 완만하게 준다. 클래스별 송신 횟수를 정하는 값이고 서버 프레임 레이트보다 낮을 때만 뜻이 있다.

DynamicSpatialFrequency는 거리와 시야 방향 존마다 주기를 보간해 gather 안에서 직접 리플리케이션한다. prioritize 단계를 거치지 않아 DistancePriorityScale과 StarvationPriorityScale이 효과가 없다. 기본 존은 constexpr 30 Hz 가정이다. Net.RepGraph.DyanmicSpatialization.Reinit(오타가 실제 이름)도 같은 30 Hz 기본값을 다시 만들 뿐이어서 틱이 다르면 프로젝트가 존과 비트 예산을 직접 구성한다. 측정에서 호출은 16회로 줄지만 gather가 0.01에서 0.07 ms로 늘어 0.40 ms다. Cull Distance 안의 dynamic 액터가 수백 개일 때 송신량을 줄이는 용도이고 CPU는 늘어난다. 존 표의 함정은 커스텀 그래프 절에 있다.

DistancePriorityScale은 거리 점수의 가중치다. 거리 검사가 if (DistancePriorityScale > 0) 안에 있어 0이면 거리 컬링이 꺼진다. 측정에서 채널이 76에서 153으로, 호출이 34회로 늘었다. 거리 가중치만 끄려면 아주 작은 양수를 쓴다.

StarvationPriorityScale은 오래 못 받은 액터를 앞으로 당기는 가중치다. 위 표에서는 포화가 없어서 0으로 둬도 변화가 없었다. 포화돼서 뒤의 액터가 밀릴 때만 뜻이 있고 Net.RepGraph.StarvedList(마지막 리플리케이션 이후 프레임 수 순)로 확인한다. 포화 조건은 아래에서 따로 쟀다.

ActorChannelFrameTimeout은 마지막 gather 뒤 채널을 닫기까지의 프레임이다. 전역 여유 2를 더해 기본 7프레임이다. 0이면 relevancy로는 채널을 닫지 않는다(dormancy·tear-off·파괴로는 닫힌다). 0에서 채널이 212개가 되고 AI가 Cull Distance 경계를 드나드는 동안 계속 는다. Cull Distance 경계에서 채널이 자주 열리고 닫히면 올린다. 열린 채널은 양쪽 메모리를 쓰고 클라이언트에 액터가 남는다.

커스텀 그래프: 라우팅 테이블, Team Node, 걸리는 것#

커스텀 그래프의 출발점은 플러그인에 들어 있는 UBasicReplicationGraph다. 플러그인을 켜고 ReplicationDriverClassName에 /Script/ReplicationGraph.BasicReplicationGraph를 적으면 켜진다. Basic의 라우팅은 셋뿐이다.

• bAlwaysRelevant면 전역 ActorList
• bOnlyRelevantToOwner면 연결별 노드
• 나머지는 전부 Grid의 AddActor_Dormancy

RouteAddNetworkActorToNodes에는 주석이 하나 달려 있다. 엔진에는 액터가 움직이는지 판별하는 코드가 없고 AActor에 그 정보가 없으므로 깨어 있으면 움직일 수 있다는 가정으로 넣는다는 내용이다. 안 움직이는 소품 수천 개를 깨운 채로 두면 Basic은 그만큼의 PrepareForReplication 비용을 낸다.

static과 dynamic을 가르려면 프로젝트가 클래스 라우팅 테이블을 만들어야 하고, 이것이 커스텀 그래프를 쓰는 첫 번째 이유다. Basic에는 owner 변경의 재라우팅, PlayerState 빈도 제한, 팀 같은 범주도 없다. PlayerState는 bAlwaysRelevant라 전역 리스트로 가긴 한다.

1
UENUM()
2
enum class EClassRepNodeMapping : uint8
3
{
4
  NotRouted,
5
  RelevantAllConnections,
6
  RelevantOwnerConnection,
7
  Spatialize_Static,
8
  Spatialize_Dynamic,
9
  Spatialize_Dormancy,
10
};
11

12
static bool IsSpatialized(EClassRepNodeMapping Mapping) { return Mapping >= EClassRepNodeMapping::Spatialize_Static; }
13

14
UCLASS()
15
class UExampleReplicationGraph : public UReplicationGraph
16
{
17
  GENERATED_BODY()
18

19
public:
20
  virtual void InitGlobalActorClassSettings() override;
21
  virtual void InitGlobalGraphNodes() override;
22
  virtual void InitConnectionGraphNodes(UNetReplicationGraphConnection* RepGraphConnection) override;
23
  virtual void RouteAddNetworkActorToNodes(const FNewReplicatedActorInfo& ActorInfo, FGlobalActorReplicationInfo& GlobalInfo) override;
24
  virtual void RouteRemoveNetworkActorToNodes(const FNewReplicatedActorInfo& ActorInfo) override;
25

26
  EClassRepNodeMapping GetClassNodeMapping(UClass* Class) const;
27
  void InitClassReplicationInfo(FClassReplicationInfo& Info, UClass* Class, bool bSpatialize) const;
28

29
  UPROPERTY() TObjectPtr<UReplicationGraphNode_GridSpatialization2D> GridNode;
30
  UPROPERTY() TObjectPtr<UReplicationGraphNode_ActorList> AlwaysRelevantNode;
31
  TClassMap<EClassRepNodeMapping> ClassRepNodePolicies;
32
  TMap<TWeakObjectPtr<UNetConnection>, TObjectPtr<UReplicationGraphNode_AlwaysRelevant_ForConnection>> ConnectionNodes;
33
};
34

35
// 모든 PlayerState를 프레임당 TargetActorsPerFrame개씩 돌려 보내는 노드 (공식 문서의 PlayerStateFrequencyLimiter)
36
UCLASS()
37
class UExampleNode_PlayerStateFrequencyLimiter : public UReplicationGraphNode
38
{
39
  GENERATED_BODY()
40

41
public:
42
  // 이 플래그가 없으면 InitNode가 PrepareForReplication 목록에 넣지 않아 노드가 아무것도 돌려주지 않는다 (Team Node 절 참고)
43
  UExampleNode_PlayerStateFrequencyLimiter() { bRequiresPrepareForReplicationCall = true; }
44

45
  virtual void NotifyAddNetworkActor(const FNewReplicatedActorInfo& Actor) override {}
46
  virtual bool NotifyRemoveNetworkActor(const FNewReplicatedActorInfo& Actor, bool bWarnIfNotFound = true) override { return false; }
47
  virtual bool NotifyActorRenamed(const FRenamedReplicatedActorInfo& Actor, bool bWarnIfNotFound = true) override { return false; }
48
  virtual void PrepareForReplication() override;
49
  virtual void GatherActorListsForConnection(const FConnectionGatherActorListParameters& Params) override;
50

51
  int32 TargetActorsPerFrame = 2;
52
  TArray<FActorRepListRefView> ReplicationActorLists;
53
};

1
EClassRepNodeMapping UExampleReplicationGraph::GetClassNodeMapping(UClass* Class) const
2
{
3
  if (!Class) return EClassRepNodeMapping::NotRouted;
4

5
  // 명시적으로 정한 클래스는 그대로
6
  if (const EClassRepNodeMapping* Explicit = ClassRepNodePolicies.FindWithoutClassRecursion(Class)) return *Explicit;
7

8
  const AActor* CDO = Cast<AActor>(Class->GetDefaultObject());
9
  if (!CDO || !CDO->GetIsReplicated()) return EClassRepNodeMapping::NotRouted;
10

11
  // 부모와 플래그가 같으면 부모의 매핑을 따른다. NotRouted로 둔 PlayerState의 서브클래스도 여기로 온다
12
  if (const AActor* SuperCDO = Cast<AActor>(Class->GetSuperClass()->GetDefaultObject()))
13
  {
14
    if (SuperCDO->GetIsReplicated() == CDO->GetIsReplicated()
15
      && SuperCDO->bAlwaysRelevant == CDO->bAlwaysRelevant
16
      && SuperCDO->bOnlyRelevantToOwner == CDO->bOnlyRelevantToOwner
17
      && SuperCDO->bNetUseOwnerRelevancy == CDO->bNetUseOwnerRelevancy)
18
    {
19
      return GetClassNodeMapping(Class->GetSuperClass());
20
    }
21
  }
22

23
  // 레거시 플래그에서 기본값을 유도한다. 프로젝트 설정으로 덮어쓰는 부분은 생략
24
  if (CDO->bAlwaysRelevant && !CDO->bOnlyRelevantToOwner) return EClassRepNodeMapping::RelevantAllConnections;
25
  if (CDO->bOnlyRelevantToOwner) return EClassRepNodeMapping::RelevantOwnerConnection;
26
  return EClassRepNodeMapping::Spatialize_Dynamic;
27
}
28

29
void UExampleReplicationGraph::InitClassReplicationInfo(FClassReplicationInfo& Info, UClass* Class, bool bSpatialize) const
30
{
31
  const AActor* CDO = Class->GetDefaultObject<AActor>();
32
  Info.ReplicationPeriodFrame = GetReplicationPeriodFrameForFrequency(CDO->GetNetUpdateFrequency());
33
  // Cull Distance는 Grid에 들어가는 클래스에만 준다. AlwaysRelevant·owner 전용 액터는 WorldLocation이 원점에 고정이라
34
  // Cull Distance가 있으면 viewer가 원점에서 그만큼 멀어지는 순간 거리 컬링에 걸린다
35
  if (bSpatialize) Info.SetCullDistanceSquared(CDO->GetNetCullDistanceSquared());
36
}
37

38
void UExampleReplicationGraph::InitGlobalActorClassSettings()
39
{
40
  Super::InitGlobalActorClassSettings();
41

42
  // 전용 노드가 있는 엔진 클래스는 라우팅하지 않는다
43
  ClassRepNodePolicies.Set(APlayerState::StaticClass(), EClassRepNodeMapping::NotRouted);
44
  ClassRepNodePolicies.Set(ALevelScriptActor::StaticClass(), EClassRepNodeMapping::NotRouted);
45
  ClassRepNodePolicies.Set(AReplicationGraphDebugActor::StaticClass(), EClassRepNodeMapping::NotRouted);
46

47
  // 초기화 뒤에 로드되는 Blueprint 서브클래스는 첫 조회 때 이 두 람다로 온다
48
  ClassRepNodePolicies.InitNewElement = [this](UClass* Class, EClassRepNodeMapping& Mapping)
49
  {
50
    Mapping = GetClassNodeMapping(Class);
51
    return true;
52
  };
53
  GlobalActorReplicationInfoMap.SetInitClassInfoFunc([this](UClass* Class, FClassReplicationInfo& Info)
54
  {
55
    InitClassReplicationInfo(Info, Class, IsSpatialized(ClassRepNodePolicies.GetChecked(Class)));
56
    return true;
57
  });
58

59
  for (TObjectIterator<UClass> It; It; ++It)
60
  {
61
    UClass* Class = *It;
62
    const AActor* CDO = Cast<AActor>(Class->GetDefaultObject());
63
    if (!CDO || !CDO->GetIsReplicated()) continue;
64
    if (Class->GetName().StartsWith(TEXT("SKEL_")) || Class->GetName().StartsWith(TEXT("REINST_"))) continue;
65

66
    // TClassMap::Get은 부모 값을 자식 키로 복사해 돌려주므로 "없을 때만 Set"이라는 가드를 쓰면 자식이 부모 라우팅을 물려받는다. 무조건 쓴다
67
    const EClassRepNodeMapping Mapping = GetClassNodeMapping(Class);
68
    ClassRepNodePolicies.Set(Class, Mapping);
69

70
    FClassReplicationInfo Info;
71
    InitClassReplicationInfo(Info, Class, IsSpatialized(Mapping));
72
    GlobalActorReplicationInfoMap.SetClassInfo(Class, Info);
73
  }
74

75
  UReplicationGraphNode_ActorListFrequencyBuckets::DefaultSettings.NumBuckets = 3;
76
  UReplicationGraphNode_ActorListFrequencyBuckets::DefaultSettings.BucketThresholds.Reset();
77
}
78

79
void UExampleReplicationGraph::InitGlobalGraphNodes()
80
{
81
  GridNode = CreateNewNode<UReplicationGraphNode_GridSpatialization2D>();
82
  GridNode->CellSize = 10000.f;                           // 100 m
83
  GridNode->SpatialBias = FVector2D(-150000.f, -200000.f); // 맵의 최소 좌표
84
  GridNode->AddToClassRebuildDenyList(AActor::StaticClass());
85
  AddGlobalGraphNode(GridNode);
86

87
  AlwaysRelevantNode = CreateNewNode<UReplicationGraphNode_ActorList>();
88
  AddGlobalGraphNode(AlwaysRelevantNode);
89

90
  AddGlobalGraphNode(CreateNewNode<UExampleNode_PlayerStateFrequencyLimiter>());
91
}
92

93
void UExampleReplicationGraph::InitConnectionGraphNodes(UNetReplicationGraphConnection* RepGraphConnection)
94
{
95
  Super::InitConnectionGraphNodes(RepGraphConnection);
96
  // viewer(PlayerController)와 ViewTarget을 매 프레임 다시 모으는 엔진 노드. owner 전용 액터도 여기에 넣는다
97
  UReplicationGraphNode_AlwaysRelevant_ForConnection* Node = CreateNewNode<UReplicationGraphNode_AlwaysRelevant_ForConnection>();
98
  AddConnectionGraphNode(Node, RepGraphConnection);
99
  ConnectionNodes.Add(RepGraphConnection->NetConnection, Node);
100
}
101

102
void UExampleReplicationGraph::RouteAddNetworkActorToNodes(const FNewReplicatedActorInfo& ActorInfo, FGlobalActorReplicationInfo& GlobalInfo)
103
{
104
  switch (ClassRepNodePolicies.GetChecked(ActorInfo.Class))
105
  {
106
  case EClassRepNodeMapping::NotRouted:              break;
107
  case EClassRepNodeMapping::RelevantAllConnections: AlwaysRelevantNode->NotifyAddNetworkActor(ActorInfo); break;
108
  case EClassRepNodeMapping::RelevantOwnerConnection:
109
    if (UNetConnection* Connection = ActorInfo.Actor->GetNetConnection())
110
    {
111
      if (TObjectPtr<UReplicationGraphNode_AlwaysRelevant_ForConnection>* Node = ConnectionNodes.Find(Connection))
112
      {
113
        (*Node)->NotifyAddNetworkActor(ActorInfo);
114
      }
115
    }
116
    break; // owner가 아직 없으면 다음 프레임에 다시 시도하는 목록이 따로 필요하다
117
  case EClassRepNodeMapping::Spatialize_Static:      GridNode->AddActor_Static(ActorInfo, GlobalInfo);   break;
118
  case EClassRepNodeMapping::Spatialize_Dynamic:     GridNode->AddActor_Dynamic(ActorInfo, GlobalInfo);  break;
119
  case EClassRepNodeMapping::Spatialize_Dormancy:    GridNode->AddActor_Dormancy(ActorInfo, GlobalInfo); break;
120
  }
121
}
122

123
void UExampleReplicationGraph::RouteRemoveNetworkActorToNodes(const FNewReplicatedActorInfo& ActorInfo)
124
{
125
  switch (ClassRepNodePolicies.GetChecked(ActorInfo.Class))
126
  {
127
  case EClassRepNodeMapping::NotRouted:              break;
128
  case EClassRepNodeMapping::RelevantAllConnections: AlwaysRelevantNode->NotifyRemoveNetworkActor(ActorInfo); break;
129
  case EClassRepNodeMapping::RelevantOwnerConnection:
130
    if (UNetConnection* Connection = ActorInfo.Actor->GetNetConnection())
131
    {
132
      if (TObjectPtr<UReplicationGraphNode_AlwaysRelevant_ForConnection>* Node = ConnectionNodes.Find(Connection))
133
      {
134
        (*Node)->NotifyRemoveNetworkActor(ActorInfo, false);
135
      }
136
    }
137
    break;
138
  case EClassRepNodeMapping::Spatialize_Static:      GridNode->RemoveActor_Static(ActorInfo);   break;
139
  case EClassRepNodeMapping::Spatialize_Dynamic:     GridNode->RemoveActor_Dynamic(ActorInfo);  break;
140
  case EClassRepNodeMapping::Spatialize_Dormancy:    GridNode->RemoveActor_Dormancy(ActorInfo); break;
141
  }
142
}

1
// PlayerState를 프레임당 TargetActorsPerFrame개씩 나눠 돌려 보낸다
2
void UExampleNode_PlayerStateFrequencyLimiter::PrepareForReplication()
3
{
4
  ReplicationActorLists.Reset();
5
  ReplicationActorLists.AddDefaulted();
6
  for (TActorIterator<APlayerState> It(GetWorld()); It; ++It)
7
  {
8
    if (!IsActorValidForReplicationGather(*It)) continue;
9
    if (ReplicationActorLists.Last().Num() >= TargetActorsPerFrame) ReplicationActorLists.AddDefaulted();
10
    ReplicationActorLists.Last().Add(*It);
11
  }
12
}
13

14
void UExampleNode_PlayerStateFrequencyLimiter::GatherActorListsForConnection(const FConnectionGatherActorListParameters& Params)
15
{
16
  if (ReplicationActorLists.Num() == 0) return;
17
  Params.OutGatheredReplicationLists.AddReplicationActorList(ReplicationActorLists[Params.ReplicationFrameNum % ReplicationActorLists.Num()]);
18
}

1
// OpenWorldReplicationGraph.cpp, UOpenWorldReplicationGraphNode_Team::GatherActorListsForConnection
2
for (FActorRepListType Actor : TeamActorList)
3
{
4
  FConnectionReplicationActorInfo& Info = Params.ConnectionManager.ActorInfoMap.FindOrAdd(Actor);
5
  if (!Info.bForceCullDistanceToZero) { Info.bForceCullDistanceToZero = 1; Forced.Add(Actor); }
6
}
7
Params.OutGatheredReplicationLists.AddReplicationActorList(TeamActorList);

도입 기준과 Iris#

기준은 서버의 ServerReplicateActors에서 보낼지 말지를 정하는 비용과 실제로 보내는 비용의 비율이다. 기본 드라이버에서 stat game의 Consider Actors Time과 Prioritize Actors Time을 합친 값이 Replicate Actor Time보다 크면 리플리케이션 그래프가 그 몫을 줄인다. 둘이 비슷하거나 리플리케이션 쪽이 크면 리플리케이션 그래프는 액터당 0.5 µs쯤을 더 쓰는 쪽이다. 측정에서는 Insights의 consider list와 prioritize 타이머로 같은 비율을 봤다.