music_quiz: 버튼 머리 hitbox 정확한 면 정합 + 라벨 text_display 자동 부착

오프셋 부호 정정 (v1.0.16 까지 모든 버전이 잘못된 convention 사용):
stone_button[face=wall, facing=X] AABB 는 facing X 쪽 face 에 붙어 안쪽
1/8 만 채움. 따라서 머리 hitbox center 는:
  south  z = 0.0625   (이전 -0.0625)
  north  z = 0.9375   (이전  1.0625)
  east   x = 0.0625   (이전 -0.0625)
  west   x = 0.9375   (이전  1.0625)

이전 부호는 머리 face 의 normal 방향 쪽으로 머리가 "튀어나온다" 라
가정했는데 실제로는 face 의 안쪽 1/8 로 들어가는 구조였음. 그 결과
v1.0.16 의 width=0.125 interaction 은 머리와 겹치지 않고 옆에 떠
있어 (touch only at edge) 클릭이 안 됨.

라벨 text_display 추가 (사용자 요청):
- button_defs 항목에 optional label, label_color, label_font, label_scale
  추가. 색 기본 black, 폰트 기본 minecraft:default, 크기 기본 1.0.
- handler 가 btn_prep 로 기본값 채운 뒤 btn 호출 — 매크로 인자 미존재
  에러 회피.
- btn 안에서 facing 별 위치/yaw 로 text_display 1개 summon. 같은 벽
  (button 머리 반대편 블록) 의 visible 면에 ~0.01 띄워 부착, y-1.
- background:0 (투명) 으로 벽에 직접 새긴 느낌.
- label 이 빈 문자열이면 summon 스킵.

commands/stop 에 stale text_display 정리도 추가 — 옛 정의 이름으로
남은 라벨이 reload 후에도 지워지지 않는 문제 방지.

music_quiz/data/mq/function/repeat/buttons/btn.mcfunction

@@ -1,72 +1,83 @@
 # 버튼 1개에 대한 매 tick 처리.
-# 매크로 인자(mq:tmp.btn): n, x, y, z, f, c
+# 매크로 인자(mq:tmp.btn): n, x, y, z, f, c, label, label_color, label_font, label_scale
 #   buttons 점수 상태:
 #     ..-2 : 비활성 (버튼 블록 제거, interaction 응답 차단)
-#     -1   : 초기화 단계 (버튼 블록 배치 + interaction entity 보장 후 0 으로)
+#     -1   : 초기화 단계 (버튼 블록 + interaction × 3 + text_display 보장 후 0)
 #     0    : 정상 (interaction 클릭 대기)
 #
-#   interaction entity 는 데이터팩이 직접 summon — /reload 시 commands/stop
-#   에서 buttons 가 -1 로 재설정되어 다음 tick 에 ensure 로직이 실행됨.
-#   -1 단계에서 같은 태그 entity 를 모두 kill 후 정확한 개수만 summon → dup
-#   누적 없이 항상 "버튼당 정확히 3개, 올바른 좌표" 상태로 수렴 (idempotent).
+#   interaction/text_display entity 는 데이터팩이 직접 summon — /reload 시
+#   commands/stop 에서 buttons 가 -1 로 재설정되어 다음 tick 에 ensure 로직
+#   실행. -1 단계에서 같은 태그 entity 를 모두 kill 후 정확한 개수만 다시
+#   summon → 항상 idempotent (dup 누적 없음, 좌표/라벨 갱신 자동 반영).
 #
-# ---- facing → 소환 오프셋 (이 파일 한 곳에서만 정의) ----
-# stone_button[face=wall] 머리 hitbox: 가로 6/16 (0.375), 세로 4/16 (0.25),
-# 두께 2/16 (0.125). interaction entity 의 horizontal hitbox 는 width × width
-# 정사각형 강제라 단일 entity 로는 "가로 0.375 × 두께 0.125" 직사각형이 불가.
-# → 두께(0.125) 만큼만 가지는 width=0.125 interaction 을 가로 방향 3개 타일
-# 링하여 버튼 머리에 정확히 정합 (가로 3 × 0.125 = 0.375, 두께 그대로 0.125).
+# ---- facing → 머리 hitbox 위치 (이 파일 한 곳에서만 정의) ----
+# stone_button[face=wall, facing=X] AABB (블록 상대 좌표):
+#   facing 의 의미 = "버튼 머리 visible 면의 normal 방향". 머리는 그 방향
+#   쪽 face 에 붙어 있고 hitbox 는 그 face 에서 안쪽(1/8) 만큼 들어감.
+#     south : z ∈ [0,    0.125]   가로 x ∈ [0.3125, 0.6875]
+#     north : z ∈ [0.875, 1]      가로 x ∈ [0.3125, 0.6875]
+#     east  : x ∈ [0,    0.125]   가로 z ∈ [0.3125, 0.6875]
+#     west  : x ∈ [0.875, 1]      가로 z ∈ [0.3125, 0.6875]
+#   세로 y ∈ [0.375, 0.625] 공통.
 #
-# facing 의미: "플레이어가 그 방향을 보면서 누른다" — 버튼 머리는 facing 의
-# 반대쪽 면에 붙어 있다. 머리 위치 (블록 상대 좌표):
-#   south : -z 면 (z=0)   → 깊이 z = -0.0625, 가로 x = 0.375 / 0.5 / 0.625
-#   north : +z 면 (z=1)   → 깊이 z =  1.0625, 가로 x = 0.375 / 0.5 / 0.625
-#   east  : -x 면 (x=0)   → 깊이 x = -0.0625, 가로 z = 0.375 / 0.5 / 0.625
-#   west  : +x 면 (x=1)   → 깊이 x =  1.0625, 가로 z = 0.375 / 0.5 / 0.625
-# 세로(y): 머리는 블록의 세로 중앙 (y+0.375 ~ y+0.625, 높이 0.25). interaction
-# Y 는 hitbox 바닥(=발 위치) → 소환 y = y+0.375, height=0.25.
+# interaction entity 의 horizontal hitbox 는 width × width 정사각형 강제라
+# 단일 entity 로는 "가로 0.375 × 두께 0.125" 직사각형 불가. → 두께(0.125)
+# 와 같은 width=0.125 인 interaction 을 가로축으로 3 개 타일링 (gap 없이
+# 인접: 중심 0.375 / 0.5 / 0.625, 각 폭 0.125 → 합 [0.3125, 0.6875]).
+# interaction Y 는 hitbox 바닥 → 소환 y = block y + 0.375, height = 0.25.
+#
+# ---- text_display 위치 (버튼 바로 아래 같은 벽면에 부착) ----
+# 같은 벽 (button 의 머리 normal 반대편 블록) 의 visible 면에 살짝 띄워
+# 부착. 텍스트 entity Y 는 텍스트 baseline 근방 → 아래 블록 바닥에 두면
+# 텍스트가 그 블록 안에 위로 솟아남.
+#   south : ~0.5  ~-1 ~0.01   yaw   0   (head 가 +z 방향 → 벽 +z=0.01 살짝 띄움)
+#   north : ~0.5  ~-1 ~0.99   yaw 180
+#   east  : ~0.01 ~-1 ~0.5    yaw -90
+#   west  : ~0.99 ~-1 ~0.5    yaw  90
 
 # ---- 비활성: 버튼 제거 + interaction 응답 차단 후 종료 ----
 $execute if score $(n) buttons matches ..-2 run setblock $(x) $(y) $(z) minecraft:air
 $execute if score $(n) buttons matches ..-2 run data modify entity @e[type=minecraft:interaction,tag=mq,tag=$(n)] response set value 0b
 $execute if score $(n) buttons matches ..-2 run return 0
 
-# ---- 초기화: 버튼 블록 배치 + interaction entity 보장 ----
-# 기존 mq/$(n) interaction 을 전부 제거 후 정확히 3개 소환.
-# 옛 월드 cmd block 으로 누적 소환된 dup 이나 엉뚱한 좌표에 남은 잔존
-# entity 까지 정리 → "정상 상태(버튼당 정확히 3개, 올바른 좌표)" 가 보장됨.
+# ---- 초기화: 블록 + interaction × 3 + text_display 보장 ----
 $execute unless score $(n) buttons matches -1.. run scoreboard players set $(n) buttons -1
 $execute if score $(n) buttons matches -1 run setblock $(x) $(y) $(z) minecraft:stone_button[face=wall,facing=$(f),powered=false]
 $execute if score $(n) buttons matches -1 run kill @e[type=minecraft:interaction,tag=mq,tag=$(n)]
+$execute if score $(n) buttons matches -1 run kill @e[type=minecraft:text_display,tag=mq,tag=$(n)]
 
-# south: 깊이축=z(-0.0625), 가로축=x, 3 타일
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.375 ~0.375 ~-0.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.5   ~0.375 ~-0.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.625 ~0.375 ~-0.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+# south: 깊이축=z(+0.0625), 가로축=x, 3 타일 + 라벨
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.375 ~0.375 ~0.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.5   ~0.375 ~0.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.625 ~0.375 ~0.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 unless data storage mq:tmp btn{label:""} if data storage mq:tmp btn{f:"south"} positioned $(x) $(y) $(z) run summon minecraft:text_display ~0.5 ~-1 ~0.01 {Tags:["mq","$(n)"],Rotation:[0f,0f],background:0,text:'{"text":"$(label)","color":"$(label_color)","font":"$(label_font)"}',transformation:{scale:[$(label_scale)f,$(label_scale)f,$(label_scale)f],translation:[0f,0f,0f],left_rotation:[0f,0f,0f,1f],right_rotation:[0f,0f,0f,1f]}}
 
-# north: 깊이축=z(+1.0625), 가로축=x, 3 타일
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.375 ~0.375 ~1.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.5   ~0.375 ~1.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.625 ~0.375 ~1.0625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+# north: 깊이축=z(+0.9375), 가로축=x, 3 타일 + 라벨
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.375 ~0.375 ~0.9375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.5   ~0.375 ~0.9375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.625 ~0.375 ~0.9375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 unless data storage mq:tmp btn{label:""} if data storage mq:tmp btn{f:"north"} positioned $(x) $(y) $(z) run summon minecraft:text_display ~0.5 ~-1 ~0.99 {Tags:["mq","$(n)"],Rotation:[180f,0f],background:0,text:'{"text":"$(label)","color":"$(label_color)","font":"$(label_font)"}',transformation:{scale:[$(label_scale)f,$(label_scale)f,$(label_scale)f],translation:[0f,0f,0f],left_rotation:[0f,0f,0f,1f],right_rotation:[0f,0f,0f,1f]}}
 
-# east: 깊이축=x(-0.0625), 가로축=z, 3 타일
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~-0.0625 ~0.375 ~0.375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~-0.0625 ~0.375 ~0.5   {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~-0.0625 ~0.375 ~0.625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+# east: 깊이축=x(+0.0625), 가로축=z, 3 타일 + 라벨
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.0625 ~0.375 ~0.375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.0625 ~0.375 ~0.5   {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.0625 ~0.375 ~0.625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 unless data storage mq:tmp btn{label:""} if data storage mq:tmp btn{f:"east"} positioned $(x) $(y) $(z) run summon minecraft:text_display ~0.01 ~-1 ~0.5 {Tags:["mq","$(n)"],Rotation:[-90f,0f],background:0,text:'{"text":"$(label)","color":"$(label_color)","font":"$(label_font)"}',transformation:{scale:[$(label_scale)f,$(label_scale)f,$(label_scale)f],translation:[0f,0f,0f],left_rotation:[0f,0f,0f,1f],right_rotation:[0f,0f,0f,1f]}}
 
-# west: 깊이축=x(+1.0625), 가로축=z, 3 타일
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~1.0625 ~0.375 ~0.375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~1.0625 ~0.375 ~0.5   {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
-$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~1.0625 ~0.375 ~0.625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+# west: 깊이축=x(+0.9375), 가로축=z, 3 타일 + 라벨
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.9375 ~0.375 ~0.375 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.9375 ~0.375 ~0.5   {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:interaction ~0.9375 ~0.375 ~0.625 {Tags:["mq","$(n)"],width:0.125f,height:0.25f,response:0b}
+$execute if score $(n) buttons matches -1 unless data storage mq:tmp btn{label:""} if data storage mq:tmp btn{f:"west"} positioned $(x) $(y) $(z) run summon minecraft:text_display ~0.99 ~-1 ~0.5 {Tags:["mq","$(n)"],Rotation:[90f,0f],background:0,text:'{"text":"$(label)","color":"$(label_color)","font":"$(label_font)"}',transformation:{scale:[$(label_scale)f,$(label_scale)f,$(label_scale)f],translation:[0f,0f,0f],left_rotation:[0f,0f,0f,1f],right_rotation:[0f,0f,0f,1f]}}
 
 $execute if score $(n) buttons matches -1 run scoreboard players set $(n) buttons 0
 
 # ---- 상시: interaction 클릭/타격 → playsound + 명령/투표 실행 ----
 # init main = 0 (퀴즈 시작 전 설정 단계) : 명령 직접 실행
 # 그 외                                  : trigger 투표 경로
-# 같은 태그를 가진 interaction 이 3개지만 `on target` 은 클릭된 1개만 통과
-# (나머지는 target 부재로 체인 중단). 따라서 selector 에 limit=1 두지 않음
-# — limit=1 을 두면 MC 가 임의로 1개를 골라 잘못된 entity 만 검사할 수 있음.
+# 한 버튼에 interaction 3개지만 `on target` 은 클릭된 1개만 통과
+# (나머지는 target 부재로 체인 중단). limit=1 을 두면 MC 가 임의로 1개를
+# 골라 잘못된 entity 만 검사하므로 limit 두지 않음.
 $execute as @e[type=minecraft:interaction,tag=mq,tag=$(n)] on target as @s positioned $(x) $(y) $(z) run playsound minecraft:block.stone_button.click_on block @s ~ ~ ~ 1 1
 $execute as @e[type=minecraft:interaction,tag=mq,tag=$(n)] on target as @s positioned $(x) $(y) $(z) if score init main matches 0 run $(c)
 $execute as @e[type=minecraft:interaction,tag=mq,tag=$(n)] on target as @s positioned $(x) $(y) $(z) unless score init main matches 0 run trigger $(n)

music_quiz/data/mq/function/repeat/buttons/btn_prep.mcfunction

@@ -0,0 +1,13 @@
+# 한 button entry 의 optional 필드 기본값을 채워 macro 호출 시 $(arg) 미존재
+# 에러를 방지한다. handler 에서 entry 복사 직후 호출.
+#
+# label        : 없으면 "" (빈 문자열) → btn 안의 text_display 분기는 label
+#                이 "" 이면 스킵.
+# label_color  : 기본 "black"
+# label_font   : 기본 "minecraft:default"
+# label_scale  : 기본 "1.0"  (Vector3f 의 한 축, 3축 동일하게 사용됨)
+
+execute unless data storage mq:tmp btn.label       run data modify storage mq:tmp btn.label       set value ""
+execute unless data storage mq:tmp btn.label_color run data modify storage mq:tmp btn.label_color set value "black"
+execute unless data storage mq:tmp btn.label_font  run data modify storage mq:tmp btn.label_font  set value "minecraft:default"
+execute unless data storage mq:tmp btn.label_scale run data modify storage mq:tmp btn.label_scale set value "1.0"

music_quiz/data/mq/function/repeat/buttons/handler.mcfunction

@@ -1,16 +1,27 @@
-# 각 button_defs 항목을 mq:tmp.btn 으로 복사 후 btn 호출.
-# btn 안에서 facing 별 분기 (if data storage mq:tmp btn{f:"..."}) 를
-# 사용하기 위해 현재 항목을 같은 storage 에 노출시킨다.
+# 각 button_defs 항목을 mq:tmp.btn 으로 복사 → optional 필드 기본값 채움
+# → btn 호출. btn 안에서 facing 별 분기 (if data storage mq:tmp btn{f:"..."})
+# 와 macro arg ($(label) 등) 둘 다 사용 가능하게 같은 storage 에 노출시킨다.
 
 data modify storage mq:tmp btn set from storage mq:main button_defs[0]
+function mq:repeat/buttons/btn_prep
 function mq:repeat/buttons/btn with storage mq:tmp btn
+
 data modify storage mq:tmp btn set from storage mq:main button_defs[1]
+function mq:repeat/buttons/btn_prep
 function mq:repeat/buttons/btn with storage mq:tmp btn
+
 data modify storage mq:tmp btn set from storage mq:main button_defs[2]
+function mq:repeat/buttons/btn_prep
 function mq:repeat/buttons/btn with storage mq:tmp btn
+
 data modify storage mq:tmp btn set from storage mq:main button_defs[3]
+function mq:repeat/buttons/btn_prep
 function mq:repeat/buttons/btn with storage mq:tmp btn
+
 data modify storage mq:tmp btn set from storage mq:main button_defs[4]
+function mq:repeat/buttons/btn_prep
 function mq:repeat/buttons/btn with storage mq:tmp btn
+
 data modify storage mq:tmp btn set from storage mq:main button_defs[5]
+function mq:repeat/buttons/btn_prep
 function mq:repeat/buttons/btn with storage mq:tmp btn