AI 튜토리얼

AI로 확장되는 무한 포켓몬 세계를 만들고 탐험하기

Node.js 또는 AI 어시스턴트로 Infinite Pokémon을 설정하고, 싱글플레이어 또는 멀티플레이어 월드를 시작하며, AI 없는 튜토리얼 미리보기를 사용하고, 맵 생성을 구성하고, 영구 저장 데이터를 보호하는 방법을 알아보세요. 이 튜토리얼에서는 프로젝트의 서버 권위형 설계, Codex 통합, 조작법, 백업, Docker 옵션 및 원격 호스팅 시 주의사항도 설명합니다.

2026년 9월 14일약 19분 소요

Infinite Pokémon이란?

Infinite Pokémon은 지속형 Pokémon 스타일의 픽셀 아트 생물 포획 RPG를 플레이할 수 있도록 만든 TypeScript 프로토타입입니다. 핵심 실험은 플레이하는 동안 계속해서 기록을 추가할 수 있는 세계입니다. 로컬 AI 하네스는 모험의 기록된 이력을 사용해 앞으로 등장할 장소, 캐릭터, 대화, 바이옴 선택지와 스토리 소재를 제안합니다.

이 프로젝트에서 AI는 권위 있는 게임 상태를 제어할 수 없습니다. 이동, 충돌, 전투, 인벤토리, 진행 상황 및 기타 게임 규칙은 서버가 강제합니다. AI 제안은 세계에 반영되기 전에 스키마, 맵 검증 및 의존성 검사를 통과해야 합니다. 방문한 장소는 안정적으로 유지되며, 새로운 목적지는 플레이어보다 앞서 생성하고 캐시할 수 있습니다.

중요: Infinite Pokémon은 교육 및 비상업적 용도로만 제작된 실험적 팬 프로젝트입니다. 공식 Pokémon 제품이 아니며 Nintendo, Creatures, GAME FREAK 또는 The Pokémon Company와 제휴하지 않습니다.

지속되는 세계의 작동 방식

서버가 계속해서 권위 있는 주체로 작동합니다. AI 제안은 트레이너를 이동시키거나, 승리를 부여하거나, 충돌을 우회하거나, 진행 상황을 직접 변경할 수 없습니다.
세계는 실제 이벤트를 기록합니다. 각 실행에는 맵, 선택지, NPC 기억, 플레이어, 생성 작업 및 이벤트 이력이 로컬 SQLite 데이터베이스에 저장됩니다.
Codex가 앞으로의 콘텐츠를 제안합니다. 호스트의 로컬 Codex 프로세스는 변경할 수 없는 스냅샷을 읽고 현재 엔진과 호환되는 범위가 제한된 제안을 생성합니다.
검증이 런타임을 보호합니다. 스키마와 맵 검사를 통해 제안된 콘텐츠를 수락할 수 있는지 결정합니다.
체크포인트가 분기를 지원합니다. 이전 체크포인트에서 계속하면 자체 데이터베이스, 기억 및 생성 컨텍스트를 가진 별도의 분기가 생성됩니다.

현재 시스템은 AI가 임의로 작성한 실행 가능한 게임플레이 대신 검증된 시드 맵 템플릿에 의존합니다. 하네스는 이름, 설명, NPC 프로필, 인사말, 바이옴 선택지, 스토리 소재 및 범위가 제한된 지형 요소를 제공할 수 있습니다. 새로운 생물, 아이템 및 탈것 비주얼은 검증된 픽셀 아트 레시피로 렌더링할 수 있지만, 외부에서 생성된 이미지를 가져오는 기능은 구현되지 않았습니다.

주요 기능

실행별로 유지되는 맵, 이벤트, 스토리 선택지 및 NPC 기억.
서버가 권한을 관리하는 이동, 충돌, 전투, 인벤토리 및 진행 시스템.
호스트의 로컬 Codex 연결을 사용하는 싱글 플레이어 탐험.
모델 호출과 토큰을 사용하지 않는 5개 지역의 한정 튜토리얼 미리보기.
최대 8개의 동시 연결과 64명의 저장된 트레이너를 지원하는 호스트 및 참가 멀티플레이어.
0부터 3까지 설정할 수 있는 맵 준비 깊이.
동시에 생성할 블록 수를 1개부터 8개까지 설정할 수 있는 생성 배치.
완료되지 않은 목적지의 대기열 상태, 재시도 및 취소 제어.
변경할 수 없는 체크포인트와 서로 격리된 타임라인 분기.
상점, 회복, 야생 조우, 루트 트레이너, 자전거, 보육원 및 혼합 알.
브라우저, 소스에서 실행하는 Electron 데스크톱 및 선택 가능한 Linux Docker 워크플로.

사전 요구 사항

일반적인 로컬 워크플로에는 Node.js 22.13 이상을 설치하세요. Node.js 22.13부터 22.15까지 지원되지만, 최신 온라인 백업 API를 사용할 수 없는 경우 데이터베이스 백업에서 잠시 블로킹되는 SQLite VACUUM INTO 대체 기능을 사용합니다.

Docker는 선택 사항입니다. 별도의 전역 Codex CLI 설치는 필요하지 않습니다. 런타임 의존성에 Codex CLI 0.153.4가 포함되어 있기 때문입니다. 브리지는 이전 버전의 전역 실행 파일로 인해 호환성이 달라지는 것을 방지하기 위해 프로젝트 로컬 CLI를 우선 사용합니다.

옵션 1: AI 어시스턴트로 설정

가장 간단한 설정 방법은 Skills CLI로 저장소의 진입 스킬을 설치하는 것입니다.

npx skills add Shellishack/infinite-pokemon --skill infinite-pokemon

그런 다음 Codex 또는 호환되는 AI 어시스턴트에게 다음과 같이 요청하세요.

$infinite-pokemon을 사용해 게임을 설정하고 시작해 줘.

진입 스킬은 에이전트가 누락된 파일을 복제하고, 사전 요구 사항을 확인하고, 의존성을 설치하고, 프로젝트를 빌드하고, 실행하도록 안내합니다. 스킬만 설치한다고 소프트웨어가 실행되지는 않습니다. 저장소 소스가 필요하며, npx skills add infinite-pokemon은 지원되는 전역 별칭이 아닙니다.

사용하기 전에 GitHub에서 진입 스킬을 확인할 수 있습니다.

옵션 2: 수동 설치 및 실행

저장소를 복제하거나 다운로드하고, 루트 디렉터리에서 터미널을 연 다음 다음 명령을 실행하세요.

npm install
npm run build
npm start

http://127.0.0.1:8788에서 비공개 호스트 콘솔을 여세요. Node의 내장 SQLite 지원에서 실험적 기능 경고가 표시될 수 있으며, 이는 프로젝트에서 예상되는 경고입니다.

Codex에 연결하고 세계에 들어가기

싱글 플레이어를 선택합니다.
로컬 연결이 아직 확인되지 않았다면 Codex에 연결을 선택합니다.
표시된 토큰 사용 안내를 검토하고 승인합니다.
메시지가 표시되면 제공업체 로그인을 완료합니다.
짧은 논스 검증이 완료될 때까지 기다립니다. 성공하면 게임이 자동으로 시작 맵에 들어갑니다.

검증 과정에서는 스킬을 로드하거나 파일을 읽지 않으며, 논스 확인 요청과 ok 응답만 사용합니다. 연결되면 설정된 생성 깊이에 따라 주변 맵이 백그라운드에서 준비됩니다. 검증, 실패한 시도, 백그라운드 생성은 제공업체의 사용 한도를 소모할 수 있으며, 일반적인 제공업체 제한과 요금이 계속 적용됩니다.

유효한 연결은 재사용됩니다. 승인된 실행을 다시 시작하면 게임은 또 하나의 간단한 확인 메시지로 로컬 로그인을 확인합니다. 확인에 실패하면 인터페이스가 연결 작업으로 돌아갑니다.

Codex 없이 튜토리얼 미리보기로 플레이하기

제공업체 액세스나 토큰 사용 없이 게임 방식을 시험하려면 Codex 연결 화면에서 싱글 플레이어를 선택한 다음 튜토리얼 미리보기 플레이를 선택하세요.

미리보기에는 미리 준비된 야외 지역 5곳과 각 지역의 실내 방이 포함되어 있습니다:

윌로브룩: 마을 광장, 정원, 펀 교수의 연구실, 별도의 주택.
위스퍼우드 트레일: 울창한 나무, 구불구불한 길, 공터, 레인저 오두막.
클로버뱅크 강: 꽃밭, 강, 목재 다리, 휴게소.
선브레이크 해안: 탁 트인 바다, 해안 길, 보드워크, 해안 기지.
웨이스톤 테라스: 지그재그 경로, 돌 테라스, 쓰러진 기둥, 기록 보관소 쉼터.

미리보기에서는 모델을 호출하지 않으며 새로운 맵이나 NPC 계획을 생성하지 않습니다. 미리보기의 경계에 도달하면 Codex를 연결하고 같은 저장 데이터로 전체 탐험을 계속할 수 있습니다. 트레이너, 발견한 맵, 튜토리얼 진행 상황은 보존됩니다. 미리보기 저장 데이터는 승격되기 전까지 원래 세계와 분리된 비공개 데이터이며, 멀티플레이어는 Codex를 연결하고 검증한 후에만 사용할 수 있습니다.

기본 조작 및 게임플레이

WASD 또는 방향키로 이동합니다.
NPC, 표지판, 아이템 또는 방 컴퓨터 바로 옆에 서서 대상을 바라본 뒤 E 또는 Space를 누릅니다.
대각선으로 가까이 있는 경우에는 상호작용할 수 없습니다.
보이는 건물 문으로 걸어 들어가거나, 인접한 타일에서 문을 바라본 뒤 E를 누릅니다.
Escape 또는 START를 눌러 파티, 가방, 트레이너 프로필, 일지, 맵, 저장 메뉴를 엽니다.
Escape를 다시 누르면 메뉴가 닫힙니다.

사람, 표지판, 울타리, 벽, 가구는 이동을 막습니다. 상호작용할 때는 물체를 통과하려 하지 말고 대상을 바라보세요. 키 큰 풀에서는 야생 조우가 발생할 수 있고, 트레이너는 도전을 제공하며, 가이드는 초보자 연습을 도와줍니다. 실내 관리인은 팀을 치료해 줄 수 있습니다.

쉼터에는 상인과 보육원 관리인이 있을 수 있습니다. 물자를 구매하거나, 자전거를 구입하거나, 레벨 5 동료 두 명을 짝지어 하이브리드 알을 만들 수 있습니다. CODEX, NURSERY, RIDES, RECORDS와 같은 추가 메뉴는 START에서 이용할 수 있습니다.

맵 생성 설정

START → SESSION을 열어 생성 동작을 조정하세요. 맵 생성 깊이는 호스트가 세계를 얼마나 멀리까지 미리 준비할지 결정합니다:

깊이 0: 도착할 때 생성합니다.
깊이 1: 주변의 맵 4개를 준비합니다. 기본값입니다.
깊이 2: 맵 12개를 준비합니다.
깊이 3: 맵 24개를 준비합니다.

대기 중인 작업은 플레이어에게 가장 가까운 맵을 우선 처리하며, 캐시된 맵은 재사용됩니다. 아직 준비되지 않은 목적지는 완료된 것처럼 표시하지 않고 실제 대기열 또는 생성 상태를 표시합니다. 재시도 및 취소 제어 기능을 사용할 수 있습니다.

생성 배치 크기는 기본적으로 동시에 3개 블록이며, 1개에서 8개까지 설정할 수 있습니다. 순차 생성을 선호하거나 동시 작업을 제한하려면 1개를 선택하세요. 생성 깊이와 동시성을 높이면 더 넓은 영역을 준비할 수 있지만, 제공업체 사용량과 생성 활동이 증가할 수 있습니다.

저장 데이터, 체크포인트 및 분기 만들기

START → SAVES를 열어 실행 기록과 변경할 수 없는 체크포인트를 관리하세요. SAVE를 선택하면 체크포인트가 생성됩니다. 이전 체크포인트에서 계속 진행하면 게임은 원래 타임라인을 덮어쓰는 대신 별도의 분기를 만듭니다.

각 분기에는 고유한 세계 기록, NPC 기억, 생성 컨텍스트, 자동 저장 데이터베이스가 있습니다. 원래 실행에서 이후에 발생한 이벤트는 새 분기의 기억이 되지 않습니다. 따라서 원래 모험을 보존하면서 다른 결과를 탐험할 수 있습니다.

브라우저 저장 데이터는 현재 브라우저와 출처에 저장된 불투명한 세션 토큰과 연결됩니다. 호스트 이름, 스킴 또는 포트를 변경하거나 브라우저 저장소를 삭제하면 게스트 브라우저가 트레이너와의 연결 정보를 잃을 수 있습니다. 게임에는 수동 복구 키 인터페이스가 제공되지 않습니다.

멀티플레이어 세션 호스팅

타이틀 화면에서 멀티플레이어 → 세션 호스트를 선택합니다.
필요한 경우 호스트의 Codex 세션을 연결하고 검증합니다.
START → SESSION을 열어 게스트 주소를 확인합니다.
신뢰할 수 있는 플레이어에게만 게스트 게임 주소를 공유합니다.

혼자 시작한 후 세션 메뉴에서 멀티플레이어 활성화를 선택할 수도 있습니다. 게스트는 멀티플레이어 → 세션 참가를 선택하고 http://HOST_LAN_ADDRESS:8787 또는 호스트의 HTTPS URL과 같은 주소를 입력합니다. 닉네임은 선택 사항인 캐릭터 텍스트이며 계정이 아닙니다.

Codex에 연결하고 생성 사용 한도를 제공하는 것은 호스트뿐입니다. 게스트는 호스트의 현재 실행 기록과 세계 기록을 공유하지만 Codex에 직접 연결하지는 않습니다. 싱글 플레이어로 돌아가기를 선택하면 현재 게스트 연결이 종료되고 새로운 공개 참가가 차단되지만 서버 측 저장 데이터는 보존됩니다.

두 네트워크 포트 이해하기

0.0.0.0:8787은 게스트 게임 서비스입니다. 멀티플레이어가 활성화된 경우에만 공개 참가를 허용합니다.
127.0.0.1:8788은 Codex 연결, 생성 설정 및 백업 제어를 위한 비공개 호스트 콘솔입니다.

포트 8788을 절대 외부에 노출하거나 리버스 프록시하지 마세요. Codex 프로세스, 자격 증명 디렉터리 또는 호스트 API를 게스트에게 노출하지 마세요. 프록시나 터널을 사용하는 경우 포트 8787의 게스트 서비스만 전달하세요.

인터넷 호스팅을 위해 저장소에는 포트 8787만 프록시하고 WebSocket을 지원하는 Caddy 설정 예제가 포함되어 있습니다. 동일 출처 검사를 위해 프록시는 원래 Host 헤더를 유지해야 합니다. 자동 NAT 통과 및 호스팅 릴레이는 포함되어 있지 않습니다.

개발 버전 또는 데스크톱 버전 실행

개발 환경에서는 TypeScript 서버와 Vite 미들웨어를 함께 실행하세요.

npm run dev

Electron 호스트 창을 열려면 먼저 프로젝트를 빌드한 다음 실행하세요.

npm run build
npm run desktop

Electron 모드는 패키지된 설치 프로그램이 아니라 소스 실행 방식의 데스크톱 셸입니다. PATH에 Node.js가 있어야 하며, 또는 NODE_BINARY을 통해 절대 경로를 지정해야 합니다. F11을 눌러 전체 화면을 전환하거나, 다음 명령으로 처음부터 전체 화면 모드로 시작하세요.

npm run desktop:fullscreen

Linux용 선택적 Docker 설정

제공된 Compose 설정은 Linux의 Docker Engine을 대상으로 하며 호스트 네트워킹을 사용합니다. 루프백 관리 리스너가 브리지 인터페이스에 배치되지 않고 로컬에서 계속 접근 가능하도록 의도적으로 포트 매핑을 포함하지 않습니다.

docker compose build
docker compose up -d
docker compose exec game node node_modules/@openai/codex/bin/codex.js login --device-auth

서버 소유자인 본인이 직접 인증을 완료하세요. world-data 볼륨은 /app/data에 월드 데이터를 저장하고, codex-private 볼륨은 /home/node/.codex에 인증 및 설정을 저장합니다. 두 볼륨을 모두 보존하고 계정 자격 증명이 들어 있는 codex-private를 보호하세요.

서버 오류를 확인하려면 다음을 실행하세요.

docker compose logs game

docker compose stop은 볼륨을 보존합니다. 월드를 유지하려면 down --volumes를 실행하지 마세요. README에서는 Windows와 macOS에서 이 Compose 설정 대신 기본 명령을 사용할 것을 권장합니다.

월드 백업 및 복원

기본 npm start는 ./data에 데이터를 저장합니다. Electron은 애플리케이션 사용자 데이터 위치 아래의 world 디렉터리를 사용합니다. 여러 실행 방식에서 동일한 월드를 사용하려면 INFINITE_DATA_DIR을 절대 경로로 설정하세요.

온라인 데이터베이스를 빠르게 백업하려면 START → SESSION → World settings → Back up world를 여세요. 백업은 backups/ 아래에 저장됩니다. 여기에는 데이터베이스 상태가 포함되지만 모든 컨텍스트 파일, 생성 로그 또는 비공개 Codex 자격 증명이 포함되는 것은 아닙니다.

전체 아카이브를 만들려면 다음을 수행하세요.

서버를 정상적으로 중지합니다.
필요한 경우 미리보기 디렉터리를 포함하여 전체 데이터 디렉터리를 복사합니다.
복사본을 별도의 디렉터리에 복원합니다.
INFINITE_DATA_DIR을 복원된 디렉터리로 설정합니다.
필요한 경우 서버를 다시 시작하고 Codex에 재연결합니다.

실행 중인 데이터베이스를 교체하거나 활성 SQLite WAL 파일과 분리하지 마세요. 복원된 월드를 확인할 때까지 원본 아카이브를 보관하세요.

유용한 설정 변수

INFINITE_DATA_DIR: 월드 데이터베이스, 스냅샷, 로그 및 백업.
PORT: 게스트 게임 포트. 기본값은 8787입니다.
ADMIN_PORT: 루프백 호스트 콘솔 포트. 기본값은 8788입니다.
CODEX_EXECUTABLE: 선택적 실행 파일 또는 codex.js 재정의 경로. 셸 래퍼는 거부됩니다.
CODEX_HOME: 호스트가 관리하는 선택적 Codex 인증 및 설정 디렉터리.
NODE_BINARY: Electron에서 사용하는 Node.js 실행 파일.
INFINITE_MAP_TIMEOUT_MS: 맵별 생성 제한 시간. 기본값은 180000이며 최대값은 600000입니다.

고급 팁

원격 관리를 비공개로 전달

원격 호스트에서 운영자의 비공개 셸을 통해 Codex를 인증하세요.

node node_modules/@openai/codex/bin/codex.js login --device-auth

그런 다음 자신의 컴퓨터에서 루프백 관리 포트를 전달하세요.

ssh -N -L 127.0.0.1:8788:127.0.0.1:8788 operator@your-server

로컬에서 http://127.0.0.1:8788을 여세요. 이 SSH 연결은 소유자 전용 관리 터널이며 공개 게임 프록시가 아닙니다.

엔진을 변경하기 전에 테스트 모음 사용

npm test
npm run build
npm run test:movement
npm run test:gameplay
npm run test:preview
npm run test:saves
npm run test:streaming
npm run test:variety
npm run test:e2e
npm run test:desktop

결정적 픽스처는 프로바이더 호출 없이 게임 메커니즘을 테스트합니다. 이동 및 게임플레이 브라우저 검사는 준비된 미리보기를 사용하고 Codex 호출이 발생하지 않는지 확인합니다.

필요한 경우에만 초기화

홈 화면의 Settings → Full game reset 작업은 저장 데이터 관리와 다릅니다. RESET으로 확인하면 모든 실행 기록, 체크포인트, 생성된 콘텐츠, 진행 상황 및 게임 설정이 삭제됩니다. 또한 게임의 Codex 승인을 삭제하지만 Codex CLI 로그인 상태는 유지됩니다.

현재 제한 사항

Infinite Pokémon은 완성된 릴리스가 아니라 프로토타입입니다. 생성 범위는 유한한 저장 공간, 제공업체 제한, 생성 시간, 그리고 엔진의 현재 어휘에 의해 제한됩니다. 지형은 검증된 템플릿을 사용하며, AI가 임의의 실행 가능한 메커니즘을 만들지는 않습니다. 거래, 완전한 서비스 센터 및 도장 시스템, 외부 이미지 생성 가져오기는 현재 기능이 아니라 향후 작업으로 설명되어 있습니다.

동시에 연결할 수 있는 연결 수 8개와 저장 가능한 트레이너 수 64개라는 멀티플레이어 제한은 구현상의 한계이며, 인터넷 규모의 용량을 의미하지 않습니다. 인터넷 호스팅을 위해서는 운영자가 상황에 맞게 방화벽, DNS, HTTPS, 포트 포워딩 또는 비공개 터널을 구성해야 합니다.

결론

Infinite Pokémon은 안정적인 서버 권한 RPG 핵심에 제한된 AI 지원 세계 확장을 결합합니다. 토큰이 필요 없는 미리 보기로 시작하고, 탐험 확장이 필요할 때 Codex를 연결하며, 체크포인트를 사용해 다양한 미래를 테스트하세요. 멀티플레이어나 원격 배포 시에는 호스트 콘솔과 인증 정보를 비공개로 유지하고, 게스트 서비스만 외부에 공개하며, 전체 데이터 디렉터리를 백업하세요.

Infinite Pokémon GitHub 저장소에서 소스 코드, 문서, 구현 참고 사항, 스킬, 크레딧 및 면책 조항을 확인할 수 있습니다.