Moteur de script Lua MagmaCore

MagmaCore fournit un moteur de script Lua partage utilise par plusieurs plugins Nightbreak. Le moteur gere le sandboxing, la planification, la gestion des zones, l'interaction avec le monde, les tables d'entites et l'interface joueur -- le tout avec une API coherente entre les plugins.

Actuellement, les plugins suivants utilisent ce moteur :

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

Cette page documente les fonctionnalites partagees du moteur. Pour les hooks, APIs et workflows specifiques a chaque plugin, consultez les pages des plugins liees ci-dessus.

Mini-guide Lua

Si vous etes completement nouveau en Lua, voici la syntaxe minimale dont vous avez besoin pour ecrire 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'a ce fichier ou bloc.

Fonctions

Les fonctions sont des blocs de logique reutilisables :

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

Plus tard, vous pouvez l'appeler :

warn_player(some_player)

Verifications `if`

Utilisez if quand quelque chose ne doit se produire que parfois :

if context.player == nil then
  return
end

Cela signifie "s'il n'y a pas de joueur pour ce hook, arrete ici".

`nil`

nil signifie "pas de valeur". C'est la version Lua de "il n'y a rien ici".

Vous verifierez souvent nil avec :

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

~= signifie "n'est pas egal a".

Tables

Lua utilise les tables pour plusieurs taches :

Listes
Objets avec des cles nommees
La definition finale du script retourne

Exemple d'une table avec des cles nommees :

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

Retourner la definition du script

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

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Cette table retournee est le fichier de script.

Commentaires

Utilisez -- pour ecrire une note a destination des humains :

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

Sandbox Lua

Tous les scripts Lua s'executent dans un environnement LuaJ sandbox. Plusieurs globales qui pourraient acceder au systeme de fichiers ou a l'environnement Java sont supprimees. Les regles du sandbox sont identiques pour tous les plugins utilisant MagmaCore.

Globales supprimees

Les globales Lua standard suivantes sont definies a nil et ne peuvent pas etre utilisees :

Supprimee	Raison
`debug`	Expose l'etat interne de la VM
`dofile`	Acces au systeme de fichiers
`io`	Acces au systeme de fichiers
`load`	Chargement de code arbitraire
`loadfile`	Acces au systeme de fichiers
`luajava`	Acces direct aux classes Java
`module`	Systeme de modules (non necessaire)
`os`	Acces au systeme d'exploitation
`package`	Systeme de modules (non necessaire)
`require`	Systeme de modules / acces au systeme de fichiers

Bibliotheque standard disponible

Tout le reste de la bibliotheque standard Lua fonctionne normalement :

Categorie	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.*`
Iterateurs	`pairs`, `ipairs`, `next`
Type	`type`, `tostring`, `tonumber`, `select`, `unpack`
Gestion d'erreurs	`pcall`, `xpcall`, `error`, `assert`
Autres	`print`, `rawget`, `rawset`, `rawequal`, `rawlen`, `setmetatable`, `getmetatable`

La bibliotheque os n'est pas disponible

La bibliotheque os est completement supprimee du sandbox. Si vous avez besoin d'informations de temps, utilisez context.world:get_time() pour le temps du monde ou stockez des horodatages dans context.state en utilisant des compteurs de ticks avec on_tick / on_game_tick.

astuce

print ecrit dans la console du serveur, mais preferez context.log:info(msg) pour la sortie. Les messages de log sont prefixes avec le nom du fichier de script, ce qui facilite l'identification du script ayant produit le message.

Contrat de fichier

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

Champs de niveau superieur requis et optionnels

Champ	Requis	Type	Notes
`api_version`	Oui	Number	Doit actuellement etre `1`
`priority`	Non	Number	Priorite d'execution. Les valeurs plus basses s'executent en premier. Par defaut `0`
cles de hooks supportees	Non	Function	Doit utiliser l'un des noms de hook exacts supportes par le plugin

Regles de validation

Le fichier doit retourner une table.
api_version est requis et doit actuellement etre 1.
priority doit etre numerique si present.
Chaque cle de niveau superieur supplementaire doit etre un nom de hook supporte.
Chaque cle de hook doit pointer vers une fonction.
Les cles de niveau superieur inconnues sont rejetees.

Les fonctions d'aide et les constantes locales doivent etre placees au-dessus du return final, pas a l'interieur de la table retournee sauf s'il s'agit de hooks reels.

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
}

Syntaxe des methodes : `:` vs `.`

En Lua, object:method(arg) est un raccourci pour object.method(object, arg). L'API MagmaCore accepte les deux formes, donc les deux fonctionnent :

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

Toute la documentation utilise : de maniere coherente.

Budget d'execution

Chaque invocation de hook et chaque invocation de callback est chronometree. Si un seul appel prend plus de 50 millisecondes, le script est desactive 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 :

Evitez les boucles non bornees a l'interieur des hooks.
Gardez les handlers on_game_tick / on_tick legers -- ils s'executent a chaque tick.
Utilisez context.scheduler:run_repeating(...) pour repartir le travail sur plusieurs ticks.
Placez le travail couteux derriere un cooldown base sur l'etat ou un intervalle raisonnable.

`context.state`

Une table Lua simple qui persiste pendant toute la duree de vie de l'instance du script. Utilisez-la pour stocker des drapeaux, des compteurs, des IDs de taches, des etats de bascule et toute donnee que vous devez 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 hooks. Toutes les autres tables de contexte (context.prop, context.world, context.event, etc.) sont reconstruites a chaque fois. context.state n'est pas reconstruit -- il survit depuis le moment ou l'instance du script est creee jusqu'a sa destruction.

`context.log`

Methodes de journalisation console. Les messages sont prefixes avec le nom du fichier de script dans la console du serveur.

Methode	Notes
`log:info(message)`	Message d'information
`log:warn(message)`	Message d'avertissement
`log:error(message)`	Message de niveau avertissement (journalise au niveau WARN, identique a `log:warn`)
`log:debug(message)`	Message de debogage (apparait en niveau info avec un prefixe debug)

context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
context.log:error("Critical failure in zone setup")
context.log:debug("State value: " .. tostring(context.state.counter))

`context.cooldowns`

La table cooldowns gere les temps de recharge pour vos scripts. Il existe deux portees :

Les cooldowns locaux sont par instance de script et identifies par une cle string. Si aucune cle n'est fournie, le nom du fichier de script est utilise comme cle par defaut.
Les cooldowns globaux sont partages entre tous les scripts du meme proprietaire d'entite (par exemple, tous les scripts du meme prop, ou tous les pouvoirs Lua du meme boss).

`cooldowns:check_local(key?, duration)`

La methode la plus courante. Verifie si le cooldown est pret, et si oui, le demarre et retourne true. Si pas pret, retourne false. C'est un check-and-set atomique — pas de conditions de course.

Parametre	Type	Notes
`key`	string (optionnel)	Identifiant du cooldown. Par defaut, le nom du fichier de script.
`duration`	int	Duree 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 expire (ou n'a jamais ete defini), false s'il est encore actif.

`cooldowns:local_remaining(key?)`

Retourne le nombre de ticks restants sur le cooldown local, ou 0 s'il est pret.

`cooldowns:set_local(duration, key?)`

Definit un cooldown local sans verifier si un est deja actif. Utilisez ceci pour les reinitialisations inconditionnelles de cooldown.

Parametre	Type	Notes
`duration`	int	Duree en ticks. Passez 0 ou negatif pour effacer.
`key`	string (optionnel)	Identifiant du cooldown. Par defaut, le nom du fichier de script.

`cooldowns:global_ready()`

Retourne true si le cooldown global (partage entre tous les scripts de la meme entite) a expire.

`cooldowns:set_global(duration)`

Definit le cooldown global.

Parametre	Type	Notes
`duration`	int	Duree en ticks

Cooldowns globaux EliteMobs

Dans les scripts de pouvoirs EliteMobs, global_ready() et set_global() utilisent le systeme de cooldown de pouvoirs integre du boss, qui est partage entre tous les pouvoirs Lua du meme boss. Les cooldowns locaux dans EliteMobs sont egalement partages entre tous les pouvoirs de la meme entite boss (cles par la chaine que vous avez choisie).

`context.scheduler`

Le planificateur vous permet d'executer des taches differees et repetees. Toutes les taches appartiennent a l'instance du script et sont annulees automatiquement lorsque l'instance du script est detruite (par exemple, lorsqu'un prop est supprime ou qu'un boss meurt).

`scheduler:run_later(ticks, callback)`

Execute un callback une fois apres un delai. Retourne un ID de tache numerique.

Parametre	Type	Notes
`ticks`	int	Delai en ticks serveur (20 ticks = 1 seconde)
`callback`	function	Appelee avec un `context` frais lorsque le delai expire

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

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

Execute un callback de maniere repetee a un intervalle fixe. Retourne un ID de tache numerique.

Parametre	Type	Notes
`delay`	int	Delai initial en ticks avant la premiere execution
`interval`	int	Ticks entre chaque execution suivante
`callback`	function	Appelee avec un `context` frais a 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 tache planifiee par son ID.

Parametre	Type	Notes
`taskId`	int	L'ID de tache retourne par `run_later` ou `run_repeating`

Annulez toujours les taches repetees

Si vous demarrez une tache repetee, 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 objets). Oublier d'annuler laisse une tache en arriere-plan jusqu'a la destruction de l'instance du script, ce qui gaspille des performances et peut causer des erreurs.

Les callbacks recoivent un contexte frais

Les callbacks planifies recoivent un contexte frais en parametre. Utilisez toujours l'argument de contexte propre au callback, pas le context externe du hook qui a cree le callback. Le contexte externe peut contenir des references obsoletes.

`context.world`

La table world fournit des methodes pour interroger et interagir avec le monde Minecraft. Elle est construite a partir du monde actuel de l'entite.

Extensions specifiques aux plugins

EliteMobs etend context.world avec des methodes supplementaires pour faire apparaitre des boss, des renforts, des blocs en chute, des feux d'artifice, des potions de lancer et des blocs temporaires. Consultez EliteMobs Monde & Environnement pour l'API etendue complete. Les methodes documentees ici sont disponibles pour tous les plugins.

`world.name`

Un champ string contenant le nom du monde.

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

Retourne le nom du materiau du bloc aux coordonnees donnees sous forme de string en minuscules (par exemple "stone", "air").

Parametre	Type	Notes
`x`	int	Coordonnee X du bloc
`y`	int	Coordonnee Y du bloc
`z`	int	Coordonnee Z du bloc

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

Definit le bloc aux coordonnees donnees. S'execute sur le thread principal.

Parametre	Type	Notes
`x`	int	Coordonnee X du bloc
`y`	int	Coordonnee Y du bloc
`z`	int	Coordonnee Z du bloc
`material`	string	Nom de Material Bukkit, en minuscules (par exemple `"stone"`, `"air"`, `"oak_planks"`)

Retourne true si le bloc a ete defini avec succes, false sinon.

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

Fait apparaitre des particules a un emplacement.

Parametre	Type	Defaut	Notes
`particle`	string	requis	Nom d'enum Particle de Bukkit, en MAJUSCULES (par exemple `"FLAME"`, `"DUST"`)
`x`	number	requis	Coordonnee X
`y`	number	requis	Coordonnee Y
`z`	number	requis	Coordonnee Z
`count`	int	`1`	Nombre de particules
`dx`	number	`0`	Dispersion/decalage X
`dy`	number	`0`	Dispersion/decalage Y
`dz`	number	`0`	Dispersion/decalage Z
`speed`	number	`0`	Vitesse des particules

Particules necessitant des donnees

Certains types de particules necessitent des donnees de bloc ou d'objet qui ne sont pas supportees par cette API simple. BLOCK_CRACK, FALLING_DUST, BLOCK_DUST et ITEM_CRACK echoueront ou ne produiront aucun effet visible. Utilisez des alternatives sans donnees a la place : CLOUD, SMOKE, CAMPFIRE_COSY_SMOKE, SNOWFLAKE, FLAME, DUST, etc.

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

Joue un son a un emplacement.

Parametre	Type	Defaut	Notes
`sound`	string	requis	Nom d'enum Sound de Bukkit, en MAJUSCULES (par exemple `"ENTITY_EXPERIENCE_ORB_PICKUP"`)
`x`	number	requis	Coordonnee X
`y`	number	requis	Coordonnee Y
`z`	number	requis	Coordonnee Z
`volume`	number	`1.0`	Volume
`pitch`	number	`1.0`	Hauteur (pitch)

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

Fait tomber la foudre a un emplacement (visuel et infligeant des degats).

Parametre	Type	Notes
`x`	number	Coordonnee X
`y`	number	Coordonnee Y
`z`	number	Coordonnee Z

`world:get_time()`

Retourne l'heure actuelle du monde en ticks.

`world:set_time(ticks)`

Definit l'heure du monde.

Parametre	Type	Notes
`ticks`	int	Heure du monde (0 = aube, 6000 = midi, 13000 = nuit, 18000 = minuit)

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

Retourne un tableau de tables d'entites wrapper pour toutes les entites dans une boite englobante centree aux coordonnees donnees.

Parametre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`radius`	number	Rayon de recherche (utilise comme demi-etendue sur les trois axes)

attention

Ceci retourne TOUTES les entites a portee, y compris les entites non vivantes (supports d'armure, objets laches, etc.). Verifiez toujours avec if entity.damage then avant d'appeler les methodes d'entites vivantes.

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

Retourne un tableau de tables de joueurs wrapper pour tous les joueurs dans une boite englobante centree aux coordonnees donnees.

Parametre	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 apparaitre une entite Minecraft vanilla a l'emplacement donne.

Parametre	Type	Notes
`entity_type`	string	Nom de type d'entite Bukkit, en minuscules (par exemple `"zombie"`, `"skeleton"`, `"pig"`)
`x`	number	Coordonnee X
`y`	number	Coordonnee Y
`z`	number	Coordonnee Z

Retourne une table d'entite pour l'entite apparue (avec les methodes d'entite vivante si applicable), ou nil si le type d'entite est invalide.

`world:get_highest_block_y(x, z)`

Retourne la coordonnee Y du bloc non-air le plus haut a la position X/Z donnee.

Parametre	Type	Notes
`x`	int	Coordonnee X du bloc
`z`	int	Coordonnee 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.

Parametre	Type	Defaut	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`	table d'entite ou nil	La premiere entite touchee par le rayon, ou `nil` si aucune
`hit_location`	table de location ou nil	Le point exact ou le rayon a touche quelque chose
`hit_block`	table ou nil	`{x, y, z, material}` du bloc touche, ou `nil` si aucun bloc n'a ete touche

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

Fait apparaitre une fusee de feu d'artifice a l'emplacement donne.

Parametre	Type	Defaut	Notes
`x`	number	requis	Coordonnee X
`y`	number	requis	Coordonnee Y
`z`	number	requis	Coordonnee Z
`colors`	table	requis	Tableau de strings 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 a son etat d'origine apres un delai.

Parametre	Type	Defaut	Notes
`x`	int	requis	Coordonnee X du bloc
`y`	int	requis	Coordonnee Y du bloc
`z`	int	requis	Coordonnee Z du bloc
`material`	string	requis	Nom de Material Bukkit (par exemple `"stone"`, `"ice"`)
`ticks`	int	`0`	Duree 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 ete place, false si le materiau etait invalide ou si l'exigence d'air n'etait pas remplie.

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

Fait tomber une entite objet a l'emplacement donne avec une dispersion naturelle.

Parametre	Type	Defaut	Notes
`x`	number	requis	Coordonnee X
`y`	number	requis	Coordonnee Y
`z`	number	requis	Coordonnee Z
`material`	string	requis	Nom de Material Bukkit
`amount`	int	`1`	Taille du stack

Retourne une table d'entite pour l'objet lache, ou nil si le materiau etait invalide.

`context.zones`

La table zones vous permet de creer des zones spatiales et de les surveiller pour les evenements d'entree/sortie de joueur. Les zones sont liees a l'instance du script et nettoyees automatiquement lorsque l'instance du script est detruite.

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

Cree une zone spherique centree aux coordonnees donnees. Retourne un identifiant numerique de zone.

Parametre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`radius`	number	Rayon de la sphere

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

Cree une zone cylindrique. Retourne un identifiant numerique de zone.

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

Cree une zone cuboide. Retourne un identifiant numerique de zone.

Parametre	Type	Notes
`x`	number	Centre X
`y`	number	Centre Y
`z`	number	Centre Z
`xSize`	number	Demi-etendue en X
`ySize`	number	Demi-etendue en Y
`zSize`	number	Demi-etendue en Z

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

Commence a surveiller une zone pour les evenements d'entree/sortie de joueur. Lorsqu'un joueur entre ou quitte la zone, le callback correspondant se declenche (et, s'ils sont definis, les hooks on_zone_enter / on_zone_leave).

Parametre	Type	Notes
`handle`	int	Identifiant de zone d'un appel `create_*`
`onEnterCallback`	function ou nil	Appelee quand un joueur entre dans la zone
`onLeaveCallback`	function ou nil	Appelee quand un joueur quitte la zone

Retourne true si la surveillance a ete configuree avec succes, nil si l'identifiant de zone etait invalide.

info

Les surveillances de zones sont verifiees a chaque tick serveur pour tous les joueurs dans le meme monde. Gardez le nombre de zones raisonnable pour eviter une surcharge de performance.

`zones:unwatch(handle)`

Arrete de surveiller une zone et nettoie ses ressources.

Parametre	Type	Notes
`handle`	int	Identifiant de zone a arreter de surveiller

Exemple : Zone de declenchement de proximite

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)

    context.zones:watch(
      handle,
      function(player)
        context.log:info("Player entered zone!")
      end,
      function(player)
        context.log:info("Player left zone!")
      end
    )

    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.event`

La table event est presente lorsque le hook actuel a ete declenche par un evenement de jeu (par exemple on_right_click, on_zone_enter). Elle n'est pas presente pendant on_tick ou les callbacks planifies.

Champ / Methode	Type	Notes
`is_cancelled`	boolean	Si l'evenement a ete annule
`cancel()`	method	Annule l'evenement (empeche le comportement par defaut)
`uncancel()`	method	Desannule un evenement precedemment annule
`player`	entity table	Le joueur implique dans l'evenement, le cas echeant

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

Table d'evenements EliteMobs

Les scripts de pouvoirs EliteMobs ont une table d'evenements plus detaillee avec des montants de degats, des causes de degats, des references a l'attaquant et des methodes de modification de degats. Consultez la Reference API Lua pour les champs complets d'evenements EliteMobs.

Espace de noms `em`

La table em est disponible au moment du chargement du fichier (avant l'execution de tout hook). Elle fournit des constructeurs d'aide pour creer des tables de position, des tables de vecteurs et des definitions de zones utilisees dans toute l'API.

Fonction	Objectif
`em.create_location(x, y, z [, world, yaw, pitch])`	Cree une table de position avec nom de monde, yaw et pitch optionnels. La table retournee dispose egalement d'une methode `.add(dx, dy, dz)` qui decale la position sur place et la retourne pour le chainage.
`em.create_vector(x, y, z)`	Cree une table de vecteur
`em.zone.create_sphere_zone(radius)`	Cree une definition de zone spherique
`em.zone.create_dome_zone(radius)`	Cree une definition de zone en dome
`em.zone.create_cylinder_zone(radius, height)`	Cree une definition de zone cylindrique
`em.zone.create_cuboid_zone(x, y, z)`	Cree une definition de zone cuboide
`em.zone.create_cone_zone(length, radius)`	Cree une definition de zone conique
`em.zone.create_static_ray_zone(length, thickness)`	Cree une definition de zone de rayon statique
`em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)`	Cree une definition de zone de rayon rotatif
`em.zone.create_translating_ray_zone(length, point_radius, animation_duration)`	Cree une definition de zone de rayon en translation

Les constructeurs de zones retournent des tables chainables 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 particulierement utile dans EliteMobs ou les definitions de zones sont utilisees avec context.zones:get_entities_in_zone() et context.script. Dans FreeMinecraftModels, les methodes context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) sont plus couramment utilisees pour les zones simples basees sur la surveillance.

Tables d'entites

Les tables d'entites sont retournees par les requetes de monde, les donnees d'evenement et les callbacks de zone. Elles fournissent un ensemble de champs et methodes en couches selon le type d'entite.

Champs de base d'entite

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

Methodes de base d'entite

Methode	Retourne	Notes
`teleport(location_table)`	void	Teleporte l'entite. La table de position doit avoir les champs `x`, `y`, `z`, `world` ; `yaw` et `pitch` sont optionnels.
`remove()`	void	Supprime l'entite du monde. N'agit que si l'entite est toujours valide.
`set_silent(flag)`	void	Supprime ou reactive les sons de l'entite.
`set_invulnerable(flag)`	void	Rend l'entite invulnerable ou vulnerable aux degats.
`set_gravity(flag)`	void	Active ou desactive la gravite pour l'entite.
`set_glowing(flag)`	void	Active/desactive l'effet de contour lumineux sur l'entite.

Champs d'entite vivante

Les entites vivantes (joueurs, mobs, etc.) ont tous les champs de base d'entite plus :

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

Methodes d'entite vivante

Methode	Retourne	Notes
`damage(amount)`	void	Inflige la quantite de degats donnee a l'entite
`push(x, y, z)`	void	Applique une impulsion de velocite
`set_facing(x, y, z)`	void	Definit la direction dans laquelle l'entite regarde
`add_potion_effect(effect, duration, amplifier)`	void	Ajoute un effet de potion. `effect` est un string (par exemple `"speed"`, `"slowness"`, `"regeneration"`). `duration` est en ticks. `amplifier` est le niveau de l'effet moins 1 (0 = niveau I).
`remove_potion_effect(effect)`	void	Supprime un effet de potion par nom

attention

Toutes les entites retournees par get_nearby_entities() ne sont pas des entites vivantes. Vous pouvez utiliser entity.is_player, entity.is_hostile, ou entity.is_passive pour filtrer par categorie, ou verifier if entity.damage then avant d'appeler les methodes d'entites vivantes comme damage(), push(), ou add_potion_effect().

Champs d'integration de plugins

Les tables d'entites incluent automatiquement des champs pour detecter et interagir avec les entites gerees par d'autres plugins Nightbreak. Ces champs ne sont remplis que lorsque le plugin concerne est installe -- sinon ils sont par defaut a false / nil sans surcharge.

Champs EliteMobs

Disponibles lorsque EliteMobs est installe.

Champ	Type	Notes
`is_elite`	boolean	Si l'entite est un elite EliteMobs
`is_custom_boss`	boolean	Si l'entite est un boss personnalise EliteMobs (egalement disponible dans la sous-table `elite`)
`is_significant_boss`	boolean	Si l'entite est un boss personnalise avec un multiplicateur de sante superieur a 1 (c.-a-d. une rencontre concue, pas un elite de remplissage)
`elite`	table ou nil	Sous-table d'informations elite (voir ci-dessous). `nil` si l'entite 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	Sante actuelle
`elite.max_health`	number	Sante maximale
`elite.is_custom_boss`	boolean	Si c'est un boss personnalise (par opposition a un elite naturel)
`elite.health_multiplier`	number	Multiplicateur de sante defini dans la configuration
`elite.damage_multiplier`	number	Multiplicateur de degats defini dans la configuration
`elite:remove()`	void	Supprime l'elite via le pipeline de suppression appropriate d'EliteMobs (nettoie le suivi, le butin, etc.)

Exemple : Infliger des degats differemment 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 installe.

Champ	Type	Notes
`is_modeled`	boolean	Si l'entite a un modele FMM attache (DynamicEntity ou PropEntity)
`is_prop`	boolean	Si l'entite est un prop FMM (entite decorative statique)
`model`	table ou nil	Sous-table d'informations modele (voir ci-dessous). `nil` si l'entite n'est pas modelee.

La sous-table model contient :

Champ	Type	Notes
`model.model_id`	string	L'ID du blueprint du modele (par exemple `"torch_01"`)
`model:play_animation(name, [blend], [loop])`	boolean	Joue une animation nommee. `blend` par defaut a `false`, `loop` par defaut a `false`. Retourne `true` si l'animation a ete trouvee.
`model:stop_animations()`	void	Arrete toutes les animations en cours sur le modele.
`model:remove()`	void	Supprime l'entite modelee via le pipeline de suppression appropriate de FMM.

Bridge vs Prop par defaut

Le bridge de modele (disponible sur n'importe quelle entite) met blend et loop par defaut a false. La table prop play_animation met les deux par defaut a true car les props veulent generalement des animations fusionnees et en boucle.

Exemple : Filtrer les entites 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 specifiques aux joueurs

Les entites joueurs ont tous les champs d'entite et d'entite vivante plus :

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

Methodes specifiques aux joueurs

Methode	Retourne	Notes
`send_message(msg)`	void	Envoie un message de chat au joueur. Supporte les codes couleur `&`.
`get_held_item()`	table ou nil	Retourne `{type, amount, display_name}` pour l'objet dans la main principale du joueur, ou `nil` si vide
`consume_held_item(amount?)`	void	Consomme des objets de la main principale du joueur. `amount` par defaut a `1`
`has_item(material, amount?)`	boolean	Retourne `true` si le joueur a au moins `amount` (defaut `1`) du materiau donne n'importe ou dans son inventaire
`get_target_entity([range])`	table d'entite ou nil	Retourne l'entite que le joueur regarde via raycast, ou `nil` si aucune. Portee par defaut de 50.
`get_eye_location()`	table de position	Retourne une table de position a la hauteur des yeux du joueur
`get_look_direction()`	table	Retourne un vecteur de direction `{x, y, z}` indiquant ou le joueur regarde
`send_block_change(x, y, z, material, [ticks])`	void	Envoie un faux bloc visible uniquement pour ce joueur. Si `ticks` est fourni, le faux bloc se reinitialise automatiquement apres cette duree.
`reset_block(x, y, z)`	void	Reinitialise un faux bloc au bloc reel pour ce joueur
`sleep(x, y, z)`	void	Fait entrer le joueur dans une animation de sommeil dans un lit aux coordonnees donnees. Le bloc est automatiquement restaure quand le joueur arrete de dormir.
`wake_up()`	void	Reveille un joueur endormi.

Methodes d'interface joueur

Ces methodes sont disponibles sur n'importe quelle table d'entite joueur et fournissent des moyens d'afficher des informations au joueur via les elements d'interface natifs de Minecraft.

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

Affiche une barre de boss au joueur.

Parametre	Type	Defaut	Notes
`text`	string	requis	Le texte a afficher. Supporte les codes couleur `&`.
`color`	string	`"WHITE"`	Couleur de la barre. L'une de : `"RED"`, `"BLUE"`, `"GREEN"`, `"YELLOW"`, `"PURPLE"`, `"PINK"`, `"WHITE"`
`progress`	number	requis	Remplissage de `0.0` (vide) a `1.0` (plein)
`ticks`	int	nil	Delai optionnel de masquage automatique en ticks. Si omis, la barre reste jusqu'a etre masquee manuellement.

`player:hide_boss_bar()`

Supprime la barre de boss de l'ecran du joueur. Ne prend aucun parametre.

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

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

Parametre	Type	Defaut	Notes
`text`	string	requis	Le texte a afficher. Supporte les codes couleur `&`.
`ticks`	int	nil	Duree optionnelle en ticks. Si fourni, le message est renvoye toutes les 40 ticks pour rester visible pendant toute la duree.

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

Affiche un ecran titre au joueur.

Parametre	Type	Defaut	Notes
`title`	string	requis	Texte du titre principal. Supporte les codes couleur `&`.
`subtitle`	string	`""`	Texte du sous-titre sous le titre principal. Optionnel.
`fade_in`	int	requis	Duree de fondu d'entree en ticks
`stay`	int	requis	Duree d'affichage du titre a l'ecran en ticks
`fade_out`	int	requis	Duree de fondu de sortie en ticks

Prochaines etapes

Pour les hooks, APIs et workflows specifiques aux plugins :

EliteMobs : Pour commencer | Hooks & Cycle de vie | Boss & Entites | Monde & Environnement | Zones & Ciblage
FreeMinecraftModels : Pour commencer | API Prop & Objet | Exemples

Mini-guide Lua
Sandbox Lua
- Globales supprimees
- Bibliotheque standard disponible
Contrat de fichier
- Champs de niveau superieur requis et optionnels
- Regles de validation
Syntaxe des methodes : : vs .
Budget d'execution
context.state
context.log
context.cooldowns
context.scheduler
context.world
context.zones
context.event
Espace de noms em
Tables d'entites
Methodes d'interface joueur
Prochaines etapes

Mini-guide Lua​

Variables​

Fonctions​

Verifications if​

nil​

Tables​

Retourner la definition du script​

Commentaires​

Sandbox Lua​

Globales supprimees​

Bibliotheque standard disponible​

Contrat de fichier​

Champs de niveau superieur requis et optionnels​

Regles de validation​

Syntaxe des methodes : : vs .​

Budget d'execution​

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 declenchement de proximite​

context.event​

Espace de noms em​

Tables d'entites​

Champs de base d'entite​

Methodes de base d'entite​

Champs d'entite vivante​

Methodes d'entite vivante​

Champs d'integration de plugins​

Champs EliteMobs​

Champs FreeMinecraftModels​

Champs specifiques aux joueurs​

Methodes specifiques aux joueurs​

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

Prochaines etapes​

Mini-guide Lua

Variables

Fonctions

Verifications `if`

`nil`

Tables

Retourner la definition du script

Commentaires

Sandbox Lua

Globales supprimees

Bibliotheque standard disponible

Contrat de fichier

Champs de niveau superieur requis et optionnels

Regles de validation

Syntaxe des methodes : `:` vs `.`

Budget d'execution

`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 declenchement de proximite

`context.event`

Espace de noms `em`

Tables d'entites

Champs de base d'entite

Methodes de base d'entite

Champs d'entite vivante

Methodes d'entite vivante

Champs d'integration de plugins

Champs EliteMobs

Champs FreeMinecraftModels

Champs specifiques aux joueurs

Methodes specifiques aux joueurs

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

Prochaines etapes