Minescript v5.0 문서

모든 버전의 Minescript 문서는 GitHub에서 확인할 수 있습니다.

인게임 명령

명령 기초

Minescript 명령은 인게임 채팅 콘솔에서 사용할 수 있습니다. 슬래시(/)로 시작하는 Minecraft 명령과 달리, Minescript 명령은 백슬래시(\)로 시작합니다.

minescript 폴더(minecraft 폴더 안에 있음)에 있는 Python 스크립트는 스크립트 이름 앞에 백슬래시(\)를 붙이고 파일 이름 끝의 .py를 제거하여 인게임 채팅에서 명령으로 실행할 수 있습니다. 예를 들어 Python 스크립트 minecraft/minescript/build_fortress.py는 인게임 채팅에 \build_fortress를 입력하여 Minescript 명령으로 실행할 수 있습니다. 인게임 채팅이 숨겨져 있다면, 바닐라(vanilla) Minecraft에서 t나 /를 누르는 것과 마찬가지로 \를 눌러 표시할 수 있습니다. Python 스크립트가 명령줄 매개변수를 지원하는 경우 Minescript 스크립트 명령에 매개변수를 전달할 수 있습니다. (아래 스크립트 입력의 예시를 참고하세요.)

일련의 X Y Z 매개변수를 받는 Minescript 명령은 로컬 플레이어(player)를 기준으로 한 상대 위치를 지정하기 위해 물결표(tilde) 문법을 사용할 수 있습니다. 예를 들어 ~ ~ ~나 ~-1 ~2 ~-3과 같이 사용합니다. 또는 로컬 플레이어의 x, y, z 좌표를 각각 나타내기 위해 매개변수를 $x, $y, $z로 지정할 수도 있습니다. ($ 문법은 연속된 3개의 X Y Z 좌표로 나타나지 않는 좌표를 지정할 때 특히 유용합니다.)

아래에서 선택적인 명령 매개변수는 [EXAMPLE]과 같이 대괄호로 표시됩니다. (단, 실제 명령을 입력할 때는 대괄호를 제외하고 입력하세요.)

내장 명령

ls

사용법: \ls

Minescript 내장 명령과 minescript 폴더의 Python 스크립트를 포함하여 사용 가능한 모든 Minescript 명령을 나열합니다.

help

사용법: \help NAME

주어진 스크립트 또는 명령 이름에 대한 문서를 출력합니다.

도입 버전: v1.19.2

eval

사용법: \eval PYTHON_CODE [LINE2 [LINE3 ...]]

PYTHON_CODE(및 이어지는 LINE2, LINE3 등의 선택적인 줄)를 Python 표현식(할당문의 우변에 올 수 있는 코드로, 이 경우 값이 채팅 화면에 출력됩니다) 또는 Python 문(예: for 루프)으로 실행합니다.

minescript.py의 함수는 한정자 없이 자동으로 사용할 수 있습니다.

예시:

주변 엔티티(entity)에 대한 정보를 채팅 화면에 출력합니다:

\eval "entities()"

주변 엔티티의 이름을 채팅 화면에 출력합니다:

\eval "for e in entities(): echo(e['name'])"

time 모듈을 임포트하고 3초간 대기한 후 스크린샷을 촬영합니다:

\eval "import time" "time.sleep(3)" "screenshot()"

copy

사용법: \copy X1 Y1 Z1 X2 Y2 Z2 [LABEL] [no_limit]

(X1, Y1, Z1)에서 (X2, Y2, Z2)까지의 직육면체 영역 안에 있는 블록(block)을 복사합니다. 이는 /fill 명령에 전달하는 좌표와 비슷합니다. LABEL은 선택 사항이며, 이를 통해 블록 집합에 이름을 지정할 수 있습니다.

기본값으로 1600개 이상의 청크(chunk)를 포함하는 영역을 복사하려는 시도는 허용되지 않습니다. no_limit을 전달하면 이 제한을 완화할 수 있습니다.

함께 보기: \paste.

paste

사용법: \paste X Y Z [LABEL]

이전에 \copy로 복사한 블록을 위치 (X, Y, Z)에 붙여넣습니다. 선택적 매개변수 LABEL이 주어지면, 동일한 LABEL이 지정된 가장 최근의 copy 명령에서 블록을 붙여넣습니다. 그렇지 않으면 레이블이 지정되지 않은 가장 최근의 copy 명령에서 블록을 붙여넣습니다.

참고로, \copy와 \paste는 서로 다른 월드(world)에서 실행하여 한 월드의 영역을 다른 월드로 복사할 수 있습니다.

함께 보기: \copy.

jobs

사용법: \jobs [all]

현재 실행 중인 Minescript 작업(job)을 나열합니다.

인자 없이 사용한 \jobs는 상위 작업이 관리하지 않는 모든 작업을 나열합니다.

\jobs all은 하위 작업을 포함한 모든 작업을 나열합니다. 예를 들어 상위 Python 작업 안에 내장된 Pyjinn 스크립트도 포함됩니다. 함께 보기: Pyjinn: Python 스크립트에 Pyjinn 내장하기

suspend

사용법: \suspend [JOB_ID]

현재 실행 중인 Minescript 작업을 일시 중지합니다. JOB_ID가 지정되면 해당 정수 ID를 가진 작업이 일시 중지됩니다. 지정되지 않으면 현재 실행 중인 모든 Minescript 작업이 일시 중지됩니다.

함께 보기: \resume.

z

사용법: \z [JOB_ID]

\suspend의 별칭(alias)입니다.

resume

사용법: \resume [JOB_ID]

현재 일시 중지된 Minescript 작업을 재개합니다. JOB_ID가 지정되면 해당 정수 ID를 가진 작업이 현재 일시 중지된 상태일 경우 재개됩니다. JOB_ID가 지정되지 않으면 현재 일시 중지된 모든 Minescript 작업이 재개됩니다.

함께 보기: \suspend.

killjob

사용법: \killjob JOB_ID

JOB_ID에 해당하는, 현재 실행 중이거나 일시 중지된 Minescript 작업을 종료합니다. 특수 값 -1을 지정하면 현재 실행 중이거나 일시 중지된 모든 Minescript 작업을 종료할 수 있습니다.

undo

사용법: \undo

마지막 Minescript 명령이 실행한 모든 /setblock 및 /fill 명령을, 그 이전에 존재하던 블록을 복원하여 실행 취소합니다. Minescript 명령이 실수로 건축물을 파괴한 경우, 마지막 명령 이전의 건축물 상태로 되돌리고 싶을 때 유용합니다. \undo는 여러 번 실행하여 최근 여러 Minescript 명령으로 인한 건축 변경 사항을 실행 취소할 수 있습니다.

참고: 명령 블록 안에 지정된 명령이나 상자 안의 아이템(item)처럼, Minescript 명령을 실행 취소할 때 일부 블록 상태가 손실될 수 있습니다.

설정

minescript 디렉터리에는 config.txt라는 이름의 설정 파일이 있습니다. config.txt의 텍스트 줄은 다음과 같은 형식을 가질 수 있습니다:

다음과 같은 형식의 설정 변수를 포함하는 줄: NAME=VALUE. 예: python="/usr/bin/python3".
백슬래시(\)로 끝나는 줄은 다음 줄과 이어지는 것으로 해석됩니다. \로 끝나는 줄이 여러 개 연속되면, 그 줄들은 이어지는 줄과 함께 같은 설정 줄로 간주됩니다.
#로 시작하는 줄은 주석이며 Minescript 동작에 영향을 주지 않습니다.
빈 줄은 Minescript 동작에 영향을 주지 않습니다.

설정 변수 이름:

autorun[WORLD NAME] – WORLD NAME이라는 이름의 월드에 진입할 때 실행할 명령(v3.1부터)
- 특수 이름 *는 모든 월드에 진입할 때 명령을 실행해야 함을 나타냅니다. 예를 들어 autorun[*]=eval 'echo(f"Hello, {world_info().name}!")'는 월드에 접속할 때 메시지로 환영 인사를 건넵니다.
- 동일한 월드 또는 *에 대해 여러 개의 autorun[...] 설정 줄을 지정할 수 있으며, 이 경우 일치하는 모든 명령이 동시에 실행됩니다.
- 하나의 autorun[...] 설정 줄은 세미콜론(;)으로 명령을 구분하여 여러 명령을 순차적으로 실행할 수 있습니다. 예를 들어 다음은 먼저 월드에 대한 정보를 출력한 다음 가장 가까운 엔티티(entity) 10개의 이름을 출력합니다: autorun[*]=eval "world_info()"; eval "[e.name for e in entities(sort='nearest', limit=10)]"
- python – Python 인터프리터(interpreter)의 파일 위치(Windows 기본값은 "%userprofile%\AppData\Local\Microsoft\WindowsApps\python3.exe"이고, 다른 운영체제에서는 "/usr/bin/python3")
- command – Minecraft 명령에서 스크립트나 실행 파일 호출을 사용자 지정하기 위한 설정입니다. command는 파일 확장자별로 여러 번 지정할 수 있습니다. 예를 들어 Minescript 명령 \foo에서 foo.jar와 같은 jar 파일을 실행하려면: command = { "extension": ".jar", "command": [ "/usr/bin/java", "-jar", "{command}", "{args}" ], "environment": [ "FIRST_ENV_VAR=1234", "SECOND_ENV_VAR=2468" ] } environment은 선택 사항이며, 스크립트/실행 파일에 환경 변수를 전달할 수 있게 해줍니다. Python 스크립트 실행을 설정할 때는 environment에 PYTHON_PATH를 설정하는 것을 잊지 마세요.
- command_path – Minescript 명령에서 스크립트/실행 파일을 실행하기 위한 명령 경로를 설정합니다. 절대 경로가 아닌 항목은 minescript 디렉터리를 기준으로 한 상대 경로입니다. Windows에서는 경로를 ;로 구분하고, 다른 운영체제에서는 :로 구분합니다. 기본값은 minescript 디렉터리와 그 안의 system/exec와 동일합니다.
- escape_command_double_quotes – true인 경우, command 설정 항목의 command 필드에 있는 {args} 안의 큰따옴표를 이스케이프합니다. 기본값은 Windows에서는 true, 다른 운영체제에서는 false입니다.
- max_commands_per_cycle – Minescript 처리 주기당 실행할 Minescript가 생성한 Minecraft 명령의 개수입니다. 숫자가 클수록 스크립트가 더 빠르게 실행됩니다. 기본값은 15입니다. (참고: 이 값을 너무 높게 설정하면 Minecraft의 반응성이 떨어지고 충돌이 발생할 수 있습니다.)
- command_cycle_deadline_usecs – 이 값을 초과하면 Minescript가 해당 실행 주기에서 명령 실행을 중단하는 마이크로초 단위의 임계값입니다. 기본값은 10000(10밀리초)입니다. 임계값을 초과하여 실행 중인 명령은 완료될 때까지 계속 실행되지만, 해당 주기에서는 더 이상 명령이 실행되지 않습니다.
- ticks_per_cycle – Minecraft 처리 주기당 대기할 Minecraft 게임 틱(tick)의 수입니다. 숫자가 낮을수록(최소 1까지) 스크립트가 더 빠르게 실행됩니다. v3.2부터 기본값은 1입니다. (이전에는 기본값이 3이었습니다.)
- incremental_command_suggestions – 사용자가 Minescript 명령을 입력할 때 인게임 채팅에 증분 명령 제안을 출력할지 여부를 활성화하거나 비활성화합니다. 기본값은 false입니다.
- report_job_success_threshold_millis – 스크립트 작업(job)이 이 값(밀리초 단위)보다 오래 실행된 후 성공적으로 종료된 경우 이를 화면에 보고합니다. 기본값은 3000(3초)입니다. 0이면 항상 보고하고, -1이면 절대 보고하지 않습니다. 실패한 스크립트 작업의 종료는 항상 보고됩니다 (v4.0부터)
- debug_output – true인 경우 logs/latest.log에 디버그 출력을 활성화합니다. 기본값은 false입니다.
- minescript_on_chat_received_event – true인 경우, Minescript는 "You whisper to ..."로 시작하며 백슬래시(\)로 시작하는 메시지를 포함하는 채팅 메시지를 실행합니다. 예를 들어 [execute as maxuser run tell maxuser \eval 1+2]를 실행하는 명령 블록에서 발생하는 경우입니다. 기본값은 false입니다.
- secondary_enter_key_code – enter 키(키 코드 257, Mac에서는 return이라고 함)는 채팅에서 명령을 종료하는 기본 키입니다. secondary_enter_key_code는 명령을 종료할 수도 있는 사용자 지정 가능한 보조 키입니다. 기본값은 335(KEY_KP_ENTER)입니다. 키 코드 목록은 GLFW Keyboard key tokens를 참고하세요.
- stderr_chat_ignore_pattern – 스크립트의 stderr 출력 줄을 무시하기 위한 정규 표현식입니다. 기본값은 빈 문자열인 "^$"입니다. 이는 Minescript에서 실행할 때 stderr 출력이 지나치게 많은 Python 설치 환경에서 유용할 수 있습니다.

Pyjinn

Pyjinn은 Python 문법을 기반으로 하는 Minescript의 통합 인터프리터입니다. 자세한 내용은 Pyjinn 문서를 참고하세요.

Python API

스크립트 입력

매개변수는 Minecraft에서 sys.argv로 Python 스크립트에 입력으로 전달될 수 있습니다. 예를 들어 다음 Python 스크립트는 주사위를 굴린 결과를 채팅에 출력하며, 이는 로컬 사용자에게만 보입니다 (코드를 minecraft/minescript/roll_dice.py에 복사하세요):

import random
import sys

def print_dice_roll(num_dice: int, num_sides: int):
    results = []
    for _ in range(num_dice):
        results.append(random.randint(1, num_sides))
    die_or_dice = "die" if num_dice == 1 else "dice"
    print(f"Rolled {num_dice} {num_sides}-sided {die_or_dice}: {results}")

# `sys.argv` 리스트에서 인자를 읽습니다.
# 주사위 개수에 대한 첫 번째 인자는 필수입니다.
# 주사위 면의 수에 대한 두 번째 인자는 선택 사항이며,
# 기본값은 6입니다.
num_dice = int(sys.argv[1])
num_sides = int(sys.argv[2]) if len(sys.argv) > 2 else 6
print_dice_roll(num_dice, num_sides)

위 스크립트는 Minecraft 인게임 채팅에서 실행하여 6면체 주사위 2개를 굴린 결과를 출력할 수 있습니다:

\roll_dice 2 6

이 명령은 num_dice를 2로, num_sides를 6으로 설정하는 인자를 전달합니다.

스크립트 출력

Minescript Python 스크립트는 sys.stdout과 sys.stderr를 사용해 출력을 처리하거나(예: Python의 내장 print 함수 사용), minescript.py에 정의된 함수인 echo, echo_json, chat, log를 사용해 처리할 수 있습니다.

# 인게임 채팅에 일반 텍스트 메시지를 출력합니다.
# 본인에게만 표시됩니다(흰색 텍스트로 표시):
print("Note to self...")

# 이전 print(...) 문과 동일하지만,
# stdout으로의 출력을 명시적으로 지정한 것입니다:
print("Note to self...", file=sys.stdout)

# 이전 print(...) 문들과 동일한 출력이지만,
# Minescript 함수를 사용합니다(아래의
# "스크립트 출력 리다이렉션"을 사용할 경우
# 위의 print(...) 문들과 동작이 다를 수 있습니다):
import minescript
minescript.echo("Note to self...")

# JSON 형식의 텍스트를(스타일과 색상이 적용된 텍스트를 위해)
# JSON 문자열로 본인에게만 인게임 채팅에 출력합니다:
minescript.echo_json('{"text":"hello!", "color":"green"}')

# 또는 JSON으로 변환된 Python dict나 list로:
minescript.echo_json({"text":"hello!", "color":"green"})

# 인게임 채팅에 일반 텍스트 메시지를 출력하며,
# 본인에게만 표시됩니다. stdout에 기록된 텍스트와
# 시각적으로 구분되도록 노란색 텍스트로 표시됩니다:
print("Note to self...", file=sys.stderr)

# 월드 내 모든 플레이어에게 보이는
# 채팅 메시지를 전송합니다:
minescript.chat("hi, friends!")

# Minecraft의 로그 파일에 메시지를 기록합니다
# (minecraft/logs/latest.log 안에):
minescript.log("This is a debug message that does not appear in-game.")

스크립트 출력 리다이렉션

기본적으로 스크립트의 stdout(일반적으로 print("...") 형태)과 stderr(예: print("...", file=sys.stderr))로의 출력은 흰색(stdout) 또는 노란색(stderr)의 일반 텍스트로 표시되며, 본인에게만 보입니다. 하지만 채팅에 입력하는 Minescript 명령의 끝에 리다이렉션 연산자를 사용하면 스크립트 작업에 대해 이 동작을 재정의할 수 있습니다.

다음은 minecraft/minescript/output_example.py에 복사할 수 있는 예시 스크립트입니다:

import sys
print("Output to stdout")
print("Output to stderr", file=sys.stderr)

이 스크립트는 인게임 채팅에서 다음과 같이 실행할 수 있습니다:

\output_example

Output to stdout 텍스트는 채팅에 흰색으로 표시되고, Output to stderr 텍스트는 노란색으로 표시되며, 둘 다 본인에게만 보입니다.

하지만 다음과 같이 명령에 > chat을 추가하면:

\output_example > chat

stdout으로의 출력이 여러 플레이어가 볼 수 있는 채팅으로 리다이렉션됩니다.

마찬가지로, 출력을 Minecraft 로그 파일 (minecraft/logs/latest.log)로 리다이렉션하여 인게임 채팅에 표시되지 않도록 할 수 있으며, 이는 본인에게도 표시되지 않습니다:

\output_example > log

스크립트 작업의 stdout 출력은 > null로 리다이렉션하여 완전히 비활성화할 수 있습니다:

\output_example > null

stderr로의 출력도 마찬가지로 2>로 리다이렉션할 수 있습니다:

\output_example 2> chat
\output_example 2> log
\output_example 2> null

동일한 스크립트 작업에서 stdout과 stderr를 각각 별도로 리다이렉션할 수 있습니다. 예를 들어 stdout은 여러 플레이어가 볼 수 있는 채팅으로, stderr는 채팅에 표시하지 않고 (본인에게도 표시하지 않고) Minecraft 로그 파일로 리다이렉션할 수 있습니다:

\output_example > chat 2> log

> 뒤의 공백은 생략할 수 있습니다:

\output_example >chat 2>log

스크립트 함수

minescript.py에서 임포트한 스크립트 함수는 함수로 호출하거나 비동기적으로 호출할 수 있습니다.

예를 들어 minescript.screenshot("my_screenshot.png")처럼 직접 호출하는 경우, 스크립트 함수는 Java로 구현되어 있으며 일반적으로 Java에서 함수 실행이 끝난 후에 반환됩니다. (일부 스크립트 함수는 Java 처리가 백그라운드에서 계속되는 동안 즉시 반환됩니다: execute, echo, echo_json, chat, 그리고 log.)

스크립트 함수가 실행될 수 있는 Java 실행기(executor)는 3가지가 있습니다:

minescript.tick_loop: 매 게임 틱(tick)마다 한 번씩 실행되는 게임 틱 루프(초당 20회 실행되며, 주기 시간은 50밀리초입니다)
minescript.render_loop: 프레임이 렌더링(rendering)될 때 실행됩니다(일반적으로 초당 약 60프레임이며 주기 시간은 15~20밀리초이지만, 게임 성능에 따라 크게 달라질 수 있습니다)
minescript.script_loop: 스크립트 함수를 최대한 빠르게 처리하는 실행기(executor)이지만 렌더링 스레드에서 실행되지 않으므로, Minecraft Java 코드의 스레드 안전성 부족으로 인해 불안정해지거나 심지어 게임이 충돌할 수 있습니다(주기 시간은 일반적으로 1밀리초 미만입니다)

Java 실행기(executor)는 특정 스크립트 함수에 대해, 또는 특정 스크립트 컨텍스트 내에서 선택할 수 있습니다. 스크립트 함수의 실행기 선택은 다음 우선순위에 따라 높은 순서부터 낮은 순서로 결정됩니다:

해당 함수에 필수 실행기가 설정되어 있는 경우, 그 실행기가 사용됩니다. 이는 함수의 set_required_executor 메서드로 설정하며, 예를 들어 minescript.player.set_required_executor(minescript.script_loop)와 같습니다. 기본적으로는 필수 실행기가 설정되어 있지 않습니다.
with 블록을 사용해 스크립트 컨텍스트에서 설정한 실행기, 예를 들어 with minescript.script_loop: position = minescript.player().position # 고속 스크립트 루프에서 처리됨 ...
해당 함수에 기본 실행기가 설정되어 있는 경우, 그 실행기가 사용됩니다. 이는 함수의 set_default_executor 메서드로 설정하며, 예를 들어 minescript.player.set_default_executor(minescript.script_loop)와 같습니다. 기본적으로는 개별 스크립트 함수에 기본 실행기가 설정되어 있지 않습니다.
현재 스크립트 작업(job)의 기본 실행기. 이는 전역 함수 set_default_executor로 설정하며, 예를 들어 minescript.set_default_executor(minescript.render_loop)와 같습니다. 기본값은 render_loop입니다.

스크립트 함수에 실행기를 설정하면 해당 스크립트 작업(job) 내에서 그 함수를 호출할 때만 영향을 미칩니다. 동시에 실행 중인 스크립트 작업들은 동일한 스크립트 함수에 대해 서로 다른 실행기를 설정할 수 있습니다.

참고: <script_function>.as_task(), run_tasks(), schedule_tick_tasks(), schedule_render_tasks()를 사용하는 스크립트 작업(task)은 Minescript 5.0에서 제거되었습니다. 해당 기능이 내장된 Pyjinn 스크립트와 중복되며 표현력도 떨어지기 때문입니다. Python 스크립트 내에 Pyjinn 스크립트를 내장하는 방법은 다음을 참고하세요: Pyjinn: Python 스크립트에 Pyjinn 내장하기

비동기 스크립트 함수(Async script functions)

비동기(asynchronous) 스크립트 함수를 사용하면 스크립트가 함수를 백그라운드에서 실행하고 완료를 기다릴 수 있습니다. 이는 완료까지 몇 초와 같이 오랜 시간이 걸릴 수 있는 스크립트 함수에 유용합니다.

다음 예시에서는 await_loaded_region을 사용해 일정 범위의 청크(chunk)가 로딩을 마칠 때까지 스크립트 실행을 차단합니다. 이 예시는 동기(synchronous) 방식으로 실행되는(즉, 작업이 완료될 때까지 반환하지 않는) 스크립트 함수를 직접 호출합니다:

import minescript

x, y, z = [int(p) for p in minescript.player().position]

# (x ± 50, z ± 50) 범위의 모든 청크가 로드될 때까지 대기합니다:
minescript.await_loaded_region(x - 50, z - 50, x + 50, z + 50)

minescript.echo("Chunks around player finished loading.")

다음은 앞선 예시를 변형한 것으로, 스크립트 함수를 직접 호출하는 대신 .as_async(...)를 호출해 비동기 스크립트 함수를 사용하도록 수정한 버전입니다:

import minescript

x, y, z = [int(p) for p in minescript.player().position]

# .as_async(...)를 사용하면 스크립트 함수가 "future" 값을 반환합니다:
future = minescript.await_loaded_region.as_async(x - 50, z - 50, x + 50, z + 50)

# 청크가 백그라운드에서 로딩되는 동안 다른 작업을 수행합니다...
minescript.echo("Waiting for chunks around player to finish loading...")

# future가 완료되기를, 즉 청크 로딩이 끝나기를 기다립니다:
future.wait()
minescript.echo("Chunks around player finished loading.")

비동기 스크립트 함수가 반환한 future 값은 타임아웃(timeout)과 함께 대기할 수 있으며, 타임아웃이 만료될 때까지 작업이 완료되지 않으면 TimeoutError가 발생합니다. 다음 예시에서는 주어진 범위의 청크 로딩이 끝날 때까지 "Still waiting for chunks around player to finish loading..." 메시지가 10초마다 플레이어의 채팅에 반복적으로 출력됩니다:

import minescript

x, y, z = [int(p) for p in minescript.player().position]
while True:
  try:
    # 10초 타임아웃으로 대기합니다:
    minescript.await_loaded_region.as_async(x - 50, z - 50, x + 50, z + 50).wait(timeout=10)
    minescript.echo("Chunks around player finished loading.")
    break
  except TimeoutError:
    minescript.echo("Still waiting for chunks around player to finish loading...")

java 모듈

Python에서 Java 리플렉션(reflection)을 사용하기 위한 라이브러리로, 저수준 Java API 스크립트 함수 (java_*)를 감싸는 래퍼(wrapper)입니다.

예시:

from minescript import echo
from java import JavaClass

Minecraft = JavaClass("net.minecraft.client.Minecraft")
minecraft = Minecraft.getInstance()
echo("fps:", minecraft.getFps())

AutoReleasePool
callAsyncScriptFunction
callScriptFunction
eval_pyjinn_script
Float
import_pyjinn_script
JavaBoundMember
JavaClassType
JavaFloat
JavaFuture
JavaInt
JavaObject
JavaRef
JavaString

AutoReleasePool

with 블록을 사용해 Python에서 Java 참조(reference)를 관리하기 위한 컨텍스트 매니저(context manager)입니다.

예시:

import minescript
from java import *
with AutoReleasePool() as auto:
  Object_class = auto(java_class("java.lang.Object"))
  Object_hashCode = auto(java_member(Object_class, "hashCode"))
  hello_string = auto(java_string("hello"))
  hash_value  = auto(java_call_method(hello_string, Object_hashCode))
  minescript.echo(java_to_string(hash_value))

위 예시에서 auto()로 포착된 모든 Java 참조는 위의 with 블록이 종료될 때 해제되며, 이때 자동으로 java_release()가 호출됩니다.

AutoReleasePool.call

사용법: AutoReleasePool.__call__(ref: JavaHandle) -> JavaHandle

이 풀(pool)이 삭제되거나 스코프(scope)를 벗어날 때 자동 해제되도록 ref를 추적합니다.

반환:

JavaHandle을 반환하는 함수를 편리하게 감쌀 수 있도록 ref를 그대로 반환합니다.

Float

Java의 float를 Python에서 그대로 표현하기 위한 래퍼(wrapper) 클래스(class)입니다.

Python float는 Java double에 매핑되며, Python에는 내장된 단정밀도(single-precision) float가 없습니다.

  value: float

JavaRef

Python에서 참조하는 Java 객체(object)에 대한 참조 카운터(reference counter)입니다.

JavaObject

Java 객체(object)를 Python으로 표현한 것입니다.

JavaObject.init

사용법: JavaObject(target_id: JavaHandle, ref: JavaRef = None, is_script: bool = False)

JavaHandle이 주어지면 Java 객체(object)에 대한 Python 핸들(handle)을 생성합니다.

JavaObject.toString

사용법: JavaObject.toString() -> str

Java의 this.toString()을 str로 표현하여 반환합니다.

JavaObject.set_value

사용법: JavaObject.set_value(value: Any)

이 JavaObject가 대신 value를 참조하도록 설정합니다.

value는 다음 타입(type) 중 하나일 수 있습니다: – bool: Java Boolean으로 변환됨 – int: Java Integer로 변환됨 – Float: Java Float로 변환됨 – float: Java Double로 변환됨 – str: Java String으로 변환됨 – JavaObject: 이 JavaObject는 value와 동일한 Java 객체(object)를 참조하게 됨

JavaObject.getattr

사용법: JavaObject.__getattr__(name: str)

name이라는 이름의 필드(field) 또는 메서드(method)에 접근합니다.

인자:

name: 이 JavaObject의 클래스(class)에 있는 필드(field) 또는 메서드(method)의 이름

반환:

name이 이 JavaObject의 클래스(class)에 있는 필드(field)와 일치하면, 해당 필드의 값을 Python 기본 타입(primitive) 또는 새로운 JavaObject로 반환합니다. 그렇지 않으면 JavaBoundMember를 반환하며, 이는 Java 표현식 this::methodName과 동등합니다.

JavaObject.len

사용법: JavaObject.__len__() -> int

이 JavaObject가 Java 배열(array)을 나타내는 경우, 배열의 길이를 반환합니다.

배열이 아닌 경우 TypeError가 발생합니다.

JavaObject.bool

사용법: JavaObject.__bool__() -> int

Java 참조(reference)가 null이면 False를 반환합니다.

JavaObject.getitem

사용법: JavaObject.__getitem__(i: int)

이 JavaObject가 Java 배열(array)을 나타내는 경우, array[i]를 반환합니다.

인자:

i: 배열에서 요소를 가져올 인덱스

반환:

array[i]를 Python 기본 타입(primitive) 값 또는 JavaObject로 반환합니다.

예외:

배열이 아닌 경우 TypeError가 발생합니다.

JavaBoundMember

Java 메서드(method) 참조를 Python으로 표현한 것입니다.

JavaBoundMember.init

사용법: JavaBoundMember(target_class_id: JavaHandle, target, name: str, ref: JavaRef = None, script: JavaObject = None)

대상 객체(target object)에 바인딩되어 필드(field) 또는 메서드(method)를 나타내는 멤버입니다.

인자:

target_class_id: 이 멤버를 포함하는 클래스(class)의 Java 객체(object) ID
target: 이 멤버에 접근하는 데 사용되는 대상의 Java 객체 ID
name: 이 멤버의 이름
ref: 참조(reference) 수명을 관리하는 JavaRef(선택 사항)
script: 스크립트(script) 함수에 접근하고 호출하기 위한 Pyjinn Script 객체(선택 사항)

JavaBoundMember.call

사용법: JavaBoundMember.__call__(*args)

주어진 args로 바인딩된 메서드(method)를 호출합니다.

반환:

해당하는 경우 Python 기본 타입(primitive)(bool, int, float, str)이고, 그렇지 않으면 JavaObject입니다.

JavaInt

Java Integer를 위한 JavaObject 하위 클래스(subclass)입니다.

JavaFloat

Java Float를 위한 JavaObject 하위 클래스입니다.

JavaString

Java String을 위한 JavaObject 하위 클래스입니다.

JavaClassType

Java 클래스 객체를 위한 JavaObject 하위 클래스입니다.

JavaClassType.is_enum

사용법: JavaClassType.is_enum()

이 클래스가 Java 열거형(enum) 타입(type)을 나타내면 True를 반환합니다.

JavaClassType.getattr

사용법: JavaClassType.__getattr__(name)

이 Java 클래스에서 name이라는 이름의 정적 필드(field) 또는 정적 메서드에 접근합니다.

인자:

name: 이 Java 클래스에 있는 정적 필드 또는 정적 메서드의 이름

반환:

name이 이 Java 클래스에 있는 정적 필드와 일치하면, 해당 필드의 값을 새로운 JavaObject로 반환합니다. 그렇지 않으면 JavaBoundMember를 반환하며, 이는 Java 표현식 ThisClass::staticMethodName과 동등합니다.

JavaClassType.call

사용법: JavaClassType.__call__(*args)

적용 가능한 경우, 주어진 args를 받는 이 Java 클래스의 생성자(constructor)를 호출합니다.

반환:

새로 생성된 Java 객체를 나타내는 JavaObject입니다.

callScriptFunction

사용법: callScriptFunction(func_name: str, *args) -> JavaObject

주어진 Minescript 스크립트 함수를 호출합니다.

인자:

func_name: Minescript 스크립트 함수의 이름
args: 주어진 스크립트 함수에 전달할 인자(argument)

반환:

주어진 스크립트 함수의 반환값이며, Python 기본 타입 또는 JavaObject입니다.

JavaFuture

비동기(async) 함수가 완료되면 사용 가능해지는 Java 값입니다.

JavaFuture.wait

사용법: JavaFuture.wait(timeout=None)

비동기 함수가 완료될 때까지 기다립니다.

인자:

timeout: None이 아닌 경우, 비동기 함수가 완료되기를 기다릴 시간(초 단위)

반환:

비동기 함수가 완료되면 반환되는 Python 기본 타입 값 또는 JavaObject입니다.

callAsyncScriptFunction

사용법: callAsyncScriptFunction(func_name: str, *args) -> JavaFuture

주어진 Minescript 스크립트 함수를 비동기적으로 호출합니다.

인자:

func_name: Minescript 스크립트 함수의 이름
args: 주어진 스크립트 함수에 전달할 인자

반환:

비동기 함수가 완료되면 그 반환값을 담게 될 JavaFuture입니다.

eval_pyjinn_script

사용법: eval_pyjinn_script(script_code: str) -> JavaObject

문자열(string)로 주어진 소스 코드로부터 Pyjinn 스크립트를 생성합니다.

함께 보기: Python 스크립트에 Pyjinn 내장하기

인자:

script_code: Pyjinn 소스 코드

반환:

org.pyjinn.interpreter.Script 타입의 새로운 Java 객체입니다.

도입 버전: v5.0

import_pyjinn_script

사용법: import_pyjinn_script(pyj_filename: str)

.pyj 파일로부터 Pyjinn 스크립트를 임포트합니다.

함께 보기: Python 스크립트에 Pyjinn 내장하기

인자:

pyj_filename: 임포트할 Pyjinn 코드가 담긴 .pyj 파일의 이름

반환:

org.pyjinn.interpreter.Script 타입의 새로운 Java 객체입니다.

도입 버전: v5.0

minescript 모듈

사용법: import minescript # Python 스크립트에서

이 모듈에는 스크립트가 Minescript 모드(mod)를 호출하기 위한 API가 포함되어 있습니다. 이 모듈은 라이브러리로서 스크립트에 임포트되어야 하며, 직접 실행해서는 안 됩니다.

"Compatibility:"가 명시되어 있지 않는 한, 이 모듈에 있는 API는 Python과 Pyjinn 스크립트 모두와 호환됩니다.

add_event_listener
AddEntityEvent
append_chat_history
await_loaded_region
BlockPack
BlockPacker
BlockPackerException
BlockPos
BlockRegion
BlockUpdateEvent
chat
chat_input
ChatEvent
ChatEventListener
ChunkEvent
ClientboundPacketEvent
combine_rotations
container_get_items
DamageEvent
echo
echo_json
entities
EntityData
EventLoop
EventQueue
execute
ExplosionEvent
flush
get_block
get_block_list
get_block_region
getblock
getblocklist
HandItems
ItemStack
java_access_field
java_array_index
java_array_length
java_assign
java_bool
java_call_method
java_call_script_function
java_class
java_ctor
java_double
java_field_names
java_float
java_int
java_long
java_member
java_method_names
java_new_array
java_new_instance
java_release
java_string
java_to_string
JavaArray
JavaClass
JavaFloat
JavaInt
JavaList
JavaMap
JavaString
job_info
JobInfo
KeyEvent
KeyEventListener
log
ManagedCallback
MinescriptRuntimeOptions
MouseEvent
player
player_get_targeted_block
player_get_targeted_entity
player_hand_items
player_health
player_inventory
player_inventory_select_slot
player_inventory_slot_to_hotbar
player_look_at
player_name
player_orientation
player_position
player_press_attack
player_press_backward
player_press_drop
player_press_forward
player_press_jump
player_press_left
player_press_pick_item
player_press_right
player_press_sneak
player_press_sprint
player_press_swap_hands
player_press_use
player_set_orientation
players
press_key_bind
remove_event_listener
RenderEvent
Rotation
Rotations
screen_name
screenshot
ServerboundPacketEvent
set_chat_input
set_default_executor
set_interval
set_timeout
show_chat_screen
TakeItemEvent
TargetedBlock
TickEvent
Vector3f
version_info
VersionInfo
world_info
WorldEvent
WorldInfo

BlockPos

블록(block) 공간에서 (x: int, y: int, z: int) 위치를 나타내는 튜플입니다.

Vector3f

3차원 공간에서 (x: float, y: float, z: float) 위치 또는 오프셋을 나타내는 튜플입니다.

MinescriptRuntimeOptions

Minescript 모듈 옵션입니다.

호환성: Python 전용.

  legacy_dict_return_values: bool = False  # v4.0 이전 동작을 재현하려면 `True`로 설정

execute

사용법: execute(command: str)

주어진 명령을 실행합니다.

command가 백슬래시(\)로 시작하면 Minescript 명령으로 처리되고, 그렇지 않으면 Minecraft 명령으로 처리됩니다(슬래시 접두사는 선택 사항입니다).

참고: 이 함수는 Minescript 2.0에서는 exec라는 이름이었습니다. 이전 이름은 v3.0부터 더 이상 사용할 수 없습니다.

도입 버전: v2.1

echo

사용법: echo(*messages)

일반 텍스트 메시지를 채팅에 출력합니다.

출력된 메시지는 로컬 플레이어(local player)에게만 표시됩니다.

인자가 여러 개 주어지면, 메시지 사이에 공백을 넣어 연결합니다.

v4.0에서 업데이트: 여러 개의 일반 텍스트 메시지를 지원합니다.

도입 버전: v2.0

echo_json

사용법: echo_json(json_text)

JSON 형식의 텍스트를 채팅에 출력합니다.

출력된 텍스트는 로컬 플레이어에게만 표시됩니다.

json_text는 JSON 텍스트를 나타내는 문자열이거나 리스트 또는 딕셔너리일 수 있습니다. 리스트나 딕셔너리인 경우, 표준 json 모듈을 사용해 JSON 문자열로 변환하세요.

도입 버전: v4.0

chat

사용법: chat(*messages)

메시지를 채팅으로 전송합니다.

messages[0]이 슬래시나 백슬래시로 시작하는 문자열이면, 메시지가 명령으로 실행되지 않고 채팅으로 전송되도록 자동으로 앞에 공백을 추가합니다. len(messages)가 1보다 크면, 메시지 사이에 공백을 넣어 연결합니다. 빈 messages는 무시합니다.

v4.0에서 업데이트: 여러 개의 메시지를 지원합니다.

도입 버전: v2.0

log

사용법: log(*messages)

메시지를 latest.log에 전송합니다.

v4.0에서 업데이트: 모든 타입의 메시지를 지원합니다. 메시지를 str로 자동 변환합니다.

도입 버전: v3.0

screenshot

사용법: screenshot(filename: str=None)

F2 키를 누르는 것과 유사하게 스크린샷을 촬영합니다.

인자:

filename: 지정하면 screenshots 디렉터리 기준 상대 경로의 스크린샷 파일명입니다; “.png” 확장자가 이미 붙어 있지 않으면 스크린샷 파일에 확장자가 추가됩니다.

도입 버전: v2.1

JobInfo

  job_id: int
  command: List[str]
  source: str
  status: str
  parent_job_id: Union[int, None]
  self: bool

job_info

사용법: job_info() -> List[JobInfo]

활성 Minescript 작업(job)에 대한 정보를 반환합니다.

반환:

JobInfo. 이 호출을 실행 중인 작업의 경우, JobInfo.self는 True입니다.

도입 버전: v4.0

flush

사용법: flush()

이 작업에서 이전에 실행한 모든 스크립트(script) 명령이 완료될 때까지 기다립니다.

호환성: Python 전용.

도입 버전: v2.1

player_name

사용법: player_name() -> str

로컬 플레이어의 이름을 가져옵니다.

도입 버전: v2.1

player_position

사용법: player_position() -> List[float]

로컬 플레이어(local player)의 위치를 가져옵니다.

반환:

플레이어의 위치, [x: float, y: float, z: float] 형식

v4.0에서 업데이트: done_callback 인자를 제거했습니다. 비동기(async) 실행을 위해 player_position().as_async()를 사용하세요.

ItemStack

  item: str
  count: int
  nbt: str = None
  slot: int = None
  selected: bool = None

HandItems

  main_hand: ItemStack
  off_hand: ItemStack

player_hand_items

사용법: player_hand_items() -> HandItems

로컬 플레이어의 양손에 있는 아이템(item)을 가져옵니다.

반환:

플레이어의 양손에 있는 아이템입니다. (레거시(legacy) 방식의 반환값은 options.legacy_dict_return_values = True로 복원할 수 있습니다)

v4.0에서 업데이트: 기본값으로 List[Dict[str, Any]] 대신 HandItems를 반환합니다. done_callback 인자를 제거했습니다. 비동기 실행을 위해 player_hand_items.as_async()를 사용하세요.

도입 버전: v2.0

player_inventory

사용법: player_inventory() -> List[ItemStack]

로컬 플레이어의 인벤토리(inventory)에 있는 아이템을 가져옵니다.

반환:

플레이어의 인벤토리에 있는 아이템입니다. (레거시 방식의 반환값은 options.legacy_dict_return_values = True로 복원할 수 있습니다)

v4.0에서 업데이트: 기본값으로 List[Dict[str, Any]] 대신 List[ItemStack]을 반환합니다. done_callback 인자를 제거했습니다. 비동기 실행을 위해 player_inventory.as_async()를 사용하세요.

v3.0에서 업데이트: 반환되는 딕셔너리(dict)에 "slot"과 "selected" 속성을 새로 도입했으며, "nbt"는 NBT 데이터가 있을 때만 채워집니다. (이전 버전에서는 "nbt"가 항상 채워졌으며, NBT 데이터가 없을 때는 null 값을 가졌습니다.)

도입 버전: v2.0

player_inventory_slot_to_hotbar

사용법: player_inventory_slot_to_hotbar(slot: int) -> int

인벤토리 아이템을 핫바(hotbar)로 교체합니다.

인자:

slot: 핫바로 교체할 인벤토리 슬롯(slot)(9 이상)

반환:

인벤토리 아이템이 교체되어 들어간 핫바 슬롯(0-8)

mc1.21.4에서 업데이트: Minecraft 1.21.4에서 ServerboundPickItemPacket이 제거되어 더 이상 지원되지 않습니다.

v4.0에서 업데이트: done_callback 인자를 제거했습니다. 비동기 실행을 위해 player_inventory_slot_to_hotbar.as_async(...) 를 사용하세요.

도입 버전: v3.0

player_inventory_select_slot

사용법: player_inventory_select_slot(slot: int) -> int

플레이어의 핫바에서 주어진 슬롯을 선택합니다.

인자:

slot: 플레이어의 손에서 선택할 핫바 슬롯(0-8)

반환:

이전에 선택되어 있던 핫바 슬롯

v4.0에서 업데이트: done_callback 인자를 제거했습니다. 비동기 실행을 위해 player_inventory_select_slot.as_async(...)를 사용하세요.

도입 버전: v3.0

press_key_bind

사용법: press_key_bind(key_mapping_name: str, pressed: bool)

매핑된 키 바인딩을 누르거나 놓습니다.

key_mapping_name의 유효한 값에는 다음이 포함됩니다: “key.advancements”, “key.attack”, “key.back”, “key.chat”, “key.command”, “key.drop”, “key.forward”, “key.fullscreen”, “key.hotbar.1”, “key.hotbar.2”, “key.hotbar.3”, “key.hotbar.4”, “key.hotbar.5”, “key.hotbar.6”, “key.hotbar.7”, “key.hotbar.8”, “key.hotbar.9”, “key.inventory”, “key.jump”, “key.left”, “key.loadToolbarActivator”, “key.pickItem”, “key.playerlist”, “key.right”, “key.saveToolbarActivator”, “key.screenshot”, “key.smoothCamera”, “key.sneak”, “key.socialInteractions”, “key.spectatorOutlines”, “key.sprint”, “key.swapOffhand”, “key.togglePerspective”, “key.use”

인자:

key_mapping_name: 키 바인딩의 이름
pressed: True이면 바인딩된 키를 누르고, 아니면 놓습니다

도입 버전: v4.0

player_press_forward

사용법: player_press_forward(pressed: bool)

로컬 플레이어를 앞으로 이동시키기 시작/중지하며, ‘w’ 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 앞으로 이동하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_backward

사용법: player_press_backward(pressed: bool)

로컬 플레이어를 뒤로 이동시키기 시작/중지하며, ‘s’ 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 뒤로 이동하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_left

사용법: player_press_left(pressed: bool)

로컬 플레이어를 왼쪽으로 이동시키기 시작/중지하며, ‘a’ 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 왼쪽으로 이동하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_right

사용법: player_press_right(pressed: bool)

로컬 플레이어를 오른쪽으로 이동시키기 시작/중지하며, ‘d’ 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 오른쪽으로 이동하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_jump

사용법: player_press_jump(pressed: bool)

로컬 플레이어의 점프를 시작/중지하며, 스페이스 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 점프하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_sprint

사용법: player_press_sprint(pressed: bool)

로컬 플레이어의 달리기를 시작/중지하며, 왼쪽 컨트롤 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 달리고, 아니면 멈춥니다

도입 버전: v2.1

player_press_sneak

사용법: player_press_sneak(pressed: bool)

로컬 플레이어의 웅크리기를 시작/중지하며, 왼쪽 시프트 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 웅크리고, 아니면 멈춥니다

도입 버전: v2.1

player_press_pick_item

사용법: player_press_pick_item(pressed: bool)

로컬 플레이어가 아이템을 집는 동작을 시작/중지하며, 마우스 가운데 버튼을 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 아이템을 집고, 아니면 멈춥니다

도입 버전: v2.1

player_press_use

사용법: player_press_use(pressed: bool)

로컬 플레이어가 아이템을 사용하거나 블록(block)을 선택하는 동작을 시작/중지하며, 마우스 오른쪽 버튼을 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 아이템을 사용하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_attack

사용법: player_press_attack(pressed: bool)

로컬 플레이어가 공격하거나 블록을 파괴하는 동작을 시작/중지하며, 마우스 왼쪽 버튼을 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 공격하고, 아니면 멈춥니다

도입 버전: v2.1

player_press_swap_hands

사용법: player_press_swap_hands(pressed: bool)

로컬 플레이어의 손 바꾸기를 시작/중지하며, ‘f’ 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 손을 바꾸고, 아니면 멈춥니다

도입 버전: v2.1

player_press_drop

사용법: player_press_drop(pressed: bool)

로컬 플레이어의 아이템 버리기를 시작/중지하며, ‘q’ 키를 누르거나 떼는 것을 시뮬레이션합니다.

인자:

pressed: True이면 아이템을 버리고, 아니면 멈춥니다

도입 버전: v2.1

player_orientation

사용법: player_orientation() -> List[float]

로컬 플레이어의 방향(orientation)을 가져옵니다.

반환:

도 단위 각도로 표현한 [yaw: float, pitch: float]

도입 버전: v2.1

player_set_orientation

사용법: player_set_orientation(yaw: float, pitch: float) -> bool

로컬 플레이어의 방향을 설정합니다.

인자:

yaw: 로컬 플레이어 방향의 y축 기준 회전 각도(도 단위)
pitch: 로컬 플레이어 방향의 x-z 평면 기준 회전 각도(도 단위)

반환:

성공하면 True

도입 버전: v2.1

TargetedBlock

  position: BlockPos
  distance: float
  side: str
  type: str

player_get_targeted_block

사용법: player_get_targeted_block(max_distance: float = 20) -> Union[TargetedBlock, None]

로컬 플레이어의 조준점(crosshair)에 있는 가장 가까운 블록(있는 경우)에 대한 정보를 가져옵니다.

인자:

max_distance: 블록을 찾기 위해 로컬 플레이어로부터 확인할 최대 거리

반환:

플레이어가 조준한 블록에 대한 TargetedBlock이며, 조준한 블록이 없으면 None입니다.

v4.0에서 업데이트: 반환값이 list에서 TargetedBlock으로 변경되었습니다.

도입 버전: v3.0

EntityData

  name: str
  type: str
  uuid: str
  id: int
  position: Vector3f
  yaw: float
  pitch: float
  velocity: Vector3f
  lerp_position: Vector3f = None
  health: float = None
  local: bool = None  # 로컬 플레이어(player)인 경우 `True`
  passengers: List[str] = None  # 탑승자들의 UUID를 문자열로 나타낸 값
  nbt: str = None

player_get_targeted_entity

사용법: player_get_targeted_entity(max_distance: float = 20, nbt: bool = False) -> Union[EntityData, None]

로컬 플레이어(player)의 조준선(crosshair)에 조준된 엔티티(entity)가 있다면 이를 가져옵니다.

인자:

max_distance: 조준된 엔티티를 확인할 최대 거리
nbt: True인 경우, 플레이어에 대한 "nbt" 속성을 채웁니다

반환:

플레이어가 조준한 엔티티에 대한 EntityData이며, 조준된 엔티티가 없으면 None입니다. (레거시(legacy) 스타일의 반환된 딕셔너리(dict)는 options.legacy_dict_return_values = True로 복원할 수 있습니다)

도입 버전: v4.0

player_health

사용법: player_health() -> float

로컬 플레이어의 체력(health)을 가져옵니다.

도입 버전: v3.1

player

사용법: player(*, nbt: bool = False) -> EntityData

로컬 플레이어의 속성(attribute)을 가져옵니다.

인자:

nbt: True인 경우, 플레이어에 대한 nbt 필드를 채웁니다

반환:

로컬 플레이어의 값 스냅숏(snapshot)을 나타내는 EntityData입니다. (레거시 스타일의 반환된 딕셔너리는 options.legacy_dict_return_values = True로 복원할 수 있습니다)

도입 버전: v4.0

players

사용법: players(*, nbt: bool = False, uuid: str = None, name: str = None, position: Vector3f = None, offset: Vector3f = None, min_distance: float = None, max_distance: float = None, sort: str = None, limit: int = None) -> List[EntityData]

주변 플레이어 목록과 그 속성을 가져옵니다.

인자:

nbt: True인 경우, 반환되는 각 플레이어에 대한 "nbt" 속성을 채웁니다
uuid: 엔티티의 UUID를 매칭하기 위한 정규 표현식(regular expression) (선택 사항)
name: 엔티티의 이름을 매칭하기 위한 정규 표현식 (선택 사항)
position: 엔티티를 필터링할 범위를 정의하기 위해 offset, min_distance, 또는 max_distance와 함께 사용되는 위치이며, 기본값은 로컬 플레이어의 위치입니다 (선택 사항)
offset: 엔티티를 선택하기 위한 position 기준 오프셋(offset) (선택 사항)
min_distance: 엔티티를 선택하기 위한 position 기준 최소 거리 (선택 사항)
max_distance: 엔티티를 선택하기 위한 position 기준 최대 거리 (선택 사항)
sort: “nearest”, “furthest”, “random”, “arbitrary” 중 하나 (선택 사항)
limit: 반환할 최대 엔티티 수 (선택 사항)

반환:

선택된 플레이어들의 값 스냅숏을 나타내는 List[EntityData]입니다. (레거시 방식으로 반환된 딕셔너리들은 options.legacy_dict_return_values = True로 복원할 수 있습니다)

v4.0에서 업데이트: 다음 인자가 추가되었습니다: uuid, name, type, position, offset, min_distance, max_distance, sort, limit. 기본적으로 List[Dict[str, Any]] 대신 List[EntityData]를 반환합니다. 반환되는 플레이어에 uuid와 id가 추가되었습니다.

v3.1에서 업데이트: "health"와 "local" 속성, 그리고 "nbt" 속성을 출력하기 위한 nbt 인자가 추가되었습니다.

도입 버전: v2.1

entities

사용법: entities(*, nbt: bool = False, uuid: str = None, name: str = None, type: str = None, position: Vector3f = None, offset: Vector3f = None, min_distance: float = None, max_distance: float = None, sort: str = None, limit: int = None) -> List[EntityData]

주변 엔티티 목록과 그 속성을 가져옵니다.

인자:

nbt: True인 경우, 반환되는 각 엔티티에 대한 "nbt" 속성을 채웁니다 (선택 사항)
uuid: 엔티티의 UUID를 매칭하기 위한 정규 표현식 (선택 사항)
name: 엔티티의 이름을 매칭하기 위한 정규 표현식 (선택 사항)
type: 엔티티의 타입(type)을 매칭하기 위한 정규 표현식 (선택 사항)
position: 엔티티를 필터링할 범위를 정의하기 위해 offset, min_distance, 또는 max_distance와 함께 사용되는 위치이며, 기본값은 로컬 플레이어의 위치입니다 (선택 사항)
offset: 엔티티를 선택하기 위한 position 기준 오프셋 (선택 사항)
min_distance: 엔티티를 선택하기 위한 position 기준 최소 거리 (선택 사항)
max_distance: 엔티티를 선택하기 위한 position 기준 최대 거리 (선택 사항)
sort: “nearest”, “furthest”, “random”, “arbitrary” 중 하나 (선택 사항)
limit: 반환할 최대 엔티티 수 (선택 사항)

반환:

선택된 엔티티들의 값 스냅숏을 나타내는 List[EntityData]입니다. (레거시 방식으로 반환된 딕셔너리들은 options.legacy_dict_return_values = True로 복원할 수 있습니다)

v4.0에서 업데이트: 다음 인자가 추가되었습니다: uuid, name, type, position, offset, min_distance, max_distance, sort, limit. 기본적으로 List[Dict[str, Any]] 대신 List[EntityData]를 반환합니다. 반환되는 엔티티에 uuid, id, 그리고 (탑승자가 있는 엔티티에 한해) passengers가 추가되었습니다.

v3.1에서 업데이트: "health"와 "local" 속성, 그리고 "nbt" 속성을 출력하기 위한 nbt 인자가 추가되었습니다.

도입 버전: v2.1

VersionInfo

  minecraft: str
  minescript: str
  mod_loader: str
  launcher: str
  os_name: str
  os_version: str
  minecraft_class_name: str
  pyjinn: str

version_info

사용법: version_info() -> VersionInfo

Minecraft, Minescript, 모드 로더(mod loader), 런처(launcher), OS에 대한 버전 정보를 가져옵니다.

minecraft_class_name은 메인 Minecraft 클래스(class)의 런타임(runtime) 클래스 이름이며, 난독화(obfuscated)되어 있을 수 있습니다.

반환:

VersionInfo

도입 버전: v4.0

WorldInfo

  game_ticks: int
  day_ticks: int
  raining: bool
  thundering: bool
  spawn: BlockPos
  hardcore: bool
  difficulty: str
  name: str
  address: str

world_info

사용법: world_info() -> WorldInfo

월드(world) 속성을 가져옵니다.

현재 월드가 서버 목록에서 불러온 멀티플레이어 월드인 경우, 반환되는 name과 address 속성은 서버 목록에 표시된 값입니다. 그렇지 않으면 name은 로컬에 저장된 월드의 이름이고 address는 localhost입니다.

day_ticks는 낮밤 주기와 관련된 틱(tick)입니다.

v3.1부터 world_properties()에서 이름이 변경되었습니다.

반환:

WorldInfo

도입 버전: v4.0

getblock

사용법: getblock(x: int, y: int, z: int) -> str

위치 (x, y, z)에 있는 블록(block)의 타입을 가져옵니다.

인자:

x, y, z: 가져올 블록의 위치

반환:

(x, y, z)에 있는 블록 타입을 문자열로 나타낸 값

v5.0에서 업데이트: 별칭(alias) get_block(...)이 추가되었습니다.

get_block

getblock(...)의 별칭입니다.

도입 버전: v5.0

getblocklist

사용법: getblocklist(positions: List[List[int]]) -> List[str]

지정된 [x, y, z] 위치들의 블록 타입을 가져옵니다.

인자:

x, y, z 정수 좌표 리스트로 이루어진 위치들의 리스트, 예: [[0, 0, 0], [0, 0, 1]]

반환:

주어진 위치들의 블록 타입을 문자열 리스트로 나타낸 값

v5.0에서 업데이트: 별칭 get_block_list(...)이 추가되었습니다.

v4.0에서 업데이트: done_callback 인자가 제거되었습니다. 비동기(asynchronous) 실행을 위해서는 getblocklist.as_async(...)를 사용하세요.

도입 버전: v2.1

get_block_list

getblocklist(...)의 별칭입니다.

도입 버전: v5.0

BlockRegion

축 정렬 경계 상자(axis-aligned bounding box) 내의 블록에 접근하기 위한 접근자(accessor)입니다.

get_block_region(...)을 사용하면 BlockRegion을 생성할 수 있습니다.

도입 버전: v5.0

BlockRegion.init

사용법: BlockRegion(min_pos: BlockPos, max_pos: BlockPos, blocks: Tuple[str, ...])

min_pos와 max_pos 사이(양 끝 포함)의 블록 영역을 생성합니다.

인자:

min_pos: 축 정렬 경계 상자의 최소 위치
max_pos: 축 정렬 경계 상자의 최대 위치
blocks: min_pos와 max_pos 사이(양 끝 포함)의 부피를 덮는 블록 타입 문자열들의 튜플(tuple)이며, 경계 상자의 x, y, z 방향 길이를 각각 Lx, Ly, Lz라 할 때, 튜플의 첫 번째 값은 min_pos 위치의 블록을 나타내고, 처음 Lx개의 값은 부피의 최소 y, z 모서리를 나타내며, 처음 Lx * Lz개의 값은 부피의 최소 y 평면에 있는 블록들을 나타내고, 마지막 값은 max_pos 위치의 블록을 나타냅니다.

BlockRegion.get_block

사용법: BlockRegion.get_block(x: int, y: int, z: int) -> str

위치 (x, y, z)에 있는 블록의 타입을 가져옵니다.

BlockRegion.get_index

사용법: BlockRegion.get_index(x: int, y: int, z: int) -> int

위치 (x, y, z)에 대한 blocks 시퀀스(sequence) 내 인덱스를 가져옵니다.

get_block_region

사용법: get_block_region(pos1: BlockPos, pos2: BlockPos, safety_limit: bool = True) -> BlockRegion

pos1과 pos2 사이(양 끝 포함)의 축 정렬 경계 상자 내에 있는 블록들의 타입을 가져옵니다.

인자:

pos1, pos2: 축 정렬 경계 상자(axis-aligned bounding box, aabb)의 서로 마주보는 두 모서리
safety_limit: True이면, 요청한 볼륨이 1600개 청크(chunk)를 초과할 경우 실패합니다

반환:

BlockRegion은 요청한 블록(block) 볼륨을 포괄합니다.

도입 버전: v5.0

await_loaded_region

사용법: await_loaded_region(x1: int, z1: int, x2: int, z2: int)

(x1, z1)부터 (x2, z2)까지의 영역에서 청크가 로드될 때까지 기다립니다.

인자:

x1, z1, x2, z2: 청크 로드를 기다릴 영역의 경계
timeout: 지정하면, 해당 영역이 로드될 때까지 대기할 타임아웃(timeout) 시간(초)

호환성: Python 전용입니다.

v4.0에서 업데이트: done_callback 인자가 제거되었습니다. 이제 호출은 영역이 로드될 때까지 항상 블로킹(blocking)됩니다.

set_default_executor

사용법: set_default_executor(executor: minescript_runtime.FunctionExecutor)

현재 스크립트 작업(job)에서 실행되는 스크립트 함수의 기본 실행기(executor)를 설정합니다.

기본값은 minescript.render_loop입니다.

인자:

executor: minescript.tick_loop, minescript.render_loop, minescript.script_loop 중 하나

호환성: Python 전용입니다.

도입 버전: v4.0

KeyEvent

키 이벤트(event) 데이터입니다.

키 코드 목록은 다음을 참고하세요: https://www.glfw.org/docs/3.4/group__keys.html action은 키를 뗐을 때 0, 눌렀을 때 1, 반복 입력일 때 2입니다.

  type: str
  time: float
  key: int
  scan_code: int
  action: int
  modifiers: int
  screen: str

MouseEvent

마우스 이벤트 데이터입니다.

action은 마우스 버튼을 뗐을 때 0, 눌렀을 때 1입니다.

  type: str
  time: float
  button: int
  action: int
  modifiers: int
  x: float
  y: float
  screen: str = None

ChatEvent

  type: str
  time: float
  message: str

AddEntityEvent

  type: str
  time: float
  entity: EntityData

BlockUpdateEvent

  type: str
  time: float
  position: BlockPos
  old_state: str
  new_state: str

TakeItemEvent

  type: str
  time: float
  player_uuid: str
  item: EntityData
  amount: int

DamageEvent

  type: str
  time: float
  entity_uuid: str
  cause_uuid: str
  source: str

ExplosionEvent

  type: str
  time: float
  position: Vector3f
  blockpack_base64: str

ChunkEvent

  type: str
  time: float
  loaded: bool
  x_min: int
  z_min: int
  x_max: int
  z_max: int

WorldEvent

  type: str
  time: float
  connected: bool

EventQueue

이벤트를 관리하기 위한 큐(queue)입니다.

컨텍스트 관리(context management)를 구현하여 with 표현식과 함께 사용할 수 있으며, 블록이 끝날 때 이벤트 리스너(listener)를 자동으로 등록 해제합니다. 예를 들면 다음과 같습니다.

with EventQueue() as event_queue:
  event_queue.register_chat_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.CHAT and "knock knock" in event.message.lower():
      echo("Who's there?")

호환성: Python 전용입니다. (Pyjinn의 이벤트 처리에 대해서는 add_event_listener 및 EventLoop를 참고하세요.)

도입 버전: v4.0

EventQueue.init

사용법: EventQueue()

이벤트 등록 핸들러(handler)를 생성합니다.

EventQueue.register_key_listener

사용법: EventQueue.register_key_listener()

EventType.KEY 이벤트에 대한 리스너를 KeyEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_key_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.KEY:
      if event.action == 0:
        action = 'up'
      elif event.action == 1:
        action = 'down'
      else:
        action = 'repeat'
      echo(f"Got key {action} with code {event.key}")

EventQueue.register_mouse_listener

사용법: EventQueue.register_mouse_listener()

EventType.MOUSE 이벤트에 대한 리스너를 MouseEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_mouse_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.MOUSE:
      echo(f"Got mouse {'up' if event.action == 0 else 'down'} of button {event.button}")

EventQueue.register_chat_listener

사용법: EventQueue.register_chat_listener()

EventType.CHAT 이벤트에 대한 리스너를 ChatEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_chat_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.CHAT:
      if not event.message.startswith("> "):
        echo(f"> Got chat message: {event.message}")

EventQueue.register_outgoing_chat_interceptor

사용법: EventQueue.register_outgoing_chat_interceptor(*, prefix: str = None, pattern: str = None)

EventType.OUTGOING_CHAT_INTERCEPT 이벤트에 대한 리스너를 ChatEvent로 등록합니다.

로컬 플레이어(player)가 보내는 채팅 메시지를 가로챕니다. 가로채기 대상은 prefix 또는 pattern과 일치하는 메시지로 제한할 수 있습니다. 가로챈 메시지는 chat()으로 채팅할 수 있습니다.

prefix와 pattern 중 하나만 지정할 수 있으며 둘 다 지정할 수는 없습니다. prefix와 pattern 중 어느 것도 지정하지 않으면 나가는 모든 채팅 메시지를 가로챕니다.

인자:

prefix: 지정하면, 이 리터럴(literal) 접두사(prefix)로 시작하는 메시지만 가로챕니다
pattern: 지정하면, 이 정규식(regular expression)과 일치하는 메시지만 가로챕니다

예시:

with EventQueue() as event_queue:
  event_queue.register_outgoing_chat_interceptor(pattern=".*%p.*")
  while True:
    event = event_queue.get()
    if event.type == EventType.OUTGOING_CHAT_INTERCEPT:
      # 나가는 채팅 메시지의 "%p"를 현재 위치로 바꿉니다.
      chat(event.message.replace("%p", str(player().position)))

EventQueue.register_add_entity_listener

사용법: EventQueue.register_add_entity_listener()

EventType.ADD_ENTITY 이벤트에 대한 리스너를 AddEntityEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_add_entity_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.ADD_ENTITY:
      echo(f"Entity added: {event.entity.name}")

EventQueue.register_block_update_listener

사용법: EventQueue.register_block_update_listener()

EventType.BLOCK_UPDATE 이벤트에 대한 리스너를 BlockUpdateEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_block_update_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.BLOCK_UPDATE:
      echo(f"Block updated at {event.position} to {event.new_state}")

EventQueue.register_take_item_listener

사용법: EventQueue.register_take_item_listener()

EventType.TAKE_ITEM 이벤트에 대한 리스너를 TakeItemEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_take_item_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.TAKE_ITEM:
      echo(f"Item taken: {event.item.type}")

EventQueue.register_damage_listener

사용법: EventQueue.register_damage_listener()

EventType.DAMAGE 이벤트에 대한 리스너를 DamageEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_damage_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.DAMAGE:
      echo(f"Damage from {event.source}")

EventQueue.register_explosion_listener

사용법: EventQueue.register_explosion_listener()

EventType.EXPLOSION 이벤트에 대한 리스너를 ExplosionEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_explosion_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.EXPLOSION:
      echo(f"Explosion at {event.position}")

EventQueue.register_chunk_listener

사용법: EventQueue.register_chunk_listener()

EventType.CHUNK 이벤트에 대한 리스너를 ChunkEvent로 등록합니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_chunk_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.CHUNK:
      x = event.x_min
      z = event.z_min
      echo(f"Chunk {'loaded' if event.loaded else 'unloaded'} at {x}, {z}")

EventQueue.register_world_listener

사용법: EventQueue.register_world_listener()

EventType.WORLD 이벤트에 대한 리스너를 WorldEvent로 등록합니다.

스크립트 작업(job)은 사용자의 게임 클라이언트가 월드(world)와의 연결을 끊으면 자동으로 종료되며, 단 스크립트에 활성화된 “world” 리스너가 등록되어 있는 경우는 예외입니다. “world” 리스너가 있는 작업을 포함해 모든 스크립트 작업은 게임 클라이언트가 종료될 때 함께 종료됩니다.

예시:

with EventQueue() as event_queue:
  event_queue.register_world_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.WORLD:
      if event.connected:
        log(f"Connected to world {world_info().name}.")
      else:
        log("Disconnected from world.")

도입 버전: v5.0

EventQueue.get

사용법: EventQueue.get(block: bool = True, timeout: float = None) -> Any

큐(queue)에서 다음 이벤트를 가져옵니다.

인자:

block: True이면 이벤트가 발생할 때까지 블록(block)합니다
timeout: block이 True일 때 이벤트를 기다리는 제한 시간(초)

반환:

하위 클래스에 따라 달라지는 이벤트

예외:

block이 True이고 timeout이 만료되거나, block이 False이고 큐가 비어 있는 경우 queue.Empty

KeyEventListener

사용법: KeyEventListener()

키보드 이벤트를 위한 지원 중단(deprecated)된 리스너입니다. 대신 EventQueue.register_key_listener를 사용하세요.

호환성: Python 전용.

v4.0에서 업데이트: EventQueue.register_key_listener로 대체되어 지원 중단되었습니다.

도입 버전: v3.2

ChatEventListener

사용법: ChatEventListener()

채팅 메시지 이벤트를 위한 지원 중단(deprecated)된 리스너입니다.

대신 EventQueue.register_chat_message_listener를 사용하세요.

호환성: Python 전용.

v4.0에서 업데이트: EventQueue.register_chat_message_listener로 대체되어 지원 중단되었습니다.

도입 버전: v3.2

screen_name

사용법: screen_name() -> Union[str, None]

현재 GUI 화면 이름을 가져옵니다(있는 경우).

반환:

현재 화면의 이름(str), 표시 중인 GUI 화면이 없으면 None

도입 버전: v3.2

show_chat_screen

사용법: show_chat_screen(show: bool, prompt: str = None) -> bool

채팅 화면을 표시하거나 숨깁니다.

인자:

show: True이면 채팅 화면을 표시하고, 그렇지 않으면 숨깁니다
prompt: show가 True일 때, 채팅 화면 표시 시 prompt를 채팅 입력창에 삽입합니다.

반환:

채팅 화면 표시(show=True) 또는 숨기기(show=False)가 성공하면 True

도입 버전: v4.0

append_chat_history

사용법: append_chat_history(message: str)

message를 채팅 기록에 추가합니다. 채팅에서 위/아래 화살표로 조회할 수 있습니다.

도입 버전: v4.0

chat_input

사용법: chat_input() -> List[Union[str, int]]

채팅 입력 텍스트의 상태를 가져옵니다.

반환:

[text, position] — text는 str이고, position은 text 내 커서 위치를 나타내는 int입니다

도입 버전: v4.0

set_chat_input

사용법: set_chat_input(text: str = None, position: int = None, color: int = None)

채팅 입력 텍스트의 상태를 설정합니다.

인자:

text: 지정하면 채팅 입력 텍스트를 대체합니다
position: 지정하면 커서를 채팅 입력창 내 해당 위치로 이동합니다
color: 지정하면 입력 텍스트 색상을 0xRRGGBB 형식으로 설정합니다

도입 버전: v4.0

container_get_items

사용법: container_get_items() -> List[ItemStack]

열려 있는 컨테이너(슬롯이 있는 상자, 화로 등)의 모든 아이템(item)을 가져옵니다.

반환:

컨테이너의 내용물이 표시되어 있으면 아이템(item) 목록, 그렇지 않으면 None.

도입 버전: v4.0

player_look_at

사용법: player_look_at(x: float, y: float, z: float)

카메라를 회전시켜 특정 위치를 바라보게 합니다.

인자:

x: x 위치
y: y 위치
z: z 위치

도입 버전: v4.0

Rotation

평탄화된 행 우선(row-major) 3×3 회전 행렬을 나타내는 9개의 int 값으로 이루어진 튜플입니다.

Rotations

BlockPack 및 BlockPacker 메서드(method)와 함께 사용하는 공통 회전값입니다.

도입 버전: v3.0

Rotations.IDENTITY

실질적으로 회전하지 않습니다.

Rotations.X_90

x축을 기준으로 90도 회전합니다.

Rotations.X_180

x축을 기준으로 180도 회전합니다.

Rotations.X_270

x축을 기준으로 270도 회전합니다.

Rotations.Y_90

y축을 기준으로 90도 회전합니다.

Rotations.Y_180

y축을 기준으로 180도 회전합니다.

Rotations.Y_270

y축을 기준으로 270도 회전합니다.

Rotations.Z_90

z축을 기준으로 90도 회전합니다.

Rotations.Z_180

z축을 기준으로 180도 회전합니다.

Rotations.Z_270

z축을 기준으로 270도 회전합니다.

Rotations.INVERT_X

x 좌표를 반전시킵니다(-1을 곱함).

Rotations.INVERT_Y

y 좌표를 반전시킵니다(-1을 곱함).

Rotations.INVERT_Z

z 좌표를 반전시킵니다(-1을 곱함).

combine_rotations

사용법: combine_rotations(rot1: Rotation, rot2: Rotation, /) -> Rotation

두 회전 행렬을 결합하여 하나의 회전 행렬로 만듭니다.

도입 버전: v3.0

BlockPack

BlockPack은 불변(immutable)이며 직렬화 가능한 블록(block) 모음입니다.

블록팩(blockpack)은 월드(world), 파일, 직렬화된 바이트로부터 읽거나 그쪽으로 쓸 수 있습니다. 블록팩은 불변이며 블록의 위치와 방향을 그대로 유지하지만, 월드로부터 읽거나 월드에 쓸 때 회전 및 오프셋을 적용할 수 있습니다.

가변(mutable) 블록 모음이 필요하면 BlockPacker를 참고하세요.

도입 버전: v3.0

BlockPack.read_world

사용법: @classmethod BlockPack.read_world(pos1: BlockPos, pos2: BlockPos, *, rotation: Rotation = None, offset: BlockPos = None, comments: Dict[str, str] = {}, safety_limit: bool = True) -> BlockPack

직사각형 영역 내 월드(world)의 블록(block)으로부터 블록팩(blockpack)을 생성합니다.

인자:

pos1, pos2: 월드 블록을 읽어올 직사각형 영역의 대향하는 두 모서리
rotation: 월드에서 읽은 블록 좌표에 적용할 회전 행렬
offset: 블록 좌표에 적용할 오프셋(회전 적용 후 적용됨)
comments: 새 블록팩에 포함할 키, 값 쌍
safety_limit: True이면 요청한 영역이 1600청크(chunk)를 초과할 경우 실패합니다

반환:

월드에서 읽은 블록을 담은 새 BlockPack

BlockPack.read_file

사용법: @classmethod BlockPack.read_file(filename: str, *, relative_to_cwd=False) -> BlockPack

파일로부터 블록팩(blockpack)을 읽어옵니다.

인자:

filename: 절대 경로가 아닌 경우 minescript/blockpacks 디렉터리를 기준으로 한 파일 이름 (파일 이름이 해당 확장자로 끝나지 않으면 “.zip”이 자동으로 추가됩니다)
relative_to_cwd: True이면 상대 파일 이름을 Minecraft 디렉터리 기준으로 간주합니다

반환:

파일에서 읽은 블록을 담은 새 BlockPack

BlockPack.import_data

사용법: @classmethod BlockPack.import_data(base64_data: str) -> BlockPack

base64로 인코딩된 직렬화 블록팩(blockpack) 데이터로부터 블록팩을 생성합니다.

인자:

base64_data: 블록팩 데이터의 직렬화를 담은 base64 인코딩 문자열.

반환:

base64 인코딩 데이터로부터 읽은 블록을 담은 새 BlockPack

BlockPack.block_bounds

사용법: BlockPack.block_bounds() -> (BlockPos, BlockPos)

이 BlockPack에 있는 블록(block)의 최소 및 최대 경계 좌표를 반환합니다.

BlockPack.comments

사용법: BlockPack.comments() -> Dict[str, str]

이 BlockPack에 저장된 주석을 반환합니다.

BlockPack.write_world

사용법: BlockPack.write_world(*, rotation: Rotation = None, offset: BlockPos = None)

이 BlockPack의 블록(block)을 현재 월드(world)에 씁니다. setblock, fill 명령이 필요합니다.

인자:

rotation: 월드에 쓰기 전 블록 좌표에 적용할 회전 행렬
offset: 블록 좌표에 적용할 오프셋(회전 적용 후 적용됨)

BlockPack.write_file

사용법: BlockPack.write_file(filename: str, *, relative_to_cwd=False)

이 BlockPack을 파일에 씁니다.

인자:

filename: 절대 경로가 아닌 경우 minescript/blockpacks 디렉터리를 기준으로 한 파일 이름 (파일 이름이 해당 확장자로 끝나지 않으면 “.zip”이 자동으로 추가됩니다)
relative_to_cwd: True이면 상대 파일 이름을 Minecraft 디렉터리 기준으로 간주합니다

BlockPack.export_data

사용법: BlockPack.export_data() -> str

이 BlockPack을 base64 인코딩 문자열로 직렬화합니다.

반환:

이 블록팩(blockpack)의 데이터를 담은 base64 인코딩 문자열

BlockPack.visit_blocks

사용법: BlockPack.visit_blocks(setblock: Callable[[int, int, int, str], None], fill: Callable[[int, int, int, int, int, int, str], None]) -> None

이 BlockPack의 모든 블록(block)을 방문하도록 주어진 콜백(callback)을 호출합니다.

인자:

setblock: 같은 타입의 다른 블록과 인접하지 않은 각 블록에 대해 다음과 같이 호출합니다 setblock(x, y, z, block)
fill: 같은 타입의 블록으로 이루어져 있고 1x1x1보다 큰, 축 정렬 바운딩 박스(axis-aligned bounding box, aabb)마다 서로 마주보는 모서리 (x1, y1, z1)와 (x2, y2, z2) 사이에 대해 다음과 같이 호출합니다 fill(x1, y1, z1, x2, y2, z2, block)

호환성: Pyjinn 전용.

BlockPack.del

사용법: del blockpack

이 BlockPack을 가비지 컬렉션(garbage collection) 대상으로 해제합니다.

BlockPackerException

BlockPack 작업이 실패했을 때 발생하는 예외(exception)입니다.

BlockPacker

BlockPacker는 블록으로 이루어진 가변(mutable) 컬렉션(collection)입니다.

블록은 setblock(...), fill(...), 그리고/또는 add_blockpack(...)를 호출하여 블록패커(blockpacker)에 추가할 수 있습니다. 블록을 직렬화(serialize)하거나 월드에 쓰려면, pack()을 호출하여 블록패커에 담긴 블록의 압축된 스냅샷(snapshot)을 새로운 BlockPack 형태로 생성함으로써 블록패커를 “패킹(pack)”할 수 있습니다. 블록패커는 패킹된 후에도 이전과 동일한 블록을 계속 저장하며, 이후에 블록을 추가로 더 넣을 수 있습니다.

불변(immutable)이고 직렬화 가능한 블록 컬렉션이 필요하다면 BlockPack을 참고하세요.

도입 버전: v3.0

BlockPacker.init

사용법: BlockPacker()

새로운 빈 블록패커를 생성합니다.

BlockPacker.setblock

사용법: BlockPacker.setblock(pos: BlockPos, block_type: str)

이 BlockPacker 내에 블록을 설정합니다.

인자:

pos: 설정할 블록의 위치
block_type: 설정할 블록 서술자(descriptor)

예외:

블록패커 작업이 실패하면 BlockPackerException

BlockPacker.fill

사용법: BlockPacker.fill(pos1: BlockPos, pos2: BlockPos, block_type: str)

이 BlockPacker 내에 블록을 채웁니다.

인자:

pos1, pos2: 채울 직육면체(rectangular volume) 영역의 마주보는 모서리 좌표
block_type: 채울 블록 서술자

예외:

블록패커 작업이 실패하면 BlockPackerException

BlockPacker.add_blockpack

사용법: BlockPacker.add_blockpack(blockpack: BlockPack, *, rotation: Rotation = None, offset: BlockPos = None)

BlockPack 내의 블록을 이 BlockPacker에 추가합니다.

인자:

blockpack: 블록을 복사해 올 BlockPack
rotation: 블록패커에 추가하기 전 블록 좌표에 적용할 회전 행렬(rotation matrix)
offset: 블록 좌표에 적용할 오프셋(offset)(회전 적용 후 적용됨)

BlockPacker.pack

사용법: BlockPacker.pack(*, comments: Dict[str, str] = {}) -> BlockPack

이 BlockPacker 내의 블록을 새로운 BlockPack으로 패킹합니다.

인자:

comments: 새로운 BlockPack에 포함할 키-값 쌍

반환:

이 BlockPacker에 있는 블록의 스냅샷을 담은 새로운 BlockPack

BlockPacker.del

사용법: del blockpacker

이 BlockPacker를 가비지 컬렉션 대상으로 해제합니다.

java_class

사용법: java_class(name: str) -> JavaHandle

정규화된 이름(fully qualified name)으로 Java 클래스(class)를 조회합니다. Java 클래스 객체(object)에 대한 핸들(handle)을 반환합니다.

예시: java_class("net.minescript.common.Minescript")

난독화(obfuscation)되지 않은 Java 심볼(symbol)로 Minecraft를 실행하는 경우: java_class("net.minecraft.client.Minecraft")

난독화된 심볼로 Minecraft를 실행하는 경우, name은 정규화되고 난독화된 클래스 이름이어야 합니다.

호환성: Python 전용.

도입 버전: v4.0

java_string

사용법: java_string(s: str) -> JavaHandle

Java String에 대한 핸들을 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_double

사용법: java_double(d: float) -> JavaHandle

Java Double에 대한 핸들을 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_float

사용법: java_float(f: float) -> JavaHandle

Java Float에 대한 핸들을 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_long

사용법: java_long(l: int) -> JavaHandle

Java Long에 대한 핸들을 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_int

사용법: java_int(i: int) -> JavaHandle

Java Integer에 대한 핸들을 반환합니다

호환성: Python 전용.

도입 버전: v4.0

java_bool

사용법: java_bool(b: bool) -> JavaHandle

Java Boolean에 대한 핸들을 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_ctor

사용법: java_ctor(clazz: JavaHandle)

주어진 클래스 핸들에 대한 생성자(constructor) 집합의 핸들을 반환합니다.

인자:

clazz: java_class에서 반환된 Java 클래스 핸들

호환성: Python 전용.

도입 버전: v4.0

java_new_instance

사용법: java_new_instance(ctor: JavaHandle, *args: List[JavaHandle]) -> JavaHandle

새로운 Java 인스턴스(instance)를 생성합니다.

인자:

ctor: java_ctor에서 반환된 생성자 집합
args: 생성자 매개변수(parameter)로 전달할 Java 객체의 핸들

반환:

새로 생성된 Java 객체의 핸들.

호환성: Python 전용.

도입 버전: v4.0

java_member

사용법: java_member(clazz: JavaHandle, name: str) -> JavaHandle

name과 일치하는 Java 멤버(member)를 가져옵니다.

인자:

clazz: 멤버를 조회할 대상인, java_class에서 반환된 Java 클래스 핸들
name: clazz 내에서 조회할 멤버의 이름

반환:

java_access_field 또는 java_call_method와 함께 사용할 Java 멤버 객체입니다.

호환성: Python 전용.

도입 버전: v4.0

java_access_field

사용법: java_access_field(target: JavaHandle, field: JavaHandle) -> Union[JavaHandle, None]

대상 Java 객체의 필드(field)에 접근합니다.

인자:

target: 필드에 접근할 대상 Java 객체 핸들
field: java_member에서 반환된 핸들

반환:

필드 접근으로 반환된 Java 객체의 핸들, null이면 None입니다.

호환성: Python 전용.

도입 버전: v4.0

java_call_method

사용법: java_call_method(target: JavaHandle, method: JavaHandle, *args: List[JavaHandle]) -> Union[JavaHandle, None]

대상 Java 객체의 메서드(method)를 호출합니다.

인자:

target: 메서드를 호출할 대상 Java 객체 핸들
method: java_member에서 반환된 핸들
args: 메서드 매개변수로 전달할 Java 객체의 핸들

반환:

메서드 호출로 반환된 Java 객체의 핸들, null이면 None입니다.

호환성: Python 전용.

도입 버전: v4.0

java_call_script_function

사용법: java_call_script_function(func_name: Union[str, JavaHandle], *args: List[JavaHandle]) -> JavaHandle

요청된 스크립트(script) 함수를 Java 매개변수로 호출합니다.

인자:

func_name: 스크립트 함수의 이름으로, Python str 또는 Java String에 대한 핸들입니다
args: 스크립트 함수에 인자(argument)로 전달할 Java 객체의 핸들

반환:

스크립트 함수에서 반환된 Java 객체(Optional<JsonElement>)의 핸들입니다.

호환성: Python 전용.

도입 버전: v4.0

java_array_length

사용법: java_array_length(array: JavaHandle) -> int

Java 배열(array)의 길이를 Python 정수(integer)로 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_array_index

사용법: java_array_index(array: JavaHandle, i: int) -> Union[JavaHandle, None]

Java 배열 핸들에서 인덱스(index)로 요소(element)를 가져옵니다.

인자:

array: Java 배열 객체의 핸들
i: 배열 내 인덱스

반환:

Java에서 array[i] 위치에 있는 객체의 핸들, null이면 None입니다.

호환성: Python 전용.

도입 버전: v4.0

java_new_array

사용법: java_new_array(element_type: JavaHandle, *elements: List[JavaHandle]) -> JavaHandle

주어진 요소 타입(element type)과 요소들로 새로운 Java 배열을 생성합니다.

인자:

element_type: 새 배열의 타입(type)으로 사용할 Java 클래스(Class<?>) 핸들
elements: 새 배열을 채울 Java 객체의 핸들

반환:

새 Java 배열의 핸들.

호환성: Python 전용.

도입 버전: v5.0

java_to_string

사용법: java_to_string(target: JavaHandle) -> str

Java에서 target.toString()을 호출하여 얻은 Python 문자열을 반환합니다.

호환성: Python 전용.

도입 버전: v4.0

java_assign

사용법: java_assign(dest: JavaHandle, source: JavaHandle)

dest를 source가 참조하는 객체를 참조하도록 재할당합니다.

성공하면 dest와 source 모두 처음에 source가 참조하던 동일한 Java 객체를 참조합니다.

호환성: Python 전용.

도입 버전: v4.0

java_field_names

사용법: java_field_names(clazz: JavaHandle) -> List[str]

핸들 clazz가 참조하는 클래스의 필드 이름 목록을 반환합니다.

매핑(mapping)이 설치되어 있으면 공식 필드 이름이 반환됩니다.

호환성: Python 전용.

도입 버전: v5.0

java_method_names

사용법: java_method_names(clazz: JavaHandle) -> List[str]

핸들 clazz가 참조하는 클래스의 메서드 이름 목록을 반환합니다.

매핑이 설치되어 있으면 공식 메서드 이름이 반환됩니다.

호환성: Python 전용.

도입 버전: v5.0

java_release

사용법: java_release(*targets: List[JavaHandle])

targets가 참조하는 Java 참조(reference)를 해제합니다.

호환성: Python 전용.

도입 버전: v4.0

JavaClass

사용법: JavaClass(class_name: str) -> JavaHandle

정규화된 이름(fully qualified name)이 주어지면 Java 클래스를 반환하는 Pyjinn 내장(built-in) 함수입니다.

호환성: Pyjinn 전용. (java.py를 통해 Python에서도 지원됩니다.)

JavaArray

사용법: JavaArray(pyjinn_tuple, element_type: JavaHandle = None) -> JavaHandle

Pyjinn 튜플과 선택적 요소 타입을 받아 Java 배열을 반환하는 Pyjinn 내장 함수입니다.

호환성: Pyjinn 전용.

JavaFloat

사용법: JavaFloat(number) -> JavaHandle

java.lang.Float 생성자(constructor)를 호출하는 Pyjinn 내장 함수입니다.

호환성: Pyjinn 전용.

JavaInt

사용법: JavaInt(number) -> JavaHandle

java.lang.Integer 생성자를 호출하는 Pyjinn 내장 함수입니다.

호환성: Pyjinn 전용.

JavaList

사용법: JavaList(pyjinn_list) -> JavaHandle

주어진 Pyjinn 리스트를 나타내는 Java List를 반환하는 Pyjinn 내장 함수입니다.

호환성: Pyjinn 전용.

JavaMap

사용법: JavaMap(pyjinn_list) -> JavaHandle

주어진 Pyjinn 딕셔너리를 나타내는 Java Map을 반환하는 Pyjinn 내장 함수입니다.

호환성: Pyjinn 전용.

JavaString

사용법: JavaString(pyjinn_str) -> JavaHandle

주어진 Pyjinn 문자열에 대해 Java String API를 노출하는 Pyjinn 내장 함수입니다.

호환성: Pyjinn 전용.

add_event_listener

사용법: add_event_listener(event_type: str, callback: Callable[[Any], None], **args) -> int

주어진 콜백(callback)과 인자로 이벤트 리스너(event listener)를 추가합니다.

지원되는 이벤트 유형(event type):

"add_entity" – AddEntityEvent
"block_update" – BlockUpdateEvent
"chat" – ChatEvent
"chunk" – ChunkEvent
"clientbound_packet" – ClientboundPacketEvent
"damage" – DamageEvent
"explosion" – ExplosionEvent
"key" – KeyEvent
"mouse" – MouseEvent
"outgoing_chat_intercept" – ChatEvent
"render" – RenderEvent
"serverbound_packet" – ServerboundPacketEvent
"take_item" – TakeItemEvent
"tick" – TickEvent
"world" – WorldEvent

호환성: Pyjinn 전용. (Python 이벤트 처리에 대해서는 EventQueue를 참고하세요.)

remove_event_listener

사용법: remove_event_listener(listener_id: int) -> bool

add_event_listener()로 이전에 추가한 이벤트 리스너를 제거합니다.

호환성: Pyjinn 전용.

ClientboundPacketEvent

  type: str
  listener: JavaClass("net.minecraft.client.multiplayer.ClientPacketListener")
  packet: JavaClass("net.minecraft.network.protocol.Packet")
  time: float

ServerboundPacketEvent

  type: str
  connection: JavaClass("net.minecraft.network.Connection")
  packet: JavaClass("net.minecraft.network.protocol.Packet")
  listener: JavaClass("io.netty.channel.ChannelFutureListener")
  flush: bool  # 패킷을 즉시 플러시(flush)할지 여부
  time: float

RenderEvent

add_event_listener()의 콜백과 함께 사용하는 렌더링(rendering) 이벤트입니다.

호환성: Pyjinn 전용.

  type: str  # "render"
  context: Any  # 모드 로더(mod loader)가 제공하는 렌더링 컨텍스트(context).
  time: float

TickEvent

add_event_listener()의 콜백과 함께 사용하는 틱(tick) 이벤트입니다.

호환성: Pyjinn 전용.

  type: str  # "tick"
  time: float

set_timeout

사용법: set_timeout(callback: Callable[..., None], timer_millis: int, *args, **kwargs) -> int

timer_millis 밀리초(millisecond) 후에 callback을 한 번 호출하도록 예약합니다.

반환: remove_event_listener()로 취소할 수 있는 콜백용 정수 ID입니다.

호환성: Pyjinn 전용.

set_interval

사용법: set_interval(callback: Callable[..., None], timer_millis: int, *args, **kwargs) -> int

timer_millis 밀리초마다 callback을 호출하도록 예약합니다.

반환: remove_event_listener()로 취소할 수 있는 콜백용 정수 ID입니다.

호환성: Pyjinn 전용.

ManagedCallback

Java API에 전달되는 콜백을 관리하기 위한 래퍼(wrapper)입니다.

예시:

“` callback = ManagedCallback(on_hud_render) HudRenderCallback.EVENT.register(HudRenderCallback(callback))

# 1초(1000밀리초) 후 취소합니다: set_timeout(callback.cancel, 1000) “`

호환성: Pyjinn 전용.

ManagedCallback.init

사용법: ManagedCallback(callback, cancel_on_exception=True, default_value=None)

관리형 콜백(managed callback)을 생성합니다.

인자: – callback: 관리할 호출 가능한(callable) 함수 또는 객체 – cancel_on_exception: 콜백이 예외를 발생시키면 해당 콜백을 취소합니다 – default_value: 취소된 후에도 콜백이 호출될 경우 즉시 반환할 값

ManagedCallback.cancel

사용법: ManagedCallback.cancel()

콜백을 취소하며, 이후에도 계속 호출되면 default_value를 반환합니다.

ManagedCallback.call

사용법: ManagedCallback.__call__(*args)

취소 여부를 확인한 후 이 콜백을 호출합니다.

EventLoop

이벤트에 반응할 수 있는 비동기(asynchronous) 코드를 실행하기 위한 이벤트 루프(event loop)입니다.

이벤트 루프를 사용하면 스크립트는 메인 스레드(main thread)를 차단하지 않고 async/await를 이용해 이벤트를 기다리거나 대기(sleep)할 수 있습니다.

호환성: Pyjinn 전용.

EventLoop.init

사용법: EventLoop()

새로운 EventLoop 인스턴스(instance)를 초기화합니다.

EventLoop.run

사용법: EventLoop.run(async_function)

이 이벤트 루프 내에서 비동기 함수를 실행합니다.

인자: – async_function: 이 EventLoop 인스턴스를 유일한 인자로 받아 코루틴(coroutine)을 반환하는 비동기 함수.

예외: RuntimeException: 이 이벤트 루프에서 run()이 이미 호출된 경우, 또는 async_function이 코루틴을 반환하지 않는 경우.

EventLoop.add_listener

사용법: EventLoop.add_listener(event_type: str)

지정한 이벤트 유형에 대한 리스너를 추가합니다.

인자: – event_type: 수신 대기할 이벤트의 유형(예: “chat”, “tick”, “render”).

반환: 리스너가 성공적으로 추가되면 True, 이 이벤트 유형에 대한 리스너가 이미 존재하면 False를 반환합니다.

EventLoop.remove_listener

사용법: EventLoop.remove_listener(event_type: str)

지정한 이벤트 유형에 대한 리스너를 제거합니다.

인자: – event_type: 리스너를 제거할 이벤트의 유형.

반환: 리스너가 성공적으로 제거되면 True, 이 이벤트 유형에 대한 리스너가 존재하지 않으면 False를 반환합니다.

EventLoop.sleep

사용법: EventLoop.sleep(seconds: float)

지정된 초(second) 동안 비동기적으로 대기(sleep)합니다.

대기하는 동안 발생하는 이벤트는 큐(queue)에 저장되며, 대기가 끝나면 리스트로 반환됩니다.

인자: – seconds: 대기할 시간(초).

반환: 대기하는 동안 발생한 이벤트의 리스트.

EventLoop.event

사용법: EventLoop.event(timeout_seconds: float = None)

다음 이벤트가 발생할 때까지 비동기적으로 대기합니다.

인자: – timeout_seconds: 이벤트를 기다릴 최대 시간(선택 사항)입니다.

반환: 발생한 이벤트를 반환하며, 제한 시간에 도달한 경우 None을 반환합니다.

Minescript v5.0 문서

인게임 명령

명령 기초

내장 명령

ls

help

eval

copy

paste

jobs

suspend

z

resume

killjob

undo

설정

Pyjinn

Python API

스크립트 입력

스크립트 출력

스크립트 출력 리다이렉션

스크립트 함수

비동기 스크립트 함수(Async script functions)

java 모듈

AutoReleasePool

AutoReleasePool.__call__

Float

JavaRef

JavaObject

JavaObject.__init__

JavaObject.toString

JavaObject.set_value

JavaObject.__getattr__

JavaObject.__len__

JavaObject.__bool__

JavaObject.__getitem__

JavaBoundMember

JavaBoundMember.__init__

JavaBoundMember.__call__

JavaInt

JavaFloat

JavaString

JavaClassType

JavaClassType.is_enum

JavaClassType.__getattr__

JavaClassType.__call__

callScriptFunction

JavaFuture

JavaFuture.wait

callAsyncScriptFunction

eval_pyjinn_script

import_pyjinn_script

minescript 모듈

BlockPos

Vector3f

MinescriptRuntimeOptions

execute

echo

echo_json

chat

log

screenshot

JobInfo

job_info

flush

player_name

player_position

ItemStack

HandItems

player_hand_items

player_inventory

player_inventory_slot_to_hotbar

player_inventory_select_slot

press_key_bind

player_press_forward

player_press_backward

player_press_left

player_press_right

player_press_jump

player_press_sprint

AutoReleasePool.call

JavaObject.init

JavaObject.getattr

JavaObject.len

JavaObject.bool

JavaObject.getitem

JavaBoundMember.init

JavaBoundMember.call

JavaClassType.getattr

JavaClassType.call

BlockRegion.init

EventQueue.init