Lua 腳本：Prop API

本頁涵蓋了 FreeMinecraftModels prop 腳本可用的所有 API：context.prop、context.event、context.world、context.zones、context.scheduler、context.state 和 context.log。如果您是 prop 腳本的新手，請先從入門指南開始。

`context.prop`

prop 表提供關於 prop 實體的資訊以及控制其動畫的方法。它在每次 hook 呼叫時重新建構。

欄位

欄位	類型	說明
`prop.model_id`	string	blueprint 模型名稱（例如 `"torch_01"`）
`prop.current_location`	location table	建構上下文時 prop 的位置

location 表具有標準欄位：x、y、z、world、yaw、pitch。

範例：讀取 prop 資訊

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Prop spawned: " .. (context.prop.model_id or "unknown"))
    local loc = context.prop.current_location
    if loc then
      context.log:info("Location: " .. loc.x .. ", " .. loc.y .. ", " .. loc.z)
    end
  end
}

`prop:play_animation(name, blend, loop)`

在 prop 模型上播放指定名稱的動畫。

參數	類型	預設值	說明
`name`	string	必填	模型檔案中定義的動畫名稱
`blend`	boolean	`true`	是否與目前動畫混合
`loop`	boolean	`true`	動畫是否循環播放

如果找到並啟動了動畫則回傳 true，否則回傳 false。

範例

return {
  api_version = 1,

  on_right_click = function(context)
    local success = context.prop:play_animation("open", true, false)
    if not success then
      context.log:warn("Animation 'open' not found on this model!")
    end
  end
}

`prop:stop_animation()`

停止 prop 上目前播放的所有動畫。

不接受任何參數。

範例

return {
  api_version = 1,

  on_right_click = function(context)
    context.prop:stop_animation()
  end
}

`context.event`

目前 hook 的事件資料。在 on_left_click、on_right_click 和 on_projectile_hit 中可用。在沒有關聯事件的 hook 中回傳 nil（on_spawn、on_game_tick、on_destroy、on_zone_enter、on_zone_leave）。

欄位和方法

欄位或方法	類型	說明
`event.is_cancelled`	boolean	事件目前是否已被取消
`event.cancel()`	function	取消事件（例如阻止傷害或互動）
`event.uncancel()`	function	撤銷之前取消的事件

資訊

並非所有事件都可以取消。如果底層 Bukkit 事件未實作 Cancellable，則 event.cancel() 和 event.uncancel() 不存在，event.is_cancelled 始終為 false。

範例：使 prop 無敵

範例

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event then
      context.event.cancel()
    end
  end
}

範例：檢查取消狀態

範例

return {
  api_version = 1,

  on_left_click = function(context)
    if context.event and not context.event.is_cancelled then
      context.event.cancel()
      context.log:info("Damage cancelled!")
    end
  end
}

警告

在排程的回呼中（scheduler:run_later、scheduler:run_repeating），context.event 始終為 nil。事件修改只能在事件 hook 本身中進行。

`context.world`

world 表提供查詢和與 Minecraft 世界互動的方法。它基於 prop 目前所在的世界建構。

共用 API

context.world API 與 EliteMobs 共用。FMM prop 使用與 EliteMobs Boss 相同的 Magmacore world 表。此處記載的方法是 Magmacore 基礎實作中可用的方法。完整參考請查看 EliteMobs World & Environment 頁面——其中列出的作為核心 context.world API 一部分的方法在 FMM 中同樣可用。

`world.name`

包含世界名稱的 string 欄位。

`world:get_block_at(x, y, z)`

回傳給定座標處方塊的材質名稱，為小寫字串（例如 "stone"、"air"）。

參數	類型	說明
`x`	int	方塊 X 座標
`y`	int	方塊 Y 座標
`z`	int	方塊 Z 座標

範例

return {
  api_version = 1,

  on_spawn = function(context)
    local loc = context.prop.current_location
    if loc then
      local block = context.world:get_block_at(
        math.floor(loc.x),
        math.floor(loc.y) - 1,
        math.floor(loc.z)
      )
      context.log:info("Prop is standing on: " .. block)
    end
  end
}

`world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)`

在指定位置生成粒子。

參數	類型	預設值	說明
`particle`	string	必填	Bukkit Particle 列舉名稱，大寫（例如 `"FLAME"`、`"DUST"`）
`x`	number	必填	X 座標
`y`	number	必填	Y 座標
`z`	number	必填	Z 座標
`count`	int	`1`	粒子數量
`dx`	number	`0`	X 擴散/偏移
`dy`	number	`0`	Y 擴散/偏移
`dz`	number	`0`	Z 擴散/偏移
`speed`	number	`0`	粒子速度

範例

return {
  api_version = 1,

  on_right_click = function(context)
    local loc = context.prop.current_location
    if loc then
      context.world:spawn_particle("HEART", loc.x, loc.y + 1, loc.z, 5, 0.3, 0.3, 0.3, 0)
    end
  end
}

`world:play_sound(sound, x, y, z, volume, pitch)`

在指定位置播放聲音。

參數	類型	預設值	說明
`sound`	string	必填	Bukkit Sound 列舉名稱，大寫（例如 `"ENTITY_EXPERIENCE_ORB_PICKUP"`）
`x`	number	必填	X 座標
`y`	number	必填	Y 座標
`z`	number	必填	Z 座標
`volume`	number	`1.0`	音量
`pitch`	number	`1.0`	音調

範例

return {
  api_version = 1,

  on_right_click = function(context)
    local loc = context.prop.current_location
    if loc then
      context.world:play_sound("BLOCK_NOTE_BLOCK_PLING", loc.x, loc.y, loc.z, 1.0, 1.2)
    end
  end
}

`world:strike_lightning(x, y, z)`

在指定位置劈下閃電（視覺效果並造成傷害）。

參數	類型	說明
`x`	number	X 座標
`y`	number	Y 座標
`z`	number	Z 座標

範例

return {
  api_version = 1,

  on_projectile_hit = function(context)
    local loc = context.prop.current_location
    if loc then
      context.world:strike_lightning(loc.x, loc.y, loc.z)
    end
  end
}

`world:get_time()`

回傳目前世界時間（以 tick 為單位）。

`world:set_time(ticks)`

設定世界時間。

參數	類型	說明
`ticks`	int	世界時間（0 = 黎明，6000 = 正午，13000 = 夜晚，18000 = 午夜）

`world:get_nearby_entities(x, y, z, radius)`

回傳以給定座標為中心的邊界框內所有存活實體的實體包裝表陣列。

參數	類型	說明
`x`	number	中心 X
`y`	number	中心 Y
`z`	number	中心 Z
`radius`	number	搜尋半徑（在三個軸上均用作半範圍）

範例

return {
  api_version = 1,

  on_right_click = function(context)
    local loc = context.prop.current_location
    if loc then
      local entities = context.world:get_nearby_entities(loc.x, loc.y, loc.z, 10)
      context.log:info("Found " .. #entities .. " entities nearby")
    end
  end
}

`world:get_nearby_players(x, y, z, radius)`

回傳以給定座標為中心的邊界框內所有玩家的玩家包裝表陣列。

參數	類型	說明
`x`	number	中心 X
`y`	number	中心 Y
`z`	number	中心 Z
`radius`	number	搜尋半徑

範例

return {
  api_version = 1,

  on_right_click = function(context)
    local loc = context.prop.current_location
    if loc then
      local players = context.world:get_nearby_players(loc.x, loc.y, loc.z, 20)
      for i = 1, #players do
        context.log:info("Nearby player: " .. (players[i].name or "unknown"))
      end
    end
  end
}

`context.zones`

zones 表允許您建立空間區域並監視玩家進入/離開事件。區域繫結到腳本實例，並在 prop 被移除時自動清理。

`zones:create_sphere(x, y, z, radius)`

在給定座標處建立球形區域。回傳一個數字區域控制代碼。

參數	類型	說明
`x`	number	中心 X
`y`	number	中心 Y
`z`	number	中心 Z
`radius`	number	球體半徑

`zones:create_cylinder(x, y, z, radius, height)`

建立圓柱形區域。回傳一個數字區域控制代碼。

參數	類型	說明
`x`	number	中心 X
`y`	number	中心 Y（底部）
`z`	number	中心 Z
`radius`	number	圓柱半徑
`height`	number	圓柱高度

`zones:create_cuboid(x, y, z, xSize, ySize, zSize)`

建立長方體區域。回傳一個數字區域控制代碼。

參數	類型	說明
`x`	number	中心 X
`y`	number	中心 Y
`z`	number	中心 Z
`xSize`	number	X 方向半範圍
`ySize`	number	Y 方向半範圍
`zSize`	number	Z 方向半範圍

`zones:watch(handle, onEnterCallback, onLeaveCallback)`

開始監視區域的玩家進入/離開事件。當玩家進入或離開區域時，相應的 hook 會觸發（on_zone_enter 或 on_zone_leave）。

參數	類型	說明
`handle`	int	來自 `create_*` 呼叫的區域控制代碼
`onEnterCallback`	function 或 nil	當玩家進入區域時呼叫
`onLeaveCallback`	function 或 nil	當玩家離開區域時呼叫

如果監視設定成功則回傳 true，如果區域控制代碼無效則回傳 nil。

資訊

區域監視在每個伺服器 tick 對同一世界中的所有玩家進行檢查。請保持合理的區域數量以避免效能開銷。

`zones:unwatch(handle)`

停止監視區域並清理其資源。

參數	類型	說明
`handle`	int	要停止監視的區域控制代碼

範例：近距離觸發區域

範例

return {
  api_version = 1,

  on_spawn = function(context)
    local loc = context.prop.current_location
    if loc == nil then return end

    -- Create a sphere zone around the prop
    local handle = context.zones:create_sphere(loc.x, loc.y, loc.z, 5)

    -- Watch for player enter/leave
    context.zones:watch(
      handle,
      function(player)
        context.log:info("Player entered zone!")
      end,
      function(player)
        context.log:info("Player left zone!")
      end
    )

    -- Store handle so we can clean up later if needed
    context.state.zone_handle = handle
  end,

  on_destroy = function(context)
    if context.state.zone_handle then
      context.zones:unwatch(context.state.zone_handle)
    end
  end
}

`context.scheduler`

scheduler 允許您執行延遲和重複任務。所有任務歸腳本實例所有，並在 prop 被移除時自動取消。

`scheduler:run_later(ticks, callback)`

延遲後執行一次回呼。回傳一個數字任務 ID。

參數	類型	說明
`ticks`	int	以伺服器 tick 為單位的延遲（20 tick = 1 秒）
`callback`	function	延遲到期時以新的 `context` 呼叫

範例

return {
  api_version = 1,

  on_right_click = function(context)
    context.log:info("Something will happen in 2 seconds...")

    context.scheduler:run_later(40, function(delayed_context)
      local loc = delayed_context.prop.current_location
      if loc then
        delayed_context.world:spawn_particle("EXPLOSION_EMITTER", loc.x, loc.y, loc.z, 1)
      end
    end)
  end
}

`scheduler:run_repeating(delay, interval, callback)`

以固定間隔重複執行回呼。回傳一個數字任務 ID。

參數	類型	說明
`delay`	int	第一次執行前的初始延遲（tick）
`interval`	int	每次後續執行之間的 tick 數
`callback`	function	每個間隔以新的 `context` 呼叫

範例

return {
  api_version = 1,

  on_spawn = function(context)
    -- Emit particles every second
    context.state.particle_task = context.scheduler:run_repeating(0, 20, function(tick_context)
      local loc = tick_context.prop.current_location
      if loc then
        tick_context.world:spawn_particle("FLAME", loc.x, loc.y + 1, loc.z, 3, 0.1, 0.1, 0.1, 0.02)
      end
    end)
  end,

  on_destroy = function(context)
    if context.state.particle_task then
      context.scheduler:cancel(context.state.particle_task)
    end
  end
}

`scheduler:cancel(taskId)`

透過 ID 取消已排程的任務。

參數	類型	說明
`taskId`	int	`run_later` 或 `run_repeating` 回傳的任務 ID

務必取消重複任務

如果您啟動了重複任務，務必在 on_destroy 中（或不再需要時）取消它。忘記取消會導致背景任務一直執行直到 prop 從伺服器移除，浪費效能並可能導致錯誤。

`context.state`

一個在 prop 整個生命週期內持久化的普通 Lua 表。用於儲存旗標、計數器、任務 ID、切換狀態以及需要在 hook 之間共用的任何資料。

on_spawn = function(context)
  context.state.is_open = false
  context.state.click_count = 0
  context.state.task_id = nil
end,

on_right_click = function(context)
  context.state.click_count = (context.state.click_count or 0) + 1
end

資訊

只有 context.state 在 hook 呼叫之間持久化。所有其他上下文表（context.prop、context.world、context.event 等）每次都會重新建構。

`context.log`

主控台日誌方法。訊息在伺服器主控台中以腳本檔案名稱為前綴。

方法	說明
`log:info(message)`	資訊訊息
`log:warn(message)`	警告訊息
`log:error(message)`	錯誤訊息（功能上與 warn 相同）

範例

return {
  api_version = 1,

  on_spawn = function(context)
    context.log:info("Script loaded!")
  end,

  on_right_click = function(context)
    context.log:warn("Prop was clicked -- this is a debug warning")
  end
}

執行階段模型

每個 prop 一個執行階段

每個附加了腳本的 prop 實體都會取得自己獨立的 Lua 執行階段實例。當 prop 生成時，FMM 載入 Lua 原始碼，在新的沙盒環境中執行，並儲存回傳的表。當 prop 被移除時，執行階段會關閉。

這意味著：

在檔案作用域宣告的區域變數對該 prop 實例是私有的。
context.state 在 prop 實例之間完全隔離，即使它們共用相同的腳本檔案。

任務擁有權

透過 context.scheduler 建立的所有任務歸建立它們的執行階段所有。當 prop 被移除時：

執行階段關閉。
所有擁有的任務——無論是一次性的還是重複的——都會自動取消。
所有區域監視都會被清除。

執行預算

每次 hook 呼叫和每次回呼呼叫都會計時。如果單次呼叫超過 50 毫秒，腳本將被停用並在主控台顯示警告：

[Lua] my_script.lua took 73ms in 'on_game_tick' (limit: 50ms) -- script disabled to prevent lag.

為了保持在預算內：

避免在 hook 中使用無限迴圈。
保持 on_game_tick 處理程式輕量——它們每個 tick 都會執行。
使用 context.scheduler:run_repeating(...) 將工作分散到多個 tick 中。

後續步驟

範例與模式——附有詳細說明的完整 prop 腳本
疑難排解——常見問題、除錯技巧和 QC 檢查清單
入門指南——檔案結構、hook、第一個腳本教學

context.prop​

欄位​

prop:play_animation(name, blend, loop)​

prop:stop_animation()​

context.event​

欄位和方法​

範例：使 prop 無敵​

範例：檢查取消狀態​

context.world​

world.name​

world:get_block_at(x, y, z)​

world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)​

world:play_sound(sound, x, y, z, volume, pitch)​

world:strike_lightning(x, y, z)​

world:get_time()​

world:set_time(ticks)​

world:get_nearby_entities(x, y, z, radius)​

world:get_nearby_players(x, y, z, radius)​

context.zones​

zones:create_sphere(x, y, z, radius)​

zones:create_cylinder(x, y, z, radius, height)​

zones:create_cuboid(x, y, z, xSize, ySize, zSize)​

zones:watch(handle, onEnterCallback, onLeaveCallback)​

zones:unwatch(handle)​

範例：近距離觸發區域​

context.scheduler​

scheduler:run_later(ticks, callback)​

scheduler:run_repeating(delay, interval, callback)​

scheduler:cancel(taskId)​

context.state​

context.log​

執行階段模型​

每個 prop 一個執行階段​

任務擁有權​

執行預算​

後續步驟​