Scripting

Chaque arme peut enchaîner des actions au YAML (ou via l’éditeur GUI). Ce n’est pas un langage : c’est une liste d’effets avec délai, cible, conditions et état (cooldown / stacks / once).

Le fichier est aussi copié dans plugins/GunCraft/SCRIPTING.md au premier démarrage.

Anatomie

actions:
  id-unique:
    event: BULLET_HIT_PLAYER   # quand
    action: KNOCKBACK          # quoi
    chance: 1.0                # 0.0–1.0
    delay: 0                   # ticks avant exécution
    target: victim             # shooter | victim | hit | area  (optionnel = auto)
    radius: 3                  # si target: area
    if:                        # toutes les conditions doivent matcher (ET)
      - headshot
    cooldown: 20               # ticks avant que CETTE action puisse re-proc
    stacks: 0                  # 5 = il faut 5 triggers puis proc (reset)
    stack-reset: 100           # ticks sans trigger avant reset des stacks
    once: none                 # none | shot | burst
    # … champs spécifiques au type

chance est tiré après les if, avant cooldown / stacks / once.

delay fige le contexte (tireur, victime, position, headshot, dégâts). Les conditions ne sont pas re-testées à l’exécution retardée.

Events (event)

Event	Quand
PLAYER_FIRE	Un projectile part (chaque coup d’un burst)
BURST_END	Dernier coup du burst (ou le seul coup)
BULLET_HIT_PLAYER	Hit joueur (avant le script KILL/HEADSHOT)
BULLET_HIT_MOB	Hit mob
BULLET_HIT_BLOCK	Hit bloc
HEADSHOT	Hit confirmé à la tête (joueur ou mob)
KILL	La cible meurt de ce hit
PLAYER_RELOAD	Début de reload
RELOAD_FINISH	Fin de reload
EMPTY_MAG	Clic à vide / plus de munitions
ADS_START / ADS_STOP	Arme ads: true, visée activée / relâchée
EQUIP / UNEQUIP	Arme prise / quittée (changement de slot, quit)

Un headshot déclenche à la fois BULLET_HIT_PLAYER (ou _MOB) et HEADSHOT. Utilise event: HEADSHOT ou if: headshot, pas les deux sur le même effet.

once: shot : une fois par balle (les 6 pellets d’un shotgun partagent le même shot).
once: burst : une fois pour toute la rafale.

Cible (target)

Valeur	Entités / position
shooter	Le tireur
victim	La cible hit (joueur/mob)
hit	Point d’impact (bloc ou victime)
area	Living entities dans radius (sauf le tireur)

Si target est omis :

• fire / reload / ads / equip / empty / burst → shooter
• hit bloc → hit
• hit / kill / headshot → victim

Compatibilité : sound-shooter / sound-target / message-shooter / message-target fonctionnent encore. Si tu les laisses à false et que tu mets target:, c’est target qui gagne.

Conditions (if)

Une string ou une liste. Toutes doivent être vraies.

Condition	Vrai si
headshot	Hit tête
kill / critical	La cible est morte (surtout utile sur KILL ou après delay)
aiming	ADS actif
sneaking	Shift
ammo_empty	Chargeur vide
ammo_full	Chargeur plein
victim_player	La victime est un joueur
cooldown	L’arme est en shot-delay
silenced	L’arme est sous WEAPON_COOLDOWN
in_region:spawn	WorldGuard : le point d’impact (ou le tireur) est dans la région spawn

if: headshot
if:
  - aiming
  - sneaking
if: in_region:pvp

Placeholders

Utilisables dans SEND_MESSAGE et RUN_COMMAND :

{player} {victim} {x} {y} {z} {world} {weapon} {ammo} {distance} {headshot} {damage} {kill}

Types d’actions

FX / monde

PLAY_SOUND — sound, volume (défaut 1), pitch (défaut 1), sound-shooter, sound-target

SPAWN_PARTICLE — particle, particle-count, offset, speed, force (visible de loin)

SPAWN_MOB — mob (enum Bukkit, ex. ZOMBIE)

REPLACE_BLOCK — only-on (optionnel), replace-with, duration en ticks (0 = permanent).
Si duration > 0, le bloc est restauré (sauf s’il a été changé entre-temps). WorldGuard guncraft-replace-blocks + BlockBreakEvent.

LIGHTNING — effect-only: true (défaut, visuel). false = vrai éclair (flag guncraft-explode)

EXPLODE — power (défaut 1.5), break-blocks: false, fire: false
Sans WorldGuard : OK. Avec WG : flag guncraft-explode (défaut deny). Casser les blocs exige aussi guncraft-replace-blocks.

Combat

ADD_EFFECTS — effects: [SLOW, POISON], effect-duration (ticks, défaut 100), amplifier (défaut 0), ambient

KNOCKBACK — knockback-force, knockback-direction: AWAY UP DOWN TOWARD FORWARD

PULL — attire vers le tireur, pull-force

DASH — pousse la cible (défaut FORWARD), dash-force, dash-direction

LAUNCH — comme DASH, défaut UP (shotgun jump : target: shooter)

IGNITE — ignite-ticks

FREEZE — powder snow freeze ticks + slowness, freeze-ticks

DAMAGE — extra-damage (respecte guncraft-pvp / guncraft-damage-mobs)

Arme

SET_AMMO — ammo: 0 (clamp 0–magazine)

CONSUME_AMMO — amount: 1

FORCE_RELOAD — lance un reload (évite de le mettre sur PLAYER_RELOAD)

WEAPON_COOLDOWN — ticks : l’arme ne peut plus tirer pendant X ticks (overheat)

SWAP_SKIN — skin: gold (id sous skins: de l’arme)

Items / messages / commandes

SEND_MESSAGE — message, target ou message-shooter / message-target

GIVE_ITEM / TAKE_ITEM

action: GIVE_ITEM
item:
  type: GOLD_NUGGET
  amount: 1
  name: "&6Trophy"

RUN_COMMAND — console. Désactivé tant que allow-console-commands: false. Placeholders ci-dessus.

WorldGuard

Flag	Défaut	Sert à
guncraft-shoot	allow	Tirer
guncraft-pvp	allow	Dégâts joueurs (+ DAMAGE)
guncraft-damage-mobs	allow	Dégâts mobs
guncraft-replace-blocks	deny	REPLACE_BLOCK et explosions qui cassent
guncraft-explode	deny	EXPLODE et éclair réel

Les flags s’enregistrent au démarrage (onLoad), pas au /guns reload.

/rg flag pvp guncraft-explode allow
/rg flag spawn guncraft-shoot deny

Éditeur GUI

/guns → clic droit une arme → onglet Audio / actions → livre Actions.

Liste :

• Filtres (ligne du haut) : Tous / Tir / Hit / Reload / ADS / Autre
• Clic = éditer, Shift-clic = supprimer
• Émeraude (45) = nouvelle action (événement par défaut selon le filtre)

Édition :

• Colonne gauche = contexte (événement, type, if, délai, chance, cible, cooldown, once)
• Colonne droite = payload (son, message, force, ticks, item…)
• If en chat (conditions séparées par des virgules)
• Sons : clic gauche = preview, clic droit = valider (recherche + 8 récents)

Le YAML reste la source complète : stacks, radius, particules avancées, items nommés, etc. se font plus confortablement à la main.

Exemples

Marker de sniper

actions:
  hs-sound:
    event: HEADSHOT
    action: PLAY_SOUND
    sound: ENTITY_ARROW_HIT_PLAYER
    sound-shooter: true
    once: shot
  hs-chat:
    event: HEADSHOT
    action: SEND_MESSAGE
    message: "&cHeadshot {victim} &7({distance}m)"
    target: shooter

Stun à 3 hits

actions:
  combo:
    event: BULLET_HIT_PLAYER
    action: ADD_EFFECTS
    effects: [SLOW]
    effect-duration: 40
    amplifier: 2
    stacks: 3
    stack-reset: 60
    cooldown: 80

Rocket (hit bloc)

actions:
  boom:
    event: BULLET_HIT_BLOCK
    action: EXPLODE
    power: 1.8
    break-blocks: false
    delay: 2
  flash:
    event: BULLET_HIT_BLOCK
    action: SPAWN_PARTICLE
    particle: EXPLOSION_LARGE
    particle-count: 1
    force: true

Shotgun jump

actions:
  jump:
    event: PLAYER_FIRE
    if: sneaking
    action: LAUNCH
    target: shooter
    dash-force: 0.6
    dash-direction: UP
    cooldown: 40

Overheat SMG

actions:
  heat:
    event: PLAYER_FIRE
    action: WEAPON_COOLDOWN
    ticks: 30
    stacks: 25
    stack-reset: 40

Bloc temporaire (glace)

actions:
  ice:
    event: BULLET_HIT_BLOCK
    action: REPLACE_BLOCK
    replace-with: ICE
    duration: 60
    once: shot

Bonnes pratiques

• Préfère un type natif à RUN_COMMAND.
• Shotguns : once: shot sur knockback / explode / particles.
• EXPLODE + break-blocks: true = grief. Laisse false, et le flag WG deny.
• delay pour cinématiser (flash → boom), pas pour contourner les cooldowns (le cooldown est consommé tout de suite).
• /guns reload valide le YAML et liste les actions incomplètes dans le chat.

Voir aussi le pack guns-packs/demo-pack/ (sniper headshot, shotgun knockback + jump, SMG empty click) et guns-packs/exemple-pack/ (fire / hit joueur / hit bloc).