Scripts Lua : API Prop et Objet

Cette page couvre chaque API disponible pour les scripts de props et d'objets FreeMinecraftModels : context.prop, context.item, context.event, context.player, context.world, context.zones, context.scheduler, context.state et context.log. Si vous êtes nouveau dans le scripting, commencez par Pour commencer.

`context.prop`

La table prop fournit des informations sur l'entité prop et des méthodes pour contrôler ses animations. Elle est reconstruite à neuf pour chaque appel de hook.

Champs

Champ	Type	Notes
`prop.model_id`	string	Le nom du modèle de base (ex : `"torch_01"`)
`prop.current_location`	table location	La position du prop au moment où le contexte a été construit

La table location contient les champs standard : x, y, z, world, yaw, pitch.

Exemple : lire les infos du 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)`

Joue une animation nommée sur le modèle du prop.

Paramètre	Type	Défaut	Notes
`name`	string	requis	Le nom de l'animation tel que défini dans le fichier de modèle
`blend`	boolean	`true`	S'il faut fusionner avec l'animation en cours
`loop`	boolean	`true`	Si l'animation boucle

Renvoie true si l'animation a été trouvée et démarrée, false sinon.

Exemple

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()`

Arrête toutes les animations en cours de lecture sur le prop.

Ne prend aucun paramètre.

Exemple

return {
  api_version = 1,

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

`prop:hurt_visual()`

Joue l'animation visuelle de dégâts (flash de teinte rouge) sur le prop sans lui infliger de dégâts réels.

Ne prend aucun paramètre.

Exemple

return {
  api_version = 1,

  on_left_click = function(context)
    -- Flash red when punched, but don't actually take damage
    if context.event then
      context.event.cancel()
    end
    context.prop:hurt_visual()
  end
}

`prop:pickup()`

Retire le prop du monde et lâche un objet papier de placement à son emplacement. L'objet lâché peut être utilisé par clic droit sur un bloc pour replacer le prop.

Ne prend aucun paramètre.

Exemple

return {
  api_version = 1,

  on_right_click = function(context)
    -- Let players pick up the prop by right-clicking it
    context.prop:pickup()
  end
}

`prop:mount(player)`

Monte un joueur sur la première position de siège de point de montage disponible du prop. Le modèle doit avoir des os de point de montage définis.

Paramètre	Type	Notes
`player`	table entité	Une table d'entité joueur (ex : depuis `context.event.player`)

Exemple

return {
  api_version = 1,

  on_right_click = function(context)
    local player = context.event and context.event.player
    if player then
      context.prop:mount(player)
    end
  end
}

`prop:dismount(player)`

Démonte un joueur de sa position de siège de point de montage sur le prop.

Paramètre	Type	Notes
`player`	table entité	Une table d'entité joueur

Exemple

return {
  api_version = 1,

  on_right_click = function(context)
    local player = context.event and context.event.player
    if player then
      -- Toggle mount/dismount
      local passengers = context.prop:get_passengers()
      for i = 1, #passengers do
        if passengers[i].uuid == player.uuid then
          context.prop:dismount(player)
          return
        end
      end
      context.prop:mount(player)
    end
  end
}

`prop:get_passengers()`

Renvoie un tableau Lua de tables d'entités pour tous les passagers actuels sur le prop.

Ne prend aucun paramètre.

Exemple

return {
  api_version = 1,

  on_game_tick = function(context)
    local passengers = context.prop:get_passengers()
    if #passengers > 0 then
      context.log:info("Prop has " .. #passengers .. " passenger(s)")
    end
  end
}

`prop:has_mount_points()`

Renvoie si ce prop a des os de point de montage définis dans son modèle.

Ne prend aucun paramètre. Renvoie true ou false.

Exemple

return {
  api_version = 1,

  on_right_click = function(context)
    local player = context.event and context.event.player
    if player and context.prop:has_mount_points() then
      context.prop:mount(player)
    end
  end
}

`prop:spawn_elitemobs_boss(filename, x, y, z)`

Fait apparaître un boss personnalisé EliteMobs à l'emplacement donné. Nécessite qu'EliteMobs soit installé sur le serveur.

Paramètre	Type	Notes
`filename`	string	Le nom de fichier du boss personnalisé (ex : `"my_boss.yml"`)
`x`	number	Coordonnée X
`y`	number	Coordonnée Y
`z`	number	Coordonnée Z

Renvoie une table d'entité vivante pour le boss apparu, ou nil si EliteMobs n'est pas installé ou si le fichier de boss n'existe pas.

Exemple

return {
  api_version = 1,

  on_right_click = function(context)
    local loc = context.prop.current_location
    if loc then
      local boss = context.prop:spawn_elitemobs_boss("dungeon_guardian.yml", loc.x, loc.y + 1, loc.z)
      if boss then
        context.log:info("Spawned boss: " .. (boss.name or "unknown"))
      else
        context.log:warn("Could not spawn boss -- is EliteMobs installed?")
      end
    end
  end
}

`prop:open_inventory(player, title, rows)`

Ouvre un inventaire de coffre GUI persistant pour le joueur. Le contenu est sauvegardé dans le PersistentDataContainer du prop lorsque l'inventaire est fermé, et restauré lorsqu'il est rouvert.

Paramètre	Type	Défaut	Notes
`player`	table entité	requis	Le joueur à qui montrer l'inventaire
`title`	string	requis	Le titre de l'inventaire (prend en charge les codes couleur `&`)
`rows`	int	`3`	Nombre de lignes (1-6, où 6 = 54 slots = double coffre)

Renvoie true si l'inventaire a été ouvert, false sinon.

`prop:is_viewing_inventory(player)`

Renvoie si le joueur donné a actuellement l'inventaire de ce prop ouvert.

Paramètre	Type	Notes
`player`	table entité	Le joueur à vérifier

Renvoie true ou false.

Exemple : Animation de fermeture quand l'inventaire est fermé

context.state["task_" .. player.uuid] = context.scheduler:run_repeating(5, 5, function(tick_context)
    if not tick_context.prop:is_viewing_inventory(player) then
        tick_context.prop:play_animation("close", true, false)
        tick_context.scheduler:cancel(tick_context.state["task_" .. player.uuid])
    end
end)

`prop:place_book(player)`

Prend le livre écrit ou inscriptible de la main principale du joueur et le stocke sur le prop.

Paramètre	Type	Notes
`player`	table entité	Le joueur tenant le livre

Renvoie true en cas de succès.

`prop:read_book(player)`

Ouvre le livre stocké pour lecture par le joueur.

Paramètre	Type	Notes
`player`	table entité	Le joueur à qui montrer le livre

Renvoie true si un livre a été ouvert.

`prop:take_book(player)`

Rend le livre stocké à l'inventaire du joueur et le retire du prop.

Paramètre	Type	Notes
`player`	table entité	Le joueur à qui donner le livre

Renvoie true en cas de succès.

`prop:has_book()`

Renvoie si un livre est stocké sur ce prop. Ne prend aucun paramètre.

`prop:drop_inventory()`

Lâche tout le contenu de l'inventaire stocké à l'emplacement du prop sous forme d'entités d'objets, puis efface les données stockées. Ferme automatiquement l'inventaire pour tout joueur qui le consulte actuellement.

Ne prend aucun paramètre. Renvoie true en cas de succès.

`prop:drop_book()`

Lâche le livre stocké à l'emplacement du prop sous forme d'entité d'objet et efface les données du livre stocké.

Ne prend aucun paramètre. Renvoie true en cas de succès.

`prop:set_persistent_data(key, value)`

Stocke une valeur de type chaîne dans le PersistentDataContainer de l'armor stand du prop. Ces données survivent aux redémarrages du serveur et aux déchargements de chunks.

Paramètre	Type	Notes
`key`	string	Un nom de clé unique (stocké comme `fmm_lua_<key>` en interne)
`value`	string	La valeur à stocker. Utilisez `tostring()` pour les nombres et les booléens.

Renvoie true en cas de succès, false si le prop n'a pas d'armor stand de support.

`prop:get_persistent_data(key)`

Récupère une valeur de type chaîne précédemment stockée avec set_persistent_data. Renvoie nil si la clé n'a pas été définie.

Paramètre	Type	Notes
`key`	string	Le nom de la clé utilisé dans `set_persistent_data`

Exemple : État de basculement persistant

return {
  api_version = 1,

  on_spawn = function(context)
    local saved = context.prop:get_persistent_data("active")
    context.state.active = saved == "true"
  end,

  on_right_click = function(context)
    context.state.active = not context.state.active
    context.prop:set_persistent_data("active", tostring(context.state.active))
  end
}

`context.item`

La table item est disponible uniquement dans les scripts d'objets (pas les scripts de props). Elle fournit des informations sur l'objet personnalisé et des méthodes pour le manipuler. Cette table est reconstruite à neuf pour chaque appel de hook.

Champs

Champ	Type	Notes
`item.id`	string	L'ID de type d'objet (le `fmm_item_id` de la configuration YML)

`item:material()`

Renvoie le nom du matériau de l'objet sous forme de chaîne (ex : "DIAMOND_SWORD", "STICK").

`item:get_amount()` / `item:set_amount(n)`

Obtient ou définit la taille du stack de l'objet.

Paramètre	Type	Notes
`n`	int	La nouvelle quantité du stack

`item:consume(n)`

Décrémente la quantité du stack de l'objet de n (défaut 1). Si la quantité résultante est 0 ou moins, l'objet est retiré de l'inventaire du joueur.

Paramètre	Type	Défaut	Notes
`n`	int	`1`	Quantité à consommer

`item:get_uses()` / `item:set_uses(n)`

Obtient ou définit un compteur d'utilisation personnalisé stocké dans le PersistentDataContainer de l'objet. Ceci est indépendant de la durabilité vanilla et peut être utilisé pour implémenter des systèmes de durabilité ou de charge personnalisés.

Paramètre	Type	Notes
`n`	int	Le nouveau compteur d'utilisations

`item:get_name()` / `item:set_name(s)`

Obtient ou définit le nom d'affichage de l'objet. Prend en charge les codes couleur avec &.

Paramètre	Type	Notes
`s`	string	Le nouveau nom d'affichage (ex : `"&b&lFrost Sword"`)

`item:get_lore()` / `item:set_lore(table)`

Obtient ou définit le lore de l'objet. get_lore() renvoie une table de chaînes (une par ligne). set_lore() prend une table de chaînes.

Paramètre	Type	Notes
`table`	table	Tableau de chaînes, une par ligne de lore

Exemple : Script d'objet qui suit les utilisations

return {
  api_version = 1,

  on_right_click = function(context)
    local uses = context.item:get_uses()
    if uses <= 0 then
      context.player:send_message("&cThis item is out of charges!")
      return
    end
    context.item:set_uses(uses - 1)
    context.player:send_message("&aUsed! Charges remaining: " .. (uses - 1))
  end
}

`item:get_durability()`

Renvoie une table avec les champs current et max représentant la durabilité vanilla de l'objet, ou nil si l'objet n'a pas de barre de durabilité.

Exemple

local dur = context.item:get_durability()
if dur then
  context.player:send_message("Durability: " .. dur.current .. "/" .. dur.max)
end

`item:get_durability_percentage()`

Renvoie la durabilité restante sous forme de fraction de 0.0 à 1.0, ou nil si l'objet n'a pas de barre de durabilité.

`item:use_durability(amount, can_break)`

Réduit la durabilité vanilla de l'objet d'un montant fixe.

Paramètre	Type	Défaut	Notes
`amount`	int	requis	Combien de points de durabilité à consommer
`can_break`	boolean	`false`	Si `true`, l'objet est détruit quand la durabilité atteint zéro. Si `false`, la durabilité s'arrête à 1.

`item:use_durability_percentage(fraction, can_break)`

Réduit la durabilité vanilla de l'objet d'un pourcentage de son maximum.

Paramètre	Type	Défaut	Notes
`fraction`	number	requis	Fraction de la durabilité maximale à consommer (ex : `0.1` = 10%)
`can_break`	boolean	`false`	Si `true`, l'objet est détruit quand la durabilité atteint zéro. Si `false`, la durabilité s'arrête à 1.

`context.event`

Données de l'événement pour le hook en cours. Disponible dans les hooks de clic, combat et interaction pour les scripts de props et d'objets. Renvoie nil dans les hooks qui n'ont pas d'événement associé (on_spawn, on_game_tick, on_destroy, on_zone_enter, on_zone_leave, on_equip).

Champs et méthodes

Champ ou méthode	Type	Notes
`event.player`	table entité joueur	Le joueur qui a déclenché l'événement. Disponible dans `on_left_click`, `on_right_click` et `on_projectile_hit` (le tireur, si c'était un joueur). Voir Méthodes d'entité joueur pour tous les champs et méthodes.
`event.is_cancelled`	boolean	Si l'événement est actuellement annulé
`event.cancel()`	function	Annule l'événement (ex : empêche les dégâts ou l'interaction)
`event.uncancel()`	function	Dé-annule un événement précédemment annulé

info

Tous les événements ne sont pas annulables. Si l'événement Bukkit sous-jacent n'implémente pas Cancellable, event.cancel() et event.uncancel() ne seront pas présents et event.is_cancelled sera toujours false.

Exemple : Rendre un prop invulnérable

Exemple

return {
  api_version = 1,

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

Exemple : Vérifier l'état d'annulation

Exemple

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
}

attention

Dans les callbacks planifiés (scheduler:run_later, scheduler:run_repeating), context.event est toujours nil. La modification d'événements ne peut se faire que pendant le hook d'événement lui-même.

`context.world`

L'API world est partagée entre tous les plugins Nightbreak. Voir context.world pour la référence complète.

info

Les props FMM utilisent la même table world MagmaCore que les boss EliteMobs. Toutes les méthodes documentées sur la page globale (get_block_at, set_block_at, spawn_particle, play_sound, strike_lightning, get_time, set_time, get_nearby_entities, get_nearby_players, spawn_entity, get_highest_block_y, raycast, spawn_firework) sont disponibles dans FMM. Voir l'API world MagmaCore pour les détails complets sur world:raycast() (lancer un rayon et détecter les entités/blocs touchés) et world:spawn_firework() (faire apparaître des fusées de feu d'artifice avec des couleurs et formes personnalisées). EliteMobs étend la table world avec des méthodes supplémentaires pour faire apparaître des boss, des renforts et plus -- voir Monde et environnement EliteMobs.

Méthodes d'entité joueur

Les tables d'entité joueur sont renvoyées par context.event.player, context.world:get_nearby_players() et les callbacks de zone.

API partagée

Les tables d'entité, méthodes d'entité vivante, méthodes spécifiques au joueur et méthodes d'interface joueur sont partagées entre tous les plugins Nightbreak. Voir le Moteur de scripting Lua MagmaCore pour la référence complète couvrant les champs de base d'entité, les champs et méthodes d'entité vivante, les champs et méthodes spécifiques au joueur, et les Méthodes d'interface joueur. Les nouvelles méthodes joueur incluent player:get_target_entity() (ciblage par raycast), player:get_eye_location(), player:get_look_direction(), player:send_block_change() (faux blocs par joueur), et player:reset_block() -- voir Méthodes spécifiques au joueur pour les détails.

`context.zones`

L'API zones est partagée entre tous les plugins Nightbreak. Voir context.zones pour la référence complète.

`context.scheduler`

L'API scheduler est partagée entre tous les plugins Nightbreak. Voir context.scheduler pour la référence complète.

`context.state`

L'API state est partagée entre tous les plugins Nightbreak. Voir context.state pour la référence complète.

`context.log`

L'API de journalisation est partagée entre tous les plugins Nightbreak. Voir context.log pour la référence complète.

Modèle d'exécution

Un moteur d'exécution par instance de script

Chaque entité prop qui a des scripts attachés obtient sa propre instance de moteur d'exécution Lua indépendante. Lorsque le prop apparaît, FMM charge la source Lua, l'évalue dans un environnement sandboxé frais et stocke la table retournée. Lorsque le prop est supprimé, le moteur d'exécution est arrêté.

Pour les scripts d'objets, un moteur d'exécution est créé par paire (joueur, itemId). Lorsqu'un joueur équipe un objet personnalisé, FMM crée une instance de script pour ce joueur et ce type d'objet. Lorsque l'objet est déséquipé, le moteur d'exécution est arrêté.

Cela signifie :

Les variables locales déclarées au niveau du fichier sont privées à cette instance de script.
context.state est complètement isolé entre les instances, même si elles partagent le même fichier de script.

Propriété des tâches planifiées

Toutes les tâches créées via context.scheduler appartiennent au moteur d'exécution qui les a créées. Lorsqu'un prop est supprimé :

Le moteur d'exécution s'arrête.
Chaque tâche possédée -- à la fois ponctuelles et répétitives -- est automatiquement annulée.
Toutes les surveillances de zones sont nettoyées.

Budget d'exécution

Chaque invocation de hook et chaque invocation de callback est chronométrée. Si un seul appel prend plus de 50 millisecondes, le script est désactivé avec un avertissement console :

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

Pour rester dans le budget :

Évitez les boucles non bornées dans les hooks.
Gardez les gestionnaires on_game_tick légers -- ils s'exécutent à chaque tick.
Utilisez context.scheduler:run_repeating(...) pour répartir le travail sur plusieurs ticks.

Référence complète des hooks

Cette table liste tous les hooks disponibles dans les scripts de props et d'objets.

Hooks de props (8)

Hook	Se déclenche quand	`context.event`
`on_spawn`	Le prop apparaît dans le monde	nil
`on_game_tick`	Chaque tick serveur (50ms)	nil
`on_destroy`	Le prop est supprimé	nil
`on_left_click`	Un joueur clique gauche sur le prop	événement de dégâts
`on_right_click`	Un joueur clique droit sur le prop	événement d'interaction
`on_projectile_hit`	Un projectile touche le prop	événement d'impact de projectile
`on_zone_enter`	Un joueur entre dans une zone surveillée	nil
`on_zone_leave`	Un joueur quitte une zone surveillée	nil

Hooks d'objets (22)

Hook	Catégorie	Se déclenche quand	`context.event`
`on_attack_entity`	Combat	Le joueur attaque une entité	événement de dégâts
`on_kill_entity`	Combat	Le joueur tue une entité	événement de mort
`on_take_damage`	Combat	Le joueur prend des dégâts	événement de dégâts
`on_shield_block`	Combat	Le joueur bloque avec bouclier	événement de dégâts
`on_shoot_bow`	Combat	Le joueur tire avec un arc	événement de tir à l'arc
`on_projectile_hit`	Combat	Le projectile du joueur touche	événement d'impact de projectile
`on_projectile_launch`	Combat	Le joueur lance un projectile	événement de lancement
`on_right_click`	Interaction	Le joueur fait un clic droit	événement d'interaction
`on_left_click`	Interaction	Le joueur fait un clic gauche	événement d'interaction
`on_shift_right_click`	Interaction	Le joueur fait shift+clic droit	événement d'interaction
`on_shift_left_click`	Interaction	Le joueur fait shift+clic gauche	événement d'interaction
`on_interact_entity`	Interaction	Le joueur clic droit sur une entité	événement d'interaction entité
`on_equip`	Équipement	L'objet entre dans un slot actif	nil
`on_unequip`	Équipement	L'objet quitte un slot actif	nil
`on_swap_hands`	Équipement	Échange main principale/secondaire	événement d'échange
`on_drop`	Équipement	Le joueur lâche l'objet	événement de lâcher
`on_break_block`	Utilitaire	Le joueur casse un bloc	événement de casse de bloc
`on_consume`	Utilitaire	Le joueur consomme l'objet	événement de consommation
`on_item_damage`	Utilitaire	L'objet subit des dégâts de durabilité	événement de dégâts d'objet
`on_fish`	Utilitaire	Le joueur utilise une canne à pêche	événement de pêche
`on_death`	Utilitaire	Le joueur meurt avec l'objet équipé	événement de mort
`on_game_tick`	Cycle de vie	Chaque tick tant qu'équipé	nil

Prochaines étapes

Exemples et patterns -- scripts complets fonctionnels de props et d'objets avec explications
Dépannage -- problèmes courants, astuces de débogage et liste de vérification QC
Pour commencer -- structure de fichiers, hooks, guide du premier script

context.prop
context.item
context.event
context.world
Méthodes d'entité joueur
context.zones
context.scheduler
context.state
context.log
Modèle d'exécution
Référence complète des hooks
- Hooks de props (8)
- Hooks d'objets (22)
Prochaines étapes

context.prop​

Champs​

prop:play_animation(name, blend, loop)​

prop:stop_animation()​

prop:hurt_visual()​

prop:pickup()​

prop:mount(player)​

prop:dismount(player)​

prop:get_passengers()​

prop:has_mount_points()​

prop:spawn_elitemobs_boss(filename, x, y, z)​

prop:open_inventory(player, title, rows)​

prop:is_viewing_inventory(player)​

prop:place_book(player)​

prop:read_book(player)​

prop:take_book(player)​

prop:has_book()​

prop:drop_inventory()​

prop:drop_book()​

prop:set_persistent_data(key, value)​

prop:get_persistent_data(key)​

context.item​

Champs​

item:material()​

item:get_amount() / item:set_amount(n)​

item:consume(n)​

item:get_uses() / item:set_uses(n)​

item:get_name() / item:set_name(s)​

item:get_lore() / item:set_lore(table)​

item:get_durability()​

item:get_durability_percentage()​

item:use_durability(amount, can_break)​

item:use_durability_percentage(fraction, can_break)​

context.event​

Champs et méthodes​

Exemple : Rendre un prop invulnérable​

Exemple : Vérifier l'état d'annulation​

context.world​

Méthodes d'entité joueur​

context.zones​

context.scheduler​

context.state​

context.log​

Modèle d'exécution​

Un moteur d'exécution par instance de script​

Propriété des tâches planifiées​

Budget d'exécution​

Référence complète des hooks​

Hooks de props (8)​

Hooks d'objets (22)​

Prochaines étapes​

`context.prop`

Champs

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

`prop:stop_animation()`

`prop:hurt_visual()`

`prop:pickup()`

`prop:mount(player)`

`prop:dismount(player)`

`prop:get_passengers()`

`prop:has_mount_points()`

`prop:spawn_elitemobs_boss(filename, x, y, z)`

`prop:open_inventory(player, title, rows)`

`prop:is_viewing_inventory(player)`

`prop:place_book(player)`

`prop:read_book(player)`

`prop:take_book(player)`

`prop:has_book()`

`prop:drop_inventory()`

`prop:drop_book()`

`prop:set_persistent_data(key, value)`

`prop:get_persistent_data(key)`

`context.item`

Champs

`item:material()`

`item:get_amount()` / `item:set_amount(n)`

`item:consume(n)`

`item:get_uses()` / `item:set_uses(n)`

`item:get_name()` / `item:set_name(s)`

`item:get_lore()` / `item:set_lore(table)`

`item:get_durability()`

`item:get_durability_percentage()`

`item:use_durability(amount, can_break)`

`item:use_durability_percentage(fraction, can_break)`

`context.event`

Champs et méthodes

Exemple : Rendre un prop invulnérable

Exemple : Vérifier l'état d'annulation

`context.world`

Méthodes d'entité joueur

`context.zones`

`context.scheduler`

`context.state`

`context.log`

Modèle d'exécution

Un moteur d'exécution par instance de script

Propriété des tâches planifiées

Budget d'exécution

Référence complète des hooks

Hooks de props (8)

Hooks d'objets (22)

Prochaines étapes