엔트리 MCP 사용 설명서(좌표계, 블록 JSON 형식, 엔트리파이썬 문법, 고품질 작품 제작 팁). 작업 시작 전에 한 번 읽으세요.

Entry 오프라인 앱을 원격 디버깅 포트로 실행하고 연결합니다. 이미 연결 가능하면 그대로 연결합니다. Entry가 디버그 포트 없이 실행 중이면 restart=true가 필요합니다(앱 강제 종료 → 저장 안 된 작업 손실 가능, 사용자 확인 후 사용). 시작 시 "작품 복구" 대화상자가 뜨면 recovery 옵션으로 처리합니다.

연결 상태, 작업 폴더 경로, 현재 작품 요약(장면/오브젝트 이름/변수/신호/함수, 코딩 모드, 실행 상태)을 봅니다.

작품 단위 작업. action='new': 새 작품(기본 엔트리봇 포함, empty=true면 오브젝트 모두 제거). 현재 작품은 저장하지 않으면 사라짐. action='open': .ent 파일 열기(path; 상대경로는 작업폴더/projects 기준). action='save': .ent 파일로 저장. path 생략 시 작업폴더/projects/<작품이름>.ent. 상대경로는 작업폴더/projects 기준. name을 주면 작품 이름도 변경. action='rename': 작품 이름 변경(name). action='export_json': 엔트리 원본 project JSON 전체를 반환(고급 편집용, path를 주면 파일로 저장). action='import_json': project JSON(json 문자열 또는 json_path 파일)을 그대로 불러오기.

현재 작품의 상세 구조: 장면별 오브젝트(id, 이름, 좌표, 크기, 방향, 모양/소리 목록, 레이어), 변수/리스트/신호/함수. scripts='blocks'면 각 오브젝트 코드를 compact 블록 JSON으로, 'python'이면 엔트리파이썬으로 포함.

엔트리 기본 리소스 라이브러리 검색(오프라인 내장). kind='sprite'(오브젝트: 모양 여러 개+소리 포함), 'background'(배경 오브젝트), 'picture'(모양 단일 그림), 'sound'(소리). query는 한국어/영어 키워드(공백=AND). query 없이 list_categories=true면 카테고리 목록.

라이브러리 리소스의 썸네일 이미지를 봅니다(디자인 선택용). 최대 8개.

오브젝트 추가. source='library': 라이브러리 스프라이트/배경(asset_id 또는 asset_name; entry_search_assets로 찾기). 배경은 자동으로 맨 뒤+잠금. source='image': 로컬 이미지 파일(image_paths, png/jpg/svg 등; 여러 장이면 모양 여러 개; 상대경로는 작업폴더/images 기준). source='textbox': 글상자(text, props로 fontSize/color/bgColor 등). source='empty': 빈 오브젝트(붓 그리기용 등). props로 위치/크기/이름 등을 바로 지정. scene을 주면 그 장면에 추가(없으면 현재 장면).

오브젝트 속성 변경(이름, x/y, 크기, 방향, 이동방향, 회전방식, 보이기, 현재 모양, 레이어 순서, 글상자 글자/글꼴/색 등). 실행 전 "초기 상태"를 정하는 용도입니다.

오브젝트 관리: action='delete' 삭제, 'duplicate' 복제(스크립트 포함, new_name), 'select' 선택(편집 화면에 표시).

오브젝트의 모양(picture)/소리(sound) 관리. add_picture: library_ids(entry_search_assets kind=picture의 id) 또는 files(로컬 이미지 경로; 상대경로는 작업폴더/images 기준). add_sound: library_ids(kind=sound의 id) 또는 files(mp3/wav 경로; 상대경로는 작업폴더/sounds 기준). remove_picture / remove_sound / rename_picture / rename_sound: name(현재 이름) [+ new_name].

장면 관리: add(name), rename(scene,name), select(scene), delete(scene), move(scene,index). 오브젝트는 '현재 선택된 장면'에 추가되므로, 다른 장면에 넣으려면 entry_add_object의 scene 인자를 쓰세요.

변수/리스트/신호 관리. kind='variable'|'list'|'message'. action='add'|'set'|'rename'|'delete'. variable: value(초기값), visible(무대에 표시), x,y(표시 위치), scope('global' 또는 오브젝트 이름=그 오브젝트 전용 지역변수). list: items(초기 항목 배열), visible, x, y, width, height. message: name만. 파이썬 코드로 스크립트를 넣으면 쓰인 변수/리스트/신호는 자동 생성되지만, 초기값·표시여부·위치는 여기서 정하세요.

함수(나만의 블록) 정의/재정의. 블록 모드용. params: ['이름', ...] 또는 [{name, type:'string'|'boolean'}] (문자/숫자 값 또는 판단 값). {label:'텍스트'}를 끼우면 블록 모양 중간에 글자 삽입. body: compact 블록 배열. 본문에서 매개변수는 {"type":"param","name":"h"}로 참조. kind='value'면 값 반환 함수: return_value에 반환할 값/블록. local_variables: ['i', ...] 함수 지역변수 → 본문에서 {"type":"local_get","name":"i"}, {"type":"local_set","name":"i","value":0}. 호출: 스크립트에서 {"type":"call","function":"함수이름","params":[인자...]}. (엔트리파이썬에서는 entry_set_script의 python 안에 def 함수(인자): 를 쓰면 일반 함수가 자동 생성됩니다)

오브젝트의 코드를 설정합니다. python 또는 blocks 중 하나를 주세요. python: 엔트리파이썬 코드(이벤트는 def when_start():, def when_press_key("space"): 등). 엔트리 자체 변환기로 블록으로 바뀌며, 쓰인 변수/리스트/신호/함수가 자동 생성됩니다. 'import Entry'는 생략 가능. blocks: 스레드 배열 [[이벤트블록, 블록, ...], [...]] (compact 형식, entry_guide 참고). 숫자/문자 리터럴, 드롭다운은 값 또는 이름(변수/신호/오브젝트/모양/소리/장면 이름 → id 자동 변환). mode='replace'(기본: 기존 코드 전부 교체) | 'append'(기존 코드 뒤에 스레드 추가). 결과의 warnings를 반드시 확인하세요(없는 모양/변수 등).

오브젝트 코드 읽기. format='blocks'(compact JSON, entry_set_script에 그대로 넣을 수 있음) | 'python'(엔트리파이썬) | 'raw'(엔트리 원본 JSON).

블록 사전(실행 중인 엔트리에서 직접 읽음). 인자 없이 호출하면 카테고리 목록. category: start, flow, moving, looks, brush, text, sound, judgement, calc, variable, func, analysis, ai_utilize, expansion, arduino. query: 블록 type/한글 문구/파이썬 문법 검색(공백=AND). types: 특정 블록 type들의 상세. 결과: type, text(블록 문구; [KEY]=입력칸), args(입력칸 순서·종류·옵션·기본값), statements(내부 블록 묶음 수), python(엔트리파이썬 문법).

엔트리 화면의 코딩 모드 전환: 'block'(블록코딩) | 'python'(엔트리파이썬 텍스트 편집 화면). 코드 자체는 동일하며 표시 방식만 바뀝니다. 파이썬 모드는 일부 블록(값 반환 함수, 지역변수 함수 등)을 지원하지 않습니다.

작품 실행 제어. action='start'(시작하기 버튼), 'stop', 'restart'. wait_ms만큼 기다린 뒤 결과를 돌려주며, screenshot=true면 무대 화면 캡처, state=true면 변수/오브젝트 상태 포함. 실행 중 에러/경고 로그도 포함됩니다.

화면 캡처. target='stage'(실행 화면만) | 'window'(엔트리 전체 창: 블록 편집기 포함). save_as를 주면 작업폴더/screenshots에 PNG로도 저장.

실행 상태 조회: 엔진 상태, 모든 변수/리스트 값, 각 오브젝트의 위치/크기/방향/모양/말풍선/복제본 수, 대답 값.

실행 중인 작품에 사용자 입력을 보냅니다(게임 테스트용). events를 순서대로 실행. {type:'key', key:'space'|'left'|'a'|..., duration_ms?:누르고 있을 시간(기본 100)} {type:'key_down'|'key_up', key} {type:'click', x, y} (무대 좌표, 오브젝트/마우스 클릭 이벤트 발생) {type:'mouse_move', x, y} {type:'mouse_down'|'mouse_up', x, y} {type:'text', text, submit?:true} (묻고 기다리기 대답 입력) {type:'wait', ms} 마지막에 screenshot/state를 돌려줍니다.

엔트리 앱의 콘솔 로그/예외/토스트 경고 메시지를 봅니다(디버깅용).

고급: 엔트리 렌더러에서 JavaScript를 직접 실행합니다(전역 Entry 객체, window.__entryMcp 헬퍼 사용 가능). async 함수 본문으로 실행되며 return 값이 JSON으로 반환됩니다. 다른 도구로 불가능한 경우에만 사용하세요.