N.event — Server Events

N.event() is the event-based alternative to `N.command`. Instead of triggering through `/commands`, it listens to **server events** — for example, `playerJoin`, `playerDeath`, `vehicleEnter`, or c

🔹 Basic Syntax

N.event({
  cmd: "playerJoin",
  description: "Triggered when player joins the server",
  notify: "👋 Welcome to the server!",
  action: (player) => {
    player.outputChatBox(`Hello ${player.name}, enjoy your stay!`);
  }
});

This registers a listener for the RAGE:MP event playerJoin.

🧭 Where It Works

Side	Availability	Description
🖥️ Server	✅ Available	Listens to RAGE:MP or custom events.
💻 Client	✅ Available	Listens to RAGE:MP or custom events.

⚙️ Parameters

Parameter	Type	Description
cmd	string	The event name. Can be a built-in event (e.g., "playerJoin", "playerDeath") or a custom one (e.g., "garage:open").
description	string	Short description for documentation or logs.
adminOnly	boolean / "off"	If true, only admins can trigger this event manually or through remote calls. NurJS checks player.admin === true.
args	array	Expected arguments for the event.
hint	string	Optional text shown if event is on cooldown or missing arguments.
log	string / object / boolean	Enables console/file logging for event activations.
checker	object	Checks player properties before executing the event. For example: { join: true, prison: 0 } will allow the event only if player.join === true and player.prison === 0.
notify	string	Notification text sent to player after the event executes.
createBlip	object	{ sprite, pos, name, color, shortRange } — creates a blip.
createVehicle	object	{ model, pos, color, warpInto, engine, plate, alpha } — spawns a vehicle.
createObject	object	{ model, pos, rot, dimension } — spawns an object.
vehfix	boolean	Repairs the player’s vehicle instantly if true.
cooldown	number	Delay (in seconds) before the event can run again for the same player.
tp	array	[x, y, z] — teleports the player.
playAnim	object	{ dict, name } — plays an animation.
playerScenario	string	Plays a GTA scenario (e.g. "WORLD_HUMAN_SMOKING").
weapon	object	{ model, ammo } — gives a weapon.
playerAlpha	number	Sets transparency (0–255).
tpToMarker	boolean	Teleports player to their map marker.
tpToPlayer	boolean	Teleports player to another player by ID or name.
tpPlayerToMe	boolean	Teleports another player to the current one.
setWeather	string	Sets world weather (e.g. "CLEAR", "EXTRASUNNY").
setTime	object	{ hour, minute } — sets world time.
rangefreez	object	{ radius } — freezes all players in a given radius.
safe	boolean	Wraps your action in a try/catch block to prevent crashes.
action	function	The main logic triggered when the event fires.

🧠 Checker & Admin Example

N.event({
  cmd: "playerEnterVehicle",
  description: "Auto repair for admins only",
  adminOnly: true,
  checker: { join: true },
  vehfix: true,
  notify: "🔧 Vehicle fixed automatically!"
});

✅ The event will trigger only when:

• the player joined (player.join === true), and

• the player is an admin (player.admin === true).

🔁 Cooldown Example

N.event({
  cmd: "garage:enter",
  cooldown: 10,
  notify: "⏱ Wait before entering the garage again.",
  action: (player) => {
    player.call("garage:openUI");
  }
});

Prevents the same event from firing multiple times in a short period.

🎯 Teleport & Object Example

N.event({
  cmd: "playerSpawn",
  tp: [215.5, -810.2, 30.7],
  createObject: { model: "prop_beachflag_01", pos: new mp.Vector3(215.5, -810.2, 30.7) },
  notify: "🏁 Welcome to the spawn area!"
});

Automatically teleports the player and spawns an object upon joining.

🔫 Weapons & Animations Example

N.event({
  cmd: "event:reward",
  weapon: { model: "weapon_pistol", ammo: 60 },
  playAnim: { dict: "anim@mp_snowball", name: "pickup_snowball" },
  notify: "🎁 You received a reward!"
});

🧊 Range Freeze Example

N.event({
  cmd: "area:freeze",
  description: "Freeze nearby players in 5m radius",
  rangefreez: { radius: 5 },
  notify: "❄️ All nearby players are frozen!"
});

🧩 Safe Mode Example

N.event({
  cmd: "debug:test",
  safe: true,
  action: () => {
    throw new Error("Simulated crash — handled safely");
  }
});

The safe mode ensures your event won't crash the server if it throws an error.

🧾 Logging Example

N.event({
  cmd: "admin:ban",
  log: "[ADMIN] {player} banned {args}",
  notify: "🚫 Player banned successfully.",
  action: (player, targetId) => {
    const target = mp.players.at(parseInt(targetId));
    if (target) target.kick("Banned by admin.");
  }
});

N.event() gives you complete control over RAGE:MP event logic — it’s the backbone of reactive gameplay in NurJS.

Use it to build systems like:

• player join / leave hooks

• teleport triggers

• admin panels

• garages and interiors

• quest and reward events