goodchuck 블로그
📚 연재Roamlings 개발기2/2전체 보기 →

Roamlings 개발기 ② — 데스크탑 펫이 창 위를 걷기까지, koffi로 Win32 창 위치 읽기

Roamlings 개발기 2편 · 프로토타입 단계 (2026-11-14~15 작업)

1편에서 모니터마다 투명 창을 띄워 네모 캐릭터를 바탕화면 위에 올렸습니다. 이번 편은 그 네모가 열어 둔 창 위를 걷게 만든 과정입니다. Electron에서 koffi로 Win32 API를 불러 창 위치를 읽고, 그 사각형을 발판과 벽으로 바꾸기까지 부딪힌 문제를 순서대로 정리합니다.

개발용 지형 선을 켠 Roamlings 화면 — 메모 창 두 개의 위 모서리는 초록 발판 선, 옆면은 빨강 벽 선으로 그려져 있고, 말랑이와 네모는 제목 줄 위에, 동글이는 오른쪽 메모 창 옆면에 붙어 있는 모습
개발용 지형 선을 켠 Roamlings 화면 — 메모 창 두 개의 위 모서리는 초록 발판 선, 옆면은 빨강 벽 선으로 그려져 있고, 말랑이와 네모는 제목 줄 위에, 동글이는 오른쪽 메모 창 옆면에 붙어 있는 모습

위 화면은 개발용 "지형 선 보기"를 켠 상태입니다. 초록 선이 발판, 빨강 선이 벽입니다. 이번 편은 이 선이 어떻게 생기는지에 대한 이야기입니다.

데스크탑 펫이 창 위를 걸으려면 무엇이 필요한가

처음 네모는 작업표시줄 위 바닥만 걸었습니다. 작업 영역은 Electron의 screen API가 알려 주니 어렵지 않았습니다. 그런데 이 장르의 재미는 열어 둔 창 위로 올라가는 것입니다. 그러려면 지금 화면에 어떤 창이 어디에 있는지 알아야 합니다.

Electron은 다른 프로그램의 창 목록을 알려 주지 않습니다. 1편에서 말한 "어느 엔진이든 OS API를 불러야 한다"는 부분이 바로 여기입니다. Windows라면 user32.dll과 dwmapi.dll의 함수를 직접 불러야 합니다.

koffi로 Win32 EnumWindows · DwmGetWindowAttribute 부르기

Node에서 DLL 함수를 부르는 방법은 여러 가지인데, 저는 koffi를 썼습니다. 네이티브 모듈을 따로 빌드하지 않고, 함수 모양을 문자열로 적으면 바로 부를 수 있습니다.

창 목록은 EnumWindows로 돌고, 창마다 눈에 보이는 테두리를 DwmGetWindowAttribute로 읽습니다. 실제 코드에서 핵심만 추리면 이렇습니다.

const koffi = require('koffi')
const user32 = koffi.load('user32.dll')
const dwmapi = koffi.load('dwmapi.dll')
const RECT = koffi.struct('RECT',
  { left: 'int32', top: 'int32', right: 'int32', bottom: 'int32' })
koffi.proto('bool __stdcall EnumWindowsProc(intptr_t hwnd, intptr_t lParam)')
const EnumWindows = user32.func(
  'bool __stdcall EnumWindows(EnumWindowsProc *cb, intptr_t lParam)')
const DwmRect = dwmapi.func('DwmGetWindowAttribute', 'long',
  ['intptr_t', 'uint32_t', koffi.out(koffi.pointer(RECT)), 'uint32_t'])
const DWMWA_EXTENDED_FRAME_BOUNDS = 9

const windows = []
const rect = {}
EnumWindows((hwnd) => {                // 맨 앞 창부터 뒤로 돈다
  const ok = DwmRect(hwnd, DWMWA_EXTENDED_FRAME_BOUNDS, rect, koffi.sizeof(RECT)) === 0
  if (ok) windows.push({ x: rect.left, y: rect.top,
    w: rect.right - rect.left, h: rect.bottom - rect.top })
  return true                          // 계속
}, 0)

이걸 초당 10번 읽습니다. 2026-11-14 측정에서 한 번 읽는 데 약 0.9ms였습니다. 돌려받는 값은 물리 픽셀이라 DIP 좌표로 바꿔 씁니다.

// 첫 인자는 기준이 될 내 창 — 남의 창 사각형이라 null 을 넘긴다
const d = screen.screenToDipRect(null, { x: r.x, y: r.y, width: r.w, height: r.h })

창이 움직일 때 Windows가 알려 주는 이벤트(SetWinEventHook)를 받는 방법도 있습니다. 지금은 단순한 쪽을 골라 초당 10번 직접 읽습니다. 읽는 비용이 작아서 아직 바꿀 이유가 없었고, 필요해지면 이벤트 방식으로 바꿀 여지는 남겨 두었습니다.

GetWindowRect 대신 DWMWA_EXTENDED_FRAME_BOUNDS를 쓰는 이유

창 사각형은 흔히 GetWindowRect로 읽습니다. 그런데 Windows 10 · 11의 창은 눈에 안 보이는 리사이즈 테두리(약 7px)를 갖고 있고, GetWindowRect는 그것까지 포함합니다. 그 값으로 발판을 만들면 캐릭터가 제목 줄보다 조금 위, 허공에 떠서 걷습니다.

DWMWA_EXTENDED_FRAME_BOUNDS는 눈에 보이는 테두리를 돌려줍니다. 그래서 이걸 먼저 쓰고, 실패할 때만 GetWindowRect로 물러납니다.

메모 창 오른쪽 위 모서리를 10배 확대한 비교 그림 — 초록 실선은 DWMWA_EXTENDED_FRAME_BOUNDS가 돌려준 눈에 보이는 테두리, 빨강 점선은 7px 바깥의 GetWindowRect 경계
메모 창 오른쪽 위 모서리를 10배 확대한 비교 그림 — 초록 실선은 DWMWA_EXTENDED_FRAME_BOUNDS가 돌려준 눈에 보이는 테두리, 빨강 점선은 7px 바깥의 GetWindowRect 경계

같은 메모 창을 두 함수로 재 보니, GetWindowRect가 왼쪽 · 오른쪽 · 아래로 7px씩 더 컸고 위는 같았습니다(100% 배율).

걸러야 할 창이 생각보다 많았습니다

EnumWindows는 "보이는" 창만 주는 게 아닙니다. 그대로 지형으로 쓰면 화면에 없는 창이나 보조 창까지 발판이 됩니다. 하나씩 걸러 낸 목록은 이렇습니다.

거른 창이유
안 보이는 창 · 최소화된 창화면에 없음
cloaked 창다른 가상 데스크톱 · 숨은 UWP 창. 보이는 창으로 잡히지만 화면엔 없음
제목 없는 창이름 없는 보조 창
툴 창 · 클릭 통과 창 · 활성화 안 되는 창창 스타일(WS_EX_TOOLWINDOW 등)로 거름
바탕화면 · 작업표시줄셸 창 클래스로 거름
60×40보다 작은 창설 자리가 없음
자기 오버레이 창화면 전체를 덮는 투명 창이라 거르지 않으면 전부 막힘

cloaked 여부도 같은 DwmGetWindowAttribute로 읽습니다(DWMWA_CLOAKED). 다른 가상 데스크톱의 창은 IsWindowVisible이 참이라, 이걸 보지 않으면 보이지 않는 창 위를 걷게 됩니다.

창 사각형을 발판과 벽으로 바꾸기

걸러 낸 창은 앞에서 뒤 순서로 지형이 됩니다. 위 모서리는 발판, 옆 모서리는 벽입니다. 앞 창에 가려진 부분은 발판과 벽에서 뺍니다. 뒤 창의 제목 줄이 앞 창에 반쯤 가려져 있으면, 보이는 부분만 걸을 수 있습니다.

최대화 창이 모니터 경계에 벽을 세웠습니다

모든 창을 같은 규칙으로 넣으니 최대화 창이 문제였습니다. 최대화 창의 옆면은 모니터 경계와 겹칩니다. 그 옆면이 벽이 되니, 캐릭터가 옆 모니터로 건너가지 못했습니다.

그래서 작업 영역을 꽉 채운 창은 지형에서 뺐습니다. 대신 뒤 창을 가리는 역할은 그대로 둡니다. 최대화 창 뒤에 있는 창은 없는 것과 같아야 하기 때문입니다.

최대화 창 전·후 설명 그림 — 전에는 최대화 창의 오른쪽 옆면이 모니터 경계에 빨간 벽이 되어 말랑이가 옆 모니터로 못 건너가고, 후에는 최대화 창을 지형에서 빼서 말랑이가 경계를 넘어가는 모습
최대화 창 전·후 설명 그림 — 전에는 최대화 창의 오른쪽 옆면이 모니터 경계에 빨간 벽이 되어 말랑이가 옆 모니터로 못 건너가고, 후에는 최대화 창을 지형에서 빼서 말랑이가 경계를 넘어가는 모습

창 안에 갇히는 캐릭터 — 한 방향 지형

캐릭터는 항상 맨 위 오버레이에 그려집니다. 그래서 창 "앞"에 떨어지는 일이 생깁니다. 이때 창의 네 변이 모두 막혀 있으면, 캐릭터는 창 사각형 안에 갇혀 나오지 못합니다.

그래서 창을 한 방향 지형으로 만들었습니다.

  • 위 모서리는 위에서 떨어질 때만 받아 줍니다.
  • 옆면은 바깥에서 들어올 때만 막습니다.

창 앞에 있는 캐릭터는 그냥 지나가고, 바깥에서 다가온 캐릭터만 벽에 부딪혀 오릅니다.

한 방향 지형 설명 그림 — 위에서 떨어진 말랑이는 창 위 모서리(초록)에 착지하고, 창 앞에 있는 말랑이는 옆면을 그냥 지나가고, 바깥에서 다가온 말랑이는 옆면(빨강)에 막혀 위로 오르는 세 장면
한 방향 지형 설명 그림 — 위에서 떨어진 말랑이는 창 위 모서리(초록)에 착지하고, 창 앞에 있는 말랑이는 옆면을 그냥 지나가고, 바깥에서 다가온 말랑이는 옆면(빨강)에 막혀 위로 오르는 세 장면

걷기 · 오르기 · 떨어지기 · 던지기 상태 기계

지형이 생기자 캐릭터 동작을 상태 기계로 정리했습니다.

  • 걷기 — 작업표시줄 위 바닥이나 창 제목 줄 위를 걷습니다.
  • 오르기 — 화면 끝 벽이나 창 옆면을 오르고, 창 꼭대기에 닿으면 제목 줄로 올라섭니다.
  • 떨어지기 — 서 있던 창이 움직이거나 최소화되면 떨어집니다. 10Hz로 창을 읽다가 발판이 사라지면 그때 깨어납니다.
  • 던지기 — 마우스로 집어 흔들다 놓으면, 놓기 직전 100ms의 속도로 날아가 벽 · 바닥에서 튑니다.
동글이가 메모 창 왼쪽 옆면을 타고 올라가 꼭대기에서 제목 줄 위로 올라서는 약 8초 화면 녹화
동글이가 메모 창 왼쪽 옆면을 타고 올라가 꼭대기에서 제목 줄 위로 올라서는 약 8초 화면 녹화

모니터를 넘어가면 마우스를 놓은 걸 모릅니다

던지기에는 함정이 하나 있었습니다. 오버레이는 모니터마다 따로 있는 창입니다. 캐릭터를 집은 채 옆 모니터로 끌고 가서 놓으면, 처음 집은 창은 pointerup을 받지 못할 때가 있습니다. 그러면 캐릭터는 마우스를 놓았는데도 계속 붙잡힌 상태로 남습니다.

해결은 다시 Win32였습니다. 드래그 중에는 GetAsyncKeyState(VK_LBUTTON)로 왼쪽 버튼이 아직 눌려 있는지 직접 묻습니다. 눌려 있지 않으면 pointerup을 놓친 것으로 보고 놓아 줍니다. 창 이벤트가 모니터 경계에서 끊겨도, 버튼 상태는 OS가 알고 있기 때문입니다.

지금은 Windows에서만 이렇게 동작합니다. macOS에서는 다른 창 읽기가 꺼져 바닥과 화면 끝만 지형이 됩니다.

이번 편 정리

  • 이번에 한 것 — koffi로 EnumWindows · DwmGetWindowAttribute를 불러 창 위치를 초당 10번 읽고, 위 모서리는 발판 · 옆면은 벽으로 바꿨습니다. 걷기 · 오르기 · 떨어지기 · 던지기를 상태 기계로 묶었습니다.
  • 막힌 것 — 최대화 창이 모니터 경계에 벽을 세웠고, 창 앞에 떨어진 캐릭터가 갇혔고, 모니터를 넘어 놓으면 pointerup을 놓쳤습니다. 각각 지형에서 빼기 · 한 방향 지형 · GetAsyncKeyState로 풀었습니다.
  • 다음 편 예고 — 창을 초당 10번 읽고 여러 마리를 움직여도 가벼운지 잽니다. 1편에서 미뤄 둔 "무거우면 Godot"의 답입니다.

다음 편 준비 중 · Roamlings 개발기 ③

여기까지 2편이에요. 다음 편이 올라오면 바로 받아 보세요

이어서 쓸 이야기 · 가볍게 돌리기 · AI 캐릭터 · 설정 창과 반응