Moteur de script Lua MagmaCore

MagmaCore fournit un moteur de script Lua partagé utilisé par plusieurs plugins Nightbreak. Le moteur gère le sandboxing, la planification, la gestion des zones, l'interaction avec le monde, les tables d'entités et l'interface joueur -- le tout avec une API cohérente entre les plugins.

Actuellement, les plugins suivants utilisent ce moteur :

EliteMobs -- Pouvoirs Lua pour les boss personnalisés (hooks comme on_boss_damaged_by_player, on_enter_combat, etc.)
FreeMinecraftModels -- Scripts Lua pour les props et objets personnalisés (hooks comme on_right_click, on_left_click, on_equip, etc.)

Cette page documente les fonctionnalités partagées du moteur. Pour les hooks, APIs et workflows spécifiques à chaque plugin, consultez les pages des plugins liées ci-dessus.

Mini-guide Lua

Si vous êtes complètement nouveau en Lua, voici la syntaxe minimale dont vous avez besoin pour écrire des scripts pour n'importe quel plugin Nightbreak.

Variables

Utilisez local pour stocker une valeur :

local cooldown_key = "fire_burst"
local damage_multiplier = 1.5

local signifie que la variable n'appartient qu'à ce fichier ou ce bloc.

Fonctions

Les fonctions sont des blocs de logique réutilisables :

local function warn_player(player)
  player:send_message("&cMove!")
end

Plus tard, vous pouvez l'appeler :

warn_player(some_player)

Vérifications `if`

Utilisez if quand quelque chose ne doit se produire que dans certains cas :

if context.player == nil then
  return
end

Cela signifie « s'il n'y a pas de joueur pour ce hook, on s'arrête ici ».

`nil`

nil signifie « aucune valeur ». C'est la version Lua de « il n'y a rien ici ».

Vous vérifierez souvent la présence de nil avec :

if context.event ~= nil then
  -- do something with the event
end

~= signifie « n'est pas égal à ».

Tables

Lua utilise les tables pour plusieurs usages :

Listes
Objets avec clés nommées
La définition de script finale retournée

Exemple de table avec clés nommées :

local particle = {
  particle = "FLAME",
  amount = 1,
  speed = 0.05
}

Retourner la définition du script

À la fin de chaque fichier de script, vous retournez une seule table :

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Cette table retournée est le fichier de script.

Commentaires

Utilisez -- pour écrire une note destinée aux humains :

-- This cooldown stops the attack from firing every hit
context.cooldowns:set_local(60, "fire_burst")

Sandbox Lua

Tous les scripts Lua s'exécutent dans un environnement LuaJ sandboxé. Plusieurs globales qui pourraient accéder au système de fichiers ou au runtime Java sont supprimées. Les règles du sandbox sont identiques pour tous les plugins utilisant MagmaCore.

Globales supprimées

Les globales standard Lua suivantes sont définies à nil et ne peuvent pas être utilisées :

Supprimée	Raison
`debug`	Expose l'état interne de la VM
`dofile`	Accès au système de fichiers
`io`	Accès au système de fichiers
`load`	Chargement de code arbitraire
`loadfile`	Accès au système de fichiers
`luajava`	Accès direct aux classes Java
`module`	Système de modules (non nécessaire)
`os`	Accès au système d'exploitation
`package`	Système de modules (non nécessaire)
`require`	Système de modules / accès au système de fichiers

Bibliothèque standard disponible

Tout le reste de la bibliothèque standard Lua fonctionne normalement :

Catégorie	Fonctions
Math	`math.abs`, `math.ceil`, `math.floor`, `math.max`, `math.min`, `math.random`, `math.sin`, `math.cos`, `math.sqrt`, `math.pi`, et toutes les autres fonctions `math.*`
String	`string.byte`, `string.char`, `string.find`, `string.format`, `string.gsub`, `string.len`, `string.lower`, `string.match`, `string.rep`, `string.sub`, `string.upper`, et toutes les autres fonctions `string.*`
Table	`table.insert`, `table.remove`, `table.sort`, `table.concat`, et toutes les autres fonctions `table.*`
Itérateurs	`pairs`, `ipairs`, `next`
Type	`type`, `tostring`, `tonumber`, `select`, `unpack`
Gestion des erreurs	`pcall`, `xpcall`, `error`, `assert`
Autres	`print`, `rawget`, `rawset`, `rawequal`, `rawlen`, `setmetatable`, `getmetatable`

La bibliothèque os n'est pas disponible

La bibliothèque os est entièrement supprimée du sandbox. Si vous avez besoin d'informations de timing, utilisez context.world:get_time() pour le temps du monde ou stockez des horodatages dans context.state à l'aide de compteurs de ticks avec on_tick / on_game_tick.

astuce

print écrit dans la console du serveur, mais préférez context.log:info(msg) pour la sortie. Les messages de log sont préfixés par le nom du fichier de script, ce qui facilite le repérage du script qui a produit le message.

Contrat de fichier

Chaque script Lua doit return une table. Cette table est volontairement stricte.

Champs de premier niveau requis et optionnels

Champ	Requis	Type	Notes
`api_version`	Oui	Number	Doit actuellement être `1`
`priority`	Non	Number	Priorité d'exécution. Les valeurs plus faibles s'exécutent en premier. Par défaut `0`
clés de hook prises en charge	Non	Function	Doit utiliser l'un des noms de hook exacts pris en charge par le plugin

Règles de validation

Le fichier doit retourner une table.
api_version est requis et doit actuellement être 1.
priority doit être numérique si présent.
Chaque clé supplémentaire de premier niveau doit être un nom de hook pris en charge.
Chaque clé de hook doit pointer vers une fonction.
Les clés de premier niveau inconnues sont rejetées.

Les fonctions utilitaires et les constantes locales doivent vivre au-dessus du return final, et non à l'intérieur de la table retournée, sauf s'il s'agit de véritables hooks.

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    do_something(context)
  end
}

Hooks partagés du moteur

Les hooks suivants sont disponibles pour tous les plugins utilisant le moteur de script MagmaCore. Chaque plugin ajoute ses propres hooks par-dessus ceux-ci.

Hook	Quand il se déclenche
`on_spawn`	Appelé une fois lorsque l'instance de script est créée (l'entité apparaît ou le prop est placé)
`on_game_tick`	Appelé à chaque tick du serveur tant que l'entité est en vie/active
`on_zone_enter`	Appelé lorsqu'un joueur entre dans une zone surveillée
`on_zone_leave`	Appelé lorsqu'un joueur quitte une zone surveillée

Syntaxe de méthode : `:` vs `.`

En Lua, object:method(arg) est un raccourci pour object.method(object, arg). L'API MagmaCore accepte les deux formes, donc l'une ou l'autre fonctionne :

context.log:info("hello")
context.log.info("hello")  -- same thing

Toute la documentation utilise : de manière cohérente.

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 / on_tick légers -- ils s'exécutent à chaque tick.
Utilisez context.scheduler:run_repeating(...) pour répartir le travail sur plusieurs ticks.
Déplacez le travail coûteux derrière un cooldown basé sur l'état ou un intervalle raisonnable.

Erreurs d'exécution de script

Si un script Lua lève une erreur d'exécution dans un hook ou un callback planifié, l'instance de script est immédiatement et définitivement désactivée pour cette entité. Corrigez l'erreur dans votre fichier de script -- le script se réinitialisera lors de la prochaine apparition de l'entité.

`context.state`

Une table Lua simple qui persiste pendant toute la durée de vie de l'instance de script. Utilisez-la pour stocker des drapeaux, des compteurs, des IDs de tâche, des états de bascule et toute donnée que vous souhaitez partager entre les hooks.

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

info

Seul context.state persiste entre les appels de hook. Toutes les autres tables de contexte (context.prop, context.world, context.event, etc.) sont reconstruites à neuf à chaque fois. context.state n'est pas reconstruit -- il survit du moment où l'instance de script est créée jusqu'à sa destruction.

`context.log`

Méthodes de journalisation dans la console. Les messages sont préfixés par le nom du fichier de script dans la console du serveur.

Méthode	Notes
`log:info(message)`	Message informatif
`log:warn(message)`	Message d'avertissement
`log:error(message)`	Message de niveau avertissement (loggé au niveau WARN, identique à `log:warn`)

Variante EliteMobs

Le context.log d'EliteMobs enregistre debug au lieu de error. Utilisez log:debug(message) pour la sortie de débogage (apparaît au niveau info avec un préfixe debug).

context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
context.log:error("Critical failure in zone setup")

`context.cooldowns`

La table cooldowns gère les cooldowns temporels pour vos scripts. Il existe deux portées :

Les cooldowns locaux sont par instance de script et identifiés par une clé chaîne. Si aucune clé n'est fournie, le nom de fichier du script est utilisé comme clé par défaut.
Les cooldowns globaux sont partagés entre tous les scripts sur la même entité propriétaire (par exemple tous les scripts sur le même prop, ou tous les pouvoirs Lua sur le même boss).

`cooldowns:check_local(key?, duration)`

La méthode la plus courante. Vérifie si le cooldown est prêt, et si oui, le démarre et retourne true. Si pas prêt, retourne false. C'est une vérification-et-affectation atomique — pas de conditions de course.

Paramètre	Type	Notes
`key`	string (optionnel)	Identifiant du cooldown. Par défaut le nom de fichier du script.
`duration`	int	Durée du cooldown en ticks (20 = 1 seconde)

on_right_click = function(context)
  -- Only allow this action once every 3 seconds
  if not context.cooldowns:check_local("interact", 60) then
    return
  end
  -- ... do the action
end

`cooldowns:local_ready(key?)`

Retourne true si le cooldown local a expiré (ou n'a jamais été défini), false s'il est toujours actif.

`cooldowns:local_remaining(key?)`

Retourne le nombre de ticks restants sur le cooldown local, ou 0 si prêt.

`cooldowns:set_local(duration, key?)`

Définit un cooldown local sans vérifier si un est déjà actif. Utilisez ceci pour les réinitialisations inconditionnelles de cooldown.

Paramètre	Type	Notes
`duration`	int	Durée en ticks. Passez 0 ou négatif pour effacer.
`key`	string (optionnel)	Identifiant du cooldown. Par défaut le nom de fichier du script.

`cooldowns:global_ready()`

Retourne true si le cooldown global (partagé entre tous les scripts sur la même entité) a expiré.

`cooldowns:set_global(duration)`

Définit le cooldown global.

Paramètre	Type	Notes
`duration`	int	Durée en ticks

Portées des cooldowns globaux

Le « propriétaire » d'un cooldown global dépend du type de script :

Pouvoirs Lua EliteMobs — partagés par EliteEntity (un seau par boss). global_ready() / set_global() utilisent le système de cooldown de pouvoir intégré du boss ; les cooldowns locaux sont également partagés entre tous les pouvoirs sur le même boss.
Scripts de prop FMM — partagés par PropEntity (un seau par prop placé).
Scripts d'item FMM — partagés par UUID de joueur (un seau par joueur). Les cooldowns locaux sur les items sont persistés à travers les cycles équipement/déséquipement, indexés par playerUUID → "itemId:scriptFile" → key, de sorte qu'un cooldown survit lorsque le joueur sort l'item de sa hotbar puis le replace.

`context.scheduler`

Le scheduler vous permet d'exécuter des tâches différées et répétitives. Toutes les tâches appartiennent à l'instance de script et sont automatiquement annulées lorsque l'instance de script est détruite (par exemple lorsqu'un prop est retiré ou qu'un boss meurt).

`scheduler:run_later(ticks, callback)`

Exécute un callback une seule fois après un délai. Retourne un ID de tâche numérique.

Paramètre	Type	Notes
`ticks`	int	Délai en ticks serveur (20 ticks = 1 seconde)
`callback`	function	Appelé avec un `context` frais lorsque le délai expire

context.scheduler:run_later(40, function(delayed_context)
  delayed_context.log:info("2 seconds have passed!")
end)

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

Exécute un callback de manière répétée à un intervalle fixe. Retourne un ID de tâche numérique.

Paramètre	Type	Notes
`delay`	int	Délai initial en ticks avant la première exécution
`interval`	int	Ticks entre chaque exécution suivante
`callback`	function	Appelé avec un `context` frais à chaque intervalle

context.state.particle_task = context.scheduler:run_repeating(0, 20, function(tick_context)
  tick_context.log:info("Another second passed!")
end)

`scheduler:cancel(taskId)`

Annule une tâche planifiée par son ID.

Paramètre	Type	Notes
`taskId`	int	L'ID de tâche retourné par `run_later` ou `run_repeating`

Annulez toujours les tâches répétitives

Si vous démarrez une tâche répétitive, annulez-la toujours dans votre hook de nettoyage (on_destroy pour les props, on_exit_combat / on_death pour les boss, on_unequip pour les items). Oublier d'annuler laisse une tâche en arrière-plan qui s'exécute jusqu'à ce que l'instance de script soit détruite, ce qui gaspille les performances et peut causer des erreurs.

Les callbacks reçoivent un contexte frais

Les callbacks planifiés reçoivent un contexte frais comme paramètre. Utilisez toujours l'argument context propre au callback, pas le context externe du hook qui a créé le callback. Le contexte externe peut contenir des références obsolètes.

`context.world`

La table world fournit des méthodes pour interroger et interagir avec le monde Minecraft. Elle est construite à partir du monde actuel de l'entité.

Extensions spécifiques aux plugins

EliteMobs étend context.world avec des méthodes supplémentaires pour faire apparaître des boss, des renforts, des blocs tombants, des feux d'artifice, des potions de splash et des blocs temporaires. Voir EliteMobs World & Environment pour l'API étendue complète. Les méthodes documentées ici sont disponibles dans tous les plugins.

`world.name`

Un champ chaîne contenant le nom du monde.

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

Retourne le nom du matériau du bloc aux coordonnées données sous forme de chaîne en minuscules (par exemple "stone", "air").

Paramètre	Type	Notes
`x`	int	Coordonnée X du bloc
`y`	int	Coordonnée Y du bloc
`z`	int	Coordonnée Z du bloc

`world:set_block_at(x, y, z, material)`

Définit le bloc aux coordonnées données. S'exécute sur le thread principal.

Paramètre	Type	Notes
`x`	int	Coordonnée X du bloc
`y`	int	Coordonnée Y du bloc
`z`	int	Coordonnée Z du bloc
`material`	string	Nom Bukkit Material, en minuscules (par exemple `"stone"`, `"air"`, `"oak_planks"`)

Retourne true si le bloc a été placé avec succès, false sinon.

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

Fait apparaître des particules à un emplacement.

Paramètre	Type	Défaut	Notes
`particle`	string	requis	Nom de l'enum Bukkit Particle, EN_MAJUSCULES (par exemple `"FLAME"`, `"DUST"`)
`x`	number	requis	Coordonnée X
`y`	number	requis	Coordonnée Y
`z`	number	requis	Coordonnée Z
`count`	int	`1`	Nombre de particules
`dx`	number	`0`	Dispersion/décalage X
`dy`	number	`0`	Dispersion/décalage Y
`dz`	number	`0`	Dispersion/décalage Z
`speed`	number	`0`	Vitesse des particules

Particules nécessitant des données

Certains types de particules nécessitent des données de bloc ou d'item qui ne sont pas prises en charge par cette API simple. BLOCK_CRACK, FALLING_DUST, BLOCK_DUST et ITEM_CRACK échoueront ou ne produiront aucun effet visible. Utilisez plutôt des alternatives sans données : CLOUD, SMOKE, CAMPFIRE_COSY_SMOKE, SNOWFLAKE, FLAME, DUST, etc.

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

Joue un son à un emplacement.

Paramètre	Type	Défaut	Notes
`sound`	string	requis	Nom de l'enum Bukkit Sound, EN_MAJUSCULES (par exemple `"ENTITY_EXPERIENCE_ORB_PICKUP"`)
`x`	number	requis	Coordonnée X
`y`	number	requis	Coordonnée Y
`z`	number	requis	Coordonnée Z
`volume`	number	`1.0`	Volume
`pitch`	number	`1.0`	Hauteur (pitch)

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

Frappe la foudre à un emplacement (visuel et infligeant des dégâts).

Paramètre	Type	Notes
`x`	number	Coordonnée X
`y`	number	Coordonnée Y
`z`	number	Coordonnée Z

`world:get_time()`

Retourne le temps actuel du monde en ticks.

`world:set_time(ticks)`

Définit le temps du monde.

Paramètre	Type	Notes
`ticks`	int	Temps du monde (0 = aube, 6000 = midi, 13000 = nuit, 18000 = minuit)

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

Retourne un tableau de tables d'entités pour toutes les entités à l'intérieur d'une boîte englobante centrée sur les coordonnées données.

Paramètre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`radius`	number	Rayon de recherche (utilisé comme demi-étendue sur les trois axes)

attention

Ceci retourne TOUTES les entités à portée, y compris les entités non vivantes (armor stands, items lâchés, etc.). Protégez toujours avec if entity.damage then avant d'appeler les méthodes d'entités vivantes.

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

Retourne un tableau de tables joueur pour tous les joueurs à l'intérieur d'une boîte englobante centrée sur les coordonnées données.

Paramètre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`radius`	number	Rayon de recherche

`world:spawn_entity(entity_type, x, y, z)`

Fait apparaître une entité Minecraft vanilla à l'emplacement donné.

Paramètre	Type	Notes
`entity_type`	string	Nom du type d'entité Bukkit, en minuscules (par exemple `"zombie"`, `"skeleton"`, `"pig"`)
`x`	number	Coordonnée X
`y`	number	Coordonnée Y
`z`	number	Coordonnée Z

Retourne une table d'entité pour l'entité apparue (avec les méthodes d'entité vivante le cas échéant), ou nil si le type d'entité est invalide.

`world:get_highest_block_y(x, z)`

Retourne la coordonnée Y du bloc non-air le plus haut à la position X/Z donnée.

Paramètre	Type	Notes
`x`	int	Coordonnée X du bloc
`z`	int	Coordonnée Z du bloc

`world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance])`

Lance un rayon depuis un point dans une direction et retourne des informations sur ce qu'il touche.

Paramètre	Type	Défaut	Notes
`from_x`	number	requis	Origine X
`from_y`	number	requis	Origine Y
`from_z`	number	requis	Origine Z
`dir_x`	number	requis	Composante X de la direction
`dir_y`	number	requis	Composante Y de la direction
`dir_z`	number	requis	Composante Z de la direction
`max_distance`	number	`50`	Distance maximale du rayon

Retourne une table avec les champs suivants :

Champ	Type	Notes
`hit_entity`	entity table ou nil	La première entité touchée par le rayon, ou `nil` si aucune
`hit_location`	location table ou nil	Le point exact où le rayon a touché quelque chose
`hit_block`	table ou nil	`{x, y, z, material}` du bloc touché, ou `nil` si aucun bloc n'a été touché

`world:spawn_firework(x, y, z, colors, [type], [power])`

Fait apparaître une fusée de feu d'artifice à l'emplacement donné.

Paramètre	Type	Défaut	Notes
`x`	number	requis	Coordonnée X
`y`	number	requis	Coordonnée Y
`z`	number	requis	Coordonnée Z
`colors`	table	requis	Tableau de chaînes de couleurs, par exemple `{"RED", "BLUE", "WHITE"}`
`type`	string	`"BALL"`	Forme du feu d'artifice : `"BALL"`, `"BALL_LARGE"`, `"STAR"`, `"BURST"`, `"CREEPER"`
`power`	int	`1`	Puissance de vol, 0-127

-- Example: red and gold firework burst
context.world:spawn_firework(loc.x, loc.y, loc.z, {"RED", "GOLD"}, "BURST", 2)

`world:place_temporary_block(x, y, z, material, [ticks], [require_air])`

Place un bloc qui revient automatiquement à son état d'origine après un délai.

Paramètre	Type	Défaut	Notes
`x`	int	requis	Coordonnée X du bloc
`y`	int	requis	Coordonnée Y du bloc
`z`	int	requis	Coordonnée Z du bloc
`material`	string	requis	Nom Bukkit Material (par exemple `"stone"`, `"ice"`)
`ticks`	int	`0`	Durée en ticks avant que le bloc ne revienne. 0 signifie permanent.
`require_air`	boolean	`false`	Si `true`, ne place le bloc que si la cible est de l'air

Retourne true si le bloc a été placé, false si le matériau était invalide ou si l'exigence d'air n'était pas remplie.

`world:drop_item(x, y, z, material, [amount])`

Lâche une entité item à l'emplacement donné avec une dispersion naturelle.

Paramètre	Type	Défaut	Notes
`x`	number	requis	Coordonnée X
`y`	number	requis	Coordonnée Y
`z`	number	requis	Coordonnée Z
`material`	string	requis	Nom Bukkit Material
`amount`	int	`1`	Taille de la pile

Retourne une table d'entité pour l'item lâché, ou nil si le matériau était invalide.

`context.zones`

La table zones vous permet de créer des zones spatiales et de les surveiller pour les événements d'entrée/sortie des joueurs. Les zones sont liées à l'instance de script et nettoyées automatiquement lorsque l'instance de script est détruite.

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

Crée une zone sphérique centrée sur les coordonnées données. Retourne un handle de zone numérique.

Paramètre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`radius`	number	Rayon de la sphère

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

Crée une zone cylindrique. Retourne un handle de zone numérique.

Paramètre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y (base)
`z`	number	Centre Z
`radius`	number	Rayon du cylindre
`height`	number	Hauteur du cylindre

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

Crée une zone cuboïde. Retourne un handle de zone numérique.

Paramètre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`xSize`	number	Demi-étendue en X
`ySize`	number	Demi-étendue en Y
`zSize`	number	Demi-étendue en Z

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

Démarre la surveillance d'une zone pour les événements d'entrée/sortie des joueurs. Les paramètres callback agissent comme des signaux booléens — passer une valeur non-nil (par exemple une fonction ou true) active le hook correspondant sur le script. Les callbacks eux-mêmes ne sont pas invoqués directement. À la place, la logique d'entrée/sortie se déclenche via les hooks on_zone_enter / on_zone_leave du script.

Paramètre	Type	Notes
`handle`	int	Handle de zone provenant d'un appel `create_*`
`onEnterCallback`	quelconque non-nil ou nil	Non-nil active le hook `on_zone_enter` pour cette zone
`onLeaveCallback`	quelconque non-nil ou nil	Non-nil active le hook `on_zone_leave` pour cette zone

Retourne true si la surveillance a été configurée avec succès, nil si le handle de zone était invalide.

info

Les surveillances de zone sont vérifiées à chaque tick serveur contre tous les joueurs dans le même monde. Gardez le nombre de zones raisonnable pour éviter une surcharge de performances.

`zones:unwatch(handle)`

Arrête la surveillance d'une zone et nettoie ses ressources.

Paramètre	Type	Notes
`handle`	int	Handle de zone dont arrêter la surveillance

Exemple : Zone de déclenchement par proximité

return {
  api_version = 1,

  on_spawn = function(context)
    local loc = context.prop.current_location  -- or context.boss:get_location()
    if loc == nil then return end

    local handle = context.zones:create_sphere(loc.x, loc.y, loc.z, 5)

    -- Pass non-nil values to enable on_zone_enter and on_zone_leave hooks.
    -- These are boolean signals, not callbacks — the actual logic goes in the hooks below.
    context.zones:watch(handle, true, true)

    context.state.zone_handle = handle
  end,

  on_zone_enter = function(context)
    context.log:info("Player entered zone!")
  end,

  on_zone_leave = function(context)
    context.log:info("Player left zone!")
  end,

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

`context.event`

La table event est présente lorsque le hook actuel a été déclenché par un événement de jeu (par exemple on_right_click, on_zone_enter). Elle n'est pas présente lors de on_tick ou des callbacks planifiés.

Champ / Méthode	Type	Notes
`is_cancelled`	boolean	Si l'événement a été annulé
`cancel()`	method	Annule l'événement (empêche le comportement par défaut)
`uncancel()`	method	Désannule un événement précédemment annulé
`player`	entity table	Le joueur impliqué dans l'événement, le cas échéant

on_right_click = function(context)
  if context.event then
    context.event:cancel()  -- prevent the default right-click interaction
  end
end

Table d'événement EliteMobs

Les scripts de pouvoir EliteMobs ont une table d'événement plus détaillée avec les quantités de dégâts, les causes de dégâts, les références aux attaquants et les méthodes de modification de dégâts. Voir Lua API Reference pour les champs complets de l'événement EliteMobs.

Espace de noms d'aide `em`

La table em est disponible au moment du chargement du fichier (avant que tout hook ne s'exécute). Elle fournit des constructeurs utilitaires pour construire des tables de localisation, des tables de vecteurs et des définitions de zones utilisées dans toute l'API.

Fonction	Objectif
`em.create_location(x, y, z [, world, yaw, pitch])`	Crée une table de localisation avec un nom de monde, yaw et pitch optionnels. La table retournée possède aussi une méthode `.add(dx, dy, dz)` qui décale la localisation sur place et se retourne elle-même pour le chaînage.
`em.create_vector(x, y, z)`	Crée une table vecteur
`em.zone.create_sphere_zone(radius)`	Crée une définition de zone sphérique
`em.zone.create_dome_zone(radius)`	Crée une définition de zone dôme
`em.zone.create_cylinder_zone(radius, height)`	Crée une définition de zone cylindrique
`em.zone.create_cuboid_zone(x, y, z)`	Crée une définition de zone cuboïde
`em.zone.create_cone_zone(length, radius)`	Crée une définition de zone conique
`em.zone.create_static_ray_zone(length, thickness)`	Crée une définition de zone de rayon statique
`em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)`	Crée une définition de zone de rayon rotatif
`em.zone.create_translating_ray_zone(length, point_radius, animation_duration)`	Crée une définition de zone de rayon en translation
`em.location.is_in_dungeon(loc)`	Vérifie si une localisation est à l'intérieur d'une région de donjon enregistrée
`em.location.is_protected(loc)`	Vérifie si une localisation est à l'intérieur d'une région protégée (WorldGuard, GriefPrevention, régions EM, etc.)
`em.location.owned_by(loc, namespace)`	Vérifie si un espace de noms de plugin spécifique possède la localisation (par exemple `"EliteMobs"`)
`em.location.owners(loc)`	Tableau des chaînes d'espace de noms qui possèdent la localisation
`em.location.kinds_at(loc)`	Tableau des étiquettes de type à la localisation (`"elitemobs"`, `"world_package"`, `"open_world_dungeon"`, catégorie de taille de donjon)
`em.location.has_kind(loc, kind)`	Vérifie si la localisation est étiquetée avec le type donné

Les constructeurs de zones retournent des tables chaînables avec :set_center(loc) (ou :set_origin(loc) / :set_destination(loc) selon le type de zone) :

-- At file scope: create a reusable zone shape
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_spawn = function(context)
    -- Anchor the zone at call time
    blast_zone:set_center(context.boss:get_location())
    local entities = context.zones:get_entities_in_zone(blast_zone)
    -- ...
  end
}

info

L'espace de noms em est particulièrement utile dans EliteMobs où les définitions de zones sont utilisées avec context.zones:get_entities_in_zone() et context.script. Dans FreeMinecraftModels, les méthodes context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) sont plus couramment utilisées pour les zones simples basées sur la surveillance.

Tables d'entités

Les tables d'entités sont retournées par les requêtes sur le monde, les données d'événements et les callbacks de zones. Elles fournissent un ensemble de champs et de méthodes en couches selon le type d'entité.

Champs de base d'entité

Champ	Type	Notes
`uuid`	string	L'UUID de l'entité
`entity_type`	string	Le type d'entité (par exemple `"player"`, `"zombie"`, `"skeleton"`, `"villager"`)
`is_valid`	boolean	Si la référence à l'entité est toujours valide
`is_dead`	boolean	Si l'entité est morte
`is_player`	boolean	Si l'entité est un joueur
`is_hostile`	boolean	Si l'entité est un mob hostile (zombie, squelette, etc.)
`is_passive`	boolean	Si l'entité est un mob passif (vache, cochon, poule, etc.)
`current_location`	location table	La position actuelle de l'entité (`x`, `y`, `z`, `world`, `yaw`, `pitch`)
`world`	string	Le nom du monde dans lequel se trouve l'entité

Méthodes de base d'entité

Méthode	Retourne	Notes
`teleport(location_table)`	void	Téléporte l'entité. La table de localisation doit avoir les champs `x`, `y`, `z`, `world` ; `yaw` et `pitch` sont optionnels.
`remove()`	void	Supprime l'entité du monde. N'agit que si l'entité est toujours valide.
`set_silent(flag)`	void	Supprime ou réactive les sons de l'entité.
`set_invulnerable(flag)`	void	Rend l'entité invulnérable ou vulnérable aux dégâts.
`set_gravity(flag)`	void	Active ou désactive la gravité pour l'entité.
`set_glowing(flag)`	void	Active/désactive l'effet de contour brillant sur l'entité.

Champs d'entité vivante

Les entités vivantes (joueurs, mobs, etc.) ont tous les champs de base d'entité plus :

Champ	Type	Notes
`health`	number	Santé actuelle
`maximum_health`	number	Santé maximale
`name`	string	Nom d'affichage
`is_alive`	boolean	Si l'entité est en vie

Méthodes d'entité vivante

Méthode	Retourne	Notes
`damage(amount)`	void	Inflige la quantité de dégâts donnée à l'entité
`push(x, y, z)`	void	Applique une impulsion de vélocité
`set_facing(x, y, z)`	void	Définit la direction vers laquelle l'entité fait face
`add_potion_effect(effect, duration, amplifier)`	void	Ajoute un effet de potion. `effect` est une chaîne (par exemple `"speed"`, `"slowness"`, `"regeneration"`). `duration` est en ticks. `amplifier` est le niveau d'effet moins 1 (0 = niveau I).
`remove_potion_effect(effect)`	void	Supprime un effet de potion par son nom
`get_scale()`	number	Retourne l'échelle actuelle de l'entité (1.0 par défaut sur les serveurs sans l'attribut generic.scale)
`set_scale(value)`	void	Définit l'échelle de l'entité via l'attribut generic.scale. Sans effet sur les serveurs antérieurs à 1.20.5.

attention

Toutes les entités retournées par get_nearby_entities() ne sont pas des entités vivantes. Vous pouvez utiliser entity.is_player, entity.is_hostile ou entity.is_passive pour filtrer par catégorie, ou vérifier if entity.damage then avant d'appeler les méthodes d'entité vivante comme damage(), push() ou add_potion_effect().

Champs d'intégration de plugins

Les tables d'entités incluent automatiquement des champs pour détecter et interagir avec les entités gérées par d'autres plugins Nightbreak. Ces champs ne sont remplis que lorsque le plugin concerné est installé -- sinon ils valent par défaut false / nil sans aucune surcharge.

Champs EliteMobs

Disponibles lorsque EliteMobs est installé.

Champ	Type	Notes
`is_elite`	boolean	Si l'entité est un elite EliteMobs
`is_custom_boss`	boolean	Si l'entité est un boss personnalisé EliteMobs (également disponible dans la sous-table `elite`)
`is_significant_boss`	boolean	Si l'entité est un boss personnalisé avec un multiplicateur de santé supérieur à 1 (c'est-à-dire un affrontement conçu, pas un elite de remplissage)
`elite`	table ou nil	Sous-table d'informations sur l'elite (voir ci-dessous). `nil` si l'entité n'est pas un elite.

La sous-table elite contient :

Champ	Type	Notes
`elite.level`	int	Le niveau de l'elite
`elite.name`	string	Le nom d'affichage de l'elite
`elite.health`	number	Santé actuelle
`elite.max_health`	number	Santé maximale
`elite.is_custom_boss`	boolean	S'il s'agit d'un boss personnalisé (par opposition à un elite naturel)
`elite.health_multiplier`	number	Multiplicateur de santé défini en config
`elite.damage_multiplier`	number	Multiplicateur de dégâts défini en config
`elite:remove()`	void	Supprime l'elite via le pipeline de suppression approprié d'EliteMobs (nettoie le tracking, le loot, etc.)

Exemple : Infliger des dégâts différents aux elites

local entities = context.world:get_nearby_entities(x, y, z, 5)
for _, entity in ipairs(entities) do
    if entity.is_elite then
        -- Deal double damage to elites
        entity:damage(20)
        context.log:info("Hit elite: " .. entity.elite.name .. " (level " .. entity.elite.level .. ")")
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

Champs FreeMinecraftModels

Disponibles lorsque FreeMinecraftModels est installé.

Champ	Type	Notes
`is_modeled`	boolean	Si l'entité a un modèle FMM attaché (DynamicEntity ou PropEntity)
`is_prop`	boolean	Si l'entité est un prop FMM (entité décorative statique)
`model`	table ou nil	Sous-table d'informations sur le modèle (voir ci-dessous). `nil` si l'entité n'est pas modélisée.

La sous-table model contient :

Champ	Type	Notes
`model.model_id`	string	L'ID du blueprint de modèle (par exemple `"torch_01"`)
`model.is_dynamic`	boolean	Si l'entité modélisée est une DynamicEntity (modèle de mob/boss) plutôt qu'un prop statique
`model:play_animation(name, [blend], [loop])`	boolean	Joue une animation nommée. `blend` vaut `false` par défaut, `loop` vaut `false` par défaut. Retourne `true` si l'animation a été trouvée.
`model:stop_animations()`	void	Arrête toutes les animations en cours sur le modèle.
`model:remove()`	void	Supprime l'entité modélisée via le pipeline de suppression approprié de FMM.

Bridge vs valeurs par défaut Prop

Le bridge de modèle (disponible sur n'importe quelle entité) met blend et loop à false par défaut. La table prop play_animation met les deux à true par défaut car les props veulent typiquement des animations fondues et en boucle.

Exemple : Filtrer les entités par type

local entities = context.world:get_nearby_entities(x, y, z, 10)
for _, entity in ipairs(entities) do
    if entity.is_prop then
        -- Skip props
    elseif entity.is_player then
        entity:damage(5)
    elseif entity.entity_type == "villager" then
        -- Don't hurt villagers
    elseif entity.is_elite then
        entity:damage(20)
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

Champs spécifiques aux joueurs

Les entités joueur ont tous les champs d'entité et d'entité vivante plus :

Champ	Type	Notes
`game_mode`	string	Le mode de jeu du joueur (`"creative"`, `"survival"`, `"adventure"`, `"spectator"`)

Méthodes spécifiques aux joueurs

Méthode	Retourne	Notes
`send_message(msg)`	void	Envoie un message dans le chat au joueur. Prend en charge les codes couleur `&`.
`get_held_item()`	table ou nil	Retourne `{type, amount, display_name}` pour l'item dans la main principale du joueur, ou `nil` si vide
`consume_held_item(amount?)`	void	Consomme des items de la main principale du joueur. `amount` vaut `1` par défaut
`has_item(material, amount?)`	boolean	Retourne `true` si le joueur a au moins `amount` (par défaut `1`) du matériau donné quelque part dans son inventaire
`get_target_entity([range])`	entity table ou nil	Retourne l'entité que le joueur regarde via raycast, ou `nil` si aucune. La portée par défaut est 50.
`get_eye_location()`	location table	Retourne une table de localisation à la hauteur des yeux du joueur
`get_look_direction()`	table	Retourne un vecteur de direction `{x, y, z}` pour la direction du regard du joueur
`send_block_change(x, y, z, material, [ticks])`	boolean	Envoie un faux bloc visible uniquement par ce joueur. Si `ticks` est fourni, le faux bloc se réinitialise automatiquement après cette durée. Retourne `true` en cas de succès, `false` si le matériau est invalide.
`reset_block(x, y, z)`	boolean	Réinitialise un faux bloc à la place du vrai bloc pour ce joueur. Retourne toujours `true`.
`sleep(x, y, z)`	void	Fait entrer le joueur dans une animation de sommeil dans un lit aux coordonnées données. Le bloc est automatiquement restauré lorsque le joueur cesse de dormir.
`wake_up()`	void	Réveille un joueur endormi.

Méthodes d'interface joueur

Ces méthodes sont disponibles sur n'importe quelle table d'entité joueur et fournissent des moyens d'afficher des informations au joueur via les éléments d'UI intégrés de Minecraft.

`player:show_boss_bar(text, [color], progress, [ticks])`

Affiche une barre de boss au joueur.

Paramètre	Type	Défaut	Notes
`text`	string	requis	Le texte à afficher. Prend en charge les codes couleur `&`.
`color`	string	`"WHITE"`	Couleur de la barre. Une parmi : `"RED"`, `"BLUE"`, `"GREEN"`, `"YELLOW"`, `"PURPLE"`, `"PINK"`, `"WHITE"`
`progress`	number	requis	Quantité de remplissage de `0.0` (vide) à `1.0` (plein)
`ticks`	int	nil	Délai optionnel d'auto-disparition en ticks. Si omis, la barre reste jusqu'à ce qu'elle soit cachée manuellement.

`player:hide_boss_bar()`

Supprime la barre de boss de l'écran du joueur. Ne prend aucun paramètre.

`player:show_action_bar(text, [ticks])`

Affiche du texte dans la zone d'action bar (au-dessus de la hotbar).

Paramètre	Type	Défaut	Notes
`text`	string	requis	Le texte à afficher. Prend en charge les codes couleur `&`.
`ticks`	int	nil	Durée optionnelle en ticks. Si fournie, le message est renvoyé tous les 40 ticks pour le maintenir visible pendant toute la durée.

`player:show_title(title, [subtitle], fade_in, stay, fade_out)`

Affiche un écran de titre au joueur.

Paramètre	Type	Défaut	Notes
`title`	string	requis	Texte du titre principal. Prend en charge les codes couleur `&`.
`subtitle`	string	`""`	Texte du sous-titre sous le titre principal. Optionnel.
`fade_in`	int	requis	Durée de fondu en entrée en ticks
`stay`	int	requis	Combien de temps le titre reste à l'écran en ticks
`fade_out`	int	requis	Durée de fondu en sortie en ticks

Étapes suivantes

Pour les hooks, APIs et workflows spécifiques aux plugins :

EliteMobs : Premiers pas | Hooks & cycle de vie | Boss & entités | Monde & environnement | Zones & ciblage
FreeMinecraftModels : Premiers pas | API Prop & Item | Exemples

Mini-guide Lua
Sandbox Lua
- Globales supprimées
- Bibliothèque standard disponible
Contrat de fichier
- Champs de premier niveau requis et optionnels
- Règles de validation
Hooks partagés du moteur
Syntaxe de méthode : : vs .
Budget d'exécution
context.state
context.log
context.cooldowns
context.scheduler
context.world
context.zones
context.event
Espace de noms d'aide em
Tables d'entités
Méthodes d'interface joueur
Étapes suivantes

Mini-guide Lua​

Variables​

Fonctions​

Vérifications if​

nil​

Tables​

Retourner la définition du script​

Commentaires​

Sandbox Lua​

Globales supprimées​

Bibliothèque standard disponible​

Contrat de fichier​

Champs de premier niveau requis et optionnels​

Règles de validation​

Hooks partagés du moteur​

Syntaxe de méthode : : vs .​

Budget d'exécution​

context.state​

context.log​

context.cooldowns​

cooldowns:check_local(key?, duration)​

cooldowns:local_ready(key?)​

cooldowns:local_remaining(key?)​

cooldowns:set_local(duration, key?)​

cooldowns:global_ready()​

cooldowns:set_global(duration)​

context.scheduler​

scheduler:run_later(ticks, callback)​

scheduler:run_repeating(delay, interval, callback)​

scheduler:cancel(taskId)​

context.world​

world.name​

world:get_block_at(x, y, z)​

world:set_block_at(x, y, z, material)​

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)​

world:spawn_entity(entity_type, x, y, z)​

world:get_highest_block_y(x, z)​

world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance])​

world:spawn_firework(x, y, z, colors, [type], [power])​

world:place_temporary_block(x, y, z, material, [ticks], [require_air])​

world:drop_item(x, y, z, material, [amount])​

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)​

Exemple : Zone de déclenchement par proximité​

context.event​

Espace de noms d'aide em​

Tables d'entités​

Champs de base d'entité​

Méthodes de base d'entité​

Champs d'entité vivante​

Méthodes d'entité vivante​

Champs d'intégration de plugins​

Champs EliteMobs​

Champs FreeMinecraftModels​

Champs spécifiques aux joueurs​

Méthodes spécifiques aux joueurs​

Méthodes d'interface joueur​

player:show_boss_bar(text, [color], progress, [ticks])​

player:hide_boss_bar()​

player:show_action_bar(text, [ticks])​

player:show_title(title, [subtitle], fade_in, stay, fade_out)​

Étapes suivantes​

Mini-guide Lua

Variables

Fonctions

Vérifications `if`

`nil`

Tables

Retourner la définition du script

Commentaires

Sandbox Lua

Globales supprimées

Bibliothèque standard disponible

Contrat de fichier

Champs de premier niveau requis et optionnels

Règles de validation

Hooks partagés du moteur

Syntaxe de méthode : `:` vs `.`

Budget d'exécution

`context.state`

`context.log`

`context.cooldowns`

`cooldowns:check_local(key?, duration)`

`cooldowns:local_ready(key?)`

`cooldowns:local_remaining(key?)`

`cooldowns:set_local(duration, key?)`

`cooldowns:global_ready()`

`cooldowns:set_global(duration)`

`context.scheduler`

`scheduler:run_later(ticks, callback)`

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

`scheduler:cancel(taskId)`

`context.world`

`world.name`

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

`world:set_block_at(x, y, z, material)`

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

`world:spawn_entity(entity_type, x, y, z)`

`world:get_highest_block_y(x, z)`

`world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance])`

`world:spawn_firework(x, y, z, colors, [type], [power])`

`world:place_temporary_block(x, y, z, material, [ticks], [require_air])`

`world:drop_item(x, y, z, material, [amount])`

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

Exemple : Zone de déclenchement par proximité

`context.event`

Espace de noms d'aide `em`

Tables d'entités

Champs de base d'entité

Méthodes de base d'entité

Champs d'entité vivante

Méthodes d'entité vivante

Champs d'intégration de plugins

Champs EliteMobs

Champs FreeMinecraftModels

Champs spécifiques aux joueurs

Méthodes spécifiques aux joueurs

Méthodes d'interface joueur

`player:show_boss_bar(text, [color], progress, [ticks])`

`player:hide_boss_bar()`

`player:show_action_bar(text, [ticks])`

`player:show_title(title, [subtitle], fade_in, stay, fade_out)`

Étapes suivantes