api

Ella Coat edited this page May 25, 2026 · 47 revisions

公開 API 一覧。api:namespace に集約されている。

共通の使い方
DamageAPI
HealAPI
MPAPI
ModifierAPI
Effect付与API
Mob API
神器API
Object API
Absorption (緩衝体力) API
データ取得API
PlayerVector API
LostItemsAPI
GlobalVars API
Button API

共通の使い方

全ての API 関数は以下の規約に従う。

引数を storage api: Argument.<Name> に set してから関数を呼ぶ。
関数を function api:<module>/<function> で実行 (実行者は as @s at @s で渡す)。
返り値は storage api: Return.<Name> か execute store result ... で取得。
関数側で引数は自動 remove される。ただし damage / heal / effect 系のように 複数対象への連続適用を想定して内部で自動 remove していないもの もある。これらは呼び出し側で reset 関数を呼ぶ責任があるよ (忘れると次の呼び出しに前回値が混ざってバグる)。

呼び出し例:

# 引数を set
 data modify storage api: Argument.Damage set value 10.0f
 data modify storage api: Argument.AttackType set value "Magic"
# 実行 (範囲5m以内のゾンビ全員にダメージ)
 execute as @e[type=zombie,distance=..5] run function api:damage/
# リセット
 function api:damage/reset

DamageAPI

実行者のエンティティにダメージを与えるよ。
実行者は Health を持つ Entity である必要がある。
特別な理由がない限り、ダメージ値が動的な場合は補正 function(api:damage/modifier)を実行してね。

引数

要求データ	必須	型	説明	デフォルト
実行者	o	Entity	ダメージを与える対象	-
Argument.Damage	o	float	与えるダメージ	-
Argument.AttackType	o	`"Physical"`/`"Magic"`	ダメージの第一属性	-
Argument.ElementType	×ばつ	`"None"`/`"Fire"`/`"Water"`/`"Thunder"`	ダメージの第二属性	`"None"`
Argument.FixedDamage	×ばつ	boolean	全ての補正・耐性を無視する (= 下記 6 つを一括 true)	false
Argument.BypassModifier	×ばつ	boolean	プレイヤー側の補正値を適用しないか否か	false
Argument.BypassArmorDefense	×ばつ	boolean	防具の防御値を無視するか否か	false
Argument.BypassToughness	×ばつ	boolean	防具強度を無視するか否か	false
Argument.BypassEnchantments	×ばつ	boolean	エンチャント耐性を無視するか否か	false
Argument.BypassResistance	×ばつ	boolean	耐性エフェクトを無視するか否か	false
Argument.BypassDifficulty	×ばつ	boolean	難易度補正を無視するか否か	false
Argument.ReduceEnchantment	×ばつ	enchID/{id,modifier}	protection 以外で軽減効果を持つエンチャントを追加で計算対象に組み込む (例: `"minecraft:fire_protection"` を指定すると火耐性エンチャが軽減計算に効く)	-
Argument.DeathMessage	×ばつ	TextComponent/TextComponent[]	通常の死亡メッセージと置き換えて出力するメッセージ (対象がプレイヤーの時のみ使用される)	-
Argument.AdditionalMPHeal	×ばつ	int	当てた時の MP 追加回復量 (神器の MPHealWhenHit で自動指定される)	0
Argument.DisableLog	×ばつ	boolean	ステータスログ表示を抑制	false
Argument.ApplyTrigger	×ばつ	boolean	神器の attack/damage トリガーを発火するか否か `false`にすると IsDoT 扱いになる	true
Argument.Metadata	×ばつ	any	神器・モブのトリガー処理に渡される自由データ	-

Note: 実装の都合上、 function api:damage/を呼び出しても Argument はリセットされないから、実行後にapi:damage/resetを呼んでね。

補正 function について

補正 function(api:damage/modifier)を実行することで、実行者 (= as で指定したエンティティ) の信仰補正等のダメージ補正値が Argument.Damage に適用されるよ。
通常はダメージを与える場合はこれを使用するんだけど、必ず決まったダメージを与えたい場合とかは実行者の補正値で値が変動するから使用しないようにしてね。
これを実行すると引数の Damage の値が変わるから、一回補正を掛けた後に異なる数値や属性のダメージを再度与える場合は Damage を再設定&補正 function を実行してね。

例

範囲 5M のゾンビに 7.5 の魔法・雷属性ダメージを与える

# 引数の設定
 data modify storage api: Argument.Damage set value 7.5f
 data modify storage api: Argument.AttackType set value "Magic"
 data modify storage api: Argument.ElementType set value "Thunder"
# 補正functionを実行
 function api:damage/modifier
# 範囲5m以内のゾンビを対象に
 execute as @e[type=zombie,distance=..5] run function api:damage/
# リセット
 function api:damage/reset

確定でダメージを与える (補正なし)

 data modify storage api: Argument.Damage set value 7.5f
 data modify storage api: Argument.AttackType set value "Magic"
 data modify storage api: Argument.ElementType set value "Thunder"
 data modify storage api: Argument.FixedDamage set value true
 execute as @e[type=zombie, distance=..5] run function api:damage/
 function api:damage/reset

DoT (継続ダメージ) 扱いで神器トリガーを発火させない

 data modify storage api: Argument.Damage set value 2.0f
 data modify storage api: Argument.AttackType set value "Magic"
 data modify storage api: Argument.ApplyTrigger set value false # ← これ
 execute as @s run function api:damage/
 function api:damage/reset

DeathMessage について

Argument.DeathMessageに TextComponent を指定することで、与えたダメージによってプレイヤーが死亡した際のメッセージを変更できるよ。

単体指定 : そのメッセージが死亡時に表示される
配列指定 : 複数のメッセージから死亡時にランダムで 1 つ選ばれる

同 tick 内に別の箇所等から同じプレイヤーに対して api:damage/ を実行した場合、死亡メッセージは上書きされる (上書きで未指定になる可能性を含む)。

TextComponent をダブルクォート "" で囲うとエスケープが必要になるため、シングルクォート '' で囲うのがおすすめ。

例: プレイヤー名と攻撃元の名前を埋め込む

死亡したプレイヤーの名前は{"selector":"@s"}で取得できる。攻撃元の Entity の名前は、攻撃元 Entity 探索実装が自動でセットするstorage lib: Return.AttackerNameから取得する。

 data modify storage api: Argument.Damage set value 12.0f
 data modify storage api: Argument.AttackType set value "Physical"
 data modify storage api: Argument.ElementType set value "Thunder"
 # %1$s = プレイヤー名、 %2$s = 攻撃元 Entity 名
 data modify storage api: Argument.DeathMessage append value '[{"translate":"%1$sは%2$sに串刺しにされた。","with":[{"selector":"@s"},{"nbt":"Return.AttackerName","storage":"lib:","interpret":true}]}]'
 function api:damage/modifier
 execute as @a[distance=..5] run function api:damage/
 function api:damage/reset

例: 死亡メッセージが 2 種 (プレイヤー名のみ、ランダム選択)

 data modify storage api: Argument.Damage set value 27.0f
 data modify storage api: Argument.AttackType set value "Physical"
 data modify storage api: Argument.ElementType set value "Water"
 data modify storage api: Argument.DeathMessage append value '[{"translate":"%1$sは大量の水に押し潰された。","with":[{"selector":"@s"}]}]'
 data modify storage api: Argument.DeathMessage append value '[{"translate":"%1$sは降ってきた大量の水に耐えられなかった。","with":[{"selector":"@s"}]}]'
 function api:damage/modifier
 execute as @p[distance=..5] run function api:damage/
 function api:damage/reset

HealAPI

実行者のエンティティを回復させるよ。
実行者は Health を持つ Entity である必要がある。
回復量が固定でない場合は、補正 function(api:heal/modifier)を実行してね。

引数

要求データ	必須	型	説明	デフォルト
実行者	o	Entity	回復を与える対象	-
Argument.Heal	o	float	回復する量	-
Argument.FixedHeal	×ばつ	boolean	補正を適用しないか否か	false
Argument.DisableLog	×ばつ	boolean	ステータスログ表示を抑制	false
Argument.ApplyTrigger	×ばつ	boolean	神器の heal/receive_heal トリガーを発火するか否か `false`にすると IsHoT 扱い	true
Argument.Metadata	×ばつ	any	神器のトリガー処理に渡される自由データ	-

注: 実装の都合上、 function api:heal/を呼び出しても Argument はリセットされないから、実行後に api:heal/reset を呼んでね。

使い方

範囲回復させたい場合

 data modify storage api: Argument.Heal set value 7.5f
 function api:heal/modifier
 execute as @a[distance=..5] run function api:heal/
 function api:heal/reset

HoT (継続回復) であるため、神器トリガーを発火させたくない場合

 data modify storage api: Argument.Heal set value 1.0f
 data modify storage api: Argument.ApplyTrigger set value false
 function api:heal/
 function api:heal/reset

MPAPI

対象プレイヤーの MP に関する処理。

MP 増減

任意の数値 MP を増減させるよ。

引数

要求データ	必須	型	説明
実行者	o	Player	MP を増減させるプレイヤー
Argument.Fluctuation	o	int	MP の増減量
Argument.DisableLog	×ばつ	boolean	ステータスログ表示を抑制

使い方

data modify storage api: Argument.Fluctuation set value 10
execute as <selector> run function api:mp/fluctuation

MP 設定

任意の数値 MP をその値に設定するよ。

引数

要求データ	必須	型	説明
実行者	o	Player	MP を設定するプレイヤー
Argument.Set	o	int	MP の設定値

使い方

data modify storage api: Argument.Set set value 50
execute as <selector> run function api:mp/set

MP チェック

指定した数値より現在 MP が多いか確認するよ。DevPrivilegeタグを持つプレイヤーは常に Return.IsThresholdOrMore: true を返す。

引数

要求データ	必須	型	説明
実行者	o	Player	MP をチェックする対象のプレイヤー
Argument.Threshold	o	int	MP のしきい値

返り値

データ	想定される値	型	説明
Return.IsThresholdOrMore	true/false	boolean	対象の MP がしきい値以上か否か

使い方

data modify storage api: Argument.Threshold set value 30
execute as <selector> run function api:mp/check
# 取り出し
execute if data storage api: Return{IsThresholdOrMore:true} run say MP足りてる

MP 取得

MP の現在値を取得するよ。

使い方

execute as <selector> store result score $Result Temporary run function api:mp/get_current

MP 最大値取得

MP の最大値を取得するよ。

使い方

execute as <selector> store result score $Result Temporary run function api:mp/get_max

MP 最大値更新

プレイヤーのEquipment.Modifiersや信仰補正を集計して MPMax スコアに反映する。神器の装備変化に合わせて自動で呼ばれるけど、ボーナス系の付与・解除時には手動で呼ぶ必要がある。

execute as <player> run function api:mp/update_max

ModifierAPI

プレイヤーの与/被ダメージや HP/MP 回復量に掛かる補正に対する API 。神器のEquipment.Modifiersはこの ModifierAPI の上に乗っかってる仕組み。

補正対象

Attack
- Base (attack/base)
- Physical (attack/physical)
- Magic (attack/magic)
- Fire (attack/fire)
- Water (attack/water)
- Thunder (attack/thunder)
Defense
- Base (defense/base)
- Physical (defense/physical)
- Magic (defense/magic)
- Fire (defense/fire)
- Water (defense/water)
- Thunder (defense/thunder)
Heal (heal)
Receive Heal (receive_heal)
MP Heal (mp_heal)
Max MP (max_mp)
Fall Resistance (fall_resistance)

補正の追加

指定したステータスに補正を追加するよ。

引数

要求データ	必須	型	説明
実行者	o	Player	補正を与える対象
Argument.UUID	o	int[4]	補正を後で削除する際の識別子
Argument.Amount	o	double	補正値
Argument.Operation	o	`"add"` / `"multiply_base"` / `"multiply"`	補正計算方法計算方法はGamepedia参照

使い方

function api:modifier/<補正対象>/add

例

# 引数の設定
 data modify storage api: Argument.UUID set value [I;1,1,0,0]
 data modify storage api: Argument.Amount set value 0.15
 data modify storage api: Argument.Operation set value "multiply_base"
# 補正の追加 (この場合与える物理ダメージが15%上昇する)
 function api:modifier/attack/physical/add

補正の削除

指定したステータスの指定された UUID の補正を削除するよ。

引数

要求データ	必須	型	説明
実行者	o	Player	補正を削除する対象
Argument.UUID	o	int[4]	補正追加時に指定した識別子

使い方

function api:modifier/<補正対象>/remove

例

 data modify storage api: Argument.UUID set value [I;1,1,0,0]
 function api:modifier/attack/physical/remove

補正値の取得

現在の補正値を取得するよ。

使い方

function api:modifier/<補正対象>/get
# Return.<対応するキー> に格納される

Effect 付与 API

EffectAsset の付与・解除を行う API 。詳細はエフェクトの作り方を参照。

重要 (reset): 複数対象に連続適用する想定 の give / remove/from_id / remove/from_level は内部で Argument を自動 remove しないので、呼び出し側で api:entity/mob/effect/reset を実行する責任がある。忘れると次の呼び出しに Duration / Stack / FieldOverride などの前回値が混ざってバグる。一方 get/* は内部で自動 remove するので reset 不要。

Effect 付与

data modify storage api: Argument.ID set value <EffectAssetのID>
data modify storage api: Argument.Duration set value <tick数> # オプション
data modify storage api: Argument.Stack set value <スタック数> # オプション
data modify storage api: Argument.DurationOperation set value "replace" # オプション
data modify storage api: Argument.StackOperation set value "replace" # オプション
data modify storage api: Argument.FieldOverride set value {...} # オプション
execute as <target> run function api:entity/mob/effect/give
function api:entity/mob/effect/reset # 必須

引数	必須	型	説明
Argument.ID	o	int	EffectAsset の ID
Argument.Duration	×ばつ	int	効果時間 (tick)。未指定なら register 値
Argument.Stack	×ばつ	int	付与するスタック数。未指定なら 1
Argument.DurationOperation	×ばつ	string	`"replace"` / `"add"` / `"forceReplace"`
Argument.StackOperation	×ばつ	string	同上
Argument.FieldOverride	×ばつ	compound	Field の上書き値

Effect 削除 (ID から)

data modify storage api: Argument.ID set value <EffectAssetのID>
execute as <target> run function api:entity/mob/effect/remove/from_id
function api:entity/mob/effect/reset # 必須

Effect 削除 (解除レベルから)

RequireClearLv が指定レベル以下の Effect をまとめて削除する。

data modify storage api: Argument.ClearLv set value 1 # 基本的に 1 or 2 で指定
execute as <target> run function api:entity/mob/effect/remove/from_level
function api:entity/mob/effect/reset # 必須

Effect 取得

get 系は内部で Argument を自動 remove するので、呼び出し側で reset を呼ぶ必要はないよ。

# 特定 ID の Effect 情報を取得
data modify storage api: Argument.ID set value <ID>
execute as <target> run function api:entity/mob/effect/get/from_id
# Return.Effect に格納される
# Bad_Effect の個数を取得
execute as <target> run function api:entity/mob/effect/get/size/bad
execute store result score $Bad Temporary run data get storage api: Return.EffectSize.Bad

Effect リセット

give / remove/from_id / remove/from_level を呼んだ後で実行する。これらは「1 回 set した Argument を複数対象に連続適用する」ことを想定しているので、内部で Argument を消さない設計になっている (= 呼ぶたびに自動 remove されると都度 set し直しになって非効率)。そのぶん最後に呼び出し側でリセットする責務を持つ。

function api:entity/mob/effect/reset

Argument.{ID, Duration, Stack, DurationOperation, StackOperation, FieldOverride, ClearLv, ClearType, ClearCount} をまとめて remove する。

Mob API

カスタム Mob の召喚・キル・体力操作。

Mob 召喚

指定した ID の MobAsset を召喚するよ。召喚先の座標と向きは実行者の位置・向きが基準になる。

data modify storage api: Argument.ID set value <MobAssetのID>
data modify storage api: Argument.PreInitInterceptFn set value "<関数名>" # オプション (init前に走るfunction)
execute at <pos> run function api:mob/core/summon

Mob 除去・キル

# remove (Remove トリガーを発火させる形式、主にボスとかに使うことが多い)
execute as <Mob> run function api:mob/remove
# kill (Death トリガーを発火させる形式)
execute as <Mob> run function api:mob/kill

MobHP 操作

# 増減
data modify storage api: Argument.Fluctuation set value -10.0d
execute as <Mob> run function api:mob/modify_health
# 取得
execute as <Mob> run function api:mob/get_health
# Return.Health に格納される

AssetMob かチェック

execute as <entity> run function api:mob/is_asset_mob
# Return.IsAssetMob に格納される

ダメージ転送

ForwardTargetMobUUIDスコアでペアリングした Mob へダメージを転送する。ボスの本体・分身パターンで便利。

execute as <Mob> run function api:mob/apply_to_forward_target/<...>

神器 API

詳細は神器の作り方を参照。

神器の付与

data modify storage api: Argument.ID set value <神器ID>
function api:artifact/give/from_id # 実行者のインベントリに入る

神器をワールドにドロップ

data modify storage api: Argument.ID set value <神器ID>
function api:artifact/spawn/from_id # 実行者の位置にドロップ

神器をスロット指定で置き換え

data modify storage api: Argument.ID set value <神器ID>
data modify storage api: Argument.Slot set value "mainhand"
data modify storage api: Argument.Target set value "@s"
function api:artifact/replace/from_id

神器をコンテナに格納

data modify storage api: Argument.ID set value <神器ID>
data modify storage api: Argument.Pos set value [I;<x>,<y>,<z>]
function api:artifact/box/from_id

神器の NBT だけ取得 (実体生成なし)

data modify storage api: Argument.ID set value <神器ID>
function api:artifact/storage/from_id
# Return.Artifact にItem NBTが格納される

Object API

ObjectAsset (射撃体・短命オブジェクト等) の召喚。詳細はオブジェクトの作り方を参照。

data modify storage api: Argument.ID set value <ObjectAssetのID>
data modify storage api: Argument.FieldOverride set value {Speed:8d} # オプション
execute at <pos> rotated <yaw> <pitch> run function api:object/summon

Absorption (緩衝体力) API

プレイヤーの緩衝体力 (黄色いハート部分) を管理する。

緩衝体力の追加

data modify storage api: Argument.Amount set value 10.0d
data modify storage api: Argument.UUID set value [I;1,1,0,0]
data modify storage api: Argument.Priority set value 5 # オプション (大きいほど先に消費される)
data modify storage api: Argument.WipedCallback set value "<関数名>" # オプション (全消費時に呼ばれる)
execute as <player> run function api:entity/player/absorption/add

緩衝体力の削除

data modify storage api: Argument.UUID set value [I;1,1,0,0]
execute as <player> run function api:entity/player/absorption/remove

緩衝体力の取得

execute as <player> run function api:entity/player/absorption/get
# Return.Amount, Return.Modifiers などが格納される

データ取得 API

実行者の EntityNBT を軽量に取得し、 storage に代入するよ。
この API を Mob に対して利用すると負荷が増えることが想定されるので利用しないでね。

複数の API を連続で呼ぶときの再フェッチを抑える内部キャッシュ (DataCache) があるよ。

対応する NBT

id / Pos / Motion / Rotation / fallDistance / Fire / Air / OnGround / NoGravity / Invulnerable / PortalCooldown / UUID / CustomName / CustomNameVisible / Silent / Passengers / Glowing / Tags / Health / AbsorptionAmount / HurtTime / DeathTime / FallFlying / SleepingX / SleepingY / SleepingZ / Brain / Attributes / ActiveEffects / NoAI / Team / DataVersion / Dimension / playerGameType / previousPlayerGameType / Score / SelectedItemSlot / SelectedItem / SpawnX / SpawnY / SpawnZ / SpawnForced / SleepTimer / foodLevel / foodExhaustionLevel / foodSaturationLevel / foodTickTimer / XpLevel / XpP / XpTotal / XpSeed / Inventory / EnderItems / abilities / enteredNetherPosition / RootVehicle / ShoulderEntityLeft / ShoulderEntityRight / seenCredits / recipeBook

引数

要求データ	必須	型	説明
実行者	o	Player	データを取得する対象

返り値

データ	型	説明
`api: <データ名>`	storage	取得した NBT (各キーごとに別)

使い方

function api:data_get/<対応するNBT>

例

# データ取得
 function api:data_get/health
# 実行者のHealthがapi: Healthに入ってるので出力する
 tellraw @a {"storage":"api:","nbt":"Health"}

キャッシュの無効化

特定のデータを再フェッチさせたい時:

function api:data_get/invalidate_cache

PlayerVector API

プレイヤーの前 tick からの位置差分 (= 速度ベクトル) を取得する。移動方向に依存する効果を作る時に便利。

function api:player_vector/get
# Return.Vector に [double; 3] (dx, dy, dz) が格納される

LostItemsAPI

プレイヤーが信仰なし死亡で失ったアイテムに対する API 。

没収アイテム数取得

没収されたアイテムのスロット数を取得するよ。

execute as <player> store result score $SlotItemCount Temporary run function api:lost_items/get_length

没収アイテム返還

没収されたアイテムをランダムに指定したスロット数分返却するよ。
一定の確率で指定したスロット数より少ない数が返却されることがある。

data modify storage api: Argument.Count set value 10
execute as <player> positioned ~ ~3 ~ run function api:lost_items/give

GlobalVars API

グローバル変数の取得。

function api:global_vars/get_difficulty
# Return.Difficulty に 1 (Normal) / 2 (Hard) / 3 (Blessless) のいずれかが格納される

Button API

tellraw で使うクリック可能なボタンの Text Component を生成する。

data modify storage api: Argument.Label set value '"[キャンセル]"'
data modify storage api: Argument.Key set value "cancel"
data modify storage api: Argument.Listener set value "myns:on_cancel"
function api:button/create_text_component
# 生成されたコンポーネントを tellraw で使う
tellraw @s [{"storage":"api:","nbt":"Return.ButtonTextComponent","interpret":true}]

Listener を指定すると、その function がボタンクリック時に実行される。

ハマりポイント

Argument を消し忘れる → 次回呼び出しに前回値が混ざる。神器・モブ間で同じ storage を共有してるので注意。多くの API は関数末尾で自動 remove するけど、 damage / heal 系は reset 関数を別途呼ぶ必要があるよ。
Return を取り出す前に新規 API を呼ぶ → Return が上書きされる。まず取り出して、必要なら別 storage に退避。
DoT 扱いにし忘れて神器が連発される → 継続ダメージ・継続回復は Argument.ApplyTrigger:false で IsDoT / IsHoT 扱いに。詳細は神器の作り方 - IsDoT / IsHoT のルール。
PersistentArgument を通常の Argument と混同する → PersistentArgument は複数 API をまたいで値を持ち回せる特殊な引数 (api: PersistentArgument.*)。主に AdditionalMPHeal で使われる。 prefix が違うので混同しないこと。

Uh oh!

api

共通の使い方

DamageAPI

引数

補正 function について

例

DeathMessage について

例: プレイヤー名と攻撃元の名前を埋め込む

例: 死亡メッセージが 2 種 (プレイヤー名のみ、ランダム選択)

HealAPI

引数

使い方

MPAPI

MP 増減

引数

使い方

MP 設定

引数

使い方

MP チェック

引数

返り値

使い方

MP 取得

使い方

MP 最大値取得

使い方

MP 最大値更新

ModifierAPI

補正対象

補正の追加

引数

使い方

例

補正の削除

引数

使い方

例

補正値の取得

使い方

Effect 付与 API

Effect 付与

Effect 削除 (ID から)

Effect 削除 (解除レベルから)

Effect 取得

Effect リセット

Mob API

Mob 召喚

Mob 除去・キル

MobHP 操作

AssetMob かチェック

ダメージ転送

神器 API

神器の付与

神器をワールドにドロップ

神器をスロット指定で置き換え

神器をコンテナに格納

神器の NBT だけ取得 (実体生成なし)

Object API

Absorption (緩衝体力) API

緩衝体力の追加

緩衝体力の削除

緩衝体力の取得

データ取得 API

引数

返り値

使い方

例

キャッシュの無効化

PlayerVector API

LostItemsAPI

没収アイテム数取得

没収アイテム返還

GlobalVars API

Button API

ハマりポイント

Uh oh!

Uh oh!

Uh oh!