🔌웹소켓·스크립트 API

• Bridge: 설치하거나 웹 에디터로 열기 → 새 프로젝트(Create Project). 리소스 팩은 기본으로 켜진 그대로 둬도 됩니다. Beta APIs는 스크립트 모듈을 manifest에 넣어 줍니다.
• Project Name 적기, Project Target Version 확인(2023 영상: 1.20.40) — 교육용 에디션에 쓸 때는 쓰는 교육용 에디션의 게임 버전 이하로 낮춥니다.
• 월드의 실험 기능 ‘베타 API’ 설명은 “추가 기능 팩에서 API 모듈의 "-beta" 버전 사용”. 필요하면 홀리데이·예정된 크리에이터 기능도 켭니다.
• 설정 → 제작자의 콘텐츠 로그 옵션: 콘텐츠 로그 파일 사용 / 콘텐츠 로그 GUI 사용 / 불러오기 중 콘텐츠 로그 GUI 오류 발생.

• 2026-01 영상에서 안티그래비티가 만든 main.js 앞부분(화면 원문, 이후는 화면에서 잘림)

/**
 * 간단한 채팅 명령어 예제
 * Minecraft Bedrock Script API
 */

import { world, system } from "@minecraft/server";

// ===========================
// 방법 1: /scriptevent 명령어 사용 (권장)
// 사용법: /scriptevent cmd:help 또는 /scriptevent cmd:hello
// ===========================

system.afterEvents.scriptEventReceive.subscribe((event) => {
    const { id, message, sourceEntity } = event;

    // sourceEntity가 플레이어인지 확인
    if (!sourceEntity || sourceEntity.typeId !== "minecraft:player") return;

    const player = sourceEntity;

    // 명령어 처리
    switch (id) {
        case "cmd:help":
            player.sendMessage("§e=== 도움말 ===");
            player.sendMessage("§a/scriptevent cmd:help §f- 도움말 표시");
            player.sendMessage("§a/scriptevent cmd:hello §f- 인사하기");
            player.sendMessage("§a/scriptevent cmd:time §f- 현재 게임 시간");
            player.sendMessage("§a/scriptevent cmd:pos §f- 현재 위치 확인");
            player.sendMessage("§a/scriptevent cmd:heal §f- 체력 회복");
            break;

        case "cmd:hello":
            world.sendMessage(`§b${player.name}§f님이 인사합니다! 안녕하세요! 👋`);
            break;

        case "cmd:time":
            const timeOfDay = world.getTimeOfDay();
            const hours = Math.floor(timeOfDay / 1000);
            const minutes = Math.floor((timeOfDay % 1000) / 16.67);
            // … 이하 화면에서 잘림

• AI가 참고한 레퍼런스: wiki.bedrock.dev의 Events 문서(화면). 스티브코딩 GitHub 예제 중 breakBlock.js·chatCommand.js는 이때 “Update to latest Script API patterns and fix deprecated code”로 최신 문법으로 고쳐 둠(03:20 화면).

• 2023-11 영상 화면의 main.js 전체(Bridge, @minecraft/server 1.7.0 시절)

console.warn("불러옴")

import * as server from "@minecraft/server"
import * as ui from "@minecraft/server-ui"

const world = server.world

// 커스텀 명령어
world.afterEvents.chatSend.subscribe(e => {

    const msg = e.message

    if (msg == "명령어1") {
        e.sender.runCommand("say 명령어1을 실행함")
    }
    if (msg == "명령어2") {
        e.sender.runCommand("say 명령어2를 실행함")
        e.sender.runCommand("give @s apple")
    }
    if (msg == "명령어3") {
        e.sender.runCommand("say 명령어3을 실행함")
        e.sender.runCommand("effect @s speed")
        e.sender.runCommand("")
    }

})

• 예전 버전(2022-09 영상 「5분 완성! 여러 커맨드를 한번에 실행하는 나만의 커맨드만들기」): mojang-minecraft 모듈과 beforeChat 이벤트를 써서 지금은 동작하지 않음. 영상 설명란도 2023 영상의 업데이트된 문법을 보라고 안내함. 당시 실험 기능 이름은 ‘게임테스트 프레임워크’.

import { world } from 'mojang-minecraft'

world.events.beforeChat.subscribe((ev) => {
    const player = ev.sender
    const msg = ev.message

    if (msg == "a") {
        ev.cancel = true
        player.runCommand("say a를 입력했음")
    } else if (msg == "s") {
        ev.cancel = true
        player.runCommand("say s를 입력했음")
        player.runCommand("give @s apple")
    } else if (msg == "여기에 명령어 쓰기3") {
        ev.cancel = true
        player.runCommand("say 실행됨3")
    }
})

• 블록 부수기 예제의 채팅 부분(화면 원문). 이벤트 부분은 위 슬라이드와 같음.

console.warn("불러옴")

import { world, system } from "@minecraft/server";

// 명령어 1로 스코어보드 값 약속하기
world.afterEvents.chatSend.subscribe(e => {

    const msg = e.message

    if (msg == "1") {
        e.sender.runCommand("scoreboard objectives add diamond dummy 다이아몬드")
        e.sender.runCommand("scoreboard objectives setdisplay sidebar diamond")
        e.sender.runCommand("scoreboard players set @a diamond 0")

    }
})

• 타이머 main.js 전체(화면 원문, timer.js)

console.warn("불러옴")

import { world, system } from "@minecraft/server";

// 플레이어 메시지를 저장할 변수
let sec = 0;
let countingIs = false;

// 플레이어가 메시지를 입력할 때마다 호출되는 이벤트 핸들러
world.afterEvents.chatSend.subscribe((event) => {
    const player = event.sender;
    const message = event.message;

    // '카운트다운'이라는 단어가 포함된 경우에만 변수에 저장
    if (message.includes('카운트다운')) {
        // '카운트다운'이라는 단어를 빼고 저장
        const messageToSave = message.replace('카운트다운', '').trim();

        // 입력한 메시지가 숫자인지 확인
        if (isNaN(messageToSave)) {
            player.sendMessage("카운트다운 뒤에는 숫자를 입력해주세요.");
            return;
        }

        sec = Number(messageToSave);
        console.log(`${sec}초 카운트다운 시작`);
        world.getDimension("overworld").runCommandAsync(`title @a title ${sec}초 카운트다운 시작`);
        countingIs = true;
    }

    // '정지' 입력하면 카운트다운 멈추기
    if (message === "정지") {
        sec = 0;
        console.log(`정지하기`);
        countingIs = false;
    }
});

// 남은 시간을 출력하는 함수
function printStoredMessage() {
    if (countingIs && sec > 0) {
        sec--;
        world.getDimension("overworld").runCommandAsync(`title @a actionbar 남은 시간: ${sec}초`);
    } else if (sec === 0 && countingIs) {
        countingIs = false;
        world.getDimension("overworld").runCommandAsync(`title @a actionbar 남은 시간: ${sec}초`);
        world.getDimension("overworld").runCommandAsync(`title @a title 시간 종료`);
    }
}

// 시간 간격 설정: 20틱마다 실행 (1초에 한 번)
const interval = 20;

// system.runInterval을 사용하여 주기적으로 실행
system.runInterval(printStoredMessage, interval);

• 영상(2023-12) 코드의 runCommandAsync는 최신 @minecraft/server에서 지원이 끝나 runCommand로 바꿔야 함(아래 ‘스크립트 API 소개 메모’). GitHub의 코드는 최신 문법으로 고친 것이 있으니 GitHub 쪽을 먼저 쓰기.

• 순간 이동 UI main.js 전체(화면 원문, UItp.js)

import { world, system } from "@minecraft/server";
import { ActionFormData } from "@minecraft/server-ui";

const afterEvents = world.afterEvents;

let playerPositionX, playerPositionY, playerPositionZ;

//아이템 사용했을 때 ui열기
afterEvents.itemUse.subscribe((data) => {
    const block = data.itemStack
    const player = data.source

    if (block.typeId == "minecraft:compass") {
        showForm(player);
    }
});

//ui설정
function showForm(player) {
    const formData = new ActionFormData();

    formData.title("순간 이동 장치").body("현재 위치를 저장하거나 저장된 위치로 이동하세요");
    formData.button("저장하기");
    formData.button("이동하기");

    formData.show(player).then((response) => {
        if (response.canceled) {
            return;
        }

        // 위치 저장하기
        if (response.selection === 0) {
            playerPositionX = player.location.x
            playerPositionY = player.location.y
            playerPositionZ = player.location.z

            player.runCommandAsync("title @a actionbar 위치 저장 완료");
        }

        //위치로 이동하기
        if (response.selection === 1) {
            if (playerPositionX == null) {
                player.runCommandAsync("title @a actionbar 저장된 장소가 없음");
            } else {
                player.runCommandAsync(`tp @s ${playerPositionX} ${playerPositionY} ${playerPositionZ}`);
                player.runCommandAsync("title @a actionbar 이동 완료");
            }
        }
    });
}

• 좌표를 코드 맨 위의 변수(let playerPositionX, …) 하나에 저장하므로 플레이어별로 따로 저장되지 않습니다. 여러 플레이어가 쓰면 마지막에 저장한 사람의 위치로 덮어씁니다. 확장 과제: 버튼을 하나 더 만들어 두 번째 장소 저장.
• 현재 시간 표시 currenttime.js 앞부분(화면 원문, 이후는 잘림)

import { world, system } from "@minecraft/server"
//플럼님이 제공한 코드입니다.

system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
        // 한국 시간 계산
        const kr_date = new Date(new Date().getTime() +
            (new Date().getTimezoneOffset() * 60 * 1000) +
            (9 * 60 * 60 * 1000));

        // 요일 배열 (한글)
        const weekDays = ['일', '월', '화', '수', '목', '금', '토'];

        // 날짜 형식 구성
        const year = kr_date.getFullYear();
        const month = kr_date.getMonth() + 1;  // getMonth()는 0부터 시작
        const date = kr_date.getDate();
        const day = weekDays[kr_date.getDay()];
        const time = kr_date.toString().split(` `)[4];

        // 액션바에 표시 (YYYY년 MM월 DD일 (요일) HH:MM:SS)
        player.onScreenDisplay.setActionBar(
        // … 이하 화면에서 잘림 (currenttime.js 참고)

1. 채팅 명령어: 채팅 입력에 반응
2. 블록 캐기 알림: 다이아몬드 점수
3. 침대 알람 폼: ActionFormData
4. 나침반 순간이동: 위치 저장·이동 폼
5. 카운트다운: runInterval, 20틱=1초
6. 메시지 저장: 채팅 기록 남기기
7. 채팅 퀴즈: 문제 배열 + 정답 비교

• 모듈: @minecraft/server / @minecraft/server-ui

import { world } from '@minecraft/server';

// 예전: dim.runCommandAsync(...)
world.getDimension('overworld')
     .runCommand('say 안녕!');

• AI 활용: “이런 기능을 스크립트로” 요청 / 주의: chatSend는 베타 API 실험 기능 필요 / 교육용: .mcaddon + 정식(stable) API만 쓰는 코드

• 서버가 시작될 때(system.beforeEvents.startup) customCommandRegistry로 선택지(enum)와 명령어를 등록

system.beforeEvents.startup.subscribe(e => {
    const command = e.customCommandRegistry;
    command.registerEnum(`figure:direction`, [`xy`, `xz`, `yz`]);
    command.registerCommand({
        name: `figure:circle`,
        description: "원 모양을 생성합니다",
        permissionLevel: 1,
        optionalParameters: [
            { type: 6, name: "center" }, // 중심점 좌표
            { type: 1, name: "radius" }, // 반지름 (정수)
            { type: 7, name: "blockType" }, // 블록 타입
            { type: 9, name: "figure:direction" }, // 방향 (xy, xz, yz 평면)
            { type: 0, name: "fill" } // 내부 채우기 여부
        ]
    }, (playerData, center, radius, blockType, direction, fill) => {
        // 입력하지 않은 값은 기본값: direction || "xz", fill || false
        system.run(() => { /* 원의 방정식으로 블록 놓기 (줄임) */ });
    });
});

• 매개변수 타입: 0 Boolean · 1 Integer · 2 Float · 3 String · 4 EntitySelector · 5 PlayerSelector · 6 Location · 7 BlockType · 8 ItemType · 9 Enum
• 권한 레벨: 0 Any · 1 GameDirectors(운영자·커맨드 블록, 영상 값) · 2 Admin · 3 Host · 4 Owner(콘솔)

• 코드→애드온 영상(2025-01)의 manifest 값: server 1.17.0-beta(화면), server-ui 1.4(자막). Bridge의 대상 버전은 쓰는 교육용 에디션의 게임 버전 이하로 낮춰서 만들기. 영상 설명란이 안내한 ‘교육용 에디션에서 실험기능 켜기’ 튜토리얼은 교육용 에디션에 애드온이 적용안된다면 이렇게 하면 됩니다(2023)로, UI Upgrade 애드온을 글로벌 리소스로 켜서 실험 기능 메뉴를 보이게 하는 방법입니다. 2026-07 실측에서는 교육용 에디션이 베타 API를 불러오지 않았으므로 이 방법에 기대지 말고 정식(stable) API만 쓰세요.
• 서버용 월드를 게임에서 먼저 만드는 까닭: 월드를 만들 때 정한 설정(베타 API, 행동 팩)이 그대로 서버로 옮겨집니다. 콘솔에 Level Name: apiworld가 나오면 월드 이름이 바뀐 것.
• 운영 중에는 행동 팩을 고칠 수 없습니다. 팩을 더 넣을 때 폴더 복사만으로는 안 불러오므로, 그 팩 manifest의 header uuid를 복사해 world_behavior_packs.json에 항목을 하나 더 만들고 pack_id에 넣습니다.

[
    {
        "pack_id" : "37ecd9df-cd63-4bdd-ba49-fd4def5ca511",
        "version" : [ 1, 0, 0 ]
    }
]

• 서버에서는 게임 안에서 치트를 켤 수 없어 server.properties의 allow-cheats를 true로 바꿉니다.
• 서버 폴더의 bedrock_server_how_to.html: server.properties·허용 목록(allowlist)·권한(permissions)·운영 명령·백업 설명. 서버 설치·운영은 ‘스크립트 API 서버 운영’, ‘전용 서버’ 페이지.

• 웹소켓: 게임 채팅과 내 컴퓨터의 프로그램(Node.js 서버)이 실시간으로 메시지를 주고받는 통로입니다.
• 준비: Node.js, VS Code, (챗봇을 쓸 때만) Ollama와 로컬 모델(예: llama2, mistral, gemma — 수 GB 필요). 영상의 AI 프로그램은 디스코드 안내에 ‘추가 설치: ollama.com/download/windows’, 배포 파일 WebSocket Gemma2.zip(화면).
• 서버 주소의 포트 번호는 서버 코드에 적힌 값을 씁니다(예제 코드 확인). 영상 예제는 3000번(new WebSocket.Server({ port: 3000 })).
• 연결이 안 되면 관리자 명령 프롬프트에서 루프백 허용: CheckNetIsolation LoopbackExempt -a -n="Microsoft.MinecraftUWP_8wekyb3d8bbwe" (영상 확인(1:59))
• → 노션 원문의 패키지 이름은 베드락(MinecraftUWP) 기준입니다. Microsoft Store로 설치한 교육용 에디션의 패키지 이름은 Microsoft.MinecraftEducationEdition_8wekyb3d8bbwe입니다(교사 PC의 교육용 에디션 데이터 폴더 이름으로 확인). 교육용 에디션은 ‘암호화된 웹소켓’도 꺼야 합니다(아래 「이 설정 반드시 하세요」 영상).
• 번역·AI 프로그램(영상): 웹소켓 연구 디스코드에서 받은 프로그램을 실행하면 웹소켓이 열리고 /connect localhost:3000으로 연결합니다. 번역은 Minecraft Translate, AI는 Minecraft Chat AI(Ollama 추가 설치 → 셋업 → 스타트, 채팅 !ai {메시지}). AI 답은 느리고 긴 답은 여러 줄로 나뉩니다.
• Ollama 챗봇은 로컬 모델이라 대화 내용이 외부로 나가지 않습니다. 교실 시연은 교사 PC 한 대로 충분합니다.
• 기본 예제 화면 원문(4~25줄):

// 3000번 포트에 새로운 웹소켓 서버 생성
console.log('준비 완료. Minecraft 채팅에서 /connect localhost:3000을 입력하세요')
const wss = new WebSocket.Server({ port: 3000 })

// Minecraft에서 "/connect localhost:3000"을 입력하면 연결이 생성됩니다
wss.on('connection', socket => {
  console.log('연결됨')

  // 클라이언트로부터 메시지를 받았을 때 처리
  socket.on('message', message => {
    try {
      const parsedMessage = JSON.parse(message.toString()); // 메시지를 JSON으로 파싱
      console.log('받은 메시지:', parsedMessage.body.message); // 실제 메시지 출력
      // 여기에 메시지 처리 로직을 추가할 수 있습니다
    } catch (error) {
      console.error('메시지 처리 중 오류 발생:', error); // 오류 처리
    }
  })

  // 연결이 종료되었을 때 처리
  socket.on('close', () => {
    console.log('연결 종료됨')

• 1편(2025-05): 실행하면 아무 창이 안 보여도 실행된 것. 콘솔 안내 “1. 마인크래프트 채팅창을 엽니다 (T키) 2. 아래 명령어를 붙여넣기 하세요 (Ctrl+V) /connect localhost:3000 (이미 클립보드에 복사되어 있습니다) 3. 엔터키를 눌러 실행하세요 / 연결에 실패할 경우: "setup.bat"를 실행하세요, 마인크래프트가 최신 버전인지 확인하세요”. 블록 페이지가 자동으로 안 열리면 http://localhost:4000 에 접속.
• 1편 fill 예: 시작 좌표 ~1 ~1 ~1, 끝 좌표 ~10 ~10 ~10, 금 블록, 채우기 옵션으로 속 비우기(영상에서 위치 입력 버그를 말함).
• 2편(2025-09): 반구는 채팅 1(모양 범주), 잔디블록 설치·파괴 시 “잔디블록을 설치했습니다./캤습니다.”, 채팅 2 → 카메라 상대 위치 오른쪽 0·위 0·앞 1에 잔디가 있으면 알려 줌, 나무 검을 주우면 ‘나무검 획득’. 다른 플레이어가 명령을 친 결과는 영상 02:49 화면에서 확인(누구 위치 기준인지는 두 명이 함께 시험해 보며 학생과 찾아보기 좋은 질문).
• 3편 연결 문제 점검 순서(설명란): ① 암호화된 웹소켓이 꺼져 있는지(가장 흔한 원인) ② 웹소켓이 켜져 있는지 ③ setup.bat을 관리자 권한으로 실행했는지 ④ 베드락 또는 에듀케이션 에디션인지.
• 준비물(GitHub README): Windows 10 또는 11(64비트), 마인크래프트 베드락 에디션, 크롬 또는 엣지 브라우저. 교육용 에디션에서 쓸 수 있다는 설명란 안내가 있으니, 교실 PC에서 미리 시험해 보세요.

• 코드작성기(MakeCode)보다 한 단계 깊은 방법입니다. 행동 팩에 JavaScript 파일을 넣어 게임 규칙 자체를 바꿉니다.
• 초등 교사 연수에서는 깊게 다루지 않고 “AI에게 이런 스크립트를 요청할 수 있다” 정도로 소개합니다.
• 노션 예제(2023)는 runCommandAsync를 쓰는데, 최신 @minecraft/server에서는 지원이 끝나 runCommand로 바꿔야 합니다.
• chatSend(채팅 이벤트)는 베타 API 실험 기능을 켜야 동작합니다(영상 확인(1:27): 채팅 명령어 예제에서 베타 API를 켬).
• 교육용 에디션: Bridge에서 .mcaddon으로 내보내 교육용 에디션으로 열면 행동 팩은 적용되지만, 실험 기능(베타 API) 메뉴가 없어 그 메뉴를 나오게 하는 애드온이 따로 필요합니다 — 영상 확인(5:54, 4:09). 버전마다 달라질 수 있어 연수 전에 확인하세요.
• 타이머 예제는 system.runInterval(…, 20) = 1초(20틱 = 1초).
• AI에게 코드를 받을 때(2025~2026 영상): ChatGPT는 기초 설명과 “스크립트 API를 쓰겠다”는 말을 먼저 주면 코드를 대략 짜 주지만 옛 문법을 자주 추천하므로 공식 문서와 함께 확인합니다. 복잡한 기능일수록 정확한 프롬프트와 코드를 읽는 힘이 필요합니다.

• 스티브코딩 채널의 스크립트 API 영상(61편)을 쓰임새별로 묶은 표입니다. 대부분 1~5분 길이이고, 설명란의 GitHub 코드를 main.js에 그대로 붙여 넣어 쓰는 방식입니다.
• 시작 순서(영상 확인): Bridge에서 새 프로젝트를 만들 때 베타 API를 켬 → main.js에 코드 → 월드의 실험 기능에서 ‘베타 API’를 켜고 행동 팩 적용 → 오류는 설정의 제작자 로그로 확인, manifest.json의 @minecraft/server 버전을 로그에 나온 버전으로 맞춤 → 코드를 고친 뒤에는 /reload(5:34).
• 교육용 에디션(영상 확인, 5:54): Bridge에서 .mcaddon으로 내보내 교육용 에디션으로 열면 팩은 적용되지만, 실험 기능(베타 API) 메뉴가 없어 그 메뉴를 나오게 하는 애드온이 따로 필요합니다. 버전마다 달라질 수 있어 연수 전에 확인하세요.
• 2026년 영상(jU1PpoG-VV8)부터는 코드 편집을 AI 편집기(구글 안티그래비티)에 맡깁니다. 공식 문서 주소를 레퍼런스로 함께 주면 오류가 줄어듭니다.
• 영상 날짜(시작하기 묶음): 2023-11 채팅 명령어·개발 환경, 2023-12 블록 이벤트·타이머, 2024-01 UI, 2025-01 코드→애드온, 2025-05 커스텀 명령어, 2025-10 GPTs, 2026-01 AI 편집기. 옛 영상은 API 버전이 달라 manifest 버전을 바꿔야 할 수 있습니다(그 밖에 확인된 것: 2025-02 보호 구역·은행·커스텀 인챈트 18가지, 2026-01 좀비 소환).
• PART 08 「스크립트 API 예제 7가지」와 함께 보면 좋습니다.